docs: polish getting-started

README.md

@@ -123,8 +123,8 @@ Bub is shaped by one constraint: real collaboration is messier than a solo demo.
 
 Read more:
 
-- [Why We Rewrote Bub](https://bub.build/posts/2026-04-07-why-we-rewrote-bub/)
-- [Socialized Evaluation and Agent Partnership](https://bub.build/posts/2026-03-01-bub-socialized-evaluation-and-agent-partnership/)
+- [Why We Rewrote Bub](https://bub.build/posts/why-rewrite-bub/)
+- [Socialized Evaluation and Agent Partnership](https://bub.build/posts/socialized-evaluation/)
 - [Context from Tape](https://tape.systems)
 
 ## Docs

website/AGENTS.md

@@ -137,8 +137,8 @@ The site has **three distinct i18n zones**. Each zone has its own translation me
 Follows the **exact pattern** from [`withastro/starlight/docs`](https://github.com/withastro/starlight/tree/main/docs).
 
 **Locale configuration** — `astro.config.mjs`:
-- English is the **`root` locale** — content files live under `src/content/docs/docs/` (e.g., `docs/getting-started/installation.md`).
-- Other locales get **subdirectories**: `src/content/docs/zh-cn/docs/getting-started/installation.md`.
+- English is the **`root` locale** — content files live under `src/content/docs/docs/` (e.g., `docs/getting-started/run-bub-locally.mdx`).
+- Other locales get **subdirectories**: `src/content/docs/zh-cn/docs/getting-started/run-bub-locally.mdx`.
 - The inner `docs/` directory creates the `/docs/` URL prefix — Starlight 0.38 has no `routePrefix` option, so this nesting is the standard way to namespace docs routes.
 - This keeps the URL scheme consistent: `/docs/…` for docs, `/posts/…` for blog.
 

website/src/content/docs/docs/getting-started/equip-your-bub.mdx

@@ -0,0 +1,94 @@
+---
+title: Equip Your Bub
+description: Add workspace instructions, project skills, and only the contrib plugins your Bub workspace actually needs.
+sidebar:
+  order: 2
+---
+
+Use this page after [Run Bub Locally](/docs/getting-started/run-bub-locally/). It shows how to make one workspace more useful without changing Bub itself.
+
+You will add three things:
+
+1. durable workspace rules in `AGENTS.md`
+2. reusable project procedures in `.agents/skills`
+3. optional runtime extensions installed as plugins
+
+## 1. Add workspace rules
+
+Update `AGENTS.md` so the agent has a stable operating policy for this repository:
+
+```markdown
+You are the Bub agent for this workspace.
+Read code before proposing changes.
+Prefer small, reviewable patches.
+Report verification steps explicitly.
+```
+
+Bub reads this file on every turn, so the same rules apply every time.
+
+Because Bub follows [agents.md](https://agents.md/), an existing `AGENTS.md` file from another compatible setup is often a good starting point.
+
+## 2. Add a project skill
+
+Create one project-local skill under `.agents/skills`:
+
+```bash
+mkdir -p .agents/skills/repo-map
+cat > .agents/skills/repo-map/SKILL.md <<'EOF'
+---
+name: repo-map
+description: Read the local repository layout before changing code.
+---
+
+1. Start with `rg --files` to see the repository shape.
+2. Open the smallest set of files that explains the task.
+3. Summarize the modules you touched before editing code.
+EOF
+```
+
+Verify that Bub discovers it:
+
+```bash
+uv run bub run ",skill name=repo-map"
+```
+
+Project skills in `.agents/skills` are loaded before user-level or builtin skills, so local procedures win by default.
+
+Bub follows the [Agent Skills](https://agentskills.io/) format. If you already maintain skills for another compatible agent, you can usually reuse those skill directories here.
+
+## 3. Install one extension
+
+Use plugins for extra capabilities such as tape stores and channels.
+
+If you want to see what is already available, check [hub.bub.build](https://hub.bub.build/). It collects Bub plugins and skills that you can reuse before writing your own.
+
+Use `bub install` to add only the capability you want:
+
+```bash
+uv run bub install bub-tapestore-sqlite@main
+uv run bub install bub-wechat@main
+```
+
+The main behavior to know is:
+
+- Bub keeps plugin dependencies in a managed uv project under `~/.bub/bub-project`
+- `name@ref` resolves a package from `bub-contrib` at `packages/<name>`
+- the active environment gets the plugin entry points, so the next Bub run can load them
+
+To inspect the active hook mapping after installation:
+
+```bash
+uv run bub hooks
+```
+
+If a plugin provides channels through `provide_channels()`, `uv run bub gateway` will start them together with any other enabled non-`cli` channels.
+
+## Result
+
+Your workspace now has three layers:
+
+- `AGENTS.md` defines durable local rules
+- `.agents/skills` adds reusable local procedures
+- contrib plugins add optional runtime surfaces such as tape stores or channels
+
+Next, continue with [Build Your First Plugin](/docs/getting-started/first-plugin/) if the builtins and existing plugins are still not enough.

website/src/content/docs/docs/getting-started/first-plugin.mdx

@@ -0,0 +1,111 @@
+---
+title: Build Your First Plugin
+description: Create a minimal Bub plugin, install it locally, and verify that it overrides the builtin runtime.
+sidebar:
+  order: 3
+---
+
+Use this page only after the builtins, your workspace files, and existing plugins are no longer enough.
+
+This tutorial builds a tiny local plugin that overrides Bub's model stage and echoes the incoming text. It is intentionally simple, so you can verify plugin loading without needing model credentials.
+
+## 1. Create the package skeleton
+
+```bash
+mkdir bub-echo-plugin
+cd bub-echo-plugin
+mkdir -p src/bub_echo_plugin
+touch src/bub_echo_plugin/__init__.py
+```
+
+Create `pyproject.toml`:
+
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bub-echo-plugin"
+version = "0.1.0"
+dependencies = ["bub"]
+
+[project.entry-points."bub"]
+echo = "bub_echo_plugin.plugin:echo_plugin"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bub_echo_plugin"]
+```
+
+## 2. Implement the plugin
+
+Create `src/bub_echo_plugin/plugin.py`:
+
+```python
+from __future__ import annotations
+
+from bub import hookimpl
+
+
+class EchoPlugin:
+    @hookimpl
+    def build_prompt(self, message, session_id, state):
+        if hasattr(message, "content"):
+            return str(message.content)
+        if isinstance(message, dict):
+            return str(message.get("content", ""))
+        return str(message)
+
+    @hookimpl
+    def run_model(self, prompt, session_id, state):
+        text = prompt if isinstance(prompt, str) else str(prompt)
+        return f"[echo:{session_id}] {text}"
+
+
+echo_plugin = EchoPlugin()
+```
+
+This plugin does two things:
+
+- `build_prompt()` keeps the prompt equal to the original inbound text
+- `run_model()` replaces the builtin model call with a deterministic echo response
+
+## 3. Install it into the active environment
+
+From the plugin directory:
+
+```bash
+uv pip install -e .
+```
+
+Bub loads entry points from the active Python environment, so an editable install is enough for local development.
+
+## 4. Verify that Bub loads it
+
+Check the hook report:
+
+```bash
+uv run bub hooks
+```
+
+You should see `echo` listed on both `build_prompt` and `run_model`.
+
+Now run one turn:
+
+```bash
+uv run bub run "hello from plugin tutorial"
+```
+
+The rendered outbound should include:
+
+`[echo:cli:local] hello from plugin tutorial`
+
+## Result
+
+You now have:
+
+- a package entry point under the `bub` group
+- two hook implementations that override builtin behavior
+- a local editable install workflow for quick iteration
+
+From here, continue with [Plugins](/docs/extending/plugins/) and [Hooks](/docs/extending/hooks/) for the full plugin and hook reference.

website/src/content/docs/docs/getting-started/index.mdx

@@ -1,12 +1,59 @@
 ---
 title: Getting Started
-description: Minimal path to install Bub and understand the main runtime commands.
+description: Learn what Bub is, run it locally, add local rules and skills, and extend it with plugins only when needed.
+sidebar:
+  order: 0
 ---
 
-Bub is designed to stay small at the core, so the first run is quick.
+Bub is a small Python framework for building agents in shared environments. It gives you a clear turn pipeline, a simple workspace layout, and a normal Python packaging story for extensions.
 
-- Install from PyPI or from source.
-- Start an interactive session with `bub chat`.
-- Run a one-shot turn with `bub run "hello"`.
+If you are new to Bub, start here. This section helps you get one working setup first, then add only the pieces you actually need.
 
-Continue with [Installation](/getting-started/installation/).
+## What You Need To Know
+
+1. **A small core**
+   Bub runs each turn through a visible hook pipeline. You can replace one stage without rewriting the whole system.
+2. **A shared workspace**
+   Put workspace instructions in `AGENTS.md` and repeatable local procedures in `.agents/skills`.
+3. **Standard Python extensions**
+   Plugins are normal Python packages discovered through entry points. Skills can ship with plugins through regular build tooling, including PEP 517 build hooks.
+4. **A migration path from other agents**
+   Bub follows [agents.md](https://agents.md/) for workspace instructions and [Agent Skills](https://agentskills.io/) for skills. If you already use those conventions elsewhere, you can usually reuse your `AGENTS.md` file and skill directories.
+
+## Before You Start
+
+Have these ready:
+
+- Python 3.12+
+- `uv`
+- one model access path for the model-backed step:
+  - an API key via `BUB_API_KEY`, or
+  - OAuth login via `uv run bub login openai`
+
+## What You Will Build
+
+By the end of this section, you will have:
+
+- one local Bub workspace
+- one project skill under `.agents/skills`
+- one installed extension from `bub-contrib`
+- one minimal plugin package you can iterate on locally
+
+## Recommended Path
+
+1. [Run Bub Locally](/docs/getting-started/run-bub-locally/)
+   Install Bub, create a workspace, inspect the builtin kernel, and complete the first successful turn.
+2. [Equip Your Bub](/docs/getting-started/equip-your-bub/)
+   Add rules in `AGENTS.md`, add one project skill, and install only the extension you actually need.
+3. [Build Your First Plugin](/docs/getting-started/first-plugin/)
+   Create a minimal plugin package, install it locally, and verify that Bub loads its hook implementations.
+
+## If You Need Something Else First
+
+- Want the runtime model first: go to [Architecture](/docs/concepts/architecture/)
+- Want command details: go to [CLI Reference](/docs/guides/cli/)
+- Want to configure the builtin Telegram channel: go to [Telegram](/docs/guides/telegram/)
+- Want deployment guidance: go to [Deployment](/docs/guides/deployment/)
+- Want the full plugin and hook documentation: go to [Plugins](/docs/extending/plugins/) and [Hooks](/docs/extending/hooks/)
+
+This section is meant to get you started, not cover every option. Deployment details, full Telegram setup, and the complete plugin API stay in the Guides, Concepts, and Extending sections.