docs: rewrite tenets, CLAUDE.md, and source comments around our own goals

Walked through the docs and inline comments and rewrote them so the
codebase describes itself on its own terms — what it is, how it's
built, what we believe about the design — instead of as a comparison
against anything external. Drops some stale internal audit notes from
docs/ that were never load-bearing.

Net: ~900 lines deleted, ~75 added. No behavior change.

Author: halfaipg

.settings/tenets.md

@@ -4,19 +4,7 @@ These are decisions, not aspirations — the code already reflects them.
 When in doubt, the tenet wins over momentum. When two tenets conflict,
 they're listed roughly in priority order.
 
-## 1. Better than Claude Code, not a clone
-
-We study Claude Code's source as a benchmark for feature coverage and learn
-from their architectural mistakes. Every feature we add should be a *better*
-implementation, not a copy-paste. We have CC's source for reference; what we
-copy is the *idea* (collapsed read groups, tool-status spinners, `!cmd` shell
-escape), never the wording or the data structures.
-
-**Why this matters**: this is open source. Verbatim copies of CC's prompt
-strings or code create IP risk. The technique is fine; the specific words
-must be original.
-
-## 2. Any LLM provider, never lock-in
+## 1. Any LLM provider, never lock-in
 
 OAuth login for our hosted offering, BYOK for everything else. Anthropic,
 OpenAI, Groq, OpenRouter, Ollama, anything OpenAI-compatible. Provider
@@ -25,33 +13,30 @@ abstracts the protocol differences.
 
 **Implication**: don't write code that assumes a specific provider's quirks
 unless you also write the fallback path. Don't depend on provider-specific
