@wazir-dev/cli 1.0.0

package/docs/reference/hooks.md

@@ -0,0 +1,87 @@
+# Hooks Reference
+
+Wazir defines canonical hook contracts in `hooks/definitions/*.yaml`.
+
+These hook definitions are product contracts first. Host-specific native hooks or wrapper commands must preserve the same behavior.
+
+## Canonical hook roster
+
+| Hook ID | Purpose | Failure mode |
+| --- | --- | --- |
+| `session_start` | Initialize run-local status capture and bootstrap summaries | capture |
+| `pre_tool_capture_route` | Route large tool output away from model context | warn |
+| `post_tool_capture` | Append tool execution events and captured output metadata | capture |
+| `pre_compact_summary` | Summarize captured state before compaction or handoff | warn |
+| `stop_handoff_harvest` | Persist final handoff and stop-time observability data | capture |
+| `protected_path_write_guard` | Block writes to protected canonical paths outside approved flows | block |
+| `loop_cap_guard` | Block extra iterations after the configured loop cap | block |
+
+## Source of truth
+
+- hook contracts: `hooks/definitions/*.yaml`
+- schema: `schemas/hook.schema.json`
+- required hook roster: `wazir.manifest.yaml`
+- validation command: `wazir validate hooks`
+
+## Host fallback policy
+
+Every canonical hook definition includes `host_fallback` guidance for:
+
+- Claude
+- Codex
+- Gemini
+- Cursor
+
+Fallbacks may be native hooks or wrapper commands, but they must preserve:
+
+- the same trigger intent
+- the same protected-path policy
+- the same loop-cap policy
+- the same observable outputs or an explicitly documented equivalent
+
+## Current implementation status
+
+Implemented now:
+
+- canonical hook definitions and schema validation
+- manifest-level required hook roster
+- CLI validation through `wazir validate hooks`
+- capture/status file writers through:
+  - `wazir capture init`
+  - `wazir capture event`
+  - `wazir capture route`
+  - `wazir capture output`
+  - `wazir capture summary`
+- wrapper guard scripts:
+  - `hooks/protected-path-write-guard`
+  - `hooks/loop-cap-guard`
+- session-start CLI bootstrap script (`hooks/session-start`) emitting `<cli-bootstrap-guidance>` for doctor, index, and run recovery
+
+Planned next:
+
+- wrapper/native execution helpers
+
+## CLI bootstrap
+
+The `session_start` hook emits a `<cli-bootstrap-guidance>` block alongside the skill bootstrap text. This block guides agents through a 3-step CLI bootstrap sequence at the start of every session:
+
+1. **Doctor check** -- run `wazir doctor` to validate the repo surface (manifest, hooks, state-root, exports)
+2. **Index refresh** -- run `wazir index refresh` (or `index build` if no index exists) to ensure the local index is current
+3. **Run recovery** -- check `<state-root>/runs/latest` for a prior run ID; resume it or start a new run via `capture init`
+
+The `session_start.yaml` output contract produces `cli_bootstrap_guidance` alongside `skill_bootstrap_text`. Both are injected into the agent's initial context.
+
+The bootstrap sequence is advisory -- it guides the agent but does not enforce execution order. The session-start hook always exits 0 to avoid blocking session startup.
+
+## Guardrail note
+
+Hook definitions are the authoritative product contracts. The canonical definitions above take precedence over any other hook documentation.
+
+## Current guard exit codes
+
+- `hooks/protected-path-write-guard`
+  - `0` allow
+  - `42` block
+- `hooks/loop-cap-guard`
+  - `0` allow
+  - `43` block

package/docs/reference/host-exports.md

@@ -0,0 +1,50 @@
+# Host Exports
+
+Wazir now includes a canonical export compiler for host packages under:
+
+- `exports/hosts/claude/`
+- `exports/hosts/codex/`
+- `exports/hosts/gemini/`
+- `exports/hosts/cursor/`
+
+## Current commands
+
+- `wazir export build`
+- `wazir export --check`
+
+## What `build` does
+
+The compiler currently:
+
+- validates the manifest
+- validates canonical hook definitions
+- reads canonical role files
+- reads canonical workflow files
+- writes host-specific package files under `exports/hosts/*`
+- writes `host-package.json`
+- writes `export.manifest.json`
+- records source hashes for drift detection
+
+## What `--check` does
+
+The drift check:
+
+- verifies the generated package metadata exists for every host
+- verifies the listed generated files still exist
+- compares current source hashes against each host export manifest
+- fails non-zero when canonical sources changed after the last export
+
+## Current host package shapes
+
+Current generated highlights:
+
+- Claude: `CLAUDE.md`, `.claude/settings.json`, `.claude/agents/*`, `.claude/commands/*`
+- Codex: `AGENTS.md`
+- Gemini: `GEMINI.md`
+- Cursor: `.cursor/rules/wazir-core.mdc`, `.cursor/hooks.json`
+
+## Scope note
+
+The compiler generates the canonical host packages under `exports/hosts/*`.
+
+The only root host bootstrap retained is `.claude/settings.json`, which mirrors the generated Claude settings contract.

