docs: rewrite — story arc, analogy bridge, two-part structure

GETTING-STARTED.md

@@ -16,19 +16,35 @@ tags:
 
 ---
 
+## The Problem
+
+You have been using Claude in a web browser. It works — you ask a question, you get an answer, you build something together. Then you close the tab. The next time you open it, Claude has no idea what you were working on. Every session starts from zero.
+
+If you have tried anything ambitious — a multi-day project, infrastructure work, a codebase that evolves — you have hit this wall. The context dies with the session. You end up re-explaining your setup, re-describing your architecture, re-pasting the same files. The tool is powerful but it has no memory.
+
+This guide describes a different model. One where context survives.
+
+> *If you already work with Docker, Git, and infrastructure-as-code, you know most of the building blocks here. What is different is the memory model — skip to [Step 1](#step-1--understand-your-machine-first) to start building, or read the next section for why this approach works.*
+
+---
+
 ## The Idea
 
-In a healthy forest, trees are not isolated. Beneath the soil runs a mycelium network — a living mesh that stores signals, routes nutrients, and lets organisms share information without any single node holding everything.
+In a healthy forest, trees are not isolated. Beneath the soil runs a mycelium network — a living mesh that stores signals, routes nutrients, and lets organisms share information without any single node holding everything. No single tree holds the full picture. The network does.
 
-AgentLab works on the same principle. The **Git repository** is the mycelium: the persistent, shared memory that every agent reads before acting and writes back to when done. No agent keeps private state. No chat transcript is the source of truth. The repo is.
+Now think about how a company works. There is a mailroom that receives and routes incoming material. There is a reception desk that directs visitors to the right department. Department heads make decisions within their scope. An executive team sets direction. And a managing director signs off on anything that leaves the building. Every person has a defined role, a clear boundary, and a reporting line. Nobody freelances outside their area. Every significant decision is logged.
 
-Everything else — the container, the tools, the infrastructure — grows from that root.
+This is the same structure. The Git repository is the office building — it holds the rules, the roles, the decisions, and the institutional memory. The AI agents are the staff — each one has a defined scope, works within boundaries, and writes everything back to the shared record. The human operator is the managing director — nothing leaves the building without their sign-off.
+
+This is not just a metaphor. In engineering, it is called a **digital twin** — a virtual replica of a real-world system that stays synchronised with it. NASA built physical twins of spacecraft in the 1960s so engineers could simulate problems from the ground before they became emergencies in orbit. Today, companies build digital twins of their entire operations in software — every process, every role, every decision rule exists as code that can be versioned, tested, and rebuilt from scratch.
+
+That is what the Git repo is. It is the digital twin of your development operation. When something changes — a new tool is added, a decision is made, a process is refined — it is written into the repo. When a new session starts, the agent reads the repo and picks up exactly where the last one left off. Nothing lives in chat history. Nothing lives in someone's head. The repo is the single source of truth, and everything else grows from it.
 
 ---
 
 ## Core Principles
 
-These are the design decisions that make the system safe and portable. Understanding them matters more than any specific tool choice.
+These are the design decisions that make the system safe and portable.
 
 **1. The repo is the memory.**
 Instructions, state, decisions, plans, and handoff notes all live in Git. Agents read the repo before starting work. If a session ends and a new one begins, nothing is lost — it is all in the repo.
@@ -47,6 +63,12 @@ The baseline is a laptop and a repo. Everything else — a VPS, a home server, l
 
 ---
 
+# Part 1 — Get Running
+
+Everything below this line gets you from zero to a working system. Five steps, one afternoon.
+
+---
+
 ## What You Actually Need to Start
 
 - A laptop or desktop (macOS, Linux, or Windows with WSL2)
@@ -62,14 +84,15 @@ That is it. No server. No GPU. No VPN.
 
 Before setting anything up, run hardware and environment discovery. This tells you what your machine can actually do and which setup path makes sense.
 
-**Paste this into Claude:**
+**Paste this into Claude.** Steps 1 and 2 work in any Claude interface — the web chat at claude.ai, the Claude desktop app, or Claude Code if you already have it. Claude Code is set up later in Step 3.
 
 ```
 You are a workstation discovery agent.
 
 Your job is to discover the real machine state before any architecture decisions are made.
 
-You cannot run commands yourself. You must give me the commands to run, and I will paste the output back.
+If you have access to a terminal (e.g. Claude Code), run the commands directly.
+Otherwise, give me the commands to run and I will paste the output back.
 
 First ask me which OS I am using: macOS, Linux, or Windows.
 Then give me only the commands for that OS.
@@ -135,7 +158,7 @@ Machine discovery report:
 Follow the plan Claude produces. The typical starting baseline:
 
 1. Create a workspace root folder (e.g. `~/AgentLab/` on Mac/Linux, `C:\AgentLab\` on Windows)
-2. Create subfolders: `your-repo/`, `work-rw/`, `drop-ro/`
+2. Create subfolders: `your-repo/` (the Git repo), `work-rw/` (read-write scratch space for agent output), `drop-ro/` (read-only input — files you drop in for agents to read)
 3. Initialise a Git repo inside `your-repo/` and create a `README.md`
 4. Install Docker if not already present
 5. Set up a devcontainer or Docker Compose file based on the plan Claude produced
@@ -144,6 +167,19 @@ Follow the plan Claude produces. The typical starting baseline:
 
 Do not add more until this works cleanly.
 
+When it is working, your workspace should look like this:
+
+```
+~/AgentLab/
+    your-repo/          ← Git repo — the persistent memory
+        README.md
+        CLAUDE.md       ← (created later, Step 5)
+    work-rw/            ← Read-write scratch space for agent output
+    drop-ro/            ← Read-only input — files you drop in for agents to read
+```
+
+The repo is version-controlled. The working folders are not. The container mounts all three and can read or write as appropriate.
+
 ---
 
 ## Step 4 — Orient Claude to the Current Tooling
@@ -182,7 +218,79 @@ Claude will push back on this — it will say it already knows. It does not. Its
 
 ---
 
-## Optional — Voice Input
+## Step 5 — Build the Foundation Documents
+
+The repo is the memory — but right now it is empty. These prompts tell Claude to build the documents that make the system work across sessions. Use the scaffold prompt to create all four at once, or the individual prompts to take it one document at a time.
+
+**Scaffold the full foundation in one pass:**
+```
+I have a new Git repo for AI-assisted development. I need you to create the
+following foundation documents, asking me questions before writing each one:
+
+1. README.md — what this repo is, current state, key links
+2. ENTRYPOINT.md — agent session startup, read order, execution boundaries
+3. AGENTS.md — what agents can and cannot do, branch model
+4. docs/open-loops.md — persistent backlog of unresolved items
+
+For each document: ask me the questions you need answered, write a first draft,
+show it to me, and wait for approval before moving to the next one.
+```
+
+Or build them individually:
+
+<details>
+<summary>Create your session entrypoint document</summary>
+
+```
+I am setting up a Git repo as a control plane for AI-assisted development.
+
+Create an ENTRYPOINT.md for this repo that:
+- Lists the key documents an AI agent should read before starting work
+- States what this repo is and what it is for
+- States the execution boundaries (what runs in the container vs what runs on the host)
+- States where secrets are kept and that they must never enter the repo
+
+Ask me questions about my setup before writing anything.
+```
+</details>
+
+<details>
+<summary>Create your agent operating contract</summary>
+
+```
+Create an AGENTS.md for this repo that defines:
+- What AI agents are permitted to do autonomously
+- What requires explicit human approval before proceeding
+- The Git branch model (who works on which branch)
+- What agents must never do (commit secrets, push to main directly, etc.)
+
+Ask me about my setup and which agents I am using before writing anything.
+```
+</details>
+
+<details>
+<summary>Create your open loops document</summary>
+
+```
+Create a docs/open-loops.md for this repo.
+
+This file tracks unresolved items across sessions — things that are in progress,
+decisions that have not been made, or work that is blocked. It should be read at
+the start of every session so nothing falls through the cracks between conversations.
+
+Start it with the current open items from our conversation so far.
+```
+</details>
+
+---
+
+# Part 2 — Make It Better
+
+The baseline is running. Everything below this line makes it more effective. None of it is required. Pick what is useful to you.
+
+---
+
+## Voice Input
 
 Typing long prompts into a terminal is a friction point. Local voice-to-text removes it. Audio is transcribed on your machine and inserted as text into whatever is focused — your terminal, your editor, Claude Code — without going to a cloud transcription API.
 
@@ -223,6 +331,9 @@ For the AgentLab workspace specifically, Restic pointed at your `~/AgentLab/` fo
 **Linux:**
 Snapshot tooling varies by filesystem. ZFS and Btrfs both support snapshots natively. For a simple backup-to-remote, Restic works the same as on Mac. If you are running the workspace on a standard ext4 filesystem, use rsync or Restic to an external drive or remote target.
 
+**Windows (WSL2):**
+Your workspace lives inside the WSL2 filesystem. Windows File History does not see WSL paths by default. Two options: use Restic inside WSL pointed at an external drive or cloud target, or copy the workspace to a Windows-native path (`\\wsl$\Ubuntu\home\...`) and include it in File History. The WSL approach is simpler and avoids permission mismatches.
+
 **Before any important session:**
 Take a quick backup — or at minimum ensure Time Machine or your snapshot tool has run recently. Container rebuilds are safe; host-side data loss is not recoverable from a Dockerfile.
 
@@ -286,7 +397,9 @@ It recommended from training data without verifying current status. Ask it to ch
 
 ---
 
-## Prompts to Use Once You Are Running
+## Prompts for Day-to-Day Work
+
+Once the foundation is built, these prompts are useful starting points for daily sessions.
 
 **Review what is open and decide what to do next:**
 ```
@@ -309,58 +422,3 @@ Review any agent configuration and rules in this repo.
 Explain how the agents are expected to collaborate — what each one does,
 how they hand off work, and what prevents them from conflicting.
 ```
-
----
-
-## Bootstrap Your Repo with Claude
-
-Once the baseline is running, use these prompts to build the foundation documents. Each one is a single conversation — paste the prompt, answer Claude's questions, and commit the result.
-
-**Create your session entrypoint document:**
-```
-I am setting up a Git repo as a control plane for AI-assisted development.
-
-Create an ENTRYPOINT.md for this repo that:
-- Lists the key documents an AI agent should read before starting work
-- States what this repo is and what it is for
-- States the execution boundaries (what runs in the container vs what runs on the host)
-- States where secrets are kept and that they must never enter the repo
-
-Ask me questions about my setup before writing anything.
-```
-
-**Create your agent operating contract:**
-```
-Create an AGENTS.md for this repo that defines:
-- What AI agents are permitted to do autonomously
-- What requires explicit human approval before proceeding
-- The Git branch model (who works on which branch)
-- What agents must never do (commit secrets, push to main directly, etc.)
-
-Ask me about my setup and which agents I am using before writing anything.
-```
-
-**Create your open loops document:**
-```
-Create a docs/open-loops.md for this repo.
-
-This file tracks unresolved items across sessions — things that are in progress,
-decisions that have not been made, or work that is blocked. It should be read at
-the start of every session so nothing falls through the cracks between conversations.
-
-Start it with the current open items from our conversation so far.
-```
-
-**Scaffold the full foundation in one pass:**
-```
-I have a new Git repo for AI-assisted development. I need you to create the
-following foundation documents, asking me questions before writing each one:
-
-1. README.md — what this repo is, current state, key links
-2. ENTRYPOINT.md — agent session startup, read order, execution boundaries
-3. AGENTS.md — what agents can and cannot do, branch model
-4. docs/open-loops.md — persistent backlog of unresolved items
-
-For each document: ask me the questions you need answered, write a first draft,
-show it to me, and wait for approval before moving to the next one.
-```