Docs: Fix broken internal links and add sidebar ordering

docs/README.md

@@ -4,7 +4,7 @@ title: "Perstack: The Agent Runtime"
 
 Define AI agents as declarative **Experts** in TOML. Execute them with deterministic, event-derived tracking. Each Expert runs in its own isolated context — no shared state, no prompt bloat, full execution history.
 
-- [Getting Started →](./getting-started.md)
+- [Getting Started →](./getting-started/walkthrough.md)
 - [Browse Registry →](https://platform.perstack.ai/)
 
 ## What Perstack Solves
@@ -66,25 +66,23 @@ const checkpoint = await run({
 
 ### Learn
 
-- [Getting Started](./getting-started.md) — create your first Expert and walk through the core workflow
+- [Getting Started](./getting-started/walkthrough.md) — create your first Expert and walk through the core workflow
 - **Understanding Perstack**
   - [Concept](./understanding-perstack/concept.md) — the architecture behind the runtime
   - [Experts](./understanding-perstack/experts.md) — what Experts are and how they work
   - [Runtime](./understanding-perstack/runtime.md) — execution model and event system
   - [Sandbox Integration](./understanding-perstack/sandbox-integration.md) — infrastructure-level isolation
   - [Boundary Model](./understanding-perstack/boundary-model.md) — trust boundaries between components
-  - [Registry](./understanding-perstack/registry.md) — publishing and discovering Experts
 
 ### Build
 
-- **[Making Experts](./making-experts/README.md)** — complete guide to Expert definitions
+- **[Making Experts](./making-experts/best-practices.md)** — complete guide to Expert definitions
   - [Examples](./making-experts/examples.md) — real-world use cases
   - [Best Practices](./making-experts/best-practices.md) — design guidelines for effective Experts
   - [Skills](./making-experts/skills.md) — adding MCP tools to your Experts
   - [Base Skill](./making-experts/base-skill.md) — built-in tools provided by the runtime
   - [Testing](./making-experts/testing.md) — strategies for testing Experts
-  - [Publishing](./making-experts/publishing.md) — share Experts via the Registry
-- **[Guides](./guides/README.md)** — task-oriented walkthroughs
+- **[Guides](./guides/rapid-prototyping.md)** — task-oriented walkthroughs
   - [Rapid Prototyping](./guides/rapid-prototyping.md) — validate ideas without writing code
   - [Taming Prompt Sprawl](./guides/taming-prompt-sprawl.md) — fix bloated prompts with modular Experts
   - [Extending with Tools](./guides/extending-with-tools.md) — give your Experts real-world capabilities via MCP
@@ -93,7 +91,7 @@ const checkpoint = await run({
 
 ### Run
 
-- **[Using Experts](./using-experts/README.md)** — run and integrate Experts
+- **[Using Experts](./using-experts/running-experts.md)** — run and integrate Experts
   - [Running Experts](./using-experts/running-experts.md) — CLI commands and runtime API
   - [Workspace](./using-experts/workspace.md) — file system layout and conventions
   - [State Management](./using-experts/state-management.md) — checkpoints, pausing, resuming

docs/getting-started.md → docs/getting-started/walkthrough.md

@@ -1,22 +1,21 @@
 ---
-title: "Getting Started"
+title: "Walkthrough"
+sidebar:
+  order: 1
 ---
 
-This walkthrough takes you from zero to production integration. Each step addresses one or more of the [five structural problems](../README.md#why-perstack) in agentic app development.
+This walkthrough takes you from zero to production integration.
 
 ## Prerequisites
 
 - [Node.js 22+](https://nodejs.org/)
-- An LLM provider API key (see [Providers and Models](./references/providers-and-models.md))
+- An LLM provider API key (see [Providers and Models](../references/providers-and-models.md))
 
 ```bash
 export ANTHROPIC_API_KEY=sk-ant-...
 ```
 
-## Step 1: Create an Expert
-
-> [!TIP]
-> **Addresses**: Tight coupling, The developer owns everything
+## Create an Expert
 
 Generate an Expert definition interactively:
 
@@ -51,10 +50,7 @@ instruction = "Provide split routines and HIIT plans tailored to user history."
 
 You can also write `perstack.toml` manually — `create-expert` is a convenient starting point, not a requirement.
 
-## Step 2: Run Your Expert
-
-> [!TIP]
-> **Addresses**: Broken feedback loops
+## Run Your Expert
 
 ### Interactive mode
 
@@ -76,15 +72,12 @@ npx perstack run fitness-assistant "Start today's session"
 
 | Aspect | What Perstack Does |
 | --- | --- |
-| **Isolation** | Each Expert has its own context window. No prompt bloat. |
+| **State** | Both Experts share the workspace (`./fitness-log.md`), not conversation history. |
 | **Collaboration** | `fitness-assistant` delegates to `pro-trainer` autonomously. |
 | **Observability** | Every step is visible as a structured event. |
-| **State** | Both Experts share the workspace (`./fitness-log.md`), not conversation history. |
-
-## Step 3: Analyze Execution
+| **Isolation** | Each Expert has its own context window. No prompt bloat. |
 
-> [!TIP]
-> **Addresses**: No sustained behavior (observability)
+## Analyze Execution
 
 After running an Expert, inspect what happened:
 
@@ -106,12 +99,9 @@ Key options for deeper inspection:
 
 This matters because debugging agents across model changes, requirement changes, and prompt iterations requires visibility into every decision the agent made. `perstack log` gives you that visibility without adding instrumentation code.
 
-See [CLI Reference](./references/cli.md#perstack-log) for the full list of options.
+See [CLI Reference](../references/cli.md#perstack-log) for the full list of options.
 
-## Step 4: Lock for Reproducibility
-
-> [!TIP]
-> **Addresses**: No sustained behavior (reproducibility)
+## Lock for Reproducibility
 
 ```bash
 npx perstack install
@@ -128,10 +118,7 @@ This creates a `perstack.lock` file that caches tool schemas for all MCP skills.
 
 The lockfile is optional. If not present, skills are initialized at runtime as usual.
 
-## Step 5: Integrate into Your Application
-
-> [!TIP]
-> **Addresses**: No real isolation
+## Integrate into Your Application
 
 The CLI is for prototyping. For production, integrate Experts into your application via the Execution API, sandbox providers, or runtime embedding.
 
@@ -227,7 +214,7 @@ Perstack's isolation model maps naturally to container and serverless platforms:
 - Kubernetes
 - Cloudflare Workers
 
-Each Expert runs in its own sandboxed environment. See [Going to Production](./guides/going-to-production.md) for the Docker setup pattern. Detailed guides for other providers are coming soon.
+Each Expert runs in its own sandboxed environment. See [Going to Production](../guides/going-to-production.md) for the Docker setup pattern. Detailed guides for other providers are coming soon.
 
 ### Runtime Embedding (`@perstack/runtime`)
 
@@ -269,16 +256,16 @@ The CLI is for prototyping. The runtime API is for production. Both use the same
 ## What's Next
 
 **Build more:**
-- [Making Experts](./making-experts/README.md) — full `perstack.toml` guide
-- [Skills](./making-experts/skills.md) — MCP integration patterns
-- [Taming Prompt Sprawl](./guides/taming-prompt-sprawl.md) — break monolithic prompts into collaborating Experts
+- [Making Experts](../making-experts/best-practices.md) — full `perstack.toml` guide
+- [Skills](../making-experts/skills.md) — MCP integration patterns
+- [Taming Prompt Sprawl](../guides/taming-prompt-sprawl.md) — break monolithic prompts into collaborating Experts
 
 **Understand the architecture:**
-- [Concept](./understanding-perstack/concept.md) — why isolation and observability matter
-- [Experts](./understanding-perstack/experts.md) — best practices for Expert design
-- [Sandbox Integration](./understanding-perstack/sandbox-integration.md) — infrastructure-level isolation
+- [Concept](../understanding-perstack/concept.md) — why isolation and observability matter
+- [Experts](../understanding-perstack/experts.md) — best practices for Expert design
+- [Sandbox Integration](../understanding-perstack/sandbox-integration.md) — infrastructure-level isolation
 
 **Reference:**
-- [CLI Reference](./references/cli.md) — all commands and options
-- [perstack.toml Reference](./references/perstack-toml.md) — complete configuration spec
-- [Events](./references/events.md) — runtime event schema
+- [CLI Reference](../references/cli.md) — all commands and options
+- [perstack.toml Reference](../references/perstack-toml.md) — complete configuration spec
+- [Events](../references/events.md) — runtime event schema

docs/guides/adding-ai-to-your-app.md

@@ -2,7 +2,8 @@
 title: "Adding AI to Your App"
 description: "Embed AI capabilities into your existing application. Your app stays in control while Perstack handles execution."
 tags: ["integration", "container", "events"]
-order: 2
+sidebar:
+  order: 2
 ---
 
 You have an existing application — maybe a web app, a CLI tool, or a backend service. You want to add AI capabilities, but you're not sure where to start.

docs/guides/extending-with-tools.md

@@ -2,7 +2,8 @@
 title: "Extending with Tools"
 description: "Give your agent access to web search, databases, and APIs using MCP skills. Declare tools in TOML, the runtime handles the rest."
 tags: ["tools", "mcp", "skills"]
-order: 3
+sidebar:
+  order: 3
 ---
 
 Your agent can reason and generate text. But sometimes that's not enough — you need it to search the web, query a database, or call an API.

docs/guides/going-to-production.md

@@ -2,7 +2,8 @@
 title: "Going to Production"
 description: "Deploy your agent safely and reliably. Sandbox execution in containers with full observability."
 tags: ["deployment", "container", "production"]
-order: 5
+sidebar:
+  order: 5
 ---
 
 Your agent works in development. Now you want to deploy it for real users.

docs/guides/rapid-prototyping.md

@@ -2,7 +2,8 @@
 title: "Prototyping for Agent-First Apps"
 description: "Start with the agent, not the app. Use create-expert to go from idea to working agent in seconds, then expand to tools and applications."
 tags: ["beginner", "quick-start", "create-expert"]
-order: 1
+sidebar:
+  order: 1
 ---
 
 When you build an agent-powered app, the instinct is to start with the app — set up a project, install dependencies, write scaffolding. Then somewhere in the middle, you start figuring out what the agent should actually do.
@@ -129,5 +130,5 @@ At some point, your prototype will need more. The same `perstack.toml` scales 
 
 ## What's next
 
-- [Making Experts](../making-experts/README.md) — Learn the full Expert definition format
+- [Making Experts](../making-experts/best-practices.md) — Learn the full Expert definition format
 - [Best Practices](../making-experts/best-practices.md) — Design patterns for effective Experts

docs/guides/taming-prompt-sprawl.md

@@ -2,7 +2,8 @@
 title: "Taming Prompt Sprawl"
 description: "Fix bloated prompts and confused agents. Split responsibilities across focused Experts using delegation."
 tags: ["prompts", "delegation", "architecture"]
-order: 4
+sidebar:
+  order: 4
 ---
 
 Your agent started simple. A focused prompt, clear behavior, reliable results.

docs/making-experts/base-skill.md

@@ -1,5 +1,7 @@
 ---
 title: "Base Skill"
+sidebar:
+  order: 3
 ---
 
 Every Expert automatically has access to `@perstack/base` — a built-in skill that provides file operations, runtime control, and other essential tools.

docs/making-experts/best-practices.md

@@ -1,5 +1,7 @@
 ---
 title: "Best Practices"
+sidebar:
+  order: 1
 ---
 
 These principles help you avoid common pitfalls in agent development: monoliths, complexity explosions, debugging nightmares, and fragile systems. Building a large agent head-on almost always fails.

docs/making-experts/examples.md

@@ -1,5 +1,7 @@
 ---
 title: "Examples"
+sidebar:
+  order: 4
 ---
 
 Patterns for defining Experts. Each example highlights a specific skill type or integration approach.