docs(dox): add repository guidance

Add a DOX hierarchy for CLI source, docs, benchmarks, scripts, and extension ownership boundaries.

Author: codebase-cli

.settings/AGENTS.md

@@ -0,0 +1,22 @@
+# DOX: CLI Settings
+
+## Purpose
+
+- Own durable architecture notes, standards, testing notes, and planning material for the CLI.
+
+## Local Contracts
+
+- Keep settings docs aligned with current source and package scripts.
+- Do not store secrets, local credentials, or personal machine paths unless they are examples.
+
+## Work Guidance
+
+- Put broad standards here; put source-local operational contracts in `src/**/AGENTS.md`.
+
+## Verification
+
+- Run `git diff --check`.
+
+## Child DOX Index
+
+- No child DOX files yet.

AGENTS.md

@@ -0,0 +1,55 @@
+# DOX Framework
+
+- This repository uses the DOX `AGENTS.md` hierarchy: root instructions apply everywhere, and child `AGENTS.md` files add binding local contracts for their subtrees.
+- Before editing, read this file and every `AGENTS.md` on the path to each target. If a parent index points to a child that covers the target, read that child too.
+- If instructions conflict, the closest `AGENTS.md` controls local details, but child docs must not weaken root security, quality, release, or DOX rules.
+- After meaningful changes, update the closest owning `AGENTS.md` when purpose, contracts, workflows, verification, artifacts, or child indexes changed.
+- Keep DOX docs operational: document stable contracts and current checks, not diary notes or aspirational systems.
+
+## Project Purpose
+
+- `codebase-cli` is the open-source terminal agent for Codebase. It provides an interactive TUI, headless mode, model/provider routing, tools, MCP, auth, memories, permissions, hooks, subagents, tournaments, and release packaging.
+
+## Repository Map
+
+- `src/` — TypeScript source for the CLI and all runtime subsystems.
+- `bin/` — executable shim published as the `codebase` binary.
+- `dist/` — generated build output; do not edit by hand.
+- `docs/` — user/developer reference documentation.
+- `.settings/` — durable architecture, testing, and extension notes.
+- `bench/` — benchmark scenarios, runner, and reports.
+- `scripts/` — release/build/support automation.
+- `vscode-extension/` — companion editor extension.
+- `Formula/` — package-manager/release packaging assets.
+
+## Local Contracts
+
+- Keep the CLI safe-by-default: filesystem, shell, SSH, MCP, hooks, subagents, and git tools must validate paths, permissions, and command effects.
+- Preserve cross-platform behavior for macOS/Linux/Windows unless a file explicitly scopes itself.
+- Do not log API keys, OAuth tokens, refresh tokens, credentials file contents, MCP secrets, or user clipboard/image data.
+- Treat tests as part of the public contract. When behavior changes, update the matching `*.test.ts` file or document the intentional gap.
+- Generated `dist/` files are build artifacts. Source changes belong in `src/`.
+
+## Work Guidance
+
+- Prefer small focused modules with colocated tests.
+- Keep command UX plain and terminal-friendly; avoid hidden network calls or file mutations without permission flow.
+- Use existing abstractions from `pi` packages and local subsystem APIs rather than parallel agent/tool frameworks.
+
+## Verification
+
+- Standard gate: `npm run check`.
+- Type-only: `npm run typecheck`.
+- Lint/format: `npm run lint`, `npm run lint:fix`, or `npm run format`.
+- Tests: `npm test` or targeted `npx vitest --run <file>`.
+- Build/release packaging: `npm run build`; `npm run prepublishOnly` before publishing.
+- Documentation-only edits: `git diff --check`.
+
+## Child DOX Index
+
+- `src/AGENTS.md` — CLI source architecture and subsystem index.
+- `docs/AGENTS.md` — user/developer docs.
+- `.settings/AGENTS.md` — durable project standards and planning material.
+- `bench/AGENTS.md` — benchmarks.
+- `scripts/AGENTS.md` — automation scripts.
+- `vscode-extension/AGENTS.md` — companion VS Code extension.

bench/AGENTS.md

@@ -0,0 +1,25 @@
+# DOX: Benchmarks
+
+## Purpose
+
+- Own benchmark scenarios, runner scripts, aggregate reports, and benchmark result artifacts.
+
+## Local Contracts
+
+- Benchmark scenarios must be reproducible and should document model/provider assumptions.
+- Do not treat benchmark results as marketing claims unless methodology and dates are included.
+- Keep generated result files separate from source scenarios.
+
+## Work Guidance
+
+- Prefer small scenario fixtures with explicit expected behavior.
+- Record environment details when adding new result artifacts.
+
+## Verification
+
+- Run `npm run bench` or targeted benchmark scripts when changing runner/scenario behavior.
+- Run `npm run bench:report` after changing aggregation.
+
+## Child DOX Index
+
+- No child DOX files yet.

