docs: root README + Architecture accuracy pass (ai-autopilot framework + connectors family)

Architecture.md

@@ -114,15 +114,27 @@ Largely greenfield: it builds the registry + loader + runtime around the existin
 
 Follow-up authoring options (low priority, revisit on demand): TS-first `defineSkill` (#11), a skill-scoped `skillTool()` wrapper (#12), and imperative `agent.use(skill)` runtime composition (#13). Still gated on family alignment before code lands.
 
-## `ai-autopilot` design (direction set, parked - see [issue #9](https://github.com/gemstack-land/gemstack/issues/9))
+## `ai-autopilot` design (shipped - see [issue #9](https://github.com/gemstack-land/gemstack/issues/9))
 
-The most speculative of the family, so this records direction, not a committed API. It sits above the real `ai-sdk` primitives (`asTool`, `resumeAsTool`, `resumeManyAsTool`, `SubAgentRunStore`, stop conditions).
+Began as the most speculative of the family (a Supervisor seed) and grew into the AI-building framework. It sits above the real `ai-sdk` primitives (`asTool`, `resumeAsTool`, `resumeManyAsTool`, `SubAgentRunStore`, stop conditions).
+
+The enduring design rule:
 
 - **Scope = policy, not mechanism.** The primitives are mechanism (transfer control, run a subagent, resume a paused run); autopilot is the reusable control loop deciding which agents run, in what order, how results combine, when to stop, under a budget/guardrail. Enforced rule: if a feature is just calling a primitive, it stays in `ai-sdk`; `ai-autopilot` only earns its keep as the topology / control-policy / run-lifecycle layer.
-- **Seed slice = Supervisor:** plan -> dispatch subagents (fan-out via `asTool` / `resumeManyAsTool`) -> synthesize. The smallest thing clearly more than the primitives; a universally useful topology. Other topologies (pipelines, etc.) come later, on demand.
-- **Durability = in-process first.** Reuse the existing `SubAgentRunStore` + resume primitives for pause/resume; no new peer dep in v1. A durable / queue-backed runner is deferred to a concrete long-running use case and should arrive as an optional adapter/peer, not core.
 
-Stays parked as a design sketch: revisit once `ai-mcp` and `ai-skills` land and real orchestration use cases emerge. Gated on family alignment before code lands.
+What shipped, built up from that seed (the state layer + the loop are the moat, not the prompts):
+
+- **Supervisor** — the seed topology: plan -> dispatch subagents (bounded concurrency + token budget + per-subtask isolation) -> synthesize.
+- **Personas** — reusable, stack-aware roles materialized into worker agents; **presets** (Vike flagship, Next.js) select the framework-specific ones by detecting the project's framework, on top of a framework-neutral core.
+- **Runner** — a pluggable sandbox seam (`FakeRunner` + a real `LocalRunner`; Docker/WebContainer/Flue are infra-gated adapters) where agents build and run an app.
+- **Surfaces** — the same run in a terminal, an in-page UI, or a detached background handle, over one replayable event stream.
+- **Decisions ledger** — durable memory of rejected ideas + settled choices (round-trips `DECISIONS.md`) so a run stops re-pitching what was turned down.
+- **The loop** — an event-to-prompt-chain policy (a major change fires review + code-quality + security; a new UI flow fires QA + UX), gating on a `{ blockers }` verdict, with a data-driven **prompt library**.
+- **Bootstrap** — the spine that sequences the above into scope -> architect -> build -> full-fledged loop -> deploy, taking an app from nothing to production-grade.
+- **Scale mode** — a self-maintaining `CODE-OVERVIEW.md`, refreshed only on material change.
+- **Durability = in-process first.** Reuses `SubAgentRunStore` + resume primitives for pause/resume; a durable/queue-backed runner arrives as an optional adapter, not core.
+
+The whole flow is demonstrated offline (no API key) in [`examples/bootstrap-quickstart`](./examples/bootstrap-quickstart); live end-to-end verification against a real model + `LocalRunner` is the infra-gated remainder.
 
 ## Ship order (all shipped)
 

README.md

@@ -16,7 +16,7 @@ Full documentation lives in [`docs/`](./docs/guide/index.md) (a hosted site is o
 |---|---|---|---|
 | [`ai‑sdk`](./packages/ai-sdk) | The agent runtime: providers, the agent loop, tools, streaming, middleware, structured output, memory, and evals. The engine the rest of the AI family builds on. | [Guide](./docs/packages/ai-sdk/index.md) | [![npm](https://img.shields.io/npm/v/@gemstack/ai-sdk)](https://www.npmjs.com/package/@gemstack/ai-sdk) |
 | [`ai‑skills`](./packages/ai-skills) | Portable capability bundles: load `SKILL.md` skills (instructions + tools + resources) and compose them onto an agent on demand. | [Guide](./docs/packages/ai-skills.md) | [![npm](https://img.shields.io/npm/v/@gemstack/ai-skills)](https://www.npmjs.com/package/@gemstack/ai-skills) |
-| [`ai‑autopilot`](./packages/ai-autopilot) | Orchestration: a Supervisor that plans, dispatches subagents (bounded concurrency + budget guardrails), and synthesizes the result. | [Guide](./docs/packages/ai-autopilot.md) | [![npm](https://img.shields.io/npm/v/@gemstack/ai-autopilot)](https://www.npmjs.com/package/@gemstack/ai-autopilot) |
+| [`ai‑autopilot`](./packages/ai-autopilot) | The AI‑building framework: a Supervisor (plan → dispatch → synthesize) plus stack‑aware personas, a runner sandbox, surfaces, a decisions ledger, an event‑triggered review/QA loop with a built‑in prompt library, framework presets (Vike/Next), and a bootstrap flow that takes an app from nothing to production‑grade. | [Guide](./docs/packages/ai-autopilot.md) | [![npm](https://img.shields.io/npm/v/@gemstack/ai-autopilot)](https://www.npmjs.com/package/@gemstack/ai-autopilot) |
 | [`ai‑mcp`](./packages/ai-mcp) | The agent/MCP bridge: consume a remote MCP server's tools as agent tools, and expose an agent as an MCP server. | [Guide](./docs/packages/ai-mcp.md) | [![npm](https://img.shields.io/npm/v/@gemstack/ai-mcp)](https://www.npmjs.com/package/@gemstack/ai-mcp) |
 | [`mcp`](./packages/mcp) | A standalone framework for *authoring* MCP servers: tools, resources, prompts, decorators, OAuth 2.1, a framework-neutral HTTP handler, and a test client. Agent-agnostic. | [Guide](./docs/packages/mcp.md) | [![npm](https://img.shields.io/npm/v/@gemstack/mcp)](https://www.npmjs.com/package/@gemstack/mcp) |
 
@@ -53,7 +53,7 @@ pnpm typecheck
 pnpm test
 ```
 
-This is a pnpm + Turborepo + Changesets monorepo. Runnable examples live under [`examples/`](./examples) (e.g. [`examples/mcp-quickstart`](./examples/mcp-quickstart)). See [`.changeset/README.md`](./.changeset/README.md) for the release flow.
+This is a pnpm + Turborepo + Changesets monorepo. Runnable examples live under [`examples/`](./examples) — e.g. [`mcp-quickstart`](./examples/mcp-quickstart), [`autopilot-quickstart`](./examples/autopilot-quickstart) (personas + Supervisor + runner + surfaces), and [`bootstrap-quickstart`](./examples/bootstrap-quickstart) (the whole bootstrap flow, offline). See [`.changeset/README.md`](./.changeset/README.md) for the release flow.
 
 ## Origin
 

docs/packages/ai-autopilot.md

@@ -8,6 +8,20 @@ Orchestration for [`@gemstack/ai-sdk`](/packages/ai-sdk/) agents: the "director"
 pnpm add @gemstack/ai-autopilot @gemstack/ai-sdk
 ```
 
+## The framework layers
+
+The Supervisor (below) is the seed topology. Built up from it, the package is a full framework for building software with agents — the state layer and the loop are the moat, not the prompts:
+
+- **Personas + presets** — reusable, stack-aware roles materialized into worker agents; `presetPersonas` selects the framework-specific ones (Vike flagship, Next.js) by detecting the project's framework, on top of a framework-neutral core.
+- **Runner** — a pluggable sandbox seam (`FakeRunner` + a real `LocalRunner`) where agents build and run an app; expose it to an agent with `runnerTools`.
+- **Surfaces** — the same run in a terminal, an in-page UI, or a detached background handle, over one replayable event stream (`launchAutopilot`).
+- **Decisions ledger** — durable memory of rejected ideas + settled choices (round-trips `DECISIONS.md`) so a run stops re-pitching what was turned down.
+- **The loop** — an event-to-prompt-chain policy (a major change fires review + code-quality + security; a new UI flow fires QA + UX), gating on a `{ blockers }` verdict, with a data-driven built-in **prompt library**.
+- **Bootstrap** — the spine that sequences all of the above into scope → architect → build → full-fledged loop → deploy, taking an app from nothing to production-grade.
+- **Scale mode** — a self-maintaining `CODE-OVERVIEW.md`, refreshed only on material change.
+
+See [`examples/bootstrap-quickstart`](https://github.com/gemstack-land/gemstack/tree/main/examples/bootstrap-quickstart) for all of it wired together offline.
+
 ## Supervisor (plan, dispatch, synthesize)
 
 The supervisor/worker topology is the first orchestration shape this package ships:
@@ -77,7 +91,7 @@ Progress is reported through `onEvent` as typed `SupervisorEvent`s (`plan`, `pla
 
 ## Scope (what's deferred)
 
-The supervisor dispatches **autonomous** workers via `agent.prompt()`. A worker that pauses for a client-tool or approval round-trip is reported as a failed subtask. Durable pause/resume across a supervised run (building on `ai-sdk`'s `SubAgentRunStore` and resume primitives) is a deferred adapter, as are other topologies (pipelines, debate) and queue-backed long-running execution. Those land on demand, behind optional seams, not in the core.
+The supervisor dispatches **autonomous** workers via `agent.prompt()`. A worker that pauses for a client-tool or approval round-trip is reported as a failed subtask. Durable pause/resume across a supervised run (building on `ai-sdk`'s `SubAgentRunStore` and resume primitives) is a deferred adapter, as are other topologies (pipelines, debate). Real sandboxed runner adapters (Docker / WebContainer / Flue) and live end-to-end bootstrap verification are infra-gated — the framework verifies offline against `FakeRunner` + a scripted model. Those land behind optional seams, not in the core.
 
 ## See also