@adia-ai/adia-ui-forge 0.1.2 → 0.1.3

package/skills/adia-ui-ops/references/deploy-playbooks.md

@@ -0,0 +1,259 @@
+# Deploy playbooks — exe.dev VM operations
+
+> **Owner: `adia-ui-ops` modes 1-4** (cold-start triage entry).
+> Absorbed verbatim from the retired standalone `exe-dev-ops` skill (v1.0.0,
+> 2026-05-22). Authored content untouched; only the framing wrapper changed.
+
+Operational playbook for services on **exe.dev** — shared Linux VMs reached via
+`ssh <host>.exe.xyz`. This reference captures the platform contract (which
+isn't obvious from docs), the standard layout we use across services, and the
+two-three commands that solve 90% of day-to-day tasks.
+
+## When to use
+
+- Deploying a new static site or API to a fresh exe.dev VM.
+- Updating an existing deployed site (push new `dist/`).
+- Rotating API keys or other secrets on the VM.
+- Diagnosing a down service — seeing the **"Port 8000 unbound."** error page, 502s, or failed health checks.
+- Adding a new systemd service / Caddy site to a VM already in service.
+
+## When NOT to use
+
+- DNS config — exe.dev owns `<host>.exe.xyz` subdomains; nothing to do locally.
+- TLS — the exe.dev front-door terminates HTTPS. Never bind :443 on the VM.
+- Multi-VM orchestration / auto-scaling — out of scope, single VM per service.
+- Anything requiring root on the host kernel — these are shared VMs, not full boxes.
+
+## Platform contract (the non-obvious bits)
+
+These facts are easy to get wrong because the docs are thin — we learned them the hard way.
+
+- **Your app must bind `:8000`** (plain HTTP). The exe.dev edge proxy terminates TLS on `<host>.exe.xyz` and forwards to VM `:8000`. If nothing is listening, exe.dev serves:
+
+  > **Port 8000 unbound.** `ssh <host>.exe.xyz sudo systemctl enable --now nginx`
+  >
+  > (The nginx suggestion is just their canonical example — Caddy, Node, anything that binds :8000 works.)
+
+- **Default VM user: `exedev`** — uid 1000, member of `sudo` and `docker`. Use this for service processes; don't create a dedicated service user unless you have a real isolation requirement.
+- **What's preinstalled:** `git`, `rsync`, `docker`. **Not preinstalled:** `caddy`, `node`, `npm`, `nginx`. Use apt + NodeSource for node.
+- **`127.0.0.1:9999` runs `shelley`** — exe.dev's internal agent. Localhost-only. Don't kill it, don't bind anything to 9999.
+- **Disk:** 25 GB on `/`; no separate `/srv` mount. Fits a typical static bundle + node modules comfortably.
+- **Host SSH key:** currently RSA-2048 only on new VMs (as of 2026-04). Verify the fingerprint in the exe.dev console on first connect; then `ssh-keyscan >> ~/.ssh/known_hosts`.
+
+## Standard layout (convention we use)
+
+| Path                          | Purpose                                         | Owner             |
+| ----------------------------- | ----------------------------------------------- | ----------------- |
+| `/srv/<app>/dist/`            | Static bundle served by Caddy                   | `exedev:exedev`   |
+| `/srv/<app>/server.js`        | Optional runtime (e.g. API proxy)               | `exedev:exedev`   |
+| `/etc/caddy/Caddyfile`        | Single-site; binds `:8000`                      | `root:root`       |
+| `/etc/systemd/system/<app>.service` | systemd unit for server.js               | `root:root`       |
+| `/etc/<app>.env`              | Secrets loaded via `EnvironmentFile=`           | `root:root` 0600  |
+
+**Never** put secrets in `/srv/<app>/` — that's the webroot.
+
+## Playbook: fresh provisioning
+
+```sh
+# 1. SSH in; verify host key first via exe.dev console.
+ssh <host>.exe.xyz
+
+# 2. Install runtime.
+sudo apt-get update -qq
+sudo apt-get install -y caddy
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# 3. Filesystem.
+sudo mkdir -p /srv/<app>
+sudo chown exedev:exedev /srv/<app>
+```
+
+Then from your **local** machine:
+
+```sh
+# 4. Push artifacts.
+rsync -az --delete dist/ <host>.exe.xyz:/srv/<app>/dist/
+rsync -a server.js <host>.exe.xyz:/srv/<app>/server.js   # if applicable
+
+# 5. Push Caddyfile + systemd unit.
+scp deploy/Caddyfile <host>.exe.xyz:/tmp/
+scp deploy/<app>.service <host>.exe.xyz:/tmp/
+```
+
+Back on the VM:
+
+```sh
+# 6. Activate Caddy.
+sudo mv /etc/caddy/Caddyfile /etc/caddy/Caddyfile.default.bak
+sudo mv /tmp/Caddyfile /etc/caddy/Caddyfile
+sudo systemctl reload caddy
+
+# 7. Activate service.
+sudo mv /tmp/<app>.service /etc/systemd/system/<app>.service
+sudo systemctl daemon-reload
+sudo systemctl enable --now <app>
+
+# 8. Seed secrets — do this by hand; never via agent transcript.
+sudo install -m 0600 -o root -g root /dev/null /etc/<app>.env
+sudo vim /etc/<app>.env
+sudo systemctl restart <app>
+```
+
+## Playbook: deploy an update
+
+Single command from the repo root once `npm run deploy:site` is wired:
+
+```sh
+npm run deploy:site
+```
+
+Under the hood: `npm run build:site && rsync -az --delete dist/ <host>.exe.xyz:/srv/<app>/dist/`. Caddy picks up static changes without a reload.
+
+> ⚠️ **`deploy:site` is a `--delete` deploy — treat it as destructive.** `build:site`
+> is **manual** (not wired into the npm release pipeline), so `dist/` silently drifts
+> behind `main` until someone runs it, and the rsync **deletes** everything on the
+> server that isn't in the fresh `dist/`. A real ui-kit run (2026-06-08) sent ~160 real
+> content deltas and **deleted 3,572 files**. Never fire it blind — the sequence below
+> is the contract for any `--delete` site deploy.
+
+### Hardened `--delete` deploy sequence
+
+1. **Build from a clean, fully-merged `main`** — never a feature branch. `dist/` ships
+   verbatim; whatever's missing on the server gets deleted.
+   - **In a FRESH worktree, build `@adia-ai/llm` FIRST:**
+     ```sh
+     npm run build -w @adia-ai/llm   # BEFORE build:site
+     ```
+     The `llm` package **compiles its JS at publish time** and its outputs are
+     **gitignored** — so a fresh worktree (or any tree that hasn't published llm
+     locally) has no `packages/llm/index.js`, `build:site` copies nothing, and
+     **`/packages/llm/index.js` 404s on the deployed site → component registration
+     breaks on every `/site/components/*` page** (the docs components reference it). Found
+     **live 2026-06-09**; the **0-delete dry-run proved it had never been deployed** (the
+     file was absent on the server, so there was nothing to delete — not a regression, a
+     standing gap across every prior deploy). Build llm, then `build:site`, then the
+     dry-run.
+2. **Dry-run first, and adjudicate every delete:**
+   ```sh
+   rsync -azni --delete dist/ <host>.exe.xyz:/srv/<app>/dist/   # -n simulates · -i itemizes
+   ```
+   - `*deleting` lines = files removed from prod. Bucket **every one** into a known-safe
+     class; **abort if any served-content delete is unexplained.** Safe classes seen on
+     ui-kit: gallery review artifacts (`apps/genui/.../review/cycle-*/`), stale
+     `packages/a2ui/retrieval/` + eval reports, **content-hash-rotated** CodeMirror
+     chunks (`code/{chunk,dist}-<hash>.js` — old hash deleted, new hash sent = rotation,
+     not loss), restructured `packages/llm/*.js` dist copies, `node_modules/`
+     symlink-farm dirs, and refactor-orphaned app files. None are served HTML.
+   - **Don't panic at the send count.** A fresh local build never mtime-aligns with the
+     remote, so `rsync -a` flags ~every file as a send (`<f..t` = mtime-only touch). Only
+     `<f+++` (new) and `<f.s.` / `<fcst` (content) are real deltas — the 2026-06-08 run
+     itemized 12,540 "sends" of which only ~160 carried real content.
+3. **Snapshot prod FIRST — the only safety net for `--delete`:**
+   ```sh
+   ssh <host>.exe.xyz 'cp -al /srv/<app>/dist /srv/<app>/dist.bak-<date>'   # hardlink: instant, reversible
+   ssh <host>.exe.xyz 'find /srv/<app>/dist.bak-<date> -type f | wc -l'     # confirm it materialized
+   ```
+   `cp -al` is a hardlink farm — instant, ~0 extra disk, and a true point-in-time
+   snapshot because rsync replaces inodes (writes a temp file + renames) rather than
+   mutating in place. Restore with `rm -rf dist && mv dist.bak-<date> dist`.
+4. **Deploy** (the dry-run, minus `-n`):
+   ```sh
+   rsync -az --delete dist/ <host>.exe.xyz:/srv/<app>/dist/
+   ```
+5. **Verify the FILE, not the route.** A SPA returns `200` + the app shell for *any*
+   route even when stale — `curl https://<host>.exe.xyz/` proves nothing. Curl a
+   **fixture file** that only exists in the new build, then **render-check the real
+   screens**:
+   ```sh
+   curl -s https://<host>.exe.xyz/.../scenarios/manifest.json | grep -c <new-scenario>          # >0
+   curl -s -o /dev/null -w '%{http_code}' https://<host>.exe.xyz/.../<scenario>/manifest.json   # 200
+   ```
+   File-presence is necessary but not sufficient — SPAs render client-side from the
+   fixture, so only a headless-Chromium render proves the page composes (and didn't fall
+   back to a default scenario). Run Playwright with `env -u NODE_OPTIONS` (a cmux
+   `--require` in `NODE_OPTIONS` crashes node from the repo cwd).
+6. **Rollback if verify fails** — restore the snapshot to the exact pre-deploy state:
+   ```sh
+   ssh <host>.exe.xyz 'rm -rf /srv/<app>/dist && mv /srv/<app>/dist.bak-<date> /srv/<app>/dist'
+   ```
+   Keep the snapshot until the deploy is confirmed good, then prune it.
+
+> **`build:site` DOES include the app's components** (a pre-deploy worry, disproven
+> 2026-06-08). AdiaUI apps are Light-DOM / no-bundle — components live in
+> `app/.../src/components/` (the **source** tree), which `build:site` copies wholesale,
+> so the SPA is fully renderable in `dist/`. Presence ≠ render, though; step 5's
+> render-check is still the proof.
+>
+> **The one exception — `@adia-ai/llm` (2026-06-09):** llm is NOT a source-tree
+> component; it **builds its JS at publish** (gitignored outputs), so `build:site` copies
+> nothing for it in a fresh worktree and `/packages/llm/index.js` 404s → component
+> registration breaks site-wide. Run `npm run build -w @adia-ai/llm` **before** `build:site`
+> (step 1 above). This is exactly why step 5 render-checks a **`/site/components/*`** page,
+> not just a fixture file — the 404 is invisible to file-presence and to the SPA shell.
+
+If `server.js` changed:
+
+```sh
+rsync -a server.js <host>.exe.xyz:/srv/<app>/server.js
+ssh <host>.exe.xyz 'sudo systemctl restart <app>'
+```
+
+## Playbook: rotate secrets
+
+```sh
+ssh <host>.exe.xyz 'sudo vim /etc/<app>.env && sudo systemctl restart <app>'
+```
+
+No rebuild, no redeploy. The static bundle never sees keys.
+
+## Playbook: diagnose
+
+When the site is down or returning 502, start here — everything is read-only:
+
+```sh
+ssh <host>.exe.xyz '
+  echo "=== caddy ==="
+  systemctl is-active caddy; systemctl status caddy --no-pager | head -10
+  echo "=== app service ==="
+  systemctl is-active <app>; journalctl -u <app> -n 30 --no-pager
+  echo "=== listening ports ==="
+  sudo ss -tlnp | grep -E ":(8000|3456|80|443)"
+  echo "=== caddy syntax check ==="
+  sudo caddy validate --config /etc/caddy/Caddyfile
+  echo "=== disk ==="
+  df -h /
+'
+```
+
+Common failures:
+
+| Symptom                         | Likely cause                                   | Fix                                               |
+| ------------------------------- | ---------------------------------------------- | ------------------------------------------------- |
+| "Port 8000 unbound" page        | Caddy not listening on `:8000`                 | Check Caddyfile header is `:8000` not `:80`       |
+| 502 on `/api/*`                 | `<app>` service down or wrong port             | `systemctl status <app>`; tail journalctl         |
+| 500 from `/api/llm/*`           | Missing/invalid API key                        | Check `/etc/<app>.env`, restart service           |
+| Static assets 404               | `rsync --delete` ran with wrong source         | Rebuild local `dist/`, push again                 |
+| Site serves a stale build (new fixtures 404, SPA shows a default scenario) | `deploy:site` never run after the merge — it's **manual**, not on the release pipeline | Run the hardened `--delete` sequence; verify the fixture **file**, not the route |
+| Caddy won't reload              | Syntax error in Caddyfile                      | `sudo caddy validate --config /etc/caddy/Caddyfile` |
+
+## Invariants
+
+- **Secrets never flow through agent context.** The agent should `sudo vim` *or* pause and let the human seed `/etc/<app>.env`. Never `echo "sk-..." > /etc/<app>.env` in a Bash call.
+- **Caddy binds `:8000`**, not `:80` or `:443`.
+- **`--delete` on rsync is scoped to the webroot only** (`/srv/<app>/dist/`). Never rsync-delete against `/srv/<app>/` or the VM's home.
+- **Snapshot the webroot before any `--delete` deploy.** `cp -al /srv/<app>/dist /srv/<app>/dist.bak-<date>` is the only rollback for the 3,500+ files a fresh `--delete` prunes. Dry-run and adjudicate every delete before you send.
+- **Verify a fixture FILE, never the route.** `curl /` returns `200` even when the site is stale (the SPA serves its shell for any path); proof of a live deploy is a fixture file `200` plus a browser render-check.
+- **Back up before overwriting system files.** `mv Caddyfile Caddyfile.default.bak` — not `rm`.
+
+## Current deployments
+
+- `ui-kit.exe.xyz` → AdiaUI docs + demos (repo: `chat-ui`, artifacts: `deploy/`, webroot: `/srv/adia-ui/dist/`, secrets: `/etc/adia-ui.env`, service: `adia-ui.service`). Also serves the embedded-app HCC demo at `/apps/embedded-app/app`; updated only via the manual `npm run deploy:site` (`--delete` — use the hardened sequence above).
+
+Add new hosts here as they come online.
+
+## Pairing with adia-ui-release
+
+When `adia-ui-release` mode 8 (EXE deploy) hands off, this playbook owns the
+deploy step. Release engineering builds artifacts; ops deploys them. See
+`adia-ui-release/SKILL.md` §EXE-deploy mode for the upstream hand-off contract.