package/docs/reference/launch-checklist.md

@@ -0,0 +1,172 @@
+# Discovery and Launch Checklist
+
+End-to-end checklist for launching a Wazir release into the wild.
+
+---
+
+## 1. Pre-Launch Verification
+
+Complete these before any public announcement:
+
+- [ ] **npx works:** Run `npx @wazir-dev/cli --version` from a clean machine (no local clone).
+- [ ] **GitHub Release exists:** A tagged release with release notes is published on the repo.
+- [ ] **README polished:** README.md has clear install instructions, feature summary, and badges (npm version, license, CI status).
+- [ ] **CHANGELOG updated:** Latest version entry is present with all notable changes.
+- [ ] **CI green:** All tests and linting pass on the main branch.
+- [ ] **Marketplace configs published:** All automated channels from the marketplace listings guide are live (Claude Code Plugin).
+- [ ] **Host exports current:** `exports/hosts/` directories contain the latest generated configs for all supported hosts.
+- [ ] **License file present:** `LICENSE` matches the declared license in `package.json`.
+
+---
+
+## 2. Awesome List Submissions
+
+Submit pull requests to these curated lists (one PR per list, follow each repo's contributing guidelines):
+
+### awesome-claude-code
+- **Repo:** `github.com/anthropics/awesome-claude-code` (or the most-starred community fork)
+- **Section:** Tools / Plugins / Extensions
+- **Entry format:** `[Wazir](https://github.com/MohamedAbdallah-14/Wazir) - Host-native engineering OS kit with 10 roles, 14 phases, and 308 expertise modules.`
+- **Tips:** Keep the description under 120 characters. Link directly to the repo.
+
+### awesome-ai-agents
+- **Repo:** `github.com/e2b-dev/awesome-ai-agents`
+- **Section:** Developer Tools / Coding Agents
+- **Entry format:** Follow the existing table format in the README.
+
+### awesome-llm-apps
+- **Repo:** `github.com/Shubhamsaboo/awesome-llm-apps`
+- **Section:** Developer Tools
+- **Entry format:** Follow the existing list format.
+
+---
+
+## 3. Hacker News "Show HN"
+
+### Timing
+- **Best days:** Tuesday through Thursday
+- **Best time:** 8:00-9:00 AM ET (when the US East Coast audience is waking up)
+- **Avoid:** Weekends, holidays, and days with major tech news
+
+### Title format
+```
+Show HN: Wazir – Engineering OS kit for AI coding agents (Claude, Codex, Gemini, Cursor)
+```
+
+### First comment
+Post a comment immediately after submission explaining:
+1. What problem Wazir solves (AI agents lack structured engineering workflows)
+2. How it works (10 canonical roles, 14-phase pipeline, 308 expertise modules)
+3. What makes it different (host-native, works across Claude/Codex/Gemini/Cursor)
+4. Quick install: `npx @wazir-dev/cli init`
+5. Invite feedback -- HN readers appreciate genuine requests for input
+
+### Guidelines
+- Do not ask for upvotes (against HN rules).
+- Respond to every comment within the first 2 hours.
+- Be honest about limitations and what is not yet built.
+
+---
+
+## 4. Dev.to Technical Post
+
+### Suggested outline
+
+**Title:** "How I Built an Engineering OS for AI Coding Agents"
+
+1. **Hook** -- The problem: AI agents write code but lack engineering discipline.
+2. **Architecture overview** -- 10 roles, 14 phases, expertise modules, quality gates.
+3. **Code walkthrough** -- Show a real workflow: how a feature moves from requirements through TDD to deployment.
+4. **Host-native approach** -- Explain why one kit works across Claude, Codex, Gemini, and Cursor.
+5. **Results** -- Concrete metrics or before/after comparisons.
+6. **Getting started** -- `npx @wazir-dev/cli init` with a 3-step quickstart.
+7. **Call to action** -- Star the repo, try it, file issues.
+
+### Tags
+`ai`, `productivity`, `devtools`, `opensource`
+
+### Tips
+- Include at least one diagram or screenshot.
+- Cross-post to your blog if you have one (Dev.to supports canonical URLs).
+- Respond to all comments within 24 hours.
+
+---
+
+## 5. Social Media
+
+### Twitter / X Thread
+
+Structure as a 5-7 tweet thread:
+
+1. **Hook tweet:** One-liner about the problem + link to repo.
+2. **What it is:** Brief description of Wazir.
+3. **Architecture:** 10 roles, 14 phases, 308 modules (include a diagram image).
+4. **Demo:** Short GIF or screenshot of a workflow in action.
+5. **Multi-host:** Works with Claude, Codex, Gemini, and Cursor.
+6. **Install:** `npx @wazir-dev/cli init`
+7. **Ask:** "What workflows would you add?" -- invite engagement.
+
+**Timing:** Post between 9-11 AM ET on weekdays.
+
+### LinkedIn
+
+- Write a single long-form post (not a thread).
+- Lead with the problem, not the product.
+- Include 3-5 bullet points on key features.
+- End with the install command and repo link.
+- Tag relevant people and companies (Anthropic, OpenAI, Google DeepMind).
+
+### Reddit
+
+Submit to these subreddits (read each sub's rules first):
+
+| Subreddit | Post type | Notes |
+|-----------|-----------|-------|
+| r/ClaudeAI | Link post | Flair as "Tool/Resource" if available |
+| r/LocalLLaMA | Text post | Emphasize the open-source, host-agnostic angle |
+| r/programming | Link post | Focus on engineering discipline, not AI hype |
+| r/devtools | Link post | Emphasize developer productivity |
+
+**Reddit guidelines:**
+- Do not post to multiple subreddits on the same day (looks spammy).
+- Space posts 1-2 days apart.
+- Engage genuinely with all comments.
+- Do not use marketing language -- be technical and direct.
+
+---
+
+## 6. Metrics to Track
+
+Monitor these metrics weekly for the first month, then monthly:
+
+### GitHub
+- **Stars:** Track weekly growth rate, not just total.
+- **Forks:** Indicator of serious users exploring the code.
+- **Issues opened:** Both bugs and feature requests signal engagement.
+- **Pull requests:** External PRs indicate community adoption.
+- **Clones and traffic:** Available in the repo Insights tab.
+
+### npm
+- **Weekly downloads:** Available at `npmjs.com/package/@wazir-dev/cli`.
+- **Download trend:** Use `npm-stat.com` for historical charts.
+- **Dependent packages:** Other packages that list Wazir as a dependency.
+
+### Marketplace
+- **Claude Code Plugin installs:** Check plugin analytics if available.
+- **MCP Registry page views:** Monitor via registry dashboard.
+- **Cursor Marketplace installs:** Available in the Cursor publisher dashboard.
+
+### Content
+- **HN points and comments:** Track within 24 hours of posting.
+- **Dev.to views, reactions, and comments:** Track within 1 week.
+- **Twitter impressions and engagement:** Track within 48 hours.
+- **Reddit upvotes and comments:** Track within 48 hours per subreddit.
+
+### Success benchmarks (first 30 days)
+| Metric | Target |
+|--------|--------|
+| GitHub stars | 100+ |
+| npm weekly downloads | 50+ |
+| Issues opened (external) | 10+ |
+| External PRs | 2+ |
+| HN points | 50+ |

package/docs/reference/marketplace-listings.md

@@ -0,0 +1,76 @@
+# Marketplace Listings Guide
+
+This guide covers every distribution channel for Wazir.
+
+---
+
+## Install Methods
+
+### npm (primary)
+
+```bash
+npx @wazir-dev/cli --help          # run directly
+npm install -g @wazir-dev/cli      # or install globally
+```
+
+- **Package:** [`@wazir-dev/cli`](https://www.npmjs.com/package/@wazir-dev/cli)
+
+### Homebrew (macOS)
+
+```bash
+brew tap MohamedAbdallah-14/Wazir
+brew install wazir
+```
+
+- **Tap repo:** [`homebrew-wazir`](https://github.com/MohamedAbdallah-14/homebrew-wazir)
+- **Formula source:** `homebrew/wazir.rb` in this repo
+
+### Claude Code Plugin
+
+Wazir ships as a Claude Code plugin. Users install in two steps:
+
+```bash
+# In Claude Code:
+/plugin marketplace add MohamedAbdallah-14/Wazir
+/plugin install wazir
+```
+
+- **Marketplace config:** `.claude-plugin/marketplace.json`
+- **Plugin manifest:** `.claude-plugin/plugin.json`
+- **Docs:** [Claude Code plugin marketplaces](https://code.claude.com/docs/en/plugin-marketplaces)
+
+---
+
+## Host Exports
+
+Wazir generates host-native packages for each AI coding agent. After cloning and running `npx wazir export build`, deploy to your project:
+
+| Host | Deploy command |
+|------|---------------|
+| **Claude** | `cp -r exports/hosts/claude/.claude ~/your-project/ && cp exports/hosts/claude/CLAUDE.md ~/your-project/` |
+| **Codex** | `cp exports/hosts/codex/AGENTS.md ~/your-project/` |
+| **Gemini** | `cp exports/hosts/gemini/GEMINI.md ~/your-project/` |
+| **Cursor** | `cp -r exports/hosts/cursor/.cursor ~/your-project/` |
+
+---
+
+## MCP Registry
+
+Wazir is listed in the MCP Registry as a metadata entry.
+
+- **Config file:** `server.json` (repo root)
+- **Schema:** `https://registry.modelcontextprotocol.io/schema/server.json`
+
+---
+
+## Post-Publish Checklist
+
+Run through this checklist after every `npm publish`:
+
+- [ ] **npm:** Confirm package is live at `https://www.npmjs.com/package/@wazir-dev/cli`
+- [ ] **npx smoke test:** Run `npx @wazir-dev/cli --help` from a clean environment
+- [ ] **Claude Code Plugin:** Run `/plugin marketplace add MohamedAbdallah-14/Wazir` then `/plugin install wazir`
+- [ ] **GitHub Release:** Ensure a GitHub Release exists with tag matching the npm version
+- [ ] **Homebrew:** Update SHA256 in `homebrew/wazir.rb` and push to `homebrew-wazir` tap repo
+- [ ] **Host exports:** Run `npx wazir export --check` to verify no drift
+- [ ] **CHANGELOG:** Verify `CHANGELOG.md` is updated with the new version entry

package/docs/reference/release-process.md

@@ -0,0 +1,34 @@
+# Release Process
+
+## Tag Naming
+
+Wazir uses semantic versioning: `v{MAJOR}.{MINOR}.{PATCH}`
+
+Legacy tags (V5.1, V6.x, etc.) are historical artifacts and are ignored by validators.
+
+## Release Workflow
+
+1. Create `release/<version>` branch from `develop`
+2. Update `CHANGELOG.md`: move `[Unreleased]` entries to `[<version>] - YYYY-MM-DD`
+3. Add a fresh empty `[Unreleased]` section at the top
+4. Update version in `wazir.manifest.yaml` and `package.json`
+5. Commit: `chore: prepare release <version>`
+6. Merge to `main` with `--no-ff`
+7. Tag: `git tag -a v<version> -m "v<version>"`
+8. Merge `main` back to `develop` with `--no-ff`
+9. Delete the release branch
+
+## Hotfix Workflow
+
+1. Create `hotfix/<slug>` branch from `main`
+2. Fix the issue with conventional commits
+3. Update `CHANGELOG.md` with the fix under `[Unreleased]`
+4. Follow the same merge/tag/merge-back pattern as releases
+5. Delete the hotfix branch
+
+## Bootstrap (First Wazir Release)
+
+When no Wazir release tag exists yet:
+- Diff-aware changelog validation diffs against the initial commit or `develop` creation point
+- Legacy tags are not considered release boundaries
+- The first release tag will be `v1.0.0` (or `v0.1.0` if pre-stable)

package/docs/reference/roles-reference.md

@@ -0,0 +1,77 @@
+# Roles Reference
+
+This is the lookup reference for canonical roles, workflows, and their contracts.
+
+## Canonical roles
+
+| Role | Purpose |
+|------|---------|
+| `clarifier` | Resolves ambiguity before spec production |
+| `researcher` | Gathers source-backed findings and prior art |
+| `specifier` | Produces measurable specs with acceptance criteria |
+| `content-author` | Produces finalized i18n keys, microcopy, glossary, state coverage, and accessibility copy |
+| `designer` | Transforms approved spec into visual designs using open-pencil MCP tools. Produces `.fig` files, exported code scaffolds, and design tokens |
+| `planner` | Creates implementation plans from approved spec and designs |
+| `executor` | Implements the plan (orchestrator "Dev" phase) |
+| `verifier` | QA hard gate — always mandatory (orchestrator "QA" phase) |
+| `reviewer` | Adversarial quality review (orchestrator "Reviewer" phase) |
+| `learner` | Captures scoped learnings for future runs |
+
+## Canonical workflows
+
+| Workflow | Runs after | Description |
+|----------|-----------|-------------|
+| `clarify` | — | Resolve ambiguity |
+| `discover` | `clarify` | Gather research |
+| `specify` | `discover` | Produce spec |
+| `spec-challenge` | `specify` | Adversarial spec review |
+| `author` | `spec-challenge` | Content authoring |
+| `design` | `author` | Visual design from approved spec |
+| `design-review` | `design` | Validate designs against spec, accessibility, visual consistency |
+| `plan` | `design-review` | Create implementation plan |
+| `plan-review` | `plan` | Adversarial plan review |
+| `execute` | `plan-review` | Implement the plan |
+| `verify` | `execute` | QA hard gate |
+| `review` | `verify` | Adversarial quality review |
+| `learn` | `review` | Capture scoped learnings |
+| `prepare-next` | `learn` | Produce clean next-run handoff |
+
+## Role routing valid values
+
+- `executor` — implements the task (orchestrator "Dev" phase)
+- `reviewer` — adversarial quality review (orchestrator "Reviewer" phase)
+- `verifier` — QA hard gate, always mandatory (orchestrator "QA" phase)
+
+## Contract source files
+
+- Role contracts: `roles/<role-name>.md`
+- Workflow entrypoints: `workflows/<workflow-name>.md`
+- Manifest roster: `wazir.manifest.yaml`
+
+For conceptual understanding of how roles and workflows interact, see [Roles and Workflows concepts](../concepts/roles-and-workflows.md).
+
+## Context retrieval defaults
+
+Every role contract includes a `## Context retrieval` section specifying the default recall tier and fallback strategy. Agents should consult the individual role contracts for full details.
+
+| Role | Default tier | Strategy | Fallback |
+|------|-------------|----------|----------|
+| `learner` | L0 | Inventory scan via `recall --tier L0` | L0 fails -> try L1 -> L1 fails -> direct file read |
+| `clarifier` | L1 | Structural summaries via `recall --tier L1` | If recall fails, fall back to direct file reads |
+| `researcher` | L1 | Structural summaries via `recall --tier L1` | If recall fails, fall back to direct file reads |
+| `specifier` | L1 | Structural summaries via `recall --tier L1` | If recall fails, fall back to direct file reads |
+| `content-author` | L1 | Structural summaries via `recall --tier L1` | If recall fails, fall back to direct file reads |
+| `designer` | L1 | Structural summaries via `recall --tier L1` | If recall fails, fall back to direct file reads |
+| `planner` | L1 | Structural summaries via `recall --tier L1` | If recall fails, fall back to direct file reads |
+| `executor` | Direct read | Full source via `Read` tool or `recall file` (L2) | If index search fails, use grep or file-tree exploration |
+| `verifier` | Direct read | Full source via `Read` tool or `recall file` (L2) | If index search fails, use grep or file-tree exploration |
+| `reviewer` | L1 + escalation | Start with `recall --tier L1`; escalate to direct read for logic errors, security, or ambiguous summaries | If recall fails, fall back to direct file reads |
+
+**Tier token budgets:**
+- L0: ~100 tokens (one-line identifier summary)
+- L1: ~500-2k tokens (structural summary)
+- L2/Direct: full source content
+
+Roles that explore broadly (clarifier, researcher, planner) benefit most from L1 summaries. Roles that need exact source (executor, verifier) use direct reads. The reviewer uses L1 as a triage pass before targeted deep reads.
+
+See [Indexing and Recall](../concepts/indexing-and-recall.md) for full details on tiers and commands.

package/docs/reference/skills.md

@@ -0,0 +1,33 @@
+# Skills
+
+Wazir uses skills as reusable in-host procedures.
+
+The active thesis is:
+
+- use Wazir inside your AI host
+- keep the operating model in canonical repo skills
+
+## Active Skills
+
+These skills remain on the active surface:
+
+| Skill | Purpose |
+| --- | --- |
+| `wz:using-skills` | Ensures skill discovery happens before work starts |
+| `wz:brainstorming` | Turns briefings into approved designs before implementation |
+| `scan-project` | Builds a project profile from the repo and `input/`, with index build/refresh and `index stats` in the profile output |
+| `wz:writing-plans` | Produces execution-grade implementation plans |
+| `wz:debugging` | Runs a disciplined observe-hypothesize-test-fix loop with symbol-first exploration (index search-symbols, recall L1) in the OBSERVE phase |
+| `wz:humanize` | Detects and removes AI writing patterns from text artifacts via a 4-phase pipeline (Scan, Identify, Rewrite, Verify) |
+| `wz:tdd` | Enforces RED -> GREEN -> REFACTOR for implementation work |
+| `wz:verification` | Requires fresh proof before completion claims |
+| `wz:design` | Guides the designer role through open-pencil MCP workflow to produce design artifacts |
+| `prepare-next` | Produces a clean next-run handoff without auto-loading stale context |
+| `run-audit` | Runs a structured codebase audit producing source-backed findings with remediation |
+| `self-audit` | Runs a worktree-isolated audit-fix loop — validates, audits, fixes, verifies, and merges back only on green |
+
+## Rules
+
+- Skills must reference `input/`, canonical roles/workflows, or external state-root conventions.
+- Skills must not instruct users to run background services or wrapper scripts that are not part of the canonical workflow surface.
+- When a skill becomes contradictory to the current operating model, remove it from `skills/`.

package/docs/reference/templates.md

@@ -0,0 +1,29 @@
+# Templates
+
+Wazir keeps two active template classes:
+
+- `templates/artifacts/` for run outputs and handoffs
+- `templates/examples/` for schema-aligned example payloads
+
+## Artifact Templates
+
+Active artifact templates cover:
+
+- clarification
+- research
+- spec
+- spec challenge
+- implementation plan
+- plan review
+- execution notes
+- verification proof
+- review findings
+- learning proposal
+- accepted learning
+- next-run handoff
+
+Each template requires run metadata, sources, loop number, and approval status where applicable.
+
+## Example Payloads
+
+Schema-backed examples under `templates/examples/` exist to keep schemas, examples, and validation in sync.

package/docs/reference/tooling-cli.md

@@ -0,0 +1,94 @@
+# Wazir CLI
+
+The `wazir` CLI is minimal on purpose. It exists to validate and export the host-native OS kit.
+
+## Current command surface
+
+| Command | Status | Behavior |
+| --- | --- | --- |
+| `wazir validate manifest` | implemented | Validates `wazir.manifest.yaml` against its schema and checks required repo paths exist. |
+| `wazir validate hooks` | implemented | Validates canonical hook definitions against `schemas/hook.schema.json` and the manifest hook roster. |
+| `wazir validate docs` | implemented | Validates `docs/truth-claims.yaml`, checks documented command claims against the active CLI surface, and rejects broken local doc links. |
+| `wazir validate brand` | implemented | Enforces canonical product naming on the Wazir surface. |
+| `wazir validate runtime` | implemented | Rejects non-canonical runtime wrappers, repo-local task/state paths, and forbidden runtime-only package surfaces. |
+| `wazir validate branches` | implemented | Validates the current (or `--branch`-specified) branch name against the allowed git-flow patterns. |
+| `wazir validate commits` | implemented | Validates conventional commit format for commits in the range `--base..--head` (or auto-detected base to HEAD). |
+| `wazir validate changelog` | implemented | Validates `CHANGELOG.md` structure; with `--require-entries` and `--base`, enforces new entries since the base. |
+| `wazir validate docs-drift` | implemented | Detects when source files (roles, workflows, skills, hooks) change without corresponding documentation updates. Advisory by default; `--strict` exits non-zero on drift. |
+| `wazir validate artifacts` | reserved | Exits `2` until artifact-template and example validation expands. |
+| `wazir export build` | implemented | Generates host packages under `exports/hosts/*` from canonical sources. |
+| `wazir export --check` | implemented | Verifies generated host packages still match current canonical source hashes. |
+| `wazir index build` | implemented | Builds a local SQLite-backed index under the configured state root. |
+| `wazir index refresh` | implemented | Refreshes indexed files using stored content hashes. |
+| `wazir index stats` | implemented | Reports file, symbol, outline, and summary_counts for the current index. |
+| `wazir index summarize` | implemented | Generates L0/L1 heuristic summaries for all indexed files and symbols. |
+| `wazir index search-symbols` | implemented | Searches indexed symbol names. |
+| `wazir index get-symbol` | implemented | Returns a stored symbol record by name or ID. |
+| `wazir index get-file-outline` | implemented | Returns indexed outline entries for a file. |
+| `wazir recall file` | implemented | Returns an exact line-bounded slice from an indexed file. Supports `--tier L0\|L1` for summary recall. |
+| `wazir recall symbol` | implemented | Returns an exact slice for an indexed symbol match. Supports `--tier L0\|L1` for summary recall. |
+| `wazir doctor` | implemented | Validates the active repo surface for manifest, hooks, state-root policy, and host export directory presence. |
+| `wazir status` | implemented | Reads run status directly from `<state-root>/runs/<run-id>/status.json`. |
+| `wazir capture init` | implemented | Creates a run ledger with `status.json`, `events.ndjson`, and a captures directory under the configured state root. |
+| `wazir capture event` | implemented | Appends a run event and can update phase, status, and loop counts in `status.json`. |
+| `wazir capture route` | implemented | Reserves a run-local capture file path for large tool output. |
+| `wazir capture output` | implemented | Writes captured tool output to a run-local file and records a `post_tool_capture` event. |
+| `wazir capture summary` | implemented | Writes `summary.md` and records the chosen summary or handoff event. |
+| `wazir capture usage` | implemented | Generates a token savings report for a run, showing capture routing statistics and context window savings. |
+
+## Exit codes
+
+- `0`: requested check passed
+- `1`: invalid input or validation failure
+- `2`: command surface exists but the implementation is intentionally not complete yet
+
+## Root discovery
+
+The CLI resolves the project root by walking upward from the current working directory until it finds `wazir.manifest.yaml`. This keeps checks usable from nested directories inside the repo.
+
+## State-root override
+
+Indexing and recall commands accept `--state-root <path>` so operators can keep index state wherever they want. If omitted, Wazir uses the manifest default outside the repo.
+
+`wazir status` accepts the same override when reading run-local status files.
+
+`wazir capture *` accepts the same override when writing run-local status, events, summaries, and captured output files.
+
+`wazir export build` and `wazir export --check` work from the current project root and write under `exports/hosts/*`.
+
+## Run recovery
+
+`wazir capture init` writes the current run ID to `<state-root>/runs/latest` as a plain text pointer. On session start, an agent can read this file to determine if a prior run exists and resume it rather than starting fresh.
+
+This enables run continuity across context compaction boundaries. When a session is compacted, the new context can read `latest` and call `wazir status --run <id>` to load the prior run's state.
+
+If no `latest` file exists, the agent starts a new run via `capture init`.
+
+## Token savings
+
+Wazir reduces context window consumption through two mechanisms:
+
+**Capture routing.** `wazir capture route` and `wazir capture output` redirect large tool output to run-local files instead of the context window. The agent receives a file path reference (~50 tokens) instead of the full output (potentially thousands of tokens).
+
+**Tiered recall.** `wazir recall file` and `wazir recall symbol` support `--tier L0|L1` for summary-based recall:
+- L0 (~100 tokens): one-line identifier summary
+- L1 (~500-2k tokens): structural summary with signature, purpose, dependencies
+- L2 (default): full source slice
+
+Roles are assigned default tiers based on their needs. Exploration-heavy roles (clarifier, researcher, planner) use L1 by default. Implementation roles (executor, verifier) use direct reads. See [Indexing and Recall](../concepts/indexing-and-recall.md) for details.
+
+`wazir capture usage` generates a per-run token savings report showing how many tokens were saved by capture routing and tiered recall versus direct reads.
+
+## Current scope limits
+
+- The CLI is a validation and export tool with no background processes.
+- Validation is the first active capability because it prevents fake green states while the rest of the kit is still being rebuilt.
+- Reserved commands are documented here so adopters can tell the difference between real behavior and planned behavior.
+
+## Docs truth source
+
+Executable documentation claims are registered in:
+
+- `docs/truth-claims.yaml`
+
+`wazir validate docs` uses that file plus active markdown link checks to prevent stale command and path claims from silently drifting.