docs: editorial pass — writer + developer dual review

GETTING-STARTED.md

@@ -22,7 +22,7 @@ You have been using Claude in a web browser. It works — you ask a question, yo
 
 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.
+This guide builds the thing that fixes it: a workspace where every session picks up exactly where the last one left off.
 
 > *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.*
 
@@ -30,15 +30,19 @@ This guide describes a different model. One where context survives.
 
 ## 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. No single tree holds the full picture. The network does.
+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. When a tree falls, the network remains. New growth connects to it and inherits what came before.
 
-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.
+Any well-run organisation works the same way. There is a mailroom that receives and routes what comes in. A front desk that directs people to the right department. Department heads who make decisions within their scope. An executive team that sets direction. And a managing director who signs off on anything that leaves the building. Nobody freelances outside their role. Every significant decision is written down — not because anyone loves paperwork, but because the organisation needs to function when individuals are absent, replaced, or handling something else. The institutional memory lives in the filing system, not in any one person's head.
 
-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.
+Strip away the people and the furniture and you are left with the underlying structure: defined roles, clear boundaries, a chain of authority, and a written record of every decision. That structure is what makes the organisation work — not the individuals filling the seats on any given day.
 
-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.
+A Git repository maps directly onto that structure. The repo is the office building — it holds the rules, the roles, the active state, and the institutional memory. The AI agents are the staff, each operating within a defined scope, following documented procedures, writing everything back to the shared record when they are done. The human operator is the managing director. Nothing significant happens without their approval. Nothing leaves the building without their sign-off.
 
-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.
+In engineering, this pattern has a name: a **digital twin** — a virtual replica of a real system that stays synchronised with it. NASA coined the concept in the 1960s; it is the reason the Apollo 13 crew came home alive. Today, companies build digital twins of entire operations in software — every process, every role, every decision rule exists as code that can be versioned, audited, and rebuilt from scratch.
+
+The Git repo is that twin. 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 twin and picks up where the last one left off. Nothing lives in chat history. Nothing lives in someone's head.
+
+This architecture also creates a natural boundary for sensitive work. Some of what you do involves passwords, client records, financial spreadsheets, personal notes — material that should not leave your machine. When the hardware supports it, private data can route through a local AI model that never touches the internet, while the cloud API handles the heavy reasoning. The repo holds the structure for both paths, even if you only use one on day one.
 
 ---
 
@@ -74,7 +78,7 @@ Everything below this line gets you from zero to a working system. Five steps, o
 - A laptop or desktop (macOS, Linux, or Windows with WSL2)
 - Docker
 - Git
-- A Claude account (for Claude Code)
+- A Claude account and [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) — Anthropic's command-line coding agent. It runs in a terminal and can read files, write code, and execute commands directly. It is what turns Claude from a chat assistant into a working colleague. Requires a Claude Pro, Max, or API account.
 
 That is it. No server. No GPU. No VPN.
 
@@ -122,9 +126,7 @@ Save the result as `machine-discovery.md` somewhere on your machine (outside the
 
 Now take that discovery report and use it to decide what to build.
 
-> **Use Claude Opus for this step.** Opus reasons more deeply about trade-offs and produces better plans than faster models. It burns more tokens — that is the trade-off. Use it when you are making architectural decisions. Use faster models for day-to-day work once the system is running.
+> **Use Claude Opus for this step** — it reasons more carefully about architectural trade-offs. In Claude Code: `/model claude-opus-4-6`. Switch back with `/model claude-sonnet-4-6` for day-to-day work.
->
-> In Claude Code, switch model with: `/model claude-opus-4-6` or use the `/fast` toggle to switch back when you want speed over depth.
 
 **Paste this into Claude Opus, along with the contents of machine-discovery.md:**
 
@@ -161,7 +163,7 @@ Follow the plan Claude produces. The typical starting baseline:
 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
+5. Set up a devcontainer (a Docker container configured as a full development environment) or Docker Compose file based on the plan Claude produced
 6. Authenticate Claude Code inside the container
 7. Ask Claude to describe the repo structure and confirm it can navigate it
 
@@ -173,7 +175,8 @@ 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)
+        CLAUDE.md           ← project instructions that Claude Code reads on startup
+        LLM-ENTRYPOINT.md   ← (created in Step 4)
     work-rw/                ← Read-write scratch space for agent output
     drop-ro/                ← Read-only input — files you drop in for agents to read
 ```
@@ -182,13 +185,73 @@ The repo is version-controlled. The working folders are not. The container mount
 
 ---
 
-## Step 4 — Orient Claude to the Current Tooling
+## Step 4 — 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:
+
+**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.
+```
+
+---
+
+## Step 5 — Stop Claude From Guessing
 
 Claude's training data has a cutoff date. It does not know about recent releases, breaking API changes, or tools that have emerged in the last year. If you let it write code or configuration from memory, it will confidently use outdated method names, wrong import paths, and deprecated patterns. This is one of the most common sources of wasted time when working with AI agents.
 
 The fix is simple: force Claude to fetch current documentation before writing anything.
 
