agent-afk 2.3.1 → 2.4.0

package/README.md

@@ -1,18 +1,23 @@
 # Agent AFK CLI
 
-> A TypeScript CLI, daemon, and Telegram bot for running Claude via `@anthropic-ai/claude-agent-sdk` — ships seven orchestration skills as subagents and mirrors the `agent-framework-private` plugin surface.
+> A TypeScript CLI, daemon, and Telegram bot for running Claude (via `@anthropic-ai/sdk`) or OpenAI Codex — ships four orchestration skills as built-in subagent dispatchers with cross-session memory, DAG-composed waves, and background-task support.
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
 
 ## Features
 
-- 🚀 **Real Claude Agent SDK integration** — native subagents, hooks, elicitations, cost guardrails
-- 🧩 **Seven orchestration skills as CLI subagents** — `/mint`, `/diagnose`, `/shadow-verify`, `/forge`, `/parallelize`, `/forge-gate-check`, `/forge-l2-eval`
-- 🔌 **Plugin skill-router** — skills under `~/.afk/plugins/*/skills/` auto-exposed as slash commands
-- 🏠 **AFK-scoped config** — `~/.afk/` independent of `~/.claude/`, with `afk plugin install/update/list/remove`
+- 🚀 **Provider abstraction** — Anthropic (direct) and OpenAI Codex; native subagents, hooks, elicitations, cost guardrails
+- 🧩 **Four built-in orchestration skills** — `/mint`, `/diagnose`, `/forge`, `/audit-fit`, each dispatched as an isolated subagent
+- 🧠 **Cross-session memory** — `memory_search`, `memory_update`, `procedure_write` tools backed by SQLite + `HOT.md`
+- 🕸️ **DAG-composed parallel waves** — built-in `compose` tool runs subagent nodes with dependency edges and fail-fast
+- ⏱️ **Background tasks** — Ctrl+B detaches the current turn; `/bg`, `/tasks`, `/attach` manage long-running work
+- 📲 **`send_telegram` built-in tool** — agents can push terminal-state notifications to the operator
+- 🔌 **Plugin & marketplace install** — `afk plugin install` / `afk marketplace add` keep everything under `~/.afk/`
+- 🏠 **AFK-scoped config** — `~/.afk/` independent of `~/.claude/`, with sessions, plugins, agents, commands, skills
 - 💬 **Three surfaces** — interactive REPL, daemon, Telegram bot sharing one session manager
 - 📊 **Routing telemetry** — every subagent dispatch appended to `~/.afk/agent-framework/routing-decisions.jsonl`
-- 🤖 **Multiple Claude models** — Opus, Sonnet, Haiku
+- 🤖 **Multiple models** — Opus, Sonnet, Haiku (Anthropic); GPT-5 family via Codex
+- 🧠 **Extended thinking on by default** — controllable via `AFK_THINKING` / `--thinking`
 - 🔓 **Bypass permissions mode** — no prompts, fully automated tool execution
 - 🛡️ **Type-safe** — TypeScript strict mode
 
@@ -35,7 +40,7 @@
 
 ### Prerequisites
 
-- **Node.js ≥ 18.0.0**
+- **Node.js ≥ 20.0.0** (enforced by `package.json#engines`)
 - **pnpm** — this project's lockfile is pnpm-specific. Running `npm install` will desync it.
   - Fastest path: `corepack enable` (bundled with Node ≥ 16.9), then use `pnpm` directly.
   - Or install globally: `npm install -g pnpm@latest`.
@@ -90,17 +95,21 @@ pnpm build
 
 ### CLI Commands
 
-The `afk` CLI exposes seven top-level commands registered in `src/cli/index.ts`:
+The `afk` CLI exposes eleven top-level commands registered in `src/cli/index.ts`:
 
 | Command | Purpose |
 |---|---|
 | `chat` | Single-turn message |
-| `interactive` | REPL with full Agent SDK features |
+| `interactive` | REPL with full Agent SDK features (default when invoked without a subcommand) |
 | `status` | Connection, API-key, model, bypass-mode status |
 | `config` | Dump resolved configuration |
 | `daemon` | Long-running headless agent (see `src/agent/daemon/`) |
 | `login` | OAuth flow for `console.anthropic.com` |
 | `plugin` | Manage `~/.afk/plugins/` (install / update / list / remove / enable / disable) |
