@wazir-dev/cli 1.0.0

package/docs/getting-started/01-installation.md

@@ -0,0 +1,78 @@
+# Installation
+
+## Claude Code Plugin (recommended)
+
+The fastest way to use Wazir. Two commands in Claude Code:
+
+```bash
+/plugin marketplace add MohamedAbdallah-14/Wazir
+/plugin install wazir
+```
+
+Skills, roles, and workflows are now available in your Claude sessions. No files to copy, no exports needed.
+
+## Codex
+
+Copy the generated host export to your project:
+
+```bash
+git clone https://github.com/MohamedAbdallah-14/Wazir.git
+cd wazir && npm install && npx wazir export build
+cp exports/hosts/codex/AGENTS.md ~/your-project/
+```
+
+## Gemini
+
+```bash
+git clone https://github.com/MohamedAbdallah-14/Wazir.git
+cd wazir && npm install && npx wazir export build
+cp exports/hosts/gemini/GEMINI.md ~/your-project/
+```
+
+## Cursor
+
+```bash
+git clone https://github.com/MohamedAbdallah-14/Wazir.git
+cd wazir && npm install && npx wazir export build
+cp -r exports/hosts/cursor/.cursor ~/your-project/
+```
+
+## npm (global CLI)
+
+```bash
+npm install -g @wazir-dev/cli
+```
+
+The CLI provides validation, export, indexing, and doctor commands. You still need to clone the source to build host exports.
+
+## Homebrew (macOS)
+
+```bash
+brew tap MohamedAbdallah-14/Wazir
+brew install wazir
+```
+
+## From Source (contributors)
+
+```bash
+git clone https://github.com/MohamedAbdallah-14/Wazir.git
+cd wazir
+npm ci
+npx wazir doctor    # verify environment
+npm test                 # run test suite
+```
+
+## Verify
+
+After any install method, verify with:
+
+```bash
+npx wazir doctor
+# PASS manifest: Manifest is valid.
+# PASS hooks: Hook definitions are valid.
+# PASS host-exports: All required host export directories exist.
+```
+
+## What's next
+
+[Your First Run](02-first-run.md) — walk through the full pipeline from brief to shipped code.

package/docs/getting-started/02-first-run.md

@@ -0,0 +1,102 @@
+# Your First Run
+
+Walk through the full Wazir pipeline: describe a task, clarify it, execute with TDD, and review.
+
+## What you'll do
+
+Take a vague requirement through the full pipeline and see what each role produces.
+
+## Prerequisites
+
+- Wazir installed (see [Installation](01-installation.md))
+- An AI host open in your project (Claude, Codex, Gemini, or Cursor)
+
+## Step 1: Describe your task
+
+Tell your agent what you want to build. For example:
+
+> "Add a user registration endpoint with email validation"
+
+The clarifier role activates and reads your brief.
+
+## Step 2: Clarify
+
+The clarifier asks questions and produces a structured spec with acceptance criteria. It escalates ambiguity — it never assumes.
+
+**Expected output:**
+- Acceptance criteria (testable, specific)
+- Open questions resolved
+- Scope boundaries defined
+- Assumptions and non-goals listed
+
+If the clarifier can't resolve ambiguity, it escalates to you rather than guessing.
+
+## Step 3: Spec Challenge (approval gate)
+
+A reviewer (different from the clarifier) adversarially reviews the spec. The reviewer checks for gaps, contradictions, and unstated assumptions.
+
+**Expected output:** Gate decision — APPROVED or REJECTED with specific reasons.
+
+**Your action:** You must explicitly approve the spec before planning begins. If rejected, it loops back to clarify with the reviewer's feedback.
+
+## Step 4: Plan (approval gate)
+
+The planner breaks the approved spec into ordered, testable tasks with dependencies.
+
+The plan-review phase runs adversarial review on the plan — checking for missing edge cases, incorrect ordering, and scope creep.
+
+**Expected output:** Task breakdown with:
+- Implementation order and dependencies
+- Test strategy per task
+- Estimated complexity
+
+**Your action:** You must explicitly approve the plan before execution begins.
+
+## Step 5: Execute
+
+The executor implements each task with TDD:
+1. Write a failing test (RED)
+2. Write minimal code to pass (GREEN)
+3. Refactor while green (REFACTOR)
+4. Commit with conventional message
+
+The composition engine loads role-specific expertise modules automatically — the executor gets modules on how to build, anti-patterns to avoid, and stack-specific guidance.
+
+**Expected output:**
+- Test files (failing → passing)
+- Implementation code
+- Conventional commits at each step
+
+## Step 6: Review
+
+The reviewer (never the executor) performs adversarial review against the acceptance criteria from the spec.
+
+**Expected output:** Review artifact with:
+- Pass/fail per acceptance criterion
+- Findings with severity and evidence
+- Recommendation: APPROVE, REQUEST_CHANGES, or REJECT
+
+## Step 7: Learn
+
+The learner captures what worked and what didn't. Proposed learnings go to `memory/learnings/proposed/` and require explicit review before promotion.
+
+Only learnings whose file patterns overlap the current task are loaded in future runs — the system gets smarter per-project without drifting.
+
+**Expected output:** Proposed learnings with scope tags.
+
+## Under the hood
+
+The 7 steps above map to 14 internal phases:
+
+| User Stage | Internal Phases | Roles |
+|------------|----------------|-------|
+| **Clarify** | clarify → discover → specify → spec-challenge | clarifier, researcher, specifier, reviewer |
+| **Execute** | author → design → design-review → plan → plan-review → execute → verify | content-author, designer, planner, executor, verifier |
+| **Review** | review | reviewer |
+| **Learn** | learn → prepare-next | learner |
+
+## What's next
+
+- [Architecture](../concepts/architecture.md) — understand why Wazir works this way
+- [Roles & Workflows](../concepts/roles-and-workflows.md) — deep dive into role contracts
+- [Composition Engine](../concepts/composition-engine.md) — how expertise modules are loaded