-features (e.g. Anthropic's tool_use blocks) outside of the protocol adapter
-layer in `@earendil-works/pi-ai`.
+features outside of the protocol adapter layer in `@earendil-works/pi-ai`.
 
-## 3. Simplicity beats features
+## 2. Simplicity beats features
 
-CC is 512K LOC. We're ~22K. That's not an accident — it's a position. Before
-adding a feature, ask: "is this *the* feature, or *a* feature?" Most of CC's
-features are accretion. Most ours should not be.
+The codebase is small on purpose. Before adding a feature, ask: "is this
+*the* feature, or *a* feature?" Most accretion is regret-shaped.
 
 **Practical rules**:
 - No premature abstraction. Three similar lines is better than a wrong helper.
 - No backwards-compat shims for code you're rewriting in the same PR.
 - No "let's make this configurable" before there's a second use case.
 - Comments explain *why*, not *what*. Default to none.
 
-## 4. Effect-based permissions
+## 3. Effect-based permissions
 
 Tools declare their **effects** (`reads_fs`, `writes_fs`, `runs_shell`,
 `network`). Permission policies match on effects, not tool names. Adding a
 new tool = declaring its effects; the permission system already knows what
-to do. CC has 300K+ lines of permission AST parsing for tool-name patterns;
-we have ~600 lines because we made the foundational call differently.
+to do.
 
 Don't add tool-name special-cases to the permission engine. If a real
 restriction needs to exist, it's a new effect.
 
-## 5. Streaming is a UX commitment
+## 4. Streaming is a UX commitment
 
 Models emit tokens at 60-100 Hz. Tools emit stdout in bursts. The TUI has
 to keep up *without* repainting at that rate or it'll thrash the user's
@@ -60,10 +45,10 @@ terminal. We coalesce to 16ms (60fps) in `use-coalesced-agent-events.ts`.
 If you're adding a state path the streaming pipeline goes through, ask:
 "does this allocate on every event?" Often the answer is "we make a new Map
 per update" — and that's *fine* because the reducer microbenchmark
-(`npm run bench:micro`) says we have 10M+ events/sec of headroom. But
+(`npm run bench:micro`) shows we have 10M+ events/sec of headroom. But
 don't add work without checking.
 
-## 6. The agent loop belongs to pi-mono
+## 5. The agent loop belongs to pi-mono
 
 `@earendil-works/pi-agent-core` owns: the model.run() loop, message
 shape, tool-call protocol, session persistence. We do not reimplement
@@ -74,7 +59,7 @@ Things we own: the TUI, tools, slash commands, permissions, the glue
 sidecar, OAuth, the wizard, the headless `run` subcommand, the JSON-RPC
 `app-server`.
 
-## 7. Test the load-bearing parts
+## 6. Test the load-bearing parts
 
 Tools, the reducer, the router, parsers, and credential handling have
 unit tests. The interactive TUI does not — yet. We accept the trade-off:
@@ -87,22 +72,22 @@ The faux provider from pi-ai (`registerFauxProvider`) is the right tool
 for E2E tests — see `src/agent/__test__/agent-e2e.test.ts`. No mocks, real
 agent loop, deterministic.
 
-## 8. Don't fight the user's terminal
+## 7. Don't fight the user's terminal
 
 Setting raw mode? Restore it on every exit path, including uncaught
 exceptions. Setting the terminal title? Use OSC 0 and accept that
 non-TTYs won't see it. Hiding the cursor? Show it back on unmount.
 See `src/ui/terminal-restore.ts`. The user's `stty sane` recovery
 moments are user-trust-destroying — we don't get to have those.
 
-## 9. Don't commit aspirations
+## 8. Don't commit aspirations
 
-Per `CLAUDE.md` §2.4: never commit specs, governance docs, or policy
-files for systems that do not yet exist. This `.settings/` folder
-describes what's *in the code today*, not what we'd like to build.
-If we add a feature, the docs follow the code — not the other way.
+Never commit specs, governance docs, or policy files for systems that do
+not yet exist. This `.settings/` folder describes what's *in the code
+today*, not what we'd like to build. If we add a feature, the docs follow
+the code — not the other way.
 
-## 10. Ship something you'd use
+## 9. Ship something you'd use
 
 The author runs this in production for daily development. Bugs that
 annoy us get fixed first. Features no one uses get deleted. This is a

CLAUDE.md

@@ -8,10 +8,8 @@ TUI, tools, slash commands, permissions, OAuth, sessions, and the headless
 / JSON-RPC entry points; pi-mono owns the agent loop and provider
 protocols.
 
-Goal: a **better Claude Code** — simpler architecture, any LLM provider,
-single `npm i -g` install. Not a clone. We study CC's source as a feature-coverage
-benchmark and to learn from their architectural mistakes; we do not copy
-their code or prompt wording verbatim (open-source IP discipline).
+Goals: simple architecture, any LLM provider, single `npm i -g` install,
+designed to fit cleanly in a terminal session.
 
 For deep context, read [`.settings/`](.settings/) first — `tenets.md`,
 `architecture.md`, `extending.md`, `testing.md`. Those are the canonical
@@ -144,36 +142,31 @@ CODEBASE_SCOPES         override requested scopes
 - Don't commit aspirational documentation. The code is the spec; docs
   follow the code.
 
-## Competitive context: Claude Code
+## Architectural shape
 
-We have CC's source as a benchmark. The tenets we hold differently:
+A few load-bearing decisions you should know going in:
 
-| Aspect | CC | codebase-cli |
-|---|---|---|
-| TUI framework | ink + 512K LOC | ink + ~22K LOC |
-| Tool interface | Each tool a snowflake; BashTool ~160K bytes | One `Tool` interface, ~45 implementations |
-| Permissions | AST parsers + ML classifiers + hook cascade | Effect-based policies, ~600 LOC |
-| State | 30+ field god object | Single immutable `ChatState`, reducer-driven |
-| Compaction | Three uncoordinated strategies | One proactive strategy with calibrated budget |
-| Distribution | Bun lock-in, custom bundler | Plain `npm i -g`, `tsc` only |
-| Providers | Anthropic-first | Any provider via pi-ai |
-
-The Ink-LOC contrast is the headline number: ink is fine; CC's *use* of
-it is the problem. Our thesis: 80% of CC's value in 5% of the code, by
-making better foundational choices.
-
-When you add a feature, ask: "how did CC do this, and what's a simpler
-way that avoids their pain points?"
+- **One `Tool` interface** for everything (~45 implementations in `src/tools/`).
+  Adding a tool is mechanical: declare effects, validate args with TypeBox,
+  export. No per-tool snowflakes.
+- **Effect-based permissions** (`reads_fs`, `writes_fs`, `runs_shell`,
+  `network`). Policies match on effects, not tool names. ~600 LOC total.
+- **Single immutable `ChatState`** driven by a typed reducer in
+  `src/agent/events.ts`. Every UI state transition flows through it; the
+  reducer is tested exhaustively in `events.test.ts`.
+- **One proactive compaction strategy** with a calibrated token budget.
+  See `src/compaction/`.
+- **Plain `npm i -g`** distribution. `tsc` only, no bundler.
 
 ## Recognized project files
 
 The CLI auto-loads these from the project root and injects them into
 the system prompt:
 
-- `AGENTS.md` (OpenAI Codex)
-- `CLAUDE.md` (Claude Code / this convention)
+- `AGENTS.md`
+- `CLAUDE.md`
 - `CODEX.md`
-- `.cursorrules` (Cursor)
+- `.cursorrules`
 
 ## Direct dependencies
 

docs/ARCHITECTURE.md

@@ -31,8 +31,6 @@ now TypeScript on top of `@earendil-works/pi-agent-core` + `@earendil-works/pi-a
 - Slash commands → `src/commands/`
 
 For the rationale behind those choices, read [`.settings/tenets.md`](../.settings/tenets.md).
-The "what CC got wrong" analysis in the old blueprint is preserved in
-condensed form in [`CLAUDE.md`](../CLAUDE.md#competitive-context-claude-code).
 
 The full prior document is available in git history; `git log --follow docs/ARCHITECTURE.md`
 finds the commits.