+| `marketplace` | Add / list / remove plugin marketplaces under `~/.afk/marketplaces/` |
+| `doctor` | Environment self-check (Node version, API keys, paths, config) |
+| `completion` | Print a shell completion script (`zsh`, `bash`, `fish`) |
+| `telegram` | Manage the Telegram bot daemon (start, stop, status, logs, setup) |
 
 #### Chat (single message)
 
@@ -200,32 +209,32 @@ pnpm telegram:restart
 
 ## Orchestration Skills
 
-agent-afk ships seven built-in subagent orchestrators plus `devils-advocate` (in development). These are **skill-router-dispatched**: typing `/mint add dark mode` in the REPL parses the slash form, resolves it to a skill handler under `src/skills/<name>/`, and dispatches a fresh subagent via `SubagentManager.forkSubagent()`. Every dispatch is logged to `~/.afk/agent-framework/routing-decisions.jsonl`.
+agent-afk ships four built-in subagent orchestrators. These are **built-in skills** exposed through the slash registry: typing `/mint add dark mode` in the REPL parses the slash form, resolves it to a TypeScript handler under `src/skills/<name>/index.ts`, and dispatches a fresh subagent via `SubagentManager.forkSubagent()`. Every dispatch is logged to `~/.afk/agent-framework/routing-decisions.jsonl`.
+
+The canonical list lives in `src/skills/all.ts`:
 
 | Skill | Purpose |
 |---|---|
 | `/mint` | End-to-end feature/refactor pipeline: spec → research → plan → parallelize → build → verify → heal → ship |
 | `/diagnose` | Parallel hypothesis generation + validation for bugs and failing tests |
-| `/shadow-verify` | Adversarial re-derivation of sub-agent claims before you act on them |
-| `/forge` | Generate new skills autonomously, gated by L1 capability evals |
-| `/parallelize` | Transform a linear plan into dependency-aware parallel waves |
-| `/forge-gate-check` | Report whether `/forge` is thawed; rerun the L1 eval harness |
-| `/forge-l2-eval` | Run L2 capability evals (live sub-agent verdict probes) |
+| `/forge` | Generate new skills autonomously, gated by L1/L2 capability evals (gate-check is inlined; no separate `/forge-gate-check` skill) |
+| `/audit-fit` | Audit `~/.afk` artifacts (skills, commands, agents, hooks) for correct type categorization |
 
-The same seven skills ship in two surfaces:
+Skills surface in two shapes:
 
-- **CLI surface** (this repo) — TypeScript handlers under `src/skills/<name>/` invoked via `skill-router`.
-- **Plugin surface** — prompt-based `SKILL.md` files under `agent-framework-private/skills/<name>/`, invoked inside a Claude Code session.
+- **Built-in (this repo)** — TypeScript handlers under `src/skills/<name>/`, registered via `src/skills/all.ts` and bridged into the slash registry by `src/cli/slash/builtin-skills.ts`.
+- **Plugin / user** — `SKILL.md` files discovered under `~/.afk/plugins/<plugin>/skills/<skill>/` or `~/.afk/skills/<skill>/`, scanned at session start and auto-exposed as slash commands.
 
-Vendored subagents (`qualify`, `research-agent`, `contract`) live under `src/skills/_agents/` and are kept byte-equal with the upstream copies — drift is caught by `src/skills/_agents/vendored.test.ts`.
+Vendored subagents (`qualify`, `research-agent`, `contract`) live under `src/skills/_agents/` and are kept byte-equal with the upstream copies — drift is caught by tests in `src/skills/_agents/`.
 