-**Run this prompt once Claude is up and running in your repo:**
+**Run this prompt in Claude Code** (not the web chat — Claude Code can fetch URLs and write files directly):
 
 ```
 Review the repo structure — read the README and any other docs present.
@@ -218,72 +281,6 @@ Claude will push back on this — it will say it already knows. It does not. Its
 
 ---
 
-## 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.
@@ -296,13 +293,13 @@ Typing long prompts into a terminal is a friction point. Local voice-to-text rem
 
 This is genuinely useful once the system is running. It makes working with Claude feel closer to thinking out loud.
 
-**macOS:** [SuperWhisper](https://superwhisper.com) runs locally via WhisperKit on the Apple Neural Engine. Audio is processed entirely on-device. System-wide hotkey, inserts into any focused app. Setup: open SuperWhisper → Modes → create a new mode → set type to Voice to Text → in the mode settings, change the voice model to **Standard** (the free model — select the highest-quality option that is not padlocked). Built-in Apple Dictation is a zero-setup fallback.
+| Platform | Tool | Notes |
+|---|---|---|
+| **macOS** | [SuperWhisper](https://superwhisper.com) | Runs on-device via Apple Neural Engine. Create a mode, set voice model to **Standard** (free). Built-in Apple Dictation works as a zero-setup fallback. |
+| **Windows** | [OmniDictate](https://github.com/gurjar1/OmniDictate) | Free, open-source, push-to-talk. NVIDIA GPU recommended but CPU works. |
+| **Linux** | [WhisperTux](https://github.com/cjams/whispertux) | Free, open-source, global hotkey, works without a GPU. |
 
-**Windows:** [OmniDictate](https://github.com/gurjar1/OmniDictate) — free, open-source, uses faster-whisper as the backend. Push-to-talk via Right Shift (configurable), types directly into any focused Windows application. NVIDIA GPU with CUDA gives best performance; CPU-only mode works but is slower on larger models. Available as a `.exe` installer from the Releases page. Actively maintained — v2.0 shipped December 2025. Windows SmartScreen will warn on first run (unsigned binary); click through.
+Voice dictation produces transcription artefacts — misheard words, missing punctuation, run-on sentences. Claude handles this well. You do not need to clean up every word before submitting.
-
-**Linux:** [WhisperTux](https://github.com/cjams/whispertux) — free, open-source, uses whisper.cpp as the backend. Global keyboard shortcut for start/stop, auto-injects text into the focused application. Works without a GPU — whisper.cpp runs on plain x86 with AVX. GPU acceleration supported if available. Works on GNOME and KDE. Install via `git clone` + `python3 setup.py` which handles dependencies, model download, and service registration.
-
-One practical note: voice dictation produces transcription artefacts — misheard words, missing punctuation, run-on sentences. Claude handles this well if you prompt it naturally. You do not need to clean up every word before submitting.
 
 ---
 
@@ -349,7 +346,7 @@ Once the baseline is stable, these are natural next layers — each independent,
 | Infrastructure monitoring | Prometheus + Grafana + Alertmanager | Any always-on machine — local to learn, VPS for reliability |
 | Log aggregation | Loki + Grafana Alloy | Any always-on machine |
 | Secure remote access | WireGuard VPN | A VPS |
-| Local AI inference | Ollama + Open WebUI | GPU with adequate VRAM |
+| Local AI inference | Ollama + Open WebUI — route sensitive work (passwords, financials, client data) through a local model that never leaves your machine | GPU with adequate VRAM |
 | Multi-agent workers | Codex + Gemini alongside Claude | Existing workspace |
 | Mobile operator access | Phone → agent pipeline | VPS + additional tooling |
 | Business operations layer | Ticketing, CRM, project management | Depends on scale |