Merge pull request #11 from devonartis/doc/docs-layout-archon-style

docs: audit P1/P2 corrections + docs-layout-archon-style sweep

Author: devonartis

.claude/rules/karpathy.md

@@ -0,0 +1,41 @@
+# Karpathy Guidelines — Coding Discipline
+
+Derived from Andrej Karpathy's observations on common LLM coding pitfalls. These run alongside all other project rules — not optional, not situational.
+
+## 1. Think Before Coding
+
+State assumptions explicitly before implementing. If multiple interpretations exist, present them — don't pick silently. If something is unclear, stop and ask. Push back when a simpler approach exists.
+
+## 2. Simplicity First
+
+Minimum code that solves the problem. Nothing speculative.
+
+- No features beyond what was asked
+- No abstractions for single-use code
+- No "flexibility" that wasn't requested
+- No error handling for impossible scenarios
+
+AgentAuth has 5 direct dependencies by design. Every abstraction is a candidate to reject. If a change balloons a function, stop and reconsider.
+
+## 3. Surgical Changes
+
+Touch only what you must. Clean up only your own mess.
+
+- Don't improve adjacent code, comments, or formatting
+- Don't refactor things that aren't broken
+- Match existing style, even if you'd do it differently
+- If you notice unrelated issues — note them in TECH-DEBT.md, don't fix them inline
+
+**This is especially critical in `authz/`, `token/`, and `revoke/`.** Small "improvements" to adjacent security code introduce subtle regressions that tests don't catch because the behavior change wasn't the stated goal.
+
+Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+Define success criteria before starting. Loop until verified.
+
+- "Fix the bug" → write a story that reproduces it, run against the binary, record evidence, then mark PASS
+- "Add validation" → write tests for invalid inputs, then make them pass
+- For multi-step tasks, state a brief plan with a verify step per item
+
+Weak criteria ("make it work") require constant clarification. Strong criteria let you loop independently.

.plans/bugs/BUG-CLI-002-awrit-init-config-path.md