package/docs/getting-started/03-adding-to-project.md

@@ -0,0 +1,15 @@
+---
+title: "Adding Wazir to an Existing Project"
+type: tutorial
+status: stub
+---
+
+# Adding Wazir to an Existing Project
+
+> **Status:** This tutorial is planned. See the [navigation hub](../README.md) for available content.
+
+## What You'll Build
+_Coming soon_
+
+## Prerequisites
+_Coming soon_

package/docs/getting-started/04-host-setup.md

@@ -0,0 +1,15 @@
+---
+title: "Host Setup"
+type: tutorial
+status: stub
+---
+
+# Host Setup
+
+> **Status:** This tutorial is planned. See the [navigation hub](../README.md) for available content.
+
+## What You'll Build
+_Coming soon_
+
+## Prerequisites
+_Coming soon_

package/docs/guides/ci-integration.md

@@ -0,0 +1,15 @@
+---
+title: "CI Integration"
+type: guide
+status: stub
+---
+
+# CI Integration
+
+> **Status:** This guide is planned. See the [navigation hub](../README.md) for available content.
+
+## What You'll Build
+_Coming soon_
+
+## Prerequisites
+_Coming soon_

package/docs/guides/creating-skills.md

@@ -0,0 +1,15 @@
+---
+title: "Creating Skills"
+type: guide
+status: stub
+---
+
+# Creating Skills
+
+> **Status:** This guide is planned. See the [navigation hub](../README.md) for available content.
+
+## What You'll Build
+_Coming soon_
+
+## Prerequisites
+_Coming soon_

package/docs/guides/expertise-module-authoring.md

@@ -0,0 +1,15 @@
+---
+title: "Expertise Module Authoring"
+type: guide
+status: stub
+---
+
+# Expertise Module Authoring
+
+> **Status:** This guide is planned. See the [navigation hub](../README.md) for available content.
+
+## What You'll Build
+_Coming soon_
+
+## Prerequisites
+_Coming soon_

package/docs/guides/hook-development.md

@@ -0,0 +1,15 @@
+---
+title: "Hook Development"
+type: guide
+status: stub
+---
+
+# Hook Development
+
+> **Status:** This guide is planned. See the [navigation hub](../README.md) for available content.
+
+## What You'll Build
+_Coming soon_
+
+## Prerequisites
+_Coming soon_

package/docs/guides/memory-and-learnings.md