docs/AGENTS.md

@@ -0,0 +1,25 @@
+# DOX: CLI Docs
+
+## Purpose
+
+- Own user/developer documentation for installing, migrating, configuring, and operating the CLI.
+
+## Local Contracts
+
+- Keep command names, flags, shortcuts, and config paths aligned with source code.
+- Do not document unreleased behavior as available unless clearly marked.
+- Avoid fabricated claims about provider support, benchmarks, or security guarantees.
+
+## Work Guidance
+
+- Prefer runnable examples and concise troubleshooting steps.
+- Link to source-owned settings when docs describe extension/config behavior.
+
+## Verification
+
+- Run `git diff --check`.
+- For command docs, verify the command exists in `src/commands/` or CLI help.
+
+## Child DOX Index
+
+- No child DOX files yet.

scripts/AGENTS.md

@@ -0,0 +1,25 @@
+# DOX: Scripts
+
+## Purpose
+
+- Own release, build, migration, and support automation scripts outside `src/`.
+
+## Local Contracts
+
+- Scripts must fail loudly on missing prerequisites and should avoid destructive actions unless explicitly named/flagged.
+- Do not print secrets, auth tokens, npm tokens, or local credential contents.
+- Keep release scripts aligned with `package.json` scripts.
+
+## Work Guidance
+
+- Prefer idempotent scripts and clear usage output.
+- Keep generated outputs out of source control unless intentionally versioned.
+
+## Verification
+
+- Run script help/dry-run where available.
+- Run `git diff --check`.
+
+## Child DOX Index
+
+- No child DOX files yet.

src/AGENTS.md

@@ -0,0 +1,69 @@
+# DOX: CLI Source
+
+## Purpose
+
+- Own all TypeScript runtime source for the terminal CLI, including agent orchestration, tools, TUI, auth, MCP, memory, permissions, hooks, config, sessions, and headless/server modes.
+
+## Ownership
+
+- `agent/` owns model-turn orchestration and agent-level features.
+- `tools/` owns tool implementations and permission/effect boundaries.
+- `ui/` and `ui-pi/` own interactive terminal interfaces.
+- `auth/` owns cloud auth, OAuth, token refresh, and credential storage.
+- `mcp/` owns MCP config, clients, protocol translation, and tool adaptation.
+- `memory/` owns durable memory extraction/injection/store.
+- `permissions/` owns command/effect allow/block state.
+- `commands/` owns slash-command registry and command handlers.
+- `config/` owns local/global config stores and output styles.
+- `hooks/` owns lifecycle hook loading/execution.
+- `sessions/` and `checkpoint/` own durable conversation/file-state rollback data.
+- `skills/`, `subagents/`, `ssh/`, `plan/`, `projects/`, and `app-server/` own their named subsystems.
+
+## Local Contracts
+
+- Public command behavior and CLI flags are user-facing API.
+- Tool effects must be explicit and permission-aware.
+- Path handling must resolve inside the intended cwd/worktree and handle symlinks/platform temp paths carefully.
+- Long-running work must stream status and remain interruptible.
+- Tests should avoid relying on host-specific absolute temp path spellings.
+
+## Work Guidance
+
+- Keep tests near source files and name them `<module>.test.ts`.
+- Prefer dependency injection for network/filesystem/process boundaries so tests can run offline.
+- Avoid importing from `dist/`; source imports should target `src/` modules.
+
+## Verification
+
+- Run targeted Vitest for touched subsystem files.
+- Run `npm run check` for cross-cutting source changes.
+- Run `npm run build` after changes affecting exported types, bin entrypoints, or package output.
+
+## Child DOX Index
+
+- `agent/AGENTS.md` — agent orchestration, tournament, rewind, prompts, models.
+- `tools/AGENTS.md` — tool implementations and permission boundaries.
+- `ui/AGENTS.md` — React/Ink TUI.
+- `ui-pi/AGENTS.md` — pi-based TUI/runtime widgets.
+- `auth/AGENTS.md` — OAuth/cloud credentials.
+- `mcp/AGENTS.md` — MCP clients/config/tool bridge.
+- `memory/AGENTS.md` — durable memory.
+- `permissions/AGENTS.md` — permission stores and command-prefix policy.
+- `commands/AGENTS.md` — slash commands and registry.
+- `config/AGENTS.md` — config, local LLM, output styles.
+- `hooks/AGENTS.md` — lifecycle hooks.
+- `sessions/AGENTS.md` — session persistence.
+- `checkpoint/AGENTS.md` — file/conversation checkpoint state.
+- `compaction/AGENTS.md` — conversation compaction and token budgeting.
+- `diagnostics/AGENTS.md` — health/check diagnostics.
+- `dotenv/AGENTS.md` — environment file loading.
+- `glue/AGENTS.md` — cloud glue APIs for intent/narration.
+- `headless/AGENTS.md` — non-interactive CLI runner.
+- `projects/AGENTS.md` — cloud project APIs and project commands.
+- `clipboard/AGENTS.md` — clipboard copy/image handling.
+- `user-queries/AGENTS.md` — queued user query persistence.
+- `skills/AGENTS.md` — skill loaders and registry.
+- `ssh/AGENTS.md` — SSH host config and command execution.
+- `subagents/AGENTS.md` — subagent definitions.
+- `plan/AGENTS.md` — plan mode.
+- `app-server/AGENTS.md` — local app/server protocol.