@@ -0,0 +1,129 @@
+# BUG-CLI-002 — `awrit init` writes config to wrong path
+
+**ID:** BUG-CLI-002  
+**Severity:** HIGH  
+**Introduced in:** commit `4e197a5` (`fix(cli): rename aactl binary to awrit (TD-CLI-001)`)  
+**Linked TD:** TD-CLI-002  
+**Status:** Open — fix branch not yet created
+
+---
+
+## Summary
+
+`awrit init` writes the generated config file to `~/.agentauth/config`. The broker's
+config auto-loader reads from `~/.broker/config`. These paths do not match. A user
+who runs `awrit init` without `--config-path` ends up with a config file the broker
+silently ignores, causing the broker to start with no admin secret and exit with a FATAL.
+
+---
+
+## Root Cause
+
+Two commits touched the same logical concern but were not reconciled:
+
+| Commit | File | What it did |
+|--------|------|-------------|
+| `07daa20` (TD-CFG-002) | `internal/cfg/configfile.go` | Updated broker auto-load search paths: `/etc/agentauth/config` → `/etc/broker/config`, `~/.agentauth/config` → `~/.broker/config` |
+| `4e197a5` (TD-CLI-001) | `cmd/awrit/init_cmd.go` | Created `resolveConfigPath()` with the **old paths**: `/etc/agentauth/config` and `~/.agentauth/config` |
+
+`07daa20` landed first. `4e197a5` was created after it, but introduced new code using
+the stale paths — they were never synced.
+
+---
+
+## Affected Code
+
+**File:** `cmd/awrit/init_cmd.go`  
+**Function:** `resolveConfigPath()` (lines 53–64)
+
+```go
+func resolveConfigPath() string {
+    if initConfigPath != "" {
+        return initConfigPath
+    }
+    if p := os.Getenv("AA_CONFIG_PATH"); p != "" {
+        return p
+    }
+    home, err := os.UserHomeDir()
+    if err != nil {
+        return "/etc/agentauth/config"   // ← should be /etc/broker/config
+    }
+    return home + "/.agentauth/config"  // ← should be /.broker/config
+}
+```
+
+**Broker reads from** (`internal/cfg/configfile.go:24`):
+```go
+locs = append(locs, filepath.Join(home, ".broker", "config"))
+```
+
+---
+
+## Impact
+
+A user following the getting-started guide:
+
+1. Runs `awrit init` → config written to `~/.agentauth/config`
+2. Starts broker → broker searches `~/.broker/config`, finds nothing
+3. `AA_ADMIN_SECRET` is unset → broker exits FATAL: `admin secret required`
+
+The `--config-path` flag works around this, but no getting-started doc tells users
+they need it because the default is supposed to Just Work.
+
+---
+
+## Fix
+
+**File:** `cmd/awrit/init_cmd.go:53–64`
+
+```go
+func resolveConfigPath() string {
+    if initConfigPath != "" {
+        return initConfigPath
+    }
+    if p := os.Getenv("AA_CONFIG_PATH"); p != "" {
+        return p
+    }
+    home, err := os.UserHomeDir()
+    if err != nil {
+        return "/etc/broker/config"
+    }
+    return home + "/.broker/config"
+}
+```
+
+Two literal changes. No other files affected.
+
+---
+
+## Verification
+
+After the fix, run:
+
+```bash
+# Build
+go build -o bin/awrit ./cmd/awrit
+
+# Run init
+./bin/awrit init --mode dev
+
+# Confirm path
+ls -la ~/.broker/config           # must exist
+cat ~/.broker/config              # must contain ADMIN_SECRET=...
+
+# Start broker (reads ~/.broker/config automatically)
+./bin/broker
+# Expect: broker starts, no FATAL on admin secret
+```
+
+Unit test: `internal/cfg/configfile_test.go` already tests that `~/.broker/config`
+is in the search path. Add a test in `cmd/awrit/init_cmd_test.go` (or similar)
+that calls `resolveConfigPath()` with `HOME` set and asserts the returned path
+ends in `.broker/config`.
+
+---
+
+## Branch
+
+`fix/td-cli-002-awrit-init-config-path` off `develop`  
+Needs: code fix + unit test + `./scripts/gates.sh task` green + PR

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed — Docs audit P1/P2 corrections (2026-04-12)
+
+- **`docs/getting-started-user.md`** — admin auth examples used the literal `"my-secret-key-change-in-production"` while the guide starts the broker with a randomly generated `$AA_ADMIN_SECRET`. Examples now reference `$AA_ADMIN_SECRET` so the first-run path works without 401s.
+- **`docs/awrit-reference.md`** — `awrit init` sample output showed `~/.agentwrit/config`; corrected to `~/.broker/config` (the actual default write path — or rather, the broker's read path; see TD-CLI-002 for the underlying code bug).
+- **`docs/api.md`** — JWT claims table corrected: `iss` is driven by `AA_ISSUER` (empty by default, issuer validation skipped); app token subject is `app:{internal_app_id}` not `app:{client_id}`; `aud` is driven by `AA_AUDIENCE` (omitted if unset, audience validation skipped).
+- **`docs/getting-started-operator.md`** — `AA_AUDIENCE` default corrected from `"agentwrit"` to *(empty)*. SQLite persistence note corrected: setting `AA_DB_PATH=""` does not enable memory-only mode — unset uses the `./data.db` default.
+- **`docs/api/openapi.yaml`** — `info.license` corrected from `Apache-2.0` to `AGPL-3.0` with the correct license URL. Matches `LICENSE`, `README.md`, and `CLA.md`.
+- **`docker-compose.yml`** — Docker bridge network renamed `agentauth-net` → `agentwrit-net` to match brand sweep and operator docs.
+- **`docs/README.md`** — API reference entry corrected from "22 HTTP endpoints" to "19". Concepts entry corrected from "seven components" to "eight".
+- **`docs/concepts.md`** — intro sentence corrected from "seven components" to "eight".
+- **`TECH-DEBT.md`** — added TD-CLI-002 (HIGH: `awrit init` writes to `~/.agentauth/config`, broker reads `~/.broker/config` — broken first-run path introduced in commit `4e197a5`) and TD-CLI-003 (Low: docker-compose.yml network name lag). Bug report at `.plans/bugs/BUG-CLI-002-awrit-init-config-path.md`.
+
 ### Renamed CLI binary `aactl` → `awrit` (TD-CLI-001)
 
 - **`cmd/aactl/` → `cmd/awrit/`** — directory renamed. Cobra command name changed (`Use: "aactl"` → `Use: "awrit"`). All internal CLI output, help text, and error messages updated.

CLAUDE.md

@@ -9,6 +9,7 @@
 - `.claude/rules/testing.md` — LIVE test and acceptance test expectations
 - `.claude/rules/golang.md` — Go coding standards
 - `.claude/rules/mandatory-reading.md` — **Read this entirely and summarize it back to the user at session start.** Defines what goes in MEMORY.md vs FLOW.md vs TECH-DEBT.md. Do NOT mix them up.
+- `.claude/rules/karpathy.md` — coding discipline (simplicity, surgical changes, goal-driven execution). Always active alongside the rules above.
 
 ## Defaults
 

FLOW.md

@@ -532,3 +532,37 @@ Rewrote the AgentWrit public intro copy for the rebrand (Layer 1 of Decision 013
 
 ### Status: Copy ready — apply on next agentauth-core session
 **Next:** apply the new intro to the website, core README, and any other location the old intro lives. Single source of truth in the decision file — no per-repo drift.
+
+---
+
+## 2026-04-12 — Docs audit P1/P2 corrections + TD-CLI-002 bug discovery
+
+### Action: Fixed 9 doc accuracy issues from external audit report
+
+Branch: `doc/docs-layout-archon-style`
+
+Audit report surfaced P1/P2 findings against the codebase. After verification:
+
+**Docs fixed (pure doc errors — no code changes):**
+- `docs/getting-started-user.md` — wrong admin secret literal in auth examples → `$AA_ADMIN_SECRET`
+- `docs/awrit-reference.md` — `awrit init` sample output showed `~/.agentwrit/config` → `~/.broker/config`
+- `docs/api.md` — JWT claims table: `iss` not always "agentwrit" (driven by `AA_ISSUER`, empty by default); app subject is `app:{internal_app_id}` not `app:{client_id}`; `aud` driven by `AA_AUDIENCE`, omitted if unset
+- `docs/getting-started-operator.md` — `AA_AUDIENCE` default was wrong (`"agentwrit"` → empty); SQLite memory-mode fallback claim removed (false — empty `AA_DB_PATH` falls back to `./data.db`)
+- `docs/api/openapi.yaml` — license `Apache-2.0` → `AGPL-3.0`
+- `docker-compose.yml` — network `agentauth-net` → `agentwrit-net` (brand sweep miss)
+- `docs/README.md` — endpoint count 22 → 19 (verified from route registration); component count seven → eight
+- `docs/concepts.md` — component count seven → eight
+
+**Left alone (intentional code/docs gap — code-side rebrand not done yet):**
+- `urn:agentauth:error:` in `internal/problemdetails/problemdetails.go` — docs say `urn:agentwrit:error:`, code hasn't been renamed; this is planned work
+- `agentauth_*` metric names in `internal/obs/obs.go` — docs say `agentwrit_*`, same situation
+
+**New tech debt logged:**
+- TD-CLI-002 (HIGH) — `awrit init` writes to `~/.agentauth/config`, broker reads `~/.broker/config`. Bug introduced in `4e197a5`: TD-CFG-002 fixed the broker read side but the CLI write side (`cmd/awrit/init_cmd.go:53-64`) was created with old paths. Bug report: `.plans/bugs/BUG-CLI-002-awrit-init-config-path.md`
+- TD-CLI-003 (Low) — docker-compose.yml network name lag (fixed in this session)
+
+### What's Next
+
+1. **`fix/td-cli-002-awrit-init-config-path`** — two-line fix in `cmd/awrit/init_cmd.go:53-64`, unit test, gates, PR. Bug report ready at `.plans/bugs/BUG-CLI-002-awrit-init-config-path.md`.
+2. **Code-side rebrand** — rename `agentauth_*` Prometheus metrics in `internal/obs/obs.go` and `urn:agentauth:error:` in `internal/problemdetails/problemdetails.go` to match the docs. Separate PR.
+3. **Merge `doc/docs-layout-archon-style`** — after user review.

TECH-DEBT.md

@@ -77,6 +77,7 @@ B0 removed all sidecar Go code and infrastructure but did NOT rewrite the user-f
 | TD-012 | **MISSING: Role model documentation — who does what, which scopes, and why** | **CRITICAL** | `docs/` — new file needed | See detail below. Without this document, every agent that touches the code misunderstands the system. |
 | TD-013 | `POST /v1/admin/launch-tokens` lets admin CREATE agents — admin should only LIST/REVOKE launch tokens | High | `cmd/broker/main.go:257`, `internal/admin/admin_hdl.go:58-60` | See detail below. |
 | TD-014 | **Code comments audit — all handlers, services, and types need role/scope/boundary comments** | **CRITICAL** | All `internal/` packages | Every function, handler, and type must document: what it does, who can call it (role/scope), why it exists, and its boundaries. Current code has minimal Go doc comments that describe mechanics but not roles, scopes, or security boundaries. An agent reading only the source file cannot understand who calls what or why. Standard defined in `.claude/rules/golang.md`. |
+| TD-015 | `deleg_svc.go` comment says "strict subset" but `ScopeIsSubset` allows equal scopes | Low | `internal/deleg/deleg_svc.go:10-11` | Line 10 says "The delegated scope must be a strict subset of the delegator's scope" but the actual `ScopeIsSubset` check allows equal scopes (subset-or-equal). The behavior is correct — the comment is wrong. Fix: change "strict subset" to "subset" in the package doc. |
 
 ### TD-012 Detail: Missing Role Model Document
 
@@ -352,6 +353,21 @@ Audit triggered by discovery of hardcoded `iss: "agentauth"` in `internal/token/
 
 **Not creating a TD for env var prefix** — decided 2026-04-10 to keep `AA_*` indefinitely. Neutral enough (two letters), operator-facing, highest-friction change in the whole rebrand. Re-evaluate at 1.0 if ever.
 
+| TD-CLI-002 | **`awrit init` writes config to `~/.agentauth/config` but broker reads `~/.broker/config`** — broken first-run path | **HIGH** | Immediate — breaks first-run UX | `cmd/awrit/init_cmd.go:53-64` |
+| TD-CLI-003 | **`docker-compose.yml` network still named `agentauth-net`** — docs say `agentwrit-net` after brand sweep | Low | Next compose-touching PR | `docker-compose.yml:35,42` |
+
+### TD-CLI-002 Detail: awrit init config path mismatch
+
+TD-CFG-002 (resolved 2026-04-10) updated `internal/cfg/configfile.go` to search `~/.broker/config` and `/etc/broker/config`. But commit `4e197a5` (TD-CLI-001, awrit rename) introduced `cmd/awrit/init_cmd.go` with `resolveConfigPath()` still returning `~/.agentauth/config` (home) and `/etc/agentauth/config` (fallback). The fix to the broker's *read* side and the creation of the CLI's *write* side happened in different commits and were never reconciled.
+
+**Impact:** A user who runs `awrit init` (no `--config-path`) gets a config at `~/.agentauth/config`. The broker auto-loads from `~/.broker/config`. The config is silently ignored and the broker starts with no admin secret, causing a `FATAL` exit.
+
+**Fix:** In `cmd/awrit/init_cmd.go:53-64`, update `resolveConfigPath()`:
+- `"/etc/agentauth/config"` → `"/etc/broker/config"`
+- `home + "/.agentauth/config"` → `home + "/.broker/config"`
+
+**Needs:** `fix/td-cli-002-awrit-init-config-path` branch + gates + PR. Bug report at `.plans/bugs/BUG-CLI-002-awrit-init-config-path.md`.
+
 ## When to Fix
 
 Documentation and script drift items (TD-D*, TD-S*) should be resolved **after all cherry-pick batches are complete** (B0-B6). Doing them now risks conflicts with incoming commits. Schedule as a dedicated docs refresh phase post-migration.

docker-compose.yml

@@ -32,12 +32,12 @@ services:
       timeout: 3s
       retries: 10
     networks:
-      - agentauth-net
+      - agentwrit-net
 
 
 volumes:
   broker-data:
 
 networks:
-  agentauth-net:
+  agentwrit-net:
     driver: bridge

docs/README.md

@@ -0,0 +1,86 @@
+# AgentWrit Documentation
+
+AgentWrit is an open-source credential broker for AI agents. It issues short-lived, scope-attenuated tokens so agents operate with only the permissions their task requires — nothing more, nothing longer.
+
+---
+
+## The Book of AgentWrit
+
+Start here. These pages explain what AgentWrit is, why it exists, and how every piece fits together.
+
+| Page | What you'll learn |
+|------|-------------------|
+| [What Is AgentWrit?](agentwrit-explained.md) | The problem, the solution, and the three token types — no prior knowledge required |
+| [Foundations](foundations.md) | What tokens are, why they beat API keys, and how JWTs work under the hood |
+| [The Three Actors](roles.md) | Operator, Application, Agent — who holds what token and why |
+| [Scopes and Permissions](scope-model.md) | The `action:resource:identifier` format, coverage rules, and the four enforcement points |
+| [The Credential Lifecycle](credential-model.md) | Every credential's claims, TTLs, and how they flow through the attenuation chain |
+| [Design Decisions](design-decisions.md) | Why we chose JWTs, Ed25519, SPIFFE, hash-chained audit, and everything else |
+
+---
+
+## Getting Started
+
+Hands-on guides for each persona. Pick the one that matches your role.
+
+| If you are... | Start here |
+|---------------|-----------|
+| **Just trying AgentWrit** to see how it works | [Your First Five Minutes](getting-started-user.md) |
+| **Building an AI agent** in Python, TypeScript, or Go | [Getting Started: Developer](getting-started-developer.md) |
+| **Deploying AgentWrit** in production | [Getting Started: Operator](getting-started-operator.md) |
+
+---
+
+## Guides
+
+Deeper walkthroughs for specific tasks and patterns.
+
+| Guide | What it covers |
+|-------|---------------|
+| [Common Tasks](common-tasks.md) | Token renewal, delegation, revocation, audit queries — the everyday operations |
+| [Integration Patterns](integration-patterns.md) | Resource server validation, multi-agent orchestration, cloud federation |
+| [Scenarios](scenarios.md) | End-to-end walkthroughs: data pipeline agent, customer service bot, CI/CD runner |
+| [Troubleshooting](troubleshooting.md) | Common errors, what causes them, and how to fix them |
+
+---
+
+## Reference
+
+Lookup documentation for endpoints, CLI commands, and internals.
+
+| Reference | What it covers |
+|-----------|---------------|
+| [API Reference](api.md) | All 19 HTTP endpoints — request/response formats, error codes, rate limits |
+| [CLI Reference (awrit)](awrit-reference.md) | Every `awrit` command with examples and output formats |
+| [Architecture](architecture.md) | Internal package map, component diagrams, data flow |
+| [Implementation Map](implementation-map.md) | Where every feature lives in the codebase — file paths, function names, test locations |
+| [Concepts Deep Dive](concepts.md) | The full security pattern, industry context, and all eight components |
+
+---
+
+## Live Demos
+
+See AgentWrit in action with the [Python SDK](https://github.com/devonartis/agentauth-python) demo applications:
+
+| Demo | What it shows |
+|------|-------------|
+| **[MedAssist AI](https://github.com/devonartis/agentauth-python/tree/main/demo)** | Healthcare multi-agent pipeline — clinical, prescription, and billing agents operating under strict scope isolation with LLM tool-calling, delegation, and per-patient scoping |
+| **[Support Ticket Zero-Trust](https://github.com/devonartis/agentauth-python/tree/main/demo2)** | Three LLM-driven agents processing support tickets with broker-issued scoped credentials, streaming execution via SSE, and natural token expiry |
+
+Both demos run against a real AgentWrit broker and show the full credential lifecycle: agent registration, scope enforcement, delegation, renewal, release, and revocation.
+
+---
+
+## Reading Order
+
+If you're new, this path gets you productive fastest:
+
+```
+What Is AgentWrit?  →  Your First Five Minutes  →  Pick your persona guide
+        ↓                                                    ↓
+   Foundations  →  The Three Actors  →  Scopes  →  Common Tasks
+```
+
+If you're evaluating AgentWrit for your organization, start with [What Is AgentWrit?](agentwrit-explained.md) — it's written for people who aren't deeply technical.
+
+If you're a security reviewer, start with [Concepts Deep Dive](concepts.md) and [Architecture](architecture.md).