docs: fix links and add reference pages

README.md

@@ -9,7 +9,7 @@
 
 <p align="center">
   <a href="https://perstack.ai/docs/"><strong>Docs</strong></a> ·
-  <a href="https://perstack.ai/docs/getting-started/"><strong>Getting Started</strong></a> ·
+  <a href="https://perstack.ai/docs/getting-started/walkthrough/"><strong>Getting Started</strong></a> ·
   <a href="https://github.com/perstack-ai/demo-catalog"><strong>Demo Catalog</strong></a> ·
   <a href="https://discord.gg/2xZzrxC9"><strong>Discord</strong></a> ·
   <a href="https://x.com/FL4T_LiN3"><strong>X</strong></a>
@@ -287,14 +287,17 @@ Perstack ships a five-layer stack that gives micro-agents everything they need t
 
 | Topic | Link |
 | :--- | :--- |
-| Getting started | [Getting Started](https://perstack.ai/docs/getting-started/) |
+| Getting started | [Getting Started](https://perstack.ai/docs/getting-started/walkthrough/) |
 | Architecture and core concepts | [Understanding Perstack](https://perstack.ai/docs/understanding-perstack/concept/) |
-| Expert definitions | [Making Experts](https://perstack.ai/docs/making-experts/) |
-| Rapid prototyping | [Rapid Prototyping Guide](https://perstack.ai/guides/rapid-prototyping/) |
-| Breaking agents into specialists | [Taming Prompt Sprawl](https://perstack.ai/guides/taming-prompt-sprawl/) |
-| Adding tools via MCP | [Extending with Tools](https://perstack.ai/guides/extending-with-tools/) |
+| Skills | [Skills](https://perstack.ai/docs/making-experts/skills/) |
+| Base skill (built-in tools) | [Base Skill](https://perstack.ai/docs/making-experts/base-skill/) |
+| Adding tools via MCP | [Extending with Tools](https://perstack.ai/docs/guides/extending-with-tools/) |
 | Deployment | [Deployment](https://perstack.ai/docs/operating-experts/deployment/) |
-| CLI and API reference | [References](https://perstack.ai/docs/references/cli/) |
+| Providers and models | [Providers and Models](https://perstack.ai/docs/references/providers-and-models/) |
+| CLI reference | [CLI Reference](https://perstack.ai/docs/references/cli/) |
+| `perstack.toml` reference | [perstack.toml Reference](https://perstack.ai/docs/references/perstack-toml/) |
+| Events reference | [Events Reference](https://perstack.ai/docs/references/events/) |
+| API reference | [API Reference](https://perstack.ai/api/v1/spec) |
 
 ## Demo
 

docs/getting-started/walkthrough.mdx

@@ -237,8 +237,8 @@ The CLI is for prototyping. The runtime API is for production. Both use the same
 ## What's next
 
 **Build more:**
-- [Making Experts](../making-experts/best-practices.md) — full `perstack.toml` guide
-- [Skills](../making-experts/skills.md) — MCP integration patterns
+- [Skills](../making-experts/skills.md) — MCP tool integration and skill configuration
+- [Base Skill](../making-experts/base-skill.md) — built-in tools available to all experts
 - [Taming Prompt Sprawl](../guides/taming-prompt-sprawl.md) — break monolithic prompts into collaborating experts
 
 **Understand the architecture:**

docs/guides/rapid-prototyping.md

@@ -14,7 +14,7 @@ This is backwards.
 
 This matters because the agent will keep evolving. Prompts change, capabilities expand, behavior gets refined. If the agent is tangled with your application code, every change risks breaking something unrelated. Keep the brain separate from the body, and both can evolve on their own terms.
 
-This guide uses [Perstack](https://perstack.ai) — a toolkit for agent-first development. In Perstack, agents are called **Experts**: modular micro-agents defined in plain text (`perstack.toml`), executed by a runtime that handles model access, tool orchestration, and state management. Perstack supports multiple LLM providers including Anthropic, OpenAI, and Google. You define what the agent should do; the runtime makes it work.
+This guide uses [Perstack](https://perstack.ai) — a containerized harness for agentic apps. In Perstack, agents are called **Experts**: purpose-specific micro-agents defined in TOML (`perstack.toml`), executed by a runtime that handles model access, tool orchestration, and state management. Perstack supports multiple LLM providers including Anthropic, OpenAI, Google, Fireworks, and more. You define what the agent should do; the runtime makes it work.
 
 > [!NOTE]
 > **Prerequisites:** Node.js 22+ and an LLM API key.
@@ -130,5 +130,5 @@ At some point, your prototype will need more. The same `perstack.toml` scales 
 
 ## What's next
 
-- [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
+- [Skills](../making-experts/skills.md) — MCP tool integration and skill configuration
+- [Base Skill](../making-experts/base-skill.md) — Built-in tools available to all experts

docs/index.mdx

@@ -24,7 +24,8 @@ Perstack draws clear boundaries — between your app and the harness, between th
 
 ### Build
 
-- [**Making Experts**](/docs/making-experts/best-practices/) — defining experts with skills, delegation, testing, and best practices
+- [**Skills**](/docs/making-experts/skills/) — MCP tool integration and skill configuration
+- [**Base Skill**](/docs/making-experts/base-skill/) — built-in tools available to all experts
 - [**Guides**](/docs/guides/rapid-prototyping/) — task-oriented walkthroughs from rapid prototyping to production deployment
 
 ### Operate