package/skills/adia-ui-ops/references/doc-types/adr-pattern.md

@@ -0,0 +1,210 @@
+---
+date: 2026-04-27
+coverage: canonical
+peers:
+  - decisions-log.md
+  - architecture-md.md
+  - postmortem-pattern.md
+primary_sources:
+  - Michael Nygard, "Documenting Architecture Decisions" (cognitect.com/blog/2011/11/15) — the original ADR essay
+  - https://adr.github.io — ADR organization (canonical hub)
+  - https://github.com/joelparkerhenderson/architecture-decision-record — Joel Parker Henderson's ADR catalog (most-cited examples library, actively maintained)
+  - https://adr.github.io/madr/ — MADR 4.0.0 (released 2024-09-17, "Markdown Any Decision Records")
+  - https://medium.com/olzzio/y-statements-10eb07b5a177 — Olaf Zimmermann, Y-statements (SATURN 2012)
+  - https://github.com/npryce/adr-tools — adr-tools CLI (lightly maintained)
+  - https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record — ADR / Decision Log canonical meaning
+status: research-verified
+---
+
+# Architecture Decision Records (ADRs)
+
+> **One ADR captures one architectural decision and its context — *immutably*.** Decisions don't get edited; they get superseded. The newest ADR wins; older ADRs remain as history.
+
+## What an ADR is (and isn't)
+
+An ADR is a **dated, numbered, status-bearing Markdown file** that captures:
+
+- **Why** a decision was made (the problem and constraints)
+- **What** was decided (the chosen path)
+- **What was considered** (the alternatives and why they lost)
+- **Consequences** (the trade-offs the team is signing up for)
+
+An ADR is **not** a design doc, RFC, spec, or proposal. Those describe future work; an ADR records a *commitment that has been made*. Once accepted, it is rarely edited — instead, a new ADR supersedes it.
+
+## File layout
+
+Standard:
+
+```
+.brain/adrs/
+├── 0001-record-architecture-decisions.md
+├── 0002-use-postgres-not-mysql.md
+├── 0003-rest-not-graphql.md
+├── 0004-deprecate-redis-cache.md
+└── README.md
+```
+
+Numbering is strictly sequential. Filename pattern: `NNNN-kebab-case-title.md`.
+
+## The Nygard format (canonical, ~2011)
+
+Michael Nygard's [original 2011 essay](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions) gave the field its first standard:
+
+```markdown
+# 1. Record architecture decisions
+
+Date: 2026-04-27
+
+## Status
+
+Accepted
+
+## Context
+
+What is the issue we're seeing that motivates this decision?
+
+## Decision
+
+What is the change we're making?
+
+## Consequences
+
+What becomes easier or harder because of this change?
+```
+
+Five sections: Title, Date, Status, Context, Decision, Consequences. Short and disciplined.
+
+## Status values
+
+The set is small and load-bearing:
+
+| Status | Meaning |
+|---|---|
+| `Proposed` | Drafted, under discussion, not yet accepted |
+| `Accepted` | Decided. The team is committed. |
+| `Rejected` | Considered and not adopted. Recorded so it doesn't get re-proposed without context. |
+| `Deprecated` | No longer active but not yet replaced |
+| `Superseded by ADR-NNNN` | Replaced by a newer decision |
+
+## ADR vs Architecture Decision Log (ADL) — canonical meaning
+
+The widely-cited industry view (Microsoft Azure Well-Architected Framework, AWS Prescriptive Guidance, adr.github.io):
+
+> "An Architectural Decision Record (ADR) captures a single AD and its rationale; **the collection of ADRs constitutes the decision log.**"
+
+So the canonical "decision log" is **the index of all ADRs** in `.brain/adrs/`, not a separate folder. Generate it from filenames + status fields, or maintain `.brain/adrs/README.md` as a hand-written index.
+
+Some teams *additionally* maintain a lighter `.brain/decisions/` folder for non-architectural decisions (tooling picks, library swaps, day-to-day commitments). That's a **team convention, not industry standard** — but it's a useful split when ADRs feel too heavyweight for routine choices. The audit should detect both shapes and not flag either as wrong; just note which convention is in play.
+
+## MADR 4.0.0 (Markdown Any Decision Records)
+
+MADR ([adr.github.io/madr](https://adr.github.io/madr/)) is the current canonical structured variant. Released **4.0.0 on 2024-09-17** with a notable rename: the *A* now stands for *Any* (was *Architectural*) — explicitly broadening scope to non-architectural decisions. Templates: `adr-template.md`, `adr-template-minimal.md`, `adr-template-bare.md`. **YADR** (YAML ADRs) added March 2026.
+
+MADR adds:
+
+- `Deciders:` (who decided)
+- `Consulted:` / `Informed:` (who else was looped in)
+- More explicit "Considered Options" with pros/cons per option
+
+```markdown
+---
+status: accepted
+date: 2026-04-27
+deciders: alice, bob
+consulted: data-team
+informed: engineering-all
+---
+
+# Use Postgres, not MySQL
+
+## Context and Problem Statement
+
+We need a relational database for the user-account service.
+
+## Decision Drivers
+
+- Mature JSONB support
+- Strong concurrency story
+- Existing team skills
+
+## Considered Options
+
+- Postgres
+- MySQL
+- SQLite
+
+## Decision Outcome
+
+Chosen: **Postgres**, because of JSONB + concurrency + team skills.
+
+### Consequences
+
+- Good: rich query power, strong type system
+- Bad: ops overhead vs SQLite
+
+## Pros and Cons of the Options
+
+### Postgres
+- Good: ...
+- Bad: ...
+
+### MySQL
+- Good: ...
+- Bad: ...
+```
+
+MADR's structure scales better to larger teams and audit trails. Nygard's brevity is right for smaller teams. Pick one and stick with it.
+
+## Y-statements (Zimmermann)
+
+A concise alternative format positioned by adr.github.io as current best practice. Single-sentence form:
+
+> *"In the context of `<use case / user story>`, facing `<concern>` we decided for `<option>` and neglected `<other options>`, to achieve `<system qualities>` / `<desired consequences>`, accepting `<downside / undesired consequences>`."*
+
+Origin: Olaf Zimmermann, SATURN 2012. Useful as a one-line summary line at the top of a longer ADR, or as the entire ADR for small reversible choices. Pairs well with MADR.
+
+## Tooling (April 2026)
+
+- **`adr-tools`** by Nat Pryce: https://github.com/npryce/adr-tools — Bash CLI; **lightly maintained** as of April 2026 (no recent releases; MADR-support PR #43 was rejected for maintenance burden). Still functional for the ADR-creation workflow it was built for.
+- **`adr-log`**: generates a Markdown index from a folder of ADRs.
+- **`log4brains`**: web-based ADR browser; check current maintenance state before adopting.
+- **`adr-manager`**: web-UI ADR editor.
+- **For new projects, no tool is required.** `mkdir -p .brain/adrs && cp ~/.adr-templates/madr-minimal.md .brain/adrs/0001-record-architecture-decisions.md` is enough. Tooling adds friction; many teams now skip it.
+
+## How AGENTS.md should reference ADRs
+
+In the `Where to find things` section:
+
+```markdown
+- **Architecture Decision Records:** `.brain/adrs/` — newest-first; read before making architectural changes
+```
+
+In the `Memory primitives` section:
+
+```markdown
+- **Before making architectural decisions**, read `.brain/adrs/` newest-first. If your proposed change conflicts with an `Accepted` ADR, write a new ADR superseding it; don't silently override.
+```
+
+## Common anti-patterns
+
+- **No `.brain/adrs/` folder at all** — decisions live in random PR descriptions, Slack, code comments. Memory fragmentation.
+- **ADRs as RFCs** — files marked `Proposed` that never get marked `Accepted` or `Rejected`. Status drift.
+- **Editing accepted ADRs** — defeats the audit trail. Edits should be supersessions instead.
+- **No `Status:` field** — readers can't tell what's current.
+- **Mixed numbering schemes** — `001-foo.md`, `2-bar.md`, `0003-baz.md`. Pick `NNNN-` four-digit and stick with it.
+- **No ADR for the introduction of ADRs themselves** — the first ADR (`0001`) should be "Record architecture decisions" so the practice itself is decided.
+
+## Audit checks for ADRs
+
+1. **Folder exists** at `.brain/adrs/` (or close — `.brain/architecture/decisions/`, `adrs/`, etc.).
+2. **Numbering is consistent** (`NNNN-` four-digit, sequential).
+3. **Each ADR has a `Status:` field**.
+4. **No ADRs are in `Proposed` for >30 days** (probably abandoned — flag).
+5. **`.brain/adrs/` is referenced from AGENTS.md**.
+
+## Cross-references
+
+- Decision log (looser): `decisions-log.md`
+- Architecture overview: `architecture-md.md`
+- Adding ADRs to existing repo: `../recipes/adr-introduction.md`
+- Memory organization: `../recipes/memory-organization.md`

package/skills/adia-ui-ops/references/doc-types/architecture-md.md

@@ -0,0 +1,190 @@
+---
+date: 2026-04-27
+coverage: canonical
+peers:
+  - adr-pattern.md
+  - decisions-log.md
+  - changelog.md
+primary_sources:
+  - https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html — Aleksey Kladov (matklad), "ARCHITECTURE.md" (the canonical pattern essay, Feb 2021)
+  - https://github.com/rust-lang/rust-analyzer/blob/master/docs/dev/architecture.md — rust-analyzer's ARCHITECTURE.md (the canonical example)
+  - https://github.com/sourcegraph/sourcegraph/blob/main/doc/dev/background-information/architecture/index.md — Sourcegraph's adoption of the pattern
+  - https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record — Microsoft Azure WAF on architecture documentation
+status: research-verified
+---
+
+# ARCHITECTURE.md — current state, in 30 minutes
+
+> **ARCHITECTURE.md answers: "I'm new here. Where do I look first?"** Not "what did we decide?" (that's ADRs) and not "what shipped?" (that's CHANGELOG). It is a *map of the codebase as it currently is*, optimized for someone landing in the repo cold.
+
+This pattern delivers **Promise 2 (token-and-context-optimized)** by giving an LLM agent a single high-signal entry into the codebase's structure, and **Promise 1 (less-wasteful)** by replacing the scattered "tribal knowledge" that otherwise accumulates in PR comments, Slack threads, and 3-year-old wiki pages.
+
+## Origin and canonical source
+
+The pattern was named and codified by **Aleksey Kladov** (handle: *matklad*, lead author of rust-analyzer) in the February 2021 blog post [**"ARCHITECTURE.md"**](https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html). The canonical exemplar is rust-analyzer's own [`docs/dev/architecture.md`](https://github.com/rust-lang/rust-analyzer/blob/master/docs/dev/architecture.md).
+
+Kladov's framing:
+
+> "Looking at someone else's code is hard, but very useful sometimes. The best help for an outsider is a single document, a map, which describes the *bird's-eye view* of the project, and explains how to navigate the code."
+
+The pattern has spread widely — Sourcegraph, Tantivy, hyperqueue, ripgrep, and many others use a doc by the same name (or `architecture/` folder with the same shape).
+
+## What ARCHITECTURE.md *is* (and what it's not)
+
+| ARCHITECTURE.md | Not ARCHITECTURE.md |
+|---|---|
+| Current state of the system | History of how it got here (→ git log, ADRs) |
+| Map of the codebase ("Module X lives at `src/x/`") | Decision rationale ("Why did we pick X?" → ADRs) |
+| 30-minute onboarding | Comprehensive technical reference (→ separate docs) |
+| Names directories and the responsibility of each | Lists every file (→ tooling) |
+| Cross-cutting concerns (concurrency model, error handling, lifetime) | API documentation (→ generated docs) |
+| Non-obvious intentional choices ("we deliberately don't use X") | Future plans (→ ROADMAP.md) |
+| Updated when architecture changes | Updated weekly (→ PLAN.md) |
+
+The discipline is: **document things that won't change much, that an experienced engineer would still want explained.** Module purpose, layering, where-data-flows-from-input-to-output, how-tests-are-organized, what-not-to-do.
+
+## The 30-minute onboarding shape
+
+Kladov's recommended sections (with this skill's annotations):
+
+### 1. Bird's-eye view
+
+One paragraph or one diagram. What does this project *do*? Who calls it, what does it call?
+
+```markdown
+## Bird's-eye view
+
+`acme-cli` is a Rust binary that reads YAML config from `acme.yaml`,
+queries an HTTPS API, and writes Markdown reports to stdout. It has
+no persistent state. It is invoked from CI in the user's repo.
+```
+
+If a diagram clarifies — use one. ASCII boxes are fine; Mermaid is fine; an image is fine. Don't gold-plate.
+
+### 2. Code map
+
+The load-bearing section. **For each top-level directory, one paragraph: what's in it, what's the responsibility, where the boundaries are.**
+
+```markdown
+## Code map
+
+### `src/cli/`
+Argument parsing (clap), command dispatch. No business logic — delegates to `src/core/`.
+
+### `src/core/`
+The orchestrator. Reads config, fans out to API client, aggregates results. **The only module allowed to depend on both the config layer and the API layer.**
+
+### `src/api/`
+HTTP client (reqwest). One module per endpoint group. Adding a new endpoint? Look here.
+
+### `tests/`
+Integration tests. Use the `wiremock` fixture, not real HTTP.
+```
+
+A reader (human or agent) can immediately answer: *"I want to add a new API endpoint. Where?"*
+
+### 3. Cross-cutting concerns
+
+Things that span modules and aren't inferable from the code map.
+
+```markdown
+## Cross-cutting concerns
+
+- **Error handling**: `anyhow::Error` everywhere except `src/api/` (typed errors). See ADR-0007.
+- **Concurrency**: single-threaded by default; `--parallel N` spawns tokio. Only `src/core/parallel.rs` knows async.
+- **Logging**: `tracing`, structured JSON. `RUST_LOG` configures.
+```
+
+### 4. Non-obvious intentional choices
+
+The "we deliberately don't do X" section. Saves future contributors hours.
+
+```markdown
+## Things we deliberately don't do
+
+- **No async by default.** Tokio startup dominated benchmarks. See ADR-0011.
+- **No plugin system.** Rejected (ADR-0014).
+- **No config format other than YAML.** TOML support was removed in v1.2.0.
+```
+
+ARCHITECTURE.md *summarizes* the decision and points at the ADR for *why*.
+
+### 5. Where to look first
+
+The newcomer's quick-start. Optional but high-value for LLM agents — it's a routing table for common tasks.
+
+```markdown
+## Where to look first
+
+- **Adding a CLI flag?** `src/cli/args.rs`, then dispatch in `src/cli/mod.rs`.
+- **Adding an API endpoint?** `src/api/`. Mirror an existing endpoint.
+- **Investigating a CI failure?** `tests/integration/` first, then logs.
+- **Performance regression?** `benches/` and `cargo bench`.
+```
+
+## Length and ergonomics
+
+Kladov's own rust-analyzer ARCHITECTURE.md is ~600 lines. That's at the upper end. **For most repos, 200–400 lines is right.**
+
+Under 100 lines → probably missing the code map.
+Over 800 lines → split. Move detail into per-module READMEs (`src/api/README.md`) and keep ARCHITECTURE.md as the bird's-eye + index.
+
+This skill's general guidance: **entry-level docs under ~200 lines, pushed-down detail in subdirectory READMEs.** See `../guidance/context-budget.md`.
+
+## Distinction from ADRs
+
+The most-confused boundary: ARCHITECTURE.md is **present-tense, mutable, system-wide**; ADRs are **past-tense, immutable, per-decision**. ARCHITECTURE.md answers "Where does X live?"; ADRs answer "Why did we choose X?". ARCHITECTURE.md *links* to ADRs ("see ADR-0007"), never duplicates them.
+
+## Update discipline
+
+ARCHITECTURE.md goes stale faster than ADRs and slower than PLAN.md. Recommended cadence:
+
+1. **PR-level**: any PR that adds, renames, or removes a top-level directory must update ARCHITECTURE.md in the same PR. Enforce with a CI check or a CODEOWNERS rule. See `../recipes/self-healing-hooks.md`.
+2. **Quarterly review**: a maintainer re-reads ARCHITECTURE.md against the current tree and patches drift.
+3. **LLM-on-diff**: when a large refactor lands, run an LLM-on-diff pass against ARCHITECTURE.md to flag suspect sections. See `../audit-patterns/staleness-tooling.md`.
+
+## How AGENTS.md links ARCHITECTURE.md
+
+In the `Where to find things` section:
+
+```markdown
+- **Architecture:** `ARCHITECTURE.md` — start here if you're new to the codebase
+```
+
+In the `Memory primitives` section:
+
+```markdown
+- **Before making changes that span multiple modules**, read `ARCHITECTURE.md` for the code map and cross-cutting concerns. Architecture-altering changes also require a new ADR.
+```
+
+`ARCHITECTURE.md` at repo root is the recommended location (matklad's pattern). Avoid `.brain/architecture/index.md` unless you have a folder full of related docs.
+
+## Audit checks
+
+1. **File exists** at `/ARCHITECTURE.md` (repo root, per matklad).
+2. **Code map covers all top-level src directories.** Diff `ls src/` against the headings in the code map; missing entries = staleness.
+3. **No directory mentioned in the code map is missing from disk.** Renames or removals that didn't update the doc.
+4. **Length is in 100–800 range.** Both extremes are flagged.
+5. **AGENTS.md references ARCHITECTURE.md**, not just `.brain/`.
+6. **`Last reviewed:` line or YAML `date:` is within the last 180 days.** Older = quarterly review missed.
+
+## Common anti-patterns
+
+- **No ARCHITECTURE.md** — newcomers and agents navigate by `ls` and pattern-match. Slow.
+- **Feature list, not a code map** — describes what the product does, not how it's built.
+- **History, not present-tense** — narrates evolution. That's a blog post.
+- **Duplicates ADR content** — copy-pasted "why" rationale. Link to the ADR instead.
+- **Alphabetical code map** — group by responsibility (core → adapters → entry-points).
+- **Stale code map** — directories renamed in code, not in the doc. Catch with the audit.
+- **Outsourced to a wiki** — agents can't read Confluence; drift is guaranteed. Keep it in the repo.
+
+## Cross-references
+
+- ADR pattern (decisions, not state): `adr-pattern.md`
+- Decision log (collection of ADRs): `decisions-log.md`
+- Changelog (shipped, not state): `changelog.md`
+- Plan / roadmap (planned, not state): `plan-roadmap.md`
+- Self-healing PR-gate hooks: `../recipes/self-healing-hooks.md`
+- LLM-on-diff staleness detection: `../audit-patterns/staleness-tooling.md`
+- Context budget guidance (200-line target): `../guidance/context-budget.md`
+- AGENTS.md "Where to find things" section: `../standards/agents-md-spec.md`