Docs: Restructure landing page and getting-started walkthrough

docs/README.md

@@ -1,58 +1,120 @@
 ---
-title: "Perstack: Expert Stack for Agent-first Development"
+title: "Perstack: The Agent Runtime"
 ---
 
-# Perstack: Expert Stack for Agent-first Development
+# Perstack: The Agent Runtime
 
-Perstack is a package manager and runtime for agent-first development.
-Define modular micro-agents as Experts in TOML, publish them to a registry, and compose them like npm packages.
+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.
 
-**Perstack isn't another agent framework — it's npm/npx for agents.**
-
-- [Get Started →](./getting-started.md)
+- [Getting Started →](./getting-started.md)
 - [Browse Registry →](https://platform.perstack.ai/)
 
-## Key Features
-
-- **Agent-first development toolkit**
-  - Declarative Expert definitions as modular micro-agents
-  - Dependency management for composing Experts
-  - Public registry for reusing Experts instead of rebuilding them
-- **Sandbox-ready runtime**
-  - Secure execution designed for sandbox integration
-  - Observable, event-driven architecture
-  - Reproducible, checkpoint-based history
-
-## Why Perstack?
-
-AI agent developers struggle with:
-- Complex, monolithic agent apps
-- Little to no reusability
-- No dependency management
-- Context windows that explode at scale
-
-Perstack fixes these with proven software engineering principles:
-- **Isolation** — clear separation of concerns per Expert
-- **Observability** — every step is visible and traceable
-- **Reusability** — Experts compose declaratively through the runtime
-
-## Expert Stack
-
-Perstack provides **Expert Stack**:
-- **Experts** — modular micro-agents
-- **Runtime** — executes Experts
-- **Registry** — shares Experts
-- **Sandbox Integration** — safe production execution
-
-> [!NOTE]
-> The name "Perstack" combines the Latin word "perītus" (expert) and "stack".
-
-## Next Steps
-
-- [Getting Started](./getting-started.md) — run your first Expert in 5 minutes
-- [Understanding Perstack](./understanding-perstack/concept.md) — learn core concepts
-- [Making Experts](./making-experts/README.md) — define and develop Experts
-- [Using Experts](./using-experts/README.md) — run and integrate Experts
+## What Perstack Solves
+
+Agentic app development has five structural problems. Perstack is designed to address each of them:
+
+| Problem | Perstack's Approach |
+| :--- | :--- |
+| **Tight coupling** | **A runtime** that separates Expert definitions from app code, tools, prompts, and models |
+| **Broken feedback loops** | **CLI tools** to execute and analyze Experts from day one. Expert and app evolve independently. |
+| **The developer owns everything** | Expert definitions in **`perstack.toml`** are written by domain experts using natural language. Developers focus on integration, not prompt engineering. |
+| **No sustained behavior** | **Event-derived execution** and **step-level checkpoints** help maintain reproducible behavior, even across model or provider changes |
+| **No real isolation** | **Isolation** is built into the runtime architecture — workspace boundaries, environment sandboxing, and tool whitelisting — so your platform can enforce security at the infrastructure level |
+
+For the full rationale, see the [root README](../README.md#why-perstack).
+
+## How It Works
+
+**1. Define** — Describe Experts in `perstack.toml` using natural language:
+
+```toml
+[experts."fitness-assistant"]
+description = "Manages fitness records and suggests training menus"
+instruction = """
+Conduct interview sessions and manage records in `./fitness-log.md`.
+Collaborate with `pro-trainer` for professional training menus.
+"""
+delegates = ["pro-trainer"]
+```
+
+Or generate one interactively:
+
+```bash
+npx create-expert "Create a fitness assistant that delegates to a pro trainer"
+```
+
+**2. Execute** — Run from the CLI with real-time feedback:
+
+```bash
+npx perstack start fitness-assistant "Start today's session"
+```
+
+**3. Integrate** — Embed into your application via the runtime API or Execution API:
+
+```typescript
+import { run } from "@perstack/runtime"
+
+const checkpoint = await run({
+  setting: {
+    model: "claude-sonnet-4-5-20250929",
+    providerConfig: { providerName: "anthropic" },
+    expertKey: "fitness-assistant",
+    input: { text: "Start today's session" },
+  },
+})
+```
+
+## Documentation
+
+### Learn
+
+- [Getting Started](./getting-started.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
+  - [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
+  - [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
+  - [Adding AI to Your App](./guides/adding-ai-to-your-app.md) — integrate Experts into existing applications
+  - [Going to Production](./guides/going-to-production.md) — deploy safely with container isolation
+
+### Run
+
+- **[Using Experts](./using-experts/README.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
+  - [Error Handling](./using-experts/error-handling.md) — handling failures gracefully
+- **Operating Experts** — production operations
+  - [Isolation by Design](./operating-experts/isolation-by-design.md) — production security patterns
+  - [Observing](./operating-experts/observing.md) — monitoring and debugging in production
+  - [Skill Management](./operating-experts/skill-management.md) — managing MCP skill dependencies
+  - [Deployment](./operating-experts/deployment.md) — deployment strategies and infrastructure
+
+### Reference
+
+- **References**
+  - [CLI Reference](./references/cli.md) — all commands and options
+  - [perstack.toml Reference](./references/perstack-toml.md) — complete configuration spec
+  - [Providers and Models](./references/providers-and-models.md) — supported LLM providers
+  - [Events](./references/events.md) — runtime event schema
+- **Contributing**
+  - [Roadmap](./contributing/roadmap.md) — what's planned and how to contribute
 
 ## Community