Rewrote intro docs

Author: dahlia

docs/intro.md

@@ -3,55 +3,142 @@ What is BotKit?
 
 BotKit is a TypeScript framework for creating standalone [ActivityPub] bots
 that can interact with Mastodon, Misskey, and other [fediverse] platforms.
-Built on top of the robust [Fedify] framework, BotKit lets you focus on your
-bot's logic while handling all the complexity of federation under the hood.
+Built on top of the robust [Fedify] framework, BotKit simplifies the process
+of creating federated bots while handling the underlying ActivityPub
+protocol details.
+
+Here's a simple example of what you can build with BotKit:
+
+~~~~ typescript
+import { createBot, MemoryKvStore, text } from "@fedify/botkit";
+
+const bot = createBot<void>({
+  username: "weatherbot",
+  name: "Seoul Weather Bot",
+  summary: text`I post daily weather updates for Seoul!`,
+  kv: new MemoryKvStore(),
+  // ... configuration options
+});
+
+// Respond to mentions
+bot.onMention = async (session, message) => {
+  await message.reply(
+    text`Current temperature in Seoul is 18°C with clear skies!`
+  );
+};
+
+// Post scheduled updates
+setInterval(async () => {
+  const session = bot.getSession("https://weather.example.com");
+  await session.publish(
+    text`Good morning! Today's forecast for Seoul:
+    🌡️ High: 22°C
+    💨 Low: 15°C
+    ☀️ Clear skies expected`
+  );
+}, 1000 * 60 * 60 * 24);  // Daily updates
+~~~~
 
 [ActivityPub]: https://activitypub.rocks/
 [fediverse]: https://fediverse.info/
 [Fedify]: https://fedify.dev/
 
 
-True independence 
------------------
+Key features
+------------
 
-Unlike traditional fediverse bots that require a Mastodon or Misskey account,
-BotKit lets you create fully standalone bots. Your bot runs as its own
-independent ActivityPub server, free from any platform-specific limitations or
-constraints.
+### Standalone operation
 
-Easy to use
------------
+BotKit allows you to run your bot as a standalone ActivityPub server,
+which offers several practical benefits:
 
-Getting started with BotKit is straightforward. Create a fully-functional
-fediverse bot in just a few lines of code using our intuitive API.
-We've designed BotKit to make federation as simple as possible,
-so you can focus on what your bot does best.
+ -  No need to create and maintain a Mastodon or Misskey account
+ -  Direct control over your bot's database and message queue
+  - Freedom to define your own message size limits
 
+Note that while BotKit bots are standalone, they still need to comply with
+general fediverse protocols and best practices to ensure reliable federation
+with other servers.
 
-Type-safe
----------
+### Developer-friendly API
 
-BotKit is fully written in TypeScript, providing excellent IDE integration with
-autocompletion and inline documentation. Catch potential errors at compile time
-and enjoy a more productive development experience with complete type safety.
+BotKit provides a straightforward API that handles common bot operations:
 
+Event handling
+:   Easily respond to mentions, follows, and messages.
 
-Easy to deploy
---------------
+    ~~~~ typescript
+    bot.onFollow = async (session, follower) => {
+      await session.publish(
+        text`Thanks for following me, ${follower}!`,
+        { visibility: "direct" }
+      );
+    };
+    ~~~~
 
-BotKit is designed with modern deployment in mind. With minimal dependencies and
-a lightweight footprint, you can easily deploy your bot to Deno Deploy,
-or any container platforms like Fly.io and Railway using the Deno runtime.
-Support for Node.js and Bun is planned for future releases.
+Rich content
+:   Create formatted messages with mentions, hashtags, and media.
 
+    ~~~~ typescript
+    await session.publish(
+      text`Check out ${link("BotKit docs", "https://botkit.fedify.dev/")}!
 
-Rock-solid foundation
----------------------
+        ${hashtag("FediverseBot")}`,
+      {
+        attachments: [
+          new Image({
+            mediaType: "image/png",
+            url: new URL("https://example.com/chart.png"),
+            name: "Daily statistics"
+          }),
+        ],
+      }
+    );
+    ~~~~
 
-Built on Fedify, a battle-tested ActivityPub framework, BotKit ensures robust
-federation and seamless compatibility with the fediverse ecosystem.
-You can trust that your bot will work reliably with Mastodon, Misskey,
-and other ActivityPub implementations.
+Message management
+:   Programmatically update or delete posts.
 
-Ready to create your first fediverse bot?
-[Get started with BotKit →](./start.md)
+    ~~~~ typescript
+    const msg = await session.publish(text`Initial message`);
+    await msg.update(text`Updated content`);
+    ~~~~
+
+### Type safety
+
+BotKit is written in TypeScript and provides:
+
+ -  Comprehensive type definitions for all API methods
+ -  Compile-time error checking for ActivityPub interactions
+ -  Autocomplete support in modern IDEs
+ -  Type-safe message formatting utilities
+
+### Deployment options
+
+BotKit currently supports deployment through:
+
+ -  [Deno Deploy] for serverless hosting
+ -  Docker containers on platforms like Fly.io and Railway
+ -  Self-hosted Deno runtime on your own server
+
+> [!NOTE]
+> While Node.js and Bun support are planned for future releases,
+> the current version requires Deno.
+
+[Deno Deploy]: https://deno.com/deploy
+
+### Built on Fedify
+
+BotKit builds upon [Fedify]'s proven ActivityPub implementation:
+
+ -  Robust federation with major fediverse platforms
+ -  Built-in retry mechanisms
+ -  Support for various storage backends (Redis, PostgreSQL, Deno KV)
+ -  Efficient message queue processing
+
+
+Getting started
+---------------
+
+Ready to create your first fediverse bot? Follow our
+[step-by-step guide](./start.md) to get your bot up and running in minutes.