-See the workspace-root [`SYSTEM.md`](../SYSTEM.md) for the topology, skill dependency graph, and multi-prompt loading convention.
+See [`AGENTS.md`](AGENTS.md) and [`CONTRIBUTING.md`](CONTRIBUTING.md) for repo conventions; the workspace-root [`SYSTEM.md`](../SYSTEM.md) covers the broader topology when present.
 
 ## Scripts
 
 ```bash
 # Build / dev
 pnpm build                  # tsc && node scripts/copy-prompts.js (markdown prompts → dist/)
+pnpm build:dist             # esbuild bundle into dist/ for release artifacts
 pnpm dev                    # tsx watch src/cli/index.ts
 pnpm start                  # node dist/cli/index.js
 pnpm start:chat             # shortcut for `chat`
@@ -235,26 +244,27 @@ pnpm clean                  # rm -rf dist
 
 # Testing
 pnpm test                   # vitest run (all)
-pnpm test:integration       # integration tests only
-pnpm test:e2e               # end-to-end tests only
+pnpm test:integration       # vitest run tests/integration  (note: dir not yet populated)
+pnpm test:e2e               # vitest run tests/e2e          (note: dir not yet populated)
 pnpm test:coverage          # with coverage report
 pnpm test:watch             # watch mode
 pnpm lint                   # tsc --noEmit (type-check only)
 
 # Telegram daemon
 pnpm telegram               # run in foreground
+pnpm telegram:setup         # interactive setup wizard (bot token, allowed chat IDs)
 pnpm telegram:start         # background service (launchd/systemd-style wrapper)
 pnpm telegram:stop
 pnpm telegram:status
 pnpm telegram:restart
+pnpm telegram:logs          # tail the background-service log
 
-# SDK dependency auditing
-pnpm audit:sdk              # regenerate docs/sdk-dependency.md snapshot
-pnpm audit:sdk:check        # CI gate — fail if new SDK symbols appear without a lock update
-pnpm audit:sdk:update-lock  # update .sdk-dependency.lock.json allowlist
+# Release
+pnpm release                # scripts/release.mjs — version bump + publish flow
+pnpm release:dry            # dry-run release flow (no git push / no npm publish)
 ```
 
-agent-afk is the only subrepo in its workspace that imports `@anthropic-ai/claude-agent-sdk` / `@anthropic-ai/sdk` directly. The `audit:sdk*` scripts track that surface mechanically and fail CI on unauthorized drift. See [`docs/sdk-dependency.md`](docs/sdk-dependency.md) and [`.sdk-dependency.lock.json`](.sdk-dependency.lock.json). When adding a new SDK import, run `pnpm audit:sdk:update-lock` and edit the lock entry's `reason` with a one-line justification before committing.
+> Note: `tests/integration/` and `tests/e2e/` directories are not yet populated — the live test suites live under `tests/agent/`, `tests/telegram/`, and colocated `*.test.ts` files in `src/`. The `test:integration` / `test:e2e` scripts are kept as placeholders for the planned split.
 
 ## Configuration
 
@@ -283,12 +293,17 @@ You can delete `~/.claude/` entirely and agent-afk still runs.
 Create a `.env` file in the project root:
 
 ```env
-# Required
+# Required (Anthropic provider)
 ANTHROPIC_API_KEY=sk-ant-api03-...
 
-# Optional
-CLAUDE_MODEL=sonnet                # opus | sonnet | haiku (default sonnet)
-TELEGRAM_BOT_TOKEN=1234567890:ABC...
+# Provider / model selection
+AFK_MODEL=sonnet                   # opus | sonnet | haiku (Anthropic) or codex (default sonnet)
+AFK_DEFAULT_SUBAGENT_MODEL=        # override default subagent model
+AFK_THINKING=on                    # on | off | <budget-tokens> — extended thinking (on by default)
+AFK_EFFORT=                        # low | medium | high — reasoning effort (Codex provider)
+AFK_MAX_OUTPUT_TOKENS=             # cap on output tokens per turn
+AFK_TEMPERATURE=                   # numeric override; provider-default if unset
+AFK_TIMEOUT_MS=                    # per-turn timeout
 
 # Cost guardrails (see SDK-native features below)
 AFK_MAX_BUDGET_USD=5.00
@@ -298,12 +313,32 @@ AFK_TASK_BUDGET=100000
 AFK_DISABLE_PROMPT_CACHE=          # 1 | true | yes | on disables; unset = enabled
 AFK_PROMPT_CACHE_TTL=1h            # 5m | 1h (default 1h)
 
-# Optional: Color output control
-# Set NO_COLOR=1 to disable colors (per https://no-color.org)
-# Unset or leave empty for auto-detection (disables in CI or piped output)
-NO_COLOR=
+# Cross-session memory & system prompt
+AFK_SYSTEM_PROMPT=                 # raw string — highest-priority override of AFK.md
+AFK_HOME=                          # override ~/.afk
+AFK_STATE_DIR=                     # override ~/.afk/state
+AFK_FRAMEWORK_DIR=                 # override ~/.afk/agent-framework
+AFK_AUTO_ROUTING=                  # auto-route bare slash inputs to skills
+
+# Telegram bot (foreground + background daemon + send_telegram tool)
+TELEGRAM_BOT_TOKEN=1234567890:ABC...
+AFK_TELEGRAM_BOT_TOKEN=            # alternative name accepted by setup wizard
+AFK_TELEGRAM_ALLOWED_CHAT_IDS=     # comma-separated chat IDs allowed to push to / receive from
+TELEGRAM_DATA_DIR=                 # override Telegram state dir (defaults under ~/.afk/state)
+TELEGRAM_VERBOSE=                  # 1 to log per-message details
+AFK_TELEGRAM_TRACE=                # 1 to dump raw bridge traffic
+
+# Debug / dev
+AFK_DEBUG=                         # 1 enables verbose logging
+AFK_DEBUG_CLIPBOARD=               # debug bracketed-paste / image-paste handling
+AFK_DUMP_PROMPT=                   # write resolved system prompt to a file
+
+# Color output (per https://no-color.org)
+NO_COLOR=                          # set to disable colors; unset = auto-detect (CI / pipes)
 ```
 
