docs: professional README with architecture diagrams

README.md

@@ -1,3 +1,125 @@
-# developing-with-claude
+# Developing with Claude
 
-Getting started with AI-native development workspaces
+> Run AI coding agents safely on your own machine — where the **Git repository is the memory**, not the chat history.
+
+![License](https://img.shields.io/badge/license-CC%20BY%204.0-lightgrey)
+![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue)
+![Status](https://img.shields.io/badge/status-active-brightgreen)
+
+---
+
+## How it works
+
+```mermaid
+flowchart TB
+    subgraph host["  💻  Your Machine  "]
+        secrets["🔑 Secrets & Keys\nnever enter the workspace"]
+        folders["📁 Workspace Folders\nbind-mounted, always persist"]
+    end
+
+    subgraph container["  🐳  Bounded Container — Agents Work Here  "]
+        direction LR
+        claude["Claude\nCode"]
+        codex["Codex\nCLI"]
+        gemini["Gemini\nCLI"]
+    end
+
+    subgraph repo["  📚  Git Repository — The Persistent Memory  "]
+        direction LR
+        rules["Rules &\nBoundaries"]
+        state["System\nState"]
+        tools["Scripts\n& Tools"]
+    end
+
+    folders -->|mounts into| container
+    container <-->|"reads before acting\nwrites when done"| repo
+    secrets -.->|stays here,\nnever shared| host
+```
+
+The container is bounded and disposable. The repository is permanent. Agents read the repo before every session — not the chat history — so context survives restarts, rebuilds, and parallel sessions.
+
+---
+
+## Why this exists
+
+Most AI-assisted development setups have the same failure mode: context lives in chat history. The session ends, the context is gone. The next session starts blind.
+
+This guide describes a different model:
+
+- The **Git repo** is the operating memory — rules, state, decisions, and handoff notes all live in version-controlled Markdown
+- The **Docker container** is a bounded workspace — agents can see what is mounted, not the whole machine
+- **Secrets stay on the host** — never in the repo, never in the container
+- **Production actions stay with the operator** — the container is powerful within its boundary; it does not have unlimited reach
+
+Works on a laptop with no GPU, no VPN, no server. Grows as far as you want to take it.
+
+---
+
+## What's in this guide
+
+| Document | What it covers |
+|---|---|
+| [GETTING-STARTED.md](./GETTING-STARTED.md) | Step-by-step: discover your machine, design your setup, build the baseline, orient Claude to current tooling |
+
+---
+
+## The five-minute version
+
+**1. Discover your machine** — paste the discovery prompt from `GETTING-STARTED.md` into Claude. Get a `machine-discovery.md` report.
+
+**2. Design your setup** — paste the design prompt with your discovery report into Claude Opus. Get a setup plan tailored to your hardware.
+
+**3. Build the baseline** — workspace root, subfolders, Git repo, Docker container, Claude Code authenticated. Nothing more until it works.
+
+**4. Orient Claude** — fetch current Anthropic docs and store them in the repo. Force Claude to read before it writes. Training data is frozen; the docs are not.
+
+**5. Grow deliberately** — add layers only when you have a real reason.
+
+---
+
+## Where it grows
+
+```mermaid
+graph LR
+    A["💻 Laptop\nDocker + Claude Code\n―――――――\nDay 1"]
+    B["☁️ VPS\nForgejo · WireGuard\nPrometheus · Loki\n―――――――\nWhen needed"]
+    C["🏠 Home Server\nLocal AI · Ollama\nOpen WebUI\n―――――――\nWhen justified"]
+    D["📱 Mobile\nRemote operator\naccess\n―――――――\nWhen ready"]
+
+    A -->|stable baseline| B
+    B -->|stable infra| C
+    C -->|stable local AI| D
+```
+
+Each stage is independent. None requires the next. Most of the value is in stage one.
+
+---
+
+## Core principles
+
+**The repo is the memory.**
+Everything important lives in Git. Agents read it before acting. Nothing is lost when a session ends.
+
+**Secrets stay on the host.**
+API keys, SSH keys, tokens — never in the repo, never in the container. Passed in at runtime.
+
+**Production actions stay with the operator.**
+Ansible runs, SSH, DNS changes — your terminal, not the container. You are always the gate.
+
+**Persistence is designed, not assumed.**
+Named Docker volumes for agent auth. A bootstrap script to verify state after rebuilds. Nothing relies on the container surviving.
+
+**Start simple. Grow deliberately.**
+Laptop first. Server when you need one. Local AI when the hardware justifies it.
+
+---
+
+## Getting started
+
+→ **[Read GETTING-STARTED.md](./GETTING-STARTED.md)**
+
+---
+
+## License
+
+[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — use it, adapt it, share it with attribution.