docs: update concept page with architecture diagram and fix broken links (#734)

* docs: update concept page with architecture diagram and fix broken links

- Add 5-layer architecture diagram from README
- Add design philosophy note about existing standards
- Fix 8 broken LinkCard hrefs to point to existing pages
- Remove links to non-existent pages (context-windows, delegations,
  memory, checkpoints, container-isolation, env-vars-secrets)
- Add links to runtime, boundary-model, sandbox-integration,
  and isolation-by-design pages
- Improve LinkCard descriptions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: align concept card sections with architecture diagram layers

- Add Interface layer cards (CLI, runtime embedding, observability)
- Reorder sections to match diagram: Interface → Runtime → Context → Definition → Infrastructure
- Add one-line description per layer
- Add State management, Error handling, Deployment cards
- Rewrite all card descriptions to be specific and concrete

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: FL4TLiN3

docs/understanding-perstack/concept.mdx

@@ -11,40 +11,79 @@ Perstack is built on a concept called **Expert Stack** — the harness that enab
 > [!NOTE]
 > The name "Perstack" combines the Latin word "perītus" (meaning "expert") with "stack". Perstack = Expert Stack.
 
-## Expert Stack 
+## Expert Stack
 
-Perstack organizes the complexity of micro-agents harness design into a simple stack model:
+An agent harness needs a broad set of capabilities — almost like an operating system. Perstack organizes them into a simple stack with clear separation of concerns:
 
-### Definition
+```
+┌──────────────────────────────────────────────────────────────────-┐
+│  Interface                                                        │
+│  CLI · Event streaming · Programmatic API                         │
+├──────────────────────────────────────────────────────────────────-┤
+│  Runtime                                                          │
+│  Agentic loop · Event-sourcing · Checkpointing · Tool use         │
+├──────────────────────────────────────────────────────────────────-┤
+│  Context                                                          │
+│  System prompts · Prompt caching · AgenticRAG · Extended thinking │
+├──────────────────────────────────────────────────────────────────-┤
+│  Definition                                                       │
+│  Multi-agent topology · MCP skills · Provider abstraction         │
+├──────────────────────────────────────────────────────────────────-┤
+│  Infrastructure                                                   │
+│  Sandbox isolation · Workspace boundary · Secret management       │
+└──────────────────────────────────────────────────────────────────-┘
+```
+
+Most of the features above are not new ideas. Perstack takes the usual harness building blocks — tool use, delegation, checkpointing, prompt caching, etc. — makes them easy to operate, puts them on top of standards you already know (MCP, TOML, Docker, SSE), and ships them as one runtime. Where cost or operational burden demands it, Perstack introduces its own take — micro-agents being the first example.
+
+### Interface
+
+The top layer exposes Perstack to users and applications.
 
 <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>
+  <LinkCard title="CLI" href="/docs/references/cli/">Interactive TUI (`start`), headless JSON output (`run`), log inspection, and expert management.</LinkCard>
+  <LinkCard title="@perstack/runtime" href="/docs/guides/adding-ai-to-your-app/">Embed the runtime directly in TypeScript apps for serverless and custom integrations.</LinkCard>
+  <LinkCard title="Observability" href="/docs/operating-experts/observing/">Real-time activity log, token metrics, and delegation tree.</LinkCard>
+</CardGrid>
+
+### Runtime
+
+The execution engine that drives the agentic loop.
+
+<CardGrid>
+  <LinkCard title="Runtime" href="/docs/understanding-perstack/runtime/">9-state machine — generate, call tools, delegate, resolve, and finish.</LinkCard>
+  <LinkCard title="Events" href="/docs/references/events/">Step-level event-sourcing for full execution observability and replay.</LinkCard>
+  <LinkCard title="State management" href="/docs/using-experts/state-management/">Checkpoints, resume, and job hierarchy.</LinkCard>
+  <LinkCard title="Skill management" href="/docs/operating-experts/skill-management/">Dynamic skill lifecycle — connect, discover tools, execute, disconnect.</LinkCard>
 </CardGrid>
 
 ### Context
 
+What each expert sees and knows during execution.
+
 <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>
+  <LinkCard title="Workspace" href="/docs/using-experts/workspace/">The shared filesystem where experts collaborate — not conversation history.</LinkCard>
+  <LinkCard title="Error handling" href="/docs/using-experts/error-handling/">Retries, provider-specific error normalization, and retryability detection.</LinkCard>
 </CardGrid>
 
-### Runtime
+### Definition
+
+How you declare what experts do and how they collaborate.
 
 <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>
+  <LinkCard title="Experts" href="/docs/understanding-perstack/experts/">Purpose-specific micro-agents with a single responsibility.</LinkCard>
+  <LinkCard title="perstack.toml" href="/docs/references/perstack-toml/">Declarative config — experts, skills, providers, and global defaults.</LinkCard>
+  <LinkCard title="Skills" href="/docs/making-experts/skills/">MCP tools — file ops, exec, custom MCP servers.</LinkCard>
+  <LinkCard title="Providers" href="/docs/references/providers-and-models/">LLM providers, models, and model tier selection.</LinkCard>
 </CardGrid>
 
 ### Infrastructure
 
+Isolation and security boundaries that make agents safe to operate.
+
 <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>
+  <LinkCard title="Sandbox integration" href="/docs/understanding-perstack/sandbox-integration/">Container isolation with Docker — multi-arch, non-root, ~74 MB.</LinkCard>
+  <LinkCard title="Boundary model" href="/docs/understanding-perstack/boundary-model/">Workspace boundaries, path validation, and symlink traversal prevention.</LinkCard>
+  <LinkCard title="Isolation by design" href="/docs/operating-experts/isolation-by-design/">Environment sandboxing, secret management, and exec protection.</LinkCard>
+  <LinkCard title="Deployment" href="/docs/operating-experts/deployment/">Container images, `perstack install`, and production deployment patterns.</LinkCard>
 </CardGrid>