@wazir-dev/cli 1.0.0

package/docs/readmes/features/workflows/specify.md

@@ -0,0 +1,160 @@
+# specify
+
+**Phase 3 — The contract that every phase downstream will be judged against.**
+
+![Phase](https://img.shields.io/badge/phase-3%20of%2014-blue)
+![Role](https://img.shields.io/badge/role-specifier-orange)
+![Gate](https://img.shields.io/badge/gate-hard%20%E2%98%85-red)
+![Status](https://img.shields.io/badge/status-stable-green)
+
+---
+
+## One-Line Purpose
+
+Turn clarified scope and source-backed research into a measurable spec: explicit acceptance criteria, named assumptions, and documented non-goals that all downstream phases treat as law.
+
+---
+
+## Pipeline Position
+
+```
+  DISCOVER
+    │
+    ▼
+┌─────────┐
+│ SPECIFY │  ◄── YOU ARE HERE
+└─────────┘
+    │
+    ▼
+  SPEC-CHALLENGE  ★ gate
+    │
+    ▼
+  DESIGN / PLAN ...
+```
+
+---
+
+## Role Responsible
+
+`specifier`
+
+The specifier transforms research into requirements. It does not invent requirements from nothing — it synthesizes what clarification identified and what research confirmed into a form that can be tested, challenged, and implemented. A specifier who writes acceptance criteria that cannot be verified has produced a spec in name only.
+
+---
+
+## Trigger
+
+Both of the following artifacts are available in run state:
+
+- Clarification artifact (complete, no unresolved blocking questions)
+- Research artifact (all findings cited; no unsupported hypotheses flowing forward)
+
+---
+
+## Steps
+
+1. **Load clarification and research artifacts.** The spec is synthesized from these two sources. Do not introduce requirements not traceable to either.
+
+2. **Write the problem statement.** One paragraph. What is being built and why. Crisp enough that a reviewer who has read neither brief nor research can orient.
+
+3. **Write acceptance criteria.** Each criterion must be:
+   - Testable (can be confirmed true or false with a concrete action)
+   - Specific (no weasel words like "should feel fast" or "works on mobile")
+   - Bounded (scoped to this work, not aspirationally future)
+
+4. **Document assumptions.** Explicitly record every assumption the spec depends on. If the spec is later found to be wrong because an assumption was wrong, the assumption list is the audit trail.
+
+5. **Document non-goals.** State explicitly what this work does NOT do. Non-goals prevent scope creep in planning and execution.
+
+6. **Note open items.** If any advisory question from clarification was not resolved by research, document it here as a spec assumption or escalate to the operator.
+
+7. **Produce the spec artifact.** One document containing problem statement, acceptance criteria, assumptions, and non-goals.
+
+---
+
+## Input Artifacts
+
+| Artifact | Location | Required |
+|----------|----------|----------|
+| Clarification artifact | Run state | Yes |
+| Research artifact | Run state | Yes |
+
+---
+
+## Output Artifacts
+
+| Artifact | Description |
+|----------|-------------|
+| Spec artifact | Problem statement, acceptance criteria, assumptions, non-goals |
+| Acceptance criteria | Flat testable list extracted from spec (used by verifier) |
+| Assumptions list | Named assumptions the spec depends on |
+
+---
+
+## Approval Gate
+
+> [!IMPORTANT]
+> **Explicit human approval is required before planning begins.** The spec is the contract. Once approved, the planner treats it as immutable. Changes to the spec after approval invalidate the plan and require a new planning run.
+
+The approval gate is hard. An unapproved spec cannot be handed to the planner. The `spec-challenge` workflow runs before final approval to adversarially test the spec — do not conflate spec-challenge with final approval. Both must occur.
+
+---
+
+## Example Run
+
+**Research artifact inputs (summary):**
+- CSS custom properties pattern established in codebase
+- `useLocalStorage` hook already exists for persistence
+- Mobile breakpoint at 768px
+- No brand color constraints found (assumption required)
+
+**Spec artifact produced:**
+
+```
+## Problem Statement
+Add a dark mode color scheme to the main dashboard (/dashboard). Users should be
+able to toggle between light and dark mode. Preference persists across sessions
+via localStorage. Dark mode must render correctly at the 768px mobile breakpoint.
+
+## Acceptance Criteria
+AC-1: A toggle control is visible on the /dashboard page at all viewport widths.
+AC-2: Activating the toggle switches the page to a dark color scheme within one
+      render cycle (no page reload).
+AC-3: The dark mode preference survives a page reload (localStorage persistence).
+AC-4: At 768px viewport width, the toggle is accessible and the dark scheme
+      renders without layout breakage.
+AC-5: Toggling from dark back to light restores the original light scheme.
+AC-6: No existing light mode styles are broken by the dark mode implementation.
+
+## Assumptions
+A-1: Dark color palette will be defined by the designer; no pre-existing brand
+     dark palette doc exists.
+A-2: Server-side preference sync is out of scope for this work.
+A-3: Admin panel (/admin) is not in scope.
+
+## Non-Goals
+- OS-level prefers-color-scheme auto-detection (future work)
+- Dark mode for any page other than /dashboard
+- Account-level server-side preference storage
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Impact | Prevention |
+|---------|--------|------------|
+| Writing untestable acceptance criteria | Verifier cannot confirm completion | Each AC must be verifiable with a concrete action and observable outcome |
+| Introducing requirements not in clarification or research | Scope creep before planning even starts | Trace every AC to a clarification item or research finding |
+| Omitting non-goals | Executor and planner add scope during execution | Name non-goals explicitly; "we considered X and excluded it" |
+| Writing assumptions as facts | When an assumption is wrong, there is no audit trail | Mark every assumption clearly as an assumption |
+| Merging spec with design decisions | Spec is what; design is how | AC-6 above is correct ("no existing styles broken"); "use CSS variables" belongs in the plan |
+
+---
+
+## Related
+
+- [Overview — All Workflows](README.md)
+- [Previous: discover](discover.md)
+- [Next: spec-challenge](spec-challenge.md)
+- [Roles and Workflows](../../../concepts/roles-and-workflows.md)

package/docs/readmes/features/workflows/verify.md

@@ -0,0 +1,177 @@
+# verify
+
+**Phase 11 — No completion claim without deterministic proof.**
+
+![Phase](https://img.shields.io/badge/phase-11%20of%2014-blue)
+![Role](https://img.shields.io/badge/role-verifier-orange)
+![Gate](https://img.shields.io/badge/gate-hard%20%E2%98%85-red)
+![Status](https://img.shields.io/badge/status-stable-green)
+
+---
+
+## One-Line Purpose
+
+Produce a deterministic, artifact-backed proof that every acceptance criterion claimed to be satisfied by execution is actually satisfied — because "it works" is not evidence.
+
+---
+
+## Pipeline Position
+
+```
+  EXECUTE
+    │
+    ▼
+┌────────┐
+│ VERIFY │  ◄── YOU ARE HERE
+└────────┘
+    │
+    ▼
+  REVIEW  ★ gate
+    │
+    ▼
+  LEARN ...
+```
+
+---
+
+## Role Responsible
+
+`verifier`
+
+The verifier does not review code quality, architecture choices, or style. It confirms one thing: did execution produce outcomes that satisfy the acceptance criteria? This requires running real commands and capturing real output — not reading code and reasoning about whether it would work.
+
+---
+
+## Trigger
+
+One or more execution batches are complete. The execution notes artifact exists with task completion statuses.
+
+---
+
+## Steps
+
+1. **Load the acceptance criteria from the spec.** This is the verification target. Every AC in scope must be verified.
+
+2. **Load the execution notes.** The notes list what was changed and what per-task verification was run. The verifier confirms these verification steps were valid and ran to completion.
+
+3. **Run verification for each acceptance criterion.** For each AC:
+   - Identify the relevant changed files
+   - Run the relevant test command(s), lint command(s), or visual check
+   - Capture the output
+
+4. **Map test output to acceptance criteria.** Each AC must map to at least one piece of captured output (test result, command output, screenshot). ACs without mapped output are unverified.
+
+5. **Run the full test suite.** Even if per-AC verification passes, the full suite must run clean. Regressions in adjacent functionality are execution failures.
+
+6. **Produce the verification proof artifact.** For each AC: verdict (pass/fail), the command run, and the captured output. A proof artifact must be reproducible — another verifier following the same steps should produce the same result.
+
+---
+
+## Input Artifacts
+
+| Artifact | Location | Required |
+|----------|----------|----------|
+| Changed files | Repo (working branch) | Yes |
+| Claimed outcomes / execution notes | Run state | Yes |
+| Acceptance criteria (from spec) | Run state | Yes |
+
+---
+
+## Output Artifacts
+
+| Artifact | Description |
+|----------|-------------|
+| Verification proof artifact | Per-AC: verdict, command run, captured output |
+
+---
+
+## Approval Gate
+
+> [!IMPORTANT]
+> **No completion claim can be made without a fresh verification proof artifact.** Stale proof (proof from a prior run before the most recent code changes) is not valid. The proof artifact must be produced against the current working branch state.
+
+A partial proof — where some ACs are verified and others are labelled "assumed passing" — is a verification failure. Every AC in scope must have explicit proof.
+
+---
+
+## Example Run
+
+**Acceptance criteria (abbreviated):**
+```
+AC-1: Toggle visible at all viewport widths.
+AC-2: Toggle switches scheme within one render cycle.
+AC-3: Preference persists in localStorage across sessions and new tabs.
+AC-4: Correct rendering at 768px breakpoint.
+AC-5: Toggle back to light restores original scheme.
+AC-6: No existing light mode styles broken.
+```
+
+**Verification proof artifact:**
+
+```
+## AC-1 — Toggle visibility
+Command: `npm test src/layouts/DashboardLayout.integration.test.tsx`
+Output:
+  ✓ toggle renders at 320px viewport (12ms)
+  ✓ toggle renders at 1280px viewport (8ms)
+  2 tests passed
+Verdict: PASS
+
+## AC-2 — Scheme switches within one render cycle
+Command: `npm test src/components/DarkModeToggle.test.tsx`
+Output:
+  ✓ clicking toggle applies data-theme="dark" without page reload (15ms)
+  1 test passed
+Verdict: PASS
+
+## AC-3 — localStorage persistence
+Command: `npm test src/hooks/useDarkMode.test.ts`
+Output:
+  ✓ theme value persists after localStorage clear/re-read simulation (9ms)
+  ✓ new tab simulation reads stored theme on mount (11ms)
+  2 of 6 relevant tests; full suite: 6/6 passed
+Verdict: PASS
+
+## AC-4 — 768px rendering
+Command: `npm test DarkModeToggle -- --viewport=768`
+Output:
+  ✓ touch target ≥ 44px at 768px (snapshot match) (18ms)
+  ✓ focus ring visible at 768px (snapshot match) (14ms)
+  2 tests passed
+Verdict: PASS
+
+## AC-5 — Toggle back to light
+Command: `npm test src/hooks/useDarkMode.test.ts`
+Output:
+  ✓ toggling from dark to light removes data-theme attribute (8ms)
+  1 test passed
+Verdict: PASS
+
+## AC-6 — No regressions
+Command: `npm test`
+Output: 147 tests, 147 passed, 0 failed, 0 skipped
+Verdict: PASS
+
+## Overall: ALL ACs PASS — proof is fresh against branch dark-mode-feature
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Impact | Prevention |
+|---------|--------|------------|
+| Running verification against the wrong branch | Proof is valid for a different state than what ships | Always confirm branch before running verify |
+| Mapping test names to ACs without running the tests | Proof is fabricated; review will be based on false evidence | Run every command and capture actual output — never assume |
+| Marking an AC as "implicitly covered" | The AC has no proof; review cannot confirm it | Every AC needs explicit proof; no implicit coverage |
+| Using stale proof from before the last code change | The proof does not reflect current branch state | Re-run verification after every code change |
+| Stopping at per-task verification without running the full suite | Regressions go undetected until review or production | Full suite is always the final step |
+
+---
+
+## Related
+
+- [Overview — All Workflows](README.md)
+- [Previous: execute](execute.md)
+- [Next: review](review.md)
+- [Roles and Workflows](../../../concepts/roles-and-workflows.md)

package/docs/readmes/packages/README.md

@@ -0,0 +1,50 @@
+# Package Deep Dives
+
+This directory contains detailed technical documentation for each package and plugin used by Wazir. Each document covers what the package is, why Wazir chose it specifically, how it is used in the codebase, and key patterns.
+
+## npm Packages
+
+These are declared in `package.json` as runtime dependencies.
+
+| Package | Version | Purpose | README |
+|---------|---------|---------|--------|
+| `ajv` | `^8.18.0` | JSON Schema validation for manifests and artifacts | [ajv.md](ajv.md) |
+| `gray-matter` | `^4.0.3` | YAML front-matter parsing for skill files | [gray-matter.md](gray-matter.md) |
+| `yaml` | `^2.0.0` | YAML parsing for manifest and hook definition files | [yaml.md](yaml.md) |
+
+## Built-in Node.js Modules
+
+Used as the test runner and assertion library — zero install required.
+
+| Module | Purpose | README |
+|--------|---------|--------|
+| `node:test` | Test runner replacing Jest/Vitest | [node-test.md](node-test.md) |
+| `node:assert` | Assertion library (used alongside `node:test`) | [node-test.md](node-test.md) |
+
+## Claude Code Plugins
+
+External plugins declared as optional adapters in `wazir.manifest.yaml`. Not required for Wazir to function; provides an optional enhancement layer.
+
+| Plugin | Manifest key | Purpose | README |
+|--------|-------------|---------|--------|
+| context-mode | `context_mode` | Context compression and sandboxed file execution | [context-mode.md](context-mode.md) |
+
+## Dependency Philosophy
+
+Wazir intentionally keeps its dependency footprint minimal:
+
+- **Three runtime npm dependencies** — ajv, gray-matter, yaml. No framework, no HTTP client, no ORM.
+- **Zero test framework dependencies** — `node:test` and `node:assert` are built-in to Node.js.
+- **All plugins are optional** — context-mode is declared as `package_presence: optional` in the manifest schema. Wazir's core CLI works without it installed.
+
+This philosophy means `npm install` is fast, the dependency attack surface is small, and there are no version conflicts between the test runner and the production runtime.
+
+## Reading Order
+
+If you are new to the Wazir tooling stack, read in this order:
+
+1. [yaml.md](yaml.md) — foundational; everything starts by reading a YAML file
+2. [ajv.md](ajv.md) — everything read is validated against a schema
+3. [node-test.md](node-test.md) — how the tooling is tested
+4. [gray-matter.md](gray-matter.md) — how skill files are structured and parsed
+5. [context-mode.md](context-mode.md) — optional context optimization layer

package/docs/readmes/packages/ajv.md

@@ -0,0 +1,117 @@
+# ajv
+
+> The fastest JSON Schema validator for Node.js and browsers, supporting JSON Schema drafts 04/06/07/2019/2020.
+
+[![npm version](https://img.shields.io/npm/v/ajv)](https://www.npmjs.com/package/ajv)
+[![license](https://img.shields.io/npm/l/ajv)](https://github.com/ajv-validator/ajv/blob/master/LICENSE)
+[![downloads](https://img.shields.io/npm/dm/ajv)](https://www.npmjs.com/package/ajv)
+
+## What is ajv?
+
+Ajv (Another JSON Validator) is the most widely used JSON Schema validation library in the JavaScript ecosystem. It compiles JSON Schema definitions into highly optimized JavaScript validation functions at startup time rather than interpreting the schema on every call. This compilation step is what makes ajv dramatically faster than interpreted validators — benchmarks consistently show it running 10-100x faster than naive alternatives.
+
+Ajv supports the full JSON Schema specification through multiple drafts. Wazir uses the `2020` draft flavor (`ajv/dist/2020.js`), which is the most modern and supports features like `$dynamicRef`, `unevaluatedProperties`, and the updated `prefixItems` array semantics.
+
+Beyond raw validation, ajv provides structured error output via `validate.errors`: an array of objects describing exactly which path in the instance failed, which keyword triggered the failure, and what the expected value was. This makes it practical to report meaningful validation feedback rather than generic "invalid" messages.
+
+## Why Wazir Uses ajv
+
+Wazir's entire artifact and manifest system rests on JSON Schema contracts. Every phase artifact — from `clarification.json` to `verification-proof.json` — must conform to a schema before it can be accepted. Without reliable, fast schema validation, the system cannot enforce its contracts at the tool boundary.
+
+ajv was chosen over alternatives for three specific reasons:
+
+1. **Compiled validators with caching**: Wazir compiles each schema once and caches the resulting function in a `Map` keyed by `schema.$id`. Subsequent validations of the same schema type hit the cache and pay no re-compilation cost.
+2. **Draft 2020-12 support**: The schemas in `schemas/` use `$id` URIs in the `https://wazir.dev/schemas/` namespace, a pattern encouraged by the 2020 draft. No other popular validator has first-class 2020 support in as stable a form.
+3. **`allErrors` mode**: Wazir configures ajv with `allErrors: true` so that a single validation call surfaces every problem in the document, not just the first one. This is essential for developer feedback — when a manifest or artifact is malformed, the operator sees all issues at once.
+
+## How Wazir Uses It
+
+The entire ajv surface is encapsulated in a single module:
+
+```js
+// tooling/src/schema-validator.js
+import Ajv2020 from 'ajv/dist/2020.js';
+
+const ajv = new Ajv2020({
+  allErrors: true,
+  strict: false,
+  validateFormats: false,
+});
+const validatorCache = new Map();
+
+function formatError(error) {
+  const pointer = error.instancePath || '/';
+  return `${pointer} ${error.message}`;
+}
+
+export function validateAgainstSchema(schema, data) {
+  const schemaKey = schema.$id ?? JSON.stringify(schema);
+  let validate = validatorCache.get(schemaKey);
+
+  if (!validate) {
+    validate = ajv.compile(schema);
+    validatorCache.set(schemaKey, validate);
+  }
+
+  const valid = validate(data);
+
+  return {
+    valid,
+    errors: valid ? [] : (validate.errors ?? []).map(formatError),
+  };
+}
+```
+
+This function is called in two places in production code:
+
+- `tooling/src/commands/validate.js` — validates `wazir.manifest.yaml` and every hook definition YAML against their respective schemas
+- `tooling/src/export/compiler.js` — validates the generated `host-package.json` and `export.manifest.json` objects before they are committed to disk
+
+In tests, `schema-examples.test.js` calls `validateAgainstSchema` directly against all 14 example templates to ensure every template document in `templates/examples/` stays in sync with its schema.
+
+## Key Concepts
+
+**Schema compilation**: `ajv.compile(schema)` returns a reusable `validate` function. Calling `compile` is expensive; calling the resulting function is cheap. Always compile once and cache.
+
+**`instancePath`**: In ajv's error objects, `instancePath` is a JSON Pointer (e.g., `/project/version`) pointing to the failing node in the input data. Wazir formats this as the primary error label.
+
+**`$id`**: A URI in the schema that uniquely identifies it. Wazir uses `$id` as the cache key because it is stable across calls, while `JSON.stringify(schema)` is the fallback for inline schemas without an `$id`.
+
+**`strict: false`**: Disables ajv's strict mode, which would reject schemas using unknown keywords. Wazir schemas use standard keywords only, but this option avoids surprises during schema iteration.
+
+**`validateFormats: false`**: Format validation (e.g., `"format": "uri"`) is disabled because it requires an additional package and is not needed for Wazir's structural contracts.
+
+## API Reference (Wazir-relevant subset)
+
+| API | Usage in Wazir |
+|-----|---------------------|
+| `new Ajv2020(options)` | Instantiated once as a module-level singleton |
+| `ajv.compile(schema)` | Called once per unique schema, result cached |
+| `validate(data)` | Called on every artifact/manifest to be validated |
+| `validate.errors` | Inspected when `validate()` returns `false` |
+| `error.instancePath` | Used as the human-readable location prefix in error messages |
+| `error.message` | The human-readable failure description from the keyword |
+
+## Common Patterns
+
+**Singleton + compile cache**: Create one `Ajv` instance for the entire process. Cache compiled validators by `$id`. This is the pattern used in `schema-validator.js` and is the recommended production approach.
+
+**Structured error surfacing**: Map `validate.errors` to strings before returning. Never expose the raw ajv error objects to callers — they contain internal implementation details that change across versions.
+
+**Schema-first contracts**: Every artifact type in Wazir is defined by a JSON Schema before any code produces or consumes it. The schema is the contract; the validator is the enforcement mechanism.
+
+## Alternatives Considered
+
+| Package | Why not chosen |
+|---------|---------------|
+| `zod` | TypeScript-first, runtime overhead from object construction, no JSON Schema interoperability |
+| `joi` | Custom schema language, not JSON Schema standard, harder to share schemas with non-JS consumers |
+| `jsonschema` | Older, slower, no 2020-12 draft support |
+| Native `JSON.parse` + manual checks | No schema language, no reuse, no standard tooling |
+
+## Resources
+
+- [Official documentation](https://ajv.js.org/)
+- [GitHub](https://github.com/ajv-validator/ajv)
+- [npm](https://www.npmjs.com/package/ajv)
+- [JSON Schema 2020-12 specification](https://json-schema.org/draft/2020-12/json-schema-core.html)

package/docs/readmes/packages/context-mode.md

@@ -0,0 +1,118 @@
+# context-mode
+
+> An optional Claude Code plugin that provides context compression and sandboxed code execution tools for managing large conversation windows.
+
+[![Claude Code Plugin](https://img.shields.io/badge/claude--code-plugin-blue)]()
+[![Install mode](https://img.shields.io/badge/install-external-orange)]()
+[![Status](https://img.shields.io/badge/adapter-optional-lightgrey)]()
+
+## What is context-mode?
+
+context-mode is a Claude Code plugin that addresses one of the fundamental constraints of LLM-based coding agents: context window exhaustion. As a conversation grows — through tool outputs, file reads, test results, and back-and-forth clarification — the context window fills up, forcing the agent to either compact (summarize and lose detail) or stop.
+
+context-mode provides tools that let the agent process files and run code in a sandboxed environment where only the relevant output enters the main context window. Instead of reading a 500-line file verbatim (consuming 500 lines of context), the agent can execute a targeted extraction script against the file and receive only the 10 lines it actually needed. This is the core trade: spend a tool call to save context space.
+
+The plugin also provides an indexing and search surface for large codebases, allowing the agent to find relevant content by semantic or keyword search rather than reading files speculatively.
+
+## Why Wazir References context-mode
+
+Wazir's manifest declares context-mode as an optional external adapter:
+
+```yaml
+adapters:
+  context_mode:
+    enabled_by_default: false
+    required: false
+    install_mode: external
+    package_presence: optional
+```
+
+This declaration is intentional and conservative. Wazir does not depend on context-mode for any of its core operations. The built-in indexing (`wazir index`), recall (`wazir recall`), and capture surfaces are designed to stand on their own without this adapter. The adapter entry in the manifest exists to:
+
+1. **Document the integration point**: Operators who already use context-mode can layer it on top of Wazir without conflict.
+2. **Track the dependency surface**: The manifest schema validates that only known adapters are declared, preventing undocumented external dependencies from accumulating silently.
+3. **Signal opt-in semantics**: `enabled_by_default: false` and `package_presence: optional` tell the tooling that context-mode must never be assumed to be present and must never be required for the core workflow to function.
+
+The Wazir docs explicitly state: "Use the built-in Wazir context reduction path first. Treat context-mode as an optional host-specific enhancement, not a required dependency or product center."
+
+## How Wazir Relates to It
+
+context-mode surfaces appear in the Wazir codebase in two ways:
+
+**1. Manifest adapter registration**
+
+The adapter is declared in `wazir.manifest.yaml` and validated against the adapter schema in `schemas/wazir-manifest.schema.json`. The schema defines the allowed adapter shape:
+
+```json
+"adapter": {
+  "type": "object",
+  "required": ["enabled_by_default", "required", "install_mode", "package_presence"],
+  "properties": {
+    "enabled_by_default": { "type": "boolean" },
+    "required": { "type": "boolean" },
+    "install_mode": { "enum": ["external"] },
+    "package_presence": { "enum": ["optional"] }
+  }
+}
+```
+
+Both `install_mode` and `package_presence` are constrained to `"external"` and `"optional"` respectively — the schema enforces that no adapter can be declared as required or bundled.
+
+**2. Test fixture declarations**
+
+Every test fixture that constructs a synthetic manifest includes the context-mode adapter declaration to match the schema requirements:
+
+```js
+adapters: {
+  context_mode: {
+    enabled_by_default: false,
+    required: false,
+    install_mode: 'external',
+    package_presence: 'optional',
+  },
+},
+```
+
+This appears in both `tooling/test/validate.test.js` and `tooling/test/export.test.js`.
+
+**3. Hook hints in this conversation**
+
+The `PreToolUse:Read` hook in this session adds a context tip pointing toward context-mode's `execute_file` tool as a way to process large files without loading their full content into context. This is context-mode working as designed — the hook system informing the agent of available optimization tools.
+
+## Key Concepts
+
+**Sandboxed execution**: context-mode's `execute_file` and `execute` tools run code in a restricted sandbox. Only stdout is returned to the main context. This prevents accidental side effects while enabling targeted data extraction.
+
+**Context budget management**: The guiding principle of context-mode is that context window space is a finite resource. Every file read, tool output, and conversation turn consumes it. context-mode provides alternatives to full-verbatim reads.
+
+**Opt-in only**: Wazir enforces this at the manifest schema level. No adapter can be declared as required. The system must be fully functional without any adapter installed.
+
+**Lazy integration**: If context-mode is present, the agent can use its tools. If it is absent, the agent falls back to standard file reading and native indexing. No code paths in Wazir's tooling check for or depend on context-mode being available.
+
+## Integration Pattern
+
+When context-mode is installed alongside Wazir, the recommended usage pattern is:
+
+- Use `execute_file` for large files (>50 lines) where only a subset of content is needed — the `PreToolUse:Read` hook tip surfaces this heuristic automatically.
+- Use `search` for finding relevant files across a large codebase before reading them.
+- Use `index` to pre-process a project root so that recall queries return targeted results.
+- Continue using Wazir's built-in `wazir recall` for artifact-specific retrieval.
+
+The two systems are complementary: context-mode handles general context compression; Wazir's built-in indexing handles structured artifact and role/workflow retrieval specific to the Wazir operating model.
+
+## Adapter Validation
+
+Every `wazir validate manifest` run confirms the adapter declaration:
+
+```
+$ wazir validate manifest
+Manifest is valid.
+```
+
+If the `context_mode` adapter block is removed from the manifest, the schema validation fails because `context_mode` is declared as a required key in the `adapters` object in `schemas/wazir-manifest.schema.json`. This ensures the operator cannot accidentally delete the adapter declaration and lose the documented integration surface.
+
+## Resources
+
+- [Wazir adapter documentation](../../adapters/context-mode.md)
+- [Wazir manifest schema](../../../schemas/wazir-manifest.schema.json)
+- [context-mode adapter entry in manifest](../../../wazir.manifest.yaml)