@@ -0,0 +1,34 @@
+# Memory and Learnings
+
+Wazir keeps learning durable but scoped.
+
+## Memory Layout
+
+- `memory/learnings/proposed/`
+- `memory/learnings/accepted/`
+- `memory/learnings/archived/`
+- `memory/experiments/`
+- `memory/anti-pattern-observations/`
+- `memory/summaries/`
+
+## Rules
+
+- new learnings start as proposed
+- accepted learnings require explicit review and scope tags
+- fresh runs do not auto-load learnings by default
+- experiments must record whether they improved, regressed, or were neutral
+- every learning or experiment must cite the artifacts or verification that justify it
+- stale proposed learnings should be archived instead of silently lingering as pending truth
+
+## Guardrails
+
+- do not silently rewrite canonical guidance from a learning
+- do not broaden a learning beyond its proven scope
+- archive stale or disproven learnings instead of letting them drift
+
+## Promotion Path
+
+1. Capture a proposed learning with scope, evidence, and confidence.
+2. Review it explicitly.
+3. Promote it to `memory/learnings/accepted/` only when the scope and evidence are durable.
+4. Move disproven or obsolete learnings to `memory/learnings/archived/`.

package/docs/guides/multi-host-export.md

@@ -0,0 +1,15 @@
+---
+title: "Multi-Host Export"
+type: guide
+status: stub
+---
+
+# Multi-Host Export
+
+> **Status:** This guide is planned. See the [navigation hub](../README.md) for available content.
+
+## What You'll Build
+_Coming soon_
+
+## Prerequisites
+_Coming soon_

package/docs/guides/troubleshooting.md

@@ -0,0 +1,101 @@
+# Troubleshooting
+
+This guide covers the Wazir CLI and host-native tooling surface.
+
+## `wazir validate manifest` fails
+
+Common causes:
+
+- required canonical paths are missing
+- a manifest path resolves outside the project root
+- manifest fields no longer match `schemas/wazir-manifest.schema.json`
+
+What to check:
+
+- `wazir.manifest.yaml`
+- `schemas/wazir-manifest.schema.json`
+- directory names under the repo root
+
+## `wazir validate hooks` fails
+
+Common causes:
+
+- hook YAML parses to `null` or another non-object shape
+- hook file name and `id` do not match
+- required hooks in the manifest do not match files in `hooks/definitions/`
+- a host fallback entry is missing for one of the declared hosts
+
+What to check:
+
+- `hooks/definitions/*.yaml`
+- `schemas/hook.schema.json`
+- `wazir.manifest.yaml`
+
+## `wazir index build` or `refresh` does not index what you expect
+
+Current ignore rules skip common generated or dependency trees such as:
+
+- `.git/`
+- `.worktrees/`
+- `node_modules/`
+- `dist/`
+- `build/`
+- `coverage/`
+- `.next/`
+
+Also note:
+
+- only the current built-in text/code extractor set is indexed
+- the chosen state root is skipped if it lives inside the repo
+- use `--state-root <path>` in tests or custom setups
+
+## `wazir recall file` or `recall symbol` fails
+
+Common causes:
+
+- the index was never built
+- the file or symbol is not present in the current index
+- the wrong state root is being queried
+
+Recommended sequence:
+
+1. `wazir index build --state-root <path>`
+2. `wazir index stats --state-root <path>`
+3. `wazir index search-symbols <query> --state-root <path>`
+4. retry the recall command with the same state root
+
+## `wazir doctor` fails
+
+Current doctor checks:
+
+- manifest validation
+- hook validation
+- external default state-root policy
+- required host export directories under `exports/hosts/`
+
+If doctor fails, inspect the returned check list and fix the specific failing surface instead of bypassing the command.
+
+## Guard hook blocks a write or loop
+
+Current guard wrapper exit codes:
+
+- `42` from `hooks/protected-path-write-guard`
+- `43` from `hooks/loop-cap-guard`
+
+Typical causes:
+
+- trying to write under `input/` or generated host export paths without an approved regeneration flow
+- phase loop counts in run status already meeting the configured cap
+
+## `wazir status --run <id>` fails
+
+The status command reads:
+
+- `<state-root>/runs/<run-id>/status.json`
+
+If it says the run status is missing:
+
+- confirm the run ID
+- confirm the state root
+- confirm the file exists on disk
+- use `--json` for machine-readable output during automation

package/docs/guides/writing-custom-roles.md

@@ -0,0 +1,15 @@
+---
+title: "Writing Custom Roles"
+type: guide
+status: stub
+---
+
+# Writing Custom Roles
+
+> **Status:** This guide is planned. See the [navigation hub](../README.md) for available content.
+
+## What You'll Build
+_Coming soon_
+
+## Prerequisites
+_Coming soon_