src/agent/AGENTS.md

@@ -0,0 +1,26 @@
+# DOX: Agent
+
+## Purpose
+
+- Own agent turn orchestration, project-file context, prompts, model routing, effort settings, event streams, rewind, WIP snapshots, and tournament workflows.
+
+## Local Contracts
+
+- Agent state changes must emit stable events consumed by UI/headless flows.
+- Rewind and checkpoint behavior must keep conversation and filesystem state consistent.
+- Tournaments must isolate contestant worktrees and avoid merging failed/unsafe outputs.
+- Model selection should respect user config, live overrides, local/cloud capability, and BYOK settings.
+
+## Work Guidance
+
+- Keep prompt changes paired with tests that assert critical invariants.
+- Use existing event types rather than ad hoc UI strings as contracts.
+
+## Verification
+
+- Run `npx vitest --run src/agent`.
+- For tournament/worktree changes, include real-worktree tests when feasible.
+
+## Child DOX Index
+
+- No child DOX files yet.

src/app-server/AGENTS.md

@@ -0,0 +1,24 @@
+# DOX: App Server
+
+## Purpose
+
+- Own the local app-server protocol and server used to communicate with companion app/UI surfaces.
+
+## Local Contracts
+
+- Keep protocol messages versioned or backwards-compatible when possible.
+- Validate inbound messages before dispatching work.
+- Do not expose localhost server capabilities beyond intended clients without auth/origin checks.
+
+## Work Guidance
+
+- Keep protocol definitions central in `protocol.ts`.
+- Test request/response and lifecycle behavior with server tests.
+
+## Verification
+
+- Run `npx vitest --run src/app-server`.
+
+## Child DOX Index
+
+- No child DOX files yet.

src/auth/AGENTS.md

@@ -0,0 +1,25 @@
+# DOX: Auth
+
+## Purpose
+
+- Own cloud authentication: browser/device OAuth flows, callback server, PKCE, token exchange/refresh, credential file storage, CLI auth commands, and credential validation.
+
+## Local Contracts
+
+- Credential files must be permission-hardened and never logged in full.
+- Refresh/token exchange code must handle expiry, invalid JSON, version mismatch, and concurrent refresh safely.
+- OAuth state, PKCE verifier, and redirect handling must defend against replay/mismatch.
+
+## Work Guidance
+
+- Keep network calls injectable for tests.
+- Prefer clear recovery messages that tell users how to re-authenticate.
+
+## Verification
+
+- Run `npx vitest --run src/auth`.
+- Run `npm run check` for credential or token-manager changes.
+
+## Child DOX Index
+
+- No child DOX files yet.

src/checkpoint/AGENTS.md

@@ -0,0 +1,24 @@
+# DOX: Checkpoint
+
+## Purpose
+
+- Own checkpoint storage used to rewind file and conversation state after tool actions.
+
+## Local Contracts
+
+- Checkpoints must capture enough state to undo edits without disturbing unrelated user changes.
+- Store paths must stay project-scoped and safe for concurrent sessions where practical.
+- Rewind behavior must clearly report what was restored and what could not be restored.
+
+## Work Guidance
+
+- Keep checkpoint metadata explicit and versionable.
+- Test dirty-tree, untracked-file, and missing-file scenarios when changing store behavior.
+
+## Verification
+
+- Run `npx vitest --run src/checkpoint` and related `agent/conversation-rewind` tests.
+
+## Child DOX Index
+
+- No child DOX files yet.