perstack-ai · FL4TLiN3 · Mar 1, 2026 · Mar 1, 2026
diff --git a/README.md b/README.md
@@ -116,9 +116,9 @@ perstack start my-expert "query" --env-path .env.production
 Perstack organizes the complexity of micro-agents harness design into a simple stack model:
 
 - **Definition**: `perstack.toml`, Experts, skills, providers
-- **Context**: Context windows, workspace, delegations, inference budgets
+- **Context**: Context windows, workspace, delegations, memory
 - **Runtime**: Event-sourcing, checkpoints, skill management
-- **Infrastructure**: Container isolation, workspace boundaries, env vars, secrets
+- **Infrastructure**: Container isolation, workspace boundaries, env vars/secrets
 - **Interface**: `perstack` CLI, JSON-event via `@perstack/runtime`
 
 For details, see [Understanding Perstack](https://perstack.ai/docs/understanding-perstack/concept/).

diff --git a/docs/getting-started/walkthrough.md → docs/getting-started/walkthrough.mdx b/docs/getting-started/walkthrough.md → docs/getting-started/walkthrough.mdx
@@ -8,22 +8,60 @@ This walkthrough takes you from zero to production integration.
 
 ## Prerequisites
 
-- [Node.js 22+](https://nodejs.org/)
+- Docker
 - An LLM provider API key (see [Providers and Models](../references/providers-and-models.md))
 
+### Giving API keys
+
+There are two ways to provide API keys:
+
+**1. Pass host environment variables with `-e`**
+
+Export the key on the host and forward it to the container:
+
 ```bash
 export ANTHROPIC_API_KEY=sk-ant-...
+docker run --rm -it \
+  -e ANTHROPIC_API_KEY \
+  -v ./workspace:/workspace \
+  perstack/perstack start my-expert "query"
+```
+
+**2. Store keys in a `.env` file in the workspace**
+
+Create a `.env` file in the workspace directory. Perstack loads `.env` and `.env.local` by default:
+
+```bash
+# ./workspace/.env
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+```bash
+docker run --rm -it \
+  -v ./workspace:/workspace \
+  perstack/perstack start my-expert "query"
+```
+
+You can also specify custom `.env` file paths with `--env-path`:
+
+```bash
+perstack start my-expert "query" --env-path .env.production
 ```
 
 ## Create an Expert
 
 Generate an Expert definition interactively:
 
 ```bash
-npx perstack start create-expert "Create a fitness assistant that delegates to a pro trainer"
+# Ask `create-expert` to form a team named `ai-gaming`
+docker run --pull always --rm -it \
+  -e ANTHROPIC_API_KEY \
+  -v ./ai-gaming:/workspace \
+  perstack/perstack start create-expert \
+    "Form a team named ai-gaming to build a Bun-based CLI cutting-edge indie game playable on Bash."
 ```
 
-`create-expert` is a published Expert on the [Perstack registry](https://perstack.ai/) — no local config file is needed. The CLI resolves it from the registry automatically. It does more than scaffold a file — it:
+`create-expert` is a built-in Expert. It generates a `perstack.toml` that defines a team of micro-agents. Each agent has a single responsibility and its own context window. Complex tasks are broken down and delegated to specialists.
 - generates Expert definitions in `perstack.toml` based on your description
 - tests them against real-world scenarios
 - analyzes execution history and output to evaluate the definitions
@@ -33,37 +71,50 @@ npx perstack start create-expert "Create a fitness assistant that delegates to a
 The result is a `perstack.toml` ready to use:
 
 ```toml
-# perstack.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"]
-
-[experts."pro-trainer"]
-description = "Suggests scientifically-backed training menus"
-instruction = "Provide split routines and HIIT plans tailored to user history."
+[experts."ai-gaming"]
+description = "Game development team lead"
+instruction = "Coordinate the team to build a CLI dungeon crawler."
+delegates = ["@ai-gaming/level-designer", "@ai-gaming/programmer", "@ai-gaming/tester"]
+
+[experts."@ai-gaming/level-designer"]
+description = "Designs dungeon layouts and game mechanics"
+instruction = "Design engaging dungeon levels, enemy encounters, and progression systems."
+
+[experts."@ai-gaming/programmer"]
+description = "Implements the game in TypeScript"
+instruction = "Write the game code using Bun, targeting terminal-based gameplay."
+
+[experts."@ai-gaming/tester"]
+description = "Tests the game and reports bugs"
+instruction = "Play-test the game, find bugs, and verify fixes."
 ```
 
-You can also write `perstack.toml` manually — `perstack start create-expert` is a convenient starting point, not a requirement.
+You can also write `perstack.toml` manually — `create-expert` is a convenient assistant, not necessary.
 
 ## Run Your Expert
 
 ### Interactive mode
 
 ```bash
-npx perstack start fitness-assistant "Start today's session"
+docker run --pull always --rm -it \
+  -e ANTHROPIC_API_KEY \
+  -v ./ai-gaming:/workspace \
+  perstack/perstack start ai-gaming \
+    --model "haiku-4-5" \
+    "Make a Wizardry-like dungeon crawler. Make it replayable, so players can dive in, die, and find a way to beat it."
 ```
 
 `perstack start` opens a text-based UI for developing and testing Experts. You get real-time feedback and can iterate on definitions without deploying anything.
 
 ### Headless mode
 
 ```bash
-npx perstack run fitness-assistant "Start today's session"
+docker run --pull always --rm \
+  -e ANTHROPIC_API_KEY \
+  -v ./ai-gaming:/workspace \
+  perstack/perstack run ai-gaming \
+    --model "haiku-4-5" \
+    "Make a Wizardry-like dungeon crawler. Make it replayable, so players can dive in, die, and find a way to beat it."
 ```
 
 `perstack run` outputs JSON events to stdout — designed for automation and CI pipelines.
@@ -72,10 +123,10 @@ npx perstack run fitness-assistant "Start today's session"
 
 | Aspect | What Perstack Does |
 | --- | --- |
-| **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. |
-| **Isolation** | Each Expert has its own context window. No prompt bloat. |
+| **State** | All Experts share the workspace (`./workspace`), not conversation history. |
+| **Collaboration** | Coordinator(`ai-gaming`) delegates to Delegated Experts(`@ai-gaming/level-designer`, `@ai-gaming/programmer`, `@ai-gaming/tester`) autonomously. |
+| **Observability** | Every step is visible as a structured JSON event. |
+| **Isolation** | Job is executed in sandboxed environment safely. Each Expert has its own context window. |
 
 ## Analyze Execution
 

diff --git a/docs/understanding-perstack/concept.md b/docs/understanding-perstack/concept.md
diff --git a/docs/understanding-perstack/concept.mdx b/docs/understanding-perstack/concept.mdx
@@ -0,0 +1,50 @@
+---
+title: "Concept"
+sidebar:
+  order: 1
+---
+
+import { LinkCard, CardGrid } from '@astrojs/starlight/components';
+
+Perstack is built on a concept called **Expert Stack** — the harness that enables agentic AI to be more reliable and practically useful.
+
+> [!NOTE]
+> The name "Perstack" combines the Latin word "perītus" (meaning "expert") with "stack". Perstack = Expert Stack.
+
+## Expert Stack 
+
+Perstack organizes the complexity of micro-agents harness design into a simple stack model:
+
+### Definition
+
+<CardGrid>
+  <LinkCard title="Experts" href="/understanding-perstack/experts">Purpose-specific micro-agents.</LinkCard>
+  <LinkCard title="Skills" href="/references/skills">MCP tools (file ops, exec, custom MCP servers).</LinkCard>
+  <LinkCard title="Providers" href="/references/providers-and-models">LLM providers and models.</LinkCard>
+  <LinkCard title="perstack.toml" href="/references/perstack-toml">Declarative definition of experts, skills, and providers.</LinkCard>
+</CardGrid>
+
+### Context
+
+<CardGrid>
+  <LinkCard title="Context windows" href="/understanding-perstack/context-windows">The context in which experts operate.</LinkCard>
+  <LinkCard title="Workspace" href="/understanding-perstack/workspace">The shared workspace in which experts operate.</LinkCard>
+  <LinkCard title="Delegations" href="/understanding-perstack/delegations">The delegation of tasks to other experts.</LinkCard>
+  <LinkCard title="Memory" href="/understanding-perstack/memory">The memory of the expert stack.</LinkCard>
+</CardGrid>
+
+### Runtime
+
+<CardGrid>
+  <LinkCard title="Event-sourcing" href="/references/events">The event-sourcing of the expert stack.</LinkCard>
+  <LinkCard title="Checkpoints" href="/references/checkpoints">The checkpoints of the expert stack.</LinkCard>
+  <LinkCard title="Skill management" href="/references/skill-management">The skill management of the expert stack.</LinkCard>
+</CardGrid>
+
+### Infrastructure
+
+<CardGrid>
+  <LinkCard title="Container isolation" href="/understanding-perstack/container-isolation">The container isolation of the expert stack.</LinkCard>
+  <LinkCard title="Workspace boundaries" href="/understanding-perstack/workspace-boundaries">The workspace boundaries of the expert stack.</LinkCard>
+  <LinkCard title="Env vars/secrets" href="/understanding-perstack/env-vars-secrets">The env vars/secrets of the expert stack.</LinkCard>
+</CardGrid>