+The authoritative list of supported env vars lives in `src/` — search for `process.env.AFK_` or `process.env.TELEGRAM_` for the full surface. `.env.example` mirrors the most common ones.
+
 ### System Prompt Auto-Discovery
 
 agent-afk resolves the session system prompt through a 4-tier precedence chain (highest tier wins):
@@ -317,6 +352,8 @@ agent-afk resolves the session system prompt through a 4-tier precedence chain (
 
 **AFK.md format:** Plain Markdown, no frontmatter. The entire file content (trimmed) becomes the system prompt. Empty or whitespace-only files are treated as absent (tier 4 applies instead).
 
+**Bootstrapping AFK.md:** run `/init` in the REPL to scan the current project and generate a tailored `AFK.md` at the repo root. See `src/cli/slash/commands/init.ts`.
+
 **Provenance tracking:** When using `--dump-prompt`, the `systemPromptSource` field in the dump shows which tier won:
 - `"env:AFK_SYSTEM_PROMPT"` — tier 1
 - `"file:/abs/path/afk.config.json"` — tier 2
@@ -335,12 +372,19 @@ Defaults are tuned for `agent-afk`'s long-lived surfaces (daemon, Telegram bot)
 
 Markers never leak back into stored history — `cache-policy.ts` clones-and-stamps so the canonical `messages` array stays marker-free across iterations (accumulating markers would break prefix-hash matching). Implementation: [`src/agent/providers/anthropic-direct/cache-policy.ts`](src/agent/providers/anthropic-direct/cache-policy.ts).
 
-### Supported Models
+### Supported Models & Providers
+
+agent-afk speaks to two providers through a single abstraction (`src/agent/providers/`):
 
+**Anthropic (direct)** — default. Selects from:
 - **opus** — most capable, for complex tasks
 - **sonnet** — balanced performance and speed (default)
 - **haiku** — fastest, best for simple tasks
 
+**OpenAI Codex** (`@openai/codex-sdk`) — set `AFK_MODEL=codex` (or pass `--model codex`). Implementation lives in `src/agent/providers/openai-codex.ts`. Tune reasoning effort via `AFK_EFFORT=low|medium|high`.
+
+Per-session overrides: `--model <name>`, `--thinking <on|off|N>`, `--max-output-tokens <n>`, `--temperature <n>`.
+
 ## Plugins & Slash Commands
 
 ### Installing plugins
@@ -375,26 +419,66 @@ Advanced: AFK still auto-discovers any plugin dropped into `~/.afk/plugins/<name
 
 Plugin state (telemetry, ledger, briefs) writes to `~/.afk/agent-framework/` in the AFK runtime.
 
-### Plugin skills as slash commands
+### REPL slash commands
 
-Every skill loaded from `~/.afk/plugins/<plugin>/skills/*/SKILL.md` is exposed automatically in the interactive REPL as `/<skill-name>`. There is no per-skill handler code — agent-afk asks the SDK for its skill catalog at session start (`session.supportedCommands()`) and registers a passthrough handler per entry. Typing `/mint add dark mode` pipes the raw line into the SDK turn loop; the subprocess parses the slash form natively and dispatches to the plugin's skill, exactly the way Claude Code does it.
+The interactive REPL registers slash commands directly in TypeScript (`src/cli/slash/`) — they don't pass through to any external Claude Code subprocess. Categories:
 
+**Core / session control**
 - `/help` — list all available slash commands (built-in + plugin-loaded)
-- `/skills` — discover skills loaded from plugins
-- `/reload-plugins` — reload after editing SKILL.md files on disk
-
-Implementation lives in `src/cli/slash/plugin-skills.ts`; see the module header for the flow.
-
-### SDK-native features surfaced in the REPL
-
-agent-afk wires several Claude Agent SDK capabilities that Claude Code exposes natively, so they feel the same here:
-
-- **`/agents`** — lists Task-tool subagents loaded by the SDK (plugin + user + project scope). Agents are not user-invokable slashes; they're dispatch targets the model picks via the Task tool. The list shows name, description, and model override when present. Refresh with `/reload-plugins` after editing `~/.afk/agents/` or plugin agent definitions.
-- **`/tokens`** — renders the authoritative SDK breakdown of context usage: total vs model max, auto-compact threshold, top categories, system tools, MCP tools, agents, skills, slash commands, and the last-turn API usage. Falls back to local-stats aggregation when the SDK call can't be served (e.g., before the subprocess is warm).
-- **Status-line context %** — sampled every 3 turns from `session.getContextUsage()`, cached between samples, degrades gracefully on transient failures. See `src/cli/context-sampler.ts`.
-- **Progress banners** — when the SDK emits `task_progress` events (long subagent runs, multi-tool flows), they render inline as `◦ description (stats)` plus an indented summary when present. Telegram forwards the same lines with the existing edit-throttle, and prompt suggestions trail as `💡` lines below the response. Enabled by default via `agentProgressSummaries: true`.
-- **Cost guardrails** — pass `--max-budget-usd <n>` (or set `AFK_MAX_BUDGET_USD`) to abort the session cleanly on cost breach. `--task-budget <tokens>` (or `AFK_TASK_BUDGET`) is an advisory per-task token hint surfaced to the model so it can pace itself. Both work across `afk interactive`, `afk chat`, and the Telegram bot.
-- **MCP elicitations** — when an MCP server requests OAuth consent (e.g. Supabase re-auth), the REPL prints the server name, message, and URL, then asks `Continue? [y/N]`. Empty answer cancels; `n` declines; `y` accepts. Form-mode elicitations are auto-declined in v1 (tracked in `todo.md`). Handler is installed via `elicitationRouter.install(...)`; bridges can install their own.
+- `/exit`, `/quit` — leave the REPL
+- `/clear` — clear screen
+- `/compact` — manually compact conversation history
+- `/reset` — start a fresh session, discarding history
+
+**Information**
+- `/cost` — running cost for the session
+- `/tokens` (alias `/ctx`) — SDK breakdown of context usage
+- `/history` — print prior turns
+- `/model` — show or switch active model
+- `/tools` — list registered tools
+- `/mcp` — show MCP server status
+- `/limits` — show rate-limit / budget state
+- `/debug` — toggle verbose debug output
+
+**Planning & state**
+- `/plan` — open the plan editor
+- `/todo` — manage the persistent todo list
+- `/save` — snapshot session state to disk
+- `/resume` — resume a saved session
+- `/init` — scan the current project and write `AFK.md`
+- `/changelog` — render `CHANGELOG.md` paginated
+
+**Background tasks** (Ctrl+B detaches the current turn)
+- `/bg` — list backgrounded tasks
+- `/tasks` — show running/queued tasks with status
+- `/attach <id>` — re-attach to a backgrounded task
+
+**Skills (built-in)** — see [Orchestration Skills](#orchestration-skills)
+- `/mint`, `/diagnose`, `/forge`, `/audit-fit`
+
+**Plugins / marketplaces**
+- `/skills` (alias `/builtin-skills`) — discover skills loaded from plugins & user scope
+- `/agents` — list Task-tool subagents loaded by the SDK
+- `/reload-plugins` — re-scan plugin and user directories after edits
+
+Implementation: `src/cli/slash/index.ts` (`registerAll()`), individual command modules under `src/cli/slash/commands/`. Plugin-discovered skills (`~/.afk/plugins/<plugin>/skills/<skill>/SKILL.md` and `~/.afk/skills/<skill>/SKILL.md`) are registered via `src/cli/slash/builtin-skills.ts` and `src/cli/slash/plugin-skills.ts`.
+
+### Runtime features surfaced in the REPL
+
+agent-afk wires several capabilities on top of the provider abstraction:
+
+- **Cross-session memory** — three built-in tools (`memory_search`, `memory_update`, `procedure_write`) backed by SQLite at `~/.afk/agent-framework/memory/`. `HOT.md` is injected into every future session's system prompt for durable essentials. See `src/agent/memory/` and `src/agent/tools/handlers/memory-*.ts`.
+- **`compose` tool — DAG-based orchestration** — agents (and the main session) can dispatch up to 20 subagent nodes with explicit dependency edges. Independent nodes run in parallel; dependent nodes wait. Fail-fast cancels downstream nodes by default. See `src/agent/tools/compose-executor.ts` and `src/agent/dag.ts`.
+- **Background tasks** — Ctrl+B in the REPL detaches the current turn into a tracked background task. `/bg` lists tasks, `/tasks` shows status, `/attach <id>` re-attaches. Status bar at the bottom of the REPL surfaces running task counts. Implementation: `src/cli/background-status-bar.ts`, `src/cli/commands/interactive/background.js`.
+- **`send_telegram` built-in tool** — agents can push terminal-state notifications to the operator. Recipients are gated by `AFK_TELEGRAM_ALLOWED_CHAT_IDS`; safe to attempt unconditionally (returns an error if Telegram is unconfigured). Handler: `src/agent/tools/handlers/send-telegram.ts`.
+- **Extended thinking on by default** — Anthropic's thinking budget is auto-enabled. Override per-session with `--thinking on|off|<budget-tokens>` or globally with `AFK_THINKING`.
+- **`/tokens`** — authoritative breakdown of context usage: total vs model max, auto-compact threshold, top categories, system tools, MCP tools, agents, skills, slash commands, and the last-turn API usage.
+- **Status-line context %** — sampled every few turns from `session.getContextUsage()`, cached between samples, degrades gracefully on transient failures. See `src/cli/context-sampler.ts`.
+- **Progress banners** — when the provider emits `task_progress` events (long subagent runs, multi-tool flows), they render inline as `◦ description (stats)` with an indented summary when present. Telegram forwards the same lines with edit-throttling, and prompt suggestions trail as `💡` lines below the response.
+- **Cost guardrails** — `--max-budget-usd <n>` / `AFK_MAX_BUDGET_USD` aborts on cost breach. `--task-budget <tokens>` / `AFK_TASK_BUDGET` is an advisory per-task hint surfaced to the model.
+- **MCP elicitations** — when an MCP server requests OAuth consent (e.g. Supabase re-auth), the REPL prints the server name, message, and URL, then asks `Continue? [y/N]`. Empty cancels; `n` declines; `y` accepts. Form-mode elicitations are auto-declined in v1. Handler: `src/agent/elicitation-router.ts`.
+- **Clipboard image paste** — paste images directly into the REPL (macOS pasteboard; bracketed-paste-aware). See `src/cli/input/clipboard-image.ts`.
+- **Auto-update check** — startup checks for a newer published version and prints a notice. Suppress with `afk --no-update-check`. Policy field `updatePolicy` (`notify`|`auto`|`off`) lives in `afk.config.json`. Implementation: `src/cli/update-checker.ts`.
 
 ## Bypass Permissions Mode
 
@@ -457,7 +541,17 @@ agent-afk/
 ├── src/
 │   ├── cli/
 │   │   ├── index.ts                # CLI entry (commander)
-│   │   └── commands/               # chat, interactive, status, config, daemon, login, plugin, skill-router
+│   │   ├── commands/               # chat, interactive, status, config, daemon,
+│   │   │                           # login, plugin, marketplace, doctor,
+│   │   │                           # completion, telegram, etc.
+│   │   ├── slash/                  # REPL slash registry + commands/
+│   │   │                           # (help, plan, todo, bg, tasks, attach,
+│   │   │                           #  init, changelog, builtin-skills, …)
+│   │   ├── input/                  # raw-mode, bracketed paste, clipboard images
+│   │   ├── background-status-bar.ts
+│   │   ├── context-sampler.ts
+│   │   ├── update-checker.ts
+│   │   └── config.ts, shared-helpers.ts
 │   ├── agent/
 │   │   ├── session.ts              # AgentSession barrel
 │   │   ├── session/                # agent-session, query-options, …
@@ -466,8 +560,13 @@ agent-afk/
 │   │   ├── subagent-hooks.ts
 │   │   ├── routing-telemetry.ts    # appends routing-decisions.jsonl
 │   │   ├── daemon/                 # long-running headless agent
-│   │   ├── plugins/                # afk plugin install / update / remove / index-store
-│   │   ├── providers/              # provider abstraction
+│   │   ├── plugins/                # afk plugin install / update / remove
+│   │   ├── marketplaces/           # marketplace install / resolve / manifest
+│   │   ├── providers/              # anthropic-direct, openai-codex
+│   │   ├── memory/                 # cross-session memory + HOT.md loader
+│   │   ├── tools/                  # built-in tool dispatcher + handlers
+│   │   │                           # (compose, subagent, skills, memory_*,
+│   │   │                           #  send_telegram, …)
 │   │   ├── elicitation-router.ts
 │   │   ├── hook-registry.ts, hooks.ts, default-hook-registry.ts
 │   │   ├── permissions.ts, abort-graph.ts, dag.ts, message-queue.ts
@@ -475,33 +574,42 @@ agent-afk/
 │   │   ├── shadow-verify-nudge.ts
 │   │   └── types.ts, types/
 │   ├── skills/
+│   │   ├── all.ts                  # canonical skill registry
 │   │   ├── mint/                   # /mint
 │   │   ├── diagnose/               # /diagnose
-│   │   ├── shadow-verify/          # /shadow-verify
-│   │   ├── forge/                  # /forge
-│   │   ├── parallelize/            # /parallelize
-│   │   ├── forge-gate-check/       # /forge-gate-check
-│   │   ├── forge-l2-eval/          # /forge-l2-eval
-│   │   ├── devils-advocate/        # in development
-│   │   ├── _agents/                # vendored subagents (qualify, research-agent, contract)
+│   │   ├── forge/                  # /forge (gate-check inlined)
+│   │   ├── audit-fit/              # /audit-fit
+│   │   ├── _agents/                # vendored subagents (qualify,
+│   │   │                           #  research-agent, contract)
 │   │   ├── _lib/                   # prompt-loader, shared helpers
 │   │   ├── example-template/       # scaffold for new skills
-│   │   └── index.ts
-│   ├── telegram/                   # telegram bridge
+│   │   └── user-skills.ts          # lazy scan of ~/.afk/skills + project skills
+│   ├── telemetry/                  # shared telemetry schemas
+│   ├── telegram/                   # telegram bridge (setup wizard, push, etc.)
 │   ├── telegram.ts                 # telegram bot entry
 │   ├── utils/
 │   ├── paths.ts
 │   └── index.ts
 ├── tests/
-│   ├── integration/
-│   └── e2e/
+│   ├── agent/                      # cross-cutting integration suites
+│   └── telegram/                   # telegram bridge tests
 ├── scripts/
 │   ├── copy-prompts.js             # bundles src/**/*.md into dist/ after tsc
-│   ├── audit-sdk-dependency.ts
-│   └── telegram-manager.sh
-├── docs/
-│   └── sdk-dependency.md           # committed SDK symbol snapshot
-├── .sdk-dependency.lock.json       # SDK symbol allowlist (CI-gated)
+│   ├── build-dist.mjs              # esbuild release bundle
+│   ├── release.mjs                 # version bump + publish flow
+│   ├── generate-changelog.mjs
+│   ├── audit-sdk-dependency.ts     # (not yet wired into package.json)
+│   ├── colocate-tests.mjs
+│   ├── telegram-manager.sh
+│   └── verify-install.sh
+├── docs/                           # design notes, audits, failure geometry
+├── landing/                        # marketing site assets
+├── AGENTS.md
+├── CHANGELOG.md
+├── CLAUDE.md
+├── CONTRIBUTING.md
+├── afk.config.json.example
+├── verify.sh
 ├── pnpm-lock.yaml
 ├── package.json
 ├── tsconfig.json
@@ -519,26 +627,18 @@ pnpm lint                   # type-check without emitting
 
 `pnpm build` runs `tsc` and then `scripts/copy-prompts.js`, which copies every `src/**/*.md` file into `dist/` at matching relative paths. Skills read their prompts via `readFileSync` at import time, so those markdown files must live next to the compiled `.js` output.
 
-### SDK Dependency Tracking
-
-agent-afk is the only subrepo in its workspace that imports from `@anthropic-ai/claude-agent-sdk` or `@anthropic-ai/sdk`. That surface is tracked mechanically:
-
-- [`docs/sdk-dependency.md`](docs/sdk-dependency.md) — committed snapshot of every tracked symbol, its files, and runtime-vs-type classification.
-- [`.sdk-dependency.lock.json`](.sdk-dependency.lock.json) — allowlist with per-symbol `reason` fields. CI fails when a new symbol or kind-change appears without a lock update.
-- `~/.afk/agent-framework/sdk-dependency-telemetry.jsonl` — append-only log of symbol-count deltas and SHA over time.
-
-When adding a new SDK import: run `pnpm audit:sdk:update-lock`, then edit the generated lock entry's `reason` with a one-line justification before committing.
-
 ### Testing
 
 ```bash
-pnpm test                   # all
+pnpm test                   # all (vitest run)
 pnpm test:coverage          # with coverage
 pnpm test:watch             # watch mode
-pnpm test:integration       # integration only
-pnpm test:e2e               # e2e only
+pnpm test:integration       # vitest run tests/integration  (dir not yet populated)
+pnpm test:e2e               # vitest run tests/e2e          (dir not yet populated)
 ```
 
+Tests are colocated as `*.test.ts` next to the implementation under `src/`, plus cross-cutting suites under `tests/agent/` and `tests/telegram/`.
+
 ## Troubleshooting
 
 ### API Key Issues
@@ -667,16 +767,15 @@ type SessionState = 'idle' | 'processing' | 'streaming' | 'closed';
 
 ## Contributing
 
-Contributions welcome. Standard flow:
+Contributions welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`AGENTS.md`](AGENTS.md) for repo conventions. Standard flow:
 
 1. Fork the repository
 2. Create a feature branch
-3. Make your changes
-4. Add tests
-5. Run `pnpm test && pnpm lint`
-6. Open a pull request
+3. Make your changes (add or update tests alongside)
+4. Run `pnpm test && pnpm lint`
+5. Open a pull request
 
-New orchestration skills, CI gate changes, and ceiling-ledger conventions are documented in the workspace-root [`SYSTEM.md`](../SYSTEM.md).
+New orchestration skills, CI gate changes, and ceiling-ledger conventions are documented in [`AGENTS.md`](AGENTS.md). A change log is maintained in [`CHANGELOG.md`](CHANGELOG.md) (also viewable in-REPL via `/changelog`).
 
 ## License
 
@@ -684,8 +783,10 @@ MIT © Griffin Long
 
 ## Acknowledgments
 
-- Built with [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)
+- Anthropic API client: [@anthropic-ai/sdk](https://www.npmjs.com/package/@anthropic-ai/sdk)
+- OpenAI Codex client: [@openai/codex-sdk](https://www.npmjs.com/package/@openai/codex-sdk)
 - CLI framework: [Commander.js](https://github.com/tj/commander.js)
+- Telegram: [Telegraf](https://telegraf.js.org/)
 - Testing: [Vitest](https://vitest.dev/)
 
 ---