docs(settings): add practical guides for extending and testing

Walk-throughs for adding a tool, slash command, provider, permission
policy, glue task, and microbench, plus the test conventions used in the
existing suite. Separates "what is this" (already shipped) from "how do
I work in it" so neither doc gets unwieldy.

Author: halfaipg

.settings/extending.md

@@ -0,0 +1,173 @@
+# Extending the CLI
+
+How to add the three most common things. Patterns are stable; if you need to
+deviate, find an existing example first and follow it.
+
+## Add a tool
+
+Tools are self-contained modules in `src/tools/`. Each one exports a `Tool`
+that the agent registry picks up. The canonical small example is
+`src/tools/glob.ts`. Copy its shape:
+
+```ts
+// src/tools/my-tool.ts
+import { Type } from "@sinclair/typebox";
+import type { Tool } from "./types.js";
+
+export const myTool: Tool = {
+  name: "my_tool",
+  description: "One-line summary the model sees. Be specific; this drives selection.",
+  parameters: Type.Object({
+    target: Type.String({ description: "What to operate on" }),
+    mode: Type.Optional(Type.Union([Type.Literal("fast"), Type.Literal("safe")])),
+  }),
+  effects: ["reads_fs"], // or ["writes_fs"], ["runs_shell"], ["network"]
+  execute: async (args, ctx) => {
+    // ctx.cwd, ctx.permissions, ctx.abortSignal, ctx.tasks, ctx.fileStateCache
+    // Return a string (default), or { content, isError } for richer outputs.
+    return "result string";
+  },
+};
+```
+
+Then register it in `src/tools/registry.ts` (alphabetical, please):
+
+```ts
+import { myTool } from "./my-tool.js";
+// ...
+export const BUILTIN_TOOLS = [
+  // ...
+  myTool,
+];
+```
+
+**Test it.** Drop `src/tools/my-tool.test.ts` next to the source. Use
+`makeToolContext` from `src/tools/__test__/mock-tool-context.ts` for the
+context fixture — don't hand-roll `{} as any`. Vitest convention is
+`describe(toolName, () => { ... })`.
+
+**Display polish.** Add a present-tense + past-tense label in
+`src/ui/tool-labels.ts`:
+
+```ts
+// In toolActionLabel:
+case "my_tool":
+  return `Doing ${displayPath(str("target"))}`;
+// In toolActionPast:
+case "my_tool":
+  return `Did ${displayPath(str("target"))}`;
+```
+
+If your tool reads files and produces deterministic small output that
+collapses well in runs, add it to `COLLAPSIBLE_READ_TOOLS` in
+`src/ui/tool-call-line.tsx`.
+
+## Add a slash command
+
+Commands live in `src/commands/builtins.ts`. Add one:
+
+```ts
+const myCommand: Command = {
+  name: "my-thing",
+  aliases: ["mt"],
+  description: "What this does, ≤ 60 chars — shown in /help.",
+  // mutates: true,  // only if it changes session state (clear, compact)
+  handler: async (args, ctx) => {
+    // ctx.bundle, ctx.state, ctx.emit, ctx.clearDisplay, ctx.exit, ctx.registry
+    ctx.emit("did the thing");
+    return { handled: true };
+  },
+};
+```
+
+Then add it to `BUILTIN_COMMANDS` (alphabetical). The registry handles
+parsing, dispatch, unknown-command typo suggestions, and the help listing.
+
+Slash commands that need to render persistent assistant-style messages
+should call `bundle.appendSyntheticAssistantMessage(...)` (TODO: check the
+exact name in `src/agent/agent.ts`) rather than `emit()`, which is for
+short status lines.
+
+**Test it.** `src/commands/registry.test.ts` shows the pattern. Use
+`fakeCtx()` to construct the context; only fill the fields your handler
+reads.
+
+## Add an LLM provider
+
+The agent never talks to a provider directly — `@earendil-works/pi-ai`
+does. If the provider has an OpenAI-compatible API, you usually don't need
+to add anything: users set `OPENAI_BASE_URL` + `OPENAI_API_KEY` and the
+existing path handles it.
+
+For a provider that needs a new protocol adapter, the work lives upstream
+in pi-ai, not here. Open an issue / PR on `@earendil-works/pi-ai` first;
+once it lands, expose it in our config layer:
+
+- Add a model entry to `src/config/models.ts` (look for the existing
+  Groq / Anthropic / OpenRouter entries as templates).
+- Add credential resolution to `src/auth/credentials.ts` if it needs
+  a non-standard env var or OAuth flow.
+- Add provider-specific display tweaks (icon, label, etc.) if the
+  default rendering looks off.
+
+The first-run wizard (`src/ui/FirstRunSetup.tsx`) auto-detects available
+provider credentials and offers them as options — no hardcoded provider
+list to maintain in the wizard.
+
+## Add a permission policy
+
+Effect-based, not tool-name-based. Policies live in
+`src/permissions/policies.ts`. To pre-approve a category:
+
+```ts
+{
+  match: (req) => req.effects.includes("reads_fs") && isInsideCwd(req.args.path),
+  decision: "allow",
+  reason: "read-only access inside cwd is auto-approved",
+}
+```
+
+To pre-deny:
+
+```ts
+{
+  match: (req) => req.effects.includes("runs_shell") && isDangerous(req.args.command),
+  decision: "deny",
+  reason: "dangerous shell command",
+}
+```
+
+The store evaluates policies in order until one matches; otherwise the
+user is prompted.
+
+## Add a glue task
+
+Glue is the cheap/fast sidecar model. Routing, narration, plan-mode Q&A,
+prompt suggestions all live here.
+
+A glue call should:
+- Have a graceful fallback when the glue model is unconfigured or fails.
+- Be cheap to abort — wrap the network call with `AbortController`.
+- Never feed its output into the main agent's context. Glue is for *UI
+  enrichment*, not agent reasoning.
+
+The pattern in `src/agent/prompt-suggestion.ts` is the template: small
+prompt, abort signal threaded through, silent failure mode.
+
+## Add a microbenchmark
+
+If you're touching a hot path (reducer, coalesce, diff, wrap), add a bench
+case to `src/agent/events.bench.ts` (or a peer `*.bench.ts` file).
+`npm run bench:micro` runs them. They're not part of `npm test` so they
+don't slow CI — but they give us a baseline number to spot regressions.
+
+## What NOT to extend
+
+- **Don't add a new chat-state field unless every reducer branch handles it.**
+  ChatState is the single source of truth for what the UI shows; partial
+  fields produce mysterious render bugs.
+- **Don't reach into pi-agent-core's internals.** If you need something the
+  public API doesn't give you, the fix is upstream.
+- **Don't add a separate persistence file format for new state.** Sessions,
+  history, memory, credentials, and tasks each have one canonical JSON
+  schema. Add fields, don't add sidecars.

.settings/testing.md

@@ -0,0 +1,127 @@
+# Testing
+
+## Stack
+
+- **Runner**: vitest 2.x. Config: `vitest.config.ts`. Tests are `*.test.ts`
+  / `*.test.tsx` colocated with source.
+- **Bench runner**: vitest's built-in bench. Files are `*.bench.ts`. Run
+  with `npm run bench:micro` (separate from `npm test`).
+- **Lint**: biome (`biome.json`). Run with `npm run lint`, autofix with
+  `npm run lint:fix`.
+- **Type check**: `npm run typecheck` (`tsc --noEmit`).
+- **Full pre-publish gate**: `npm run check` (typecheck + lint + test).
+
+## Run them
+
+```sh
+npm test                     # all unit tests
+npm test -- --watch          # watch mode (or `npm run test:watch`)
+npm test -- src/agent        # filter by path
+npm test -- -t "user-prompt" # filter by test name
+npm run bench:micro          # microbenchmarks
+npm run bench                # end-to-end LLM benchmarks (needs API key)
+```
+
+## Conventions
+
+### Colocation
+
+`src/foo/bar.ts` ↔ `src/foo/bar.test.ts`. Always next to the source.
+Centralized `test/` folders are an anti-pattern in this repo.
+
+### Test names describe behavior, not the function
+
+Good: `it("appends a user message and flips status to thinking")`
+Bad: `it("user-prompt action works")`
+
+The test name is the spec. Write it so a failure tells you what broke
+without reading the test body.
+
+### Use the typed mock context, not `{} as any`
+
+`src/tools/__test__/mock-tool-context.ts` provides `makeToolContext()` for
+constructing a tool context with sensible defaults you can override field
+by field. Don't hand-roll. If a tool needs a context field that mock
+doesn't have, add it to the factory.
+
+For commands, `src/commands/registry.test.ts::fakeCtx()` is the pattern.
+
+### Don't mock the filesystem in filesystem tools
+
+`vitest` runs tests in parallel by default, but the filesystem tools use
+`mkdtemp` and clean up in `afterEach`. Look at `src/tools/read-file.test.ts`
+or `src/tools/edit-file.test.ts` for the template. Mocked filesystems
+historically hide real bugs (path normalization, symlink handling, race
+conditions) — we don't.
+
+### E2E: use pi-ai's faux provider
+
+`src/agent/__test__/agent-e2e.test.ts` is the reference. `registerFauxProvider`
+from `@earendil-works/pi-ai` lets you drive the full agent loop —
+real reducer, real tool execution, real session persistence — with a
+scripted LLM response stream. No network. Deterministic.
+
+When you need an integration test that crosses agent + tools + UI state,
+this is the right tool. Don't reinvent it.
+
+### Reducers and pure functions get exhaustive tests
+
+`src/agent/events.test.ts` covers every Action variant and every
+AgentEvent type. If you add a branch, add a test in the same PR. The
+reducer is load-bearing — every state transition for every user goes
+through it.
+
+### The TUI doesn't have automated tests yet
+
+Render-layer testing (snapshotting `<App>` output, simulating keystrokes
+via `ink-testing-library`) is a known gap. Don't claim a UI change
+"works" because tests pass — type-check ≠ feature-correct for the
+rendering layer. Manually exercise the change in a real terminal.
+
+If you're adding a TUI test framework, `ink-testing-library` is the
+right choice. Open a PR; we want this.
+
+### Network-dependent tests need a guard
+
+Anything that hits a real API (web_fetch, web_search, OAuth refresh)
+needs an `it.skipIf(!process.env.NETWORK_TESTS_ENABLED)` or equivalent —
+they can't be in the default `npm test` path because contributors
+without API keys would fail their pre-commit.
+
+`src/tools/web-fetch.test.ts` uses a local mock HTTP server. That's the
+preferred pattern; only escape to live API if there's no other way.
+
+### Benchmarks don't replace tests
+
+A bench tells you *how fast*. A test tells you *whether correct*. If you
+have only a bench, you don't know it's correct. If you have only tests,
+you don't know it's fast. The reducer has both for a reason.
+
+## What's worth testing first
+
+When you walk into an unfamiliar module and want confidence:
+
+1. **Pure functions with branchy logic**. `parseAnswer` (plan), `matchOption`
+   (plan), `mergeUsage` (reducer helper), `displayPath` (UI), `truncate`,
+   `wrapText`, anything with a switch statement.
+2. **State machines.** The reducer. The session router. The OAuth state
+   transitions.
+3. **Parsers and serializers.** `extractJson`, `parseRunArgs`, the message
+   stream coalescer.
+4. **Filesystem-touching tools.** Read, edit, multi-edit, write, glob, grep.
+   Real mkdtemp, real assertions, no mocks.
+5. **Permission policies.** Effect matching + path / URL pattern matching.
+
+What's hard to test in this codebase:
+
+- The interactive TUI render output (no harness yet — see above).
+- Real-network tools (need either VCR-style fixtures or skip guards).
+- Streaming timing (the 16ms coalesce). Can be tested in microbench but
+  hard to assert on in unit tests.
+
+## CI
+
+Pre-publish runs `npm run check` automatically (via `prepublishOnly`).
+There is no separate GitHub Actions config committed to this repo yet —
+the test gate is local. If you're contributing externally, run `npm run check`
+before opening a PR; it's the same gate `npm publish` enforces.