novahiz 0.1.1 → 0.2.2

package/NOTICE.md

@@ -4,42 +4,35 @@ Novahiz is licensed under Apache-2.0. See [LICENSE](LICENSE).
 
 ## Bundled skills
 
-The `skills/` directory ships a curated set of agent skills so the system works right after installation. Each skill is its own folder, and that folder's license governs it when one is recorded, in this order:
+The `skills/` and `bundled-skills/` directories ship curated agent skills so the system works right after installation. Each skill is its own folder, and that folder's license governs it when one is recorded, in this order:
 
 1. A `LICENSE`, `LICENSE.txt`, or `NOTICE` file inside the folder.
 2. A `license:` field in the skill's frontmatter.
 3. Otherwise the skill belongs to Novahiz and ships under Apache-2.0.
 
-The `novahiz-*` pipeline skills, plus the `gate` and `memory` aliases, are Novahiz's own and always Apache-2.0.
+### Novahiz-owned skills
+
+Every skill under `skills/` is authored by Novahiz and ships under Apache-2.0 unless its frontmatter declares otherwise. Two pipeline skills keep `license: MIT`: `novahiz-humanizer` and `novahiz-security`. The twelve skills that began as third-party material (`mcp-server-builder`, `anti-AI-design`, `frontend-design-taste`, `design-system-tokens`, `apple-hig-audit`, `engineering-code-standards`, `ai-security`, `dependency-auditor`, `env-secrets-manager`, `skill-creator`, `write-a-skill`, `playwright-agent`) were fully reinvented from primary sources and now carry `author: Novahiz` and `license: Apache-2.0`. `prompt-rewriter`, `gate`, and `memory` are also Novahiz-owned (Apache-2.0).
 
 ### Third-party skills with a recorded upstream
 
 | Skill | Upstream | License |
 |---|---|---|
-| `skill-creator` | Anthropic | see `skills/skill-creator/LICENSE.txt` |
-| `humanizer` | pattern catalogue from Wikipedia's "Signs of AI writing" (WikiProject AI Cleanup), attributed in the skill body | MIT as declared in its frontmatter; the source page is CC BY-SA 4.0 |
-| `security-guidance` | ported by Alireza Rezvani from David Dworken's implementation | MIT |
 | `supabase-postgres-best-practices` | Supabase | MIT, declared in its frontmatter |
 | `supabase` | Supabase | not recorded |
-| `write-a-skill` | Matt Pocock (`mattpocock/skills`) | not recorded |
-| `clean-code` | `jackjin1997/ClawForge` | not recorded |
-| `zero-hallucination-coder` | draws on Ralph (`@snarktank`) and GSD Core (`@open-gsd`) | not recorded |
-| `adversarial-reviewer` | ekreloff | not recorded |
-| `apple-hig-expert` | Alireza Rezvani | not recorded |
-| `design-taste-frontend` | Leonxlnx | not recorded |
-| `typescript-expert`, `postgresql-optimization` | community contributions, authors not recorded | not recorded |
+| `android-reverse-engineering` | Simone Avogadro (SimoneAvogadro/android-reverse-engineering-skill) | Apache-2.0, see `bundled-skills/android-reverse-engineering/LICENSE` |
 
-### Third-party skills with no recorded upstream
+All other entries previously listed here (`skill-creator`, `write-a-skill`, `playwright-agent`, `novahiz-humanizer`, `novahiz-security`) were reinvented as original Novahiz work and no longer carry an upstream attribution.
 
-These folders carry no license file, no `license:` field, and no author. Their upstream and license could not be verified from the bundle:
+### Third-party skills with no recorded upstream
 
-`a11y-audit`, `ai-security`, `anti-AI-design`, `anti-pattern-detector`, `api-design-reviewer`, `code-reviewer`, `code-understand`, `database-designer`, `defuddle`, `dependency-auditor`, `engineering-standards`, `env-secrets-manager`, `fix`, `mcp-server-builder`, `migrate`, `review-changes`, `senior-architect`, `senior-backend`, `senior-secops`, `spec-driven-workflow`, `ui-design-system`.
+None at present. Former entries `env-secrets-manager`, `skill-creator`, and `write-a-skill` now have recorded licenses (table above). The former third-party folders `a11y-audit`, `code-reviewer`, `defuddle`, `review-changes`, and `security-guidance` were replaced by the Novahiz-owned `novahiz-*` skills and removed from the bundle; `clean-code`, `zero-hallucination-coder`, `adversarial-reviewer`, `typescript-expert`, `postgresql-optimization`, `anti-pattern-detector`, `api-design-reviewer`, `challenge`, `code-understand`, `database-designer`, `fix`, `migrate`, `senior-architect`, `senior-backend`, `senior-secops`, and `spec-driven-workflow` were removed as redundant with the `novahiz-*` pipeline or outside this project's scope.
 
-They are redistributed as they were found, and this project asserts no license over them. Each one is a candidate for either recording its license or removing it from the bundle. If you hold the rights and want a different attribution or a removal, open an issue on the repository.
+If you hold rights to a bundled skill and want a different attribution or a removal, open an issue on the repository.
 
 ## Providers
 
-Providers are referenced by install command, never vendored. Each lists its upstream license in `catalog/providers.json`. `impeccable` is installed by its provider and is not bundled.
+Providers are referenced by install command, never vendored. Each lists its upstream license in `catalog/providers.json`.
 
 ## Dependencies
 

package/README.md

@@ -1,127 +1,355 @@
-# Novahiz
-
-[![ci](https://github.com/novahiz/novahiz/actions/workflows/ci.yml/badge.svg)](https://github.com/novahiz/novahiz/actions/workflows/ci.yml)
-[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
-[![node](https://img.shields.io/badge/node-%3E%3D22.18-brightgreen.svg)](https://nodejs.org)
-
-A deterministic layer for AI coding harnesses. It catalogs your skills, classifies a prompt into categories, attaches an execution roadmap, and blocks file edits until the required skills are loaded.
-
-The decisions run in code. The same prompt and the same rule set always produce the same result. No model vote, no random sampling, no hidden state.
-
-## What it does
-
-- **Catalog** scans `SKILL.md` files, reads their frontmatter, stores them in SQLite with a curated score, and ranks them by deterministic lexical relevance.
-- **Classifier** maps a prompt to categories (code, debug, review, audit, research, browser, design, Supabase, and more) with weighted keyword rules. It returns the primary category, the required skills, and the execution roadmaps.
-- **Gate** inspects `edit`, `write`, `patch`, `apply_patch`, and shell writes. It is content-aware, so `humanizer` is required only for prose changes and `impeccable` only for style changes. The primary roadmap `skill` steps are enforced. When a required skill is not loaded, the call is blocked with an explanation.
-- **Roadmaps** attach an ordered task list to each category. The primary category drives the roadmap the agent follows.
-- **Enforcer** injects the detected categories, the roadmap checklist, and the expected skills into the system prompt.
-- **Ledger** keeps a long task in SQLite: atomic todos with an acceptance criterion and a proof, a per-todo iteration budget, work packets with exclusive file ownership, and a living plan the gate forces you to revise every few edits. The current plan is injected into the system prompt each turn, so it survives context compaction.
-
-## Pipeline
-
-Non-trivial work follows six stages, in order, each with its own skill:
-
-| # | Stage | Skill | Produces |
-|---|-------|-------|----------|
-| 1 | Plan | `novahiz-plan` | direction, boundaries, dependency order, slicing strategy, risks |
-| 2 | Clarify | `novahiz-clarify` | ambiguity families, question rounds, settled decisions |
-| 3 | Tasks | `novahiz-task` | atomic tasks with acceptance criteria and a proof |
-| 4 | Analyse | `novahiz-analyse` | the files, symbols, and unknowns that matter for the task |
-| 5 | Implement | `novahiz-implement` | increments that keep the system working |
-| 6 | Converge | `novahiz-converge` | the gap between intent and code, closed or left explicit |
-
-`novahiz-planner` orchestrates them and carries the entry rule: no non-trivial edit before a written plan. Stages 1 to 4 write nothing to the application.
-
-The clarification and planning stages ask their questions through the harness question interface, so the agent presents choices and waits for an answer instead of listing questions in prose.
-
-## Status
-
-Phase 1. The core (catalog, classifier, gate, CLI), the bundled skills, the installer, the MCP server, and the opencode adapter work and are covered by tests. Other harness adapters are next. The public interface may change before 1.0.
-
-The package exposes no programmatic import surface. It ships a CLI and an MCP server, so `package.json` declares no `main` and no `exports`.
-
-## Requirements
-
-- Node.js 22.18 or later. Node runs the TypeScript sources directly through type stripping.
-- No runtime dependencies. SQLite comes from `node:sqlite`.
-- `defuddle`, for the web extraction in the `research` roadmap step. `novahiz doctor` reports whether it is present.
-
-## Install
-
-```
-npm install -g novahiz
-novahiz init
-```
-
-Or from source:
-
-```
-git clone https://github.com/novahiz/novahiz ~/.config/novahiz
-node ~/.config/novahiz/install/install.mjs
-```
-
-Restart opencode afterward. The plugin registers the MCP server on its own.
-
-Full options and the uninstall steps are in [docs/INSTALL.md](docs/INSTALL.md).
-
-## Configuration
-
-Generic behavior lives in `catalog/` and is versioned:
-
-- `catalog/categories.json` defines each category, its keywords, the skills it requires, and its execution roadmap.
-- `catalog/rules.json` defines the pre-edit rules (file classes, path globs, prompt categories, content matches, required skills).
-- `catalog/overrides.json` holds manual curation for skills (power, stars, tags, categories).
-
-Machine-specific settings live in `novahiz.config.json`, which is gitignored: the database path, the skill roots, and gate behavior. Copy the example file to create it.
-
-## CLI
-
-```
-novahiz init                    # one-shot setup (config, skills, catalog)
-novahiz doctor                  # health check
-novahiz status                  # classification and gate state
-novahiz task new "Add CSV"      # start a tracked task
-novahiz task status             # show task progress
-novahiz task done <id>          # mark a todo complete
-novahiz report                  # session report
-novahiz clean                   # remove old logs and sessions
-novahiz upgrade                 # pull latest and rebuild catalog
-novahiz version                 # show version
-```
-
-Advanced (for power users and adapters):
-
-```
-novahiz classify "ajoute une migration supabase"
-novahiz gate --file src/hero.css --tool edit
-novahiz skills --category design-ui
-novahiz catalog "design frontend landing" --limit 5
-novahiz roadmap --category code
-novahiz dispatch --task <id>
-novahiz tokens --calibrate
-novahiz clean --days 30 --apply --vacuum
-```
-
-`gate` prints a JSON verdict and exits `0` when the edit is allowed, `2` when it is blocked. Adapters rely on that exit code.
-
-Run `novahiz` with no arguments for the full command list.
-
-## opencode adapter
-
-Copy `adapters/opencode/novahiz.ts` into `~/.config/opencode/plugins/`, or run the installer, which copies it. It loads automatically at startup. The adapter classifies each user message, injects the roadmap checklist and expected skills, tracks loaded skills, and calls the CLI gate on `edit`, `write`, `patch`, `apply_patch`, `bash`, and `shell`.
-
-The installer also drops four slash commands into the opencode command directory: `/novahiz-plan`, `/novahiz-clean`, `/novahiz-doctor`, and `/novahiz-status`. `/novahiz-plan` runs the pipeline read-only and produces the plan without writing a file.
-
-Set `NOVAHIZ_GATE=off` to disable gating for a session. Set `NOVAHIZ_HOME` when the repo is not at `~/.config/novahiz`. Set `NOVAHIZ_DB` to override the database path, which keeps tests and scratch runs off your real ledger.
-
-## Execution ledger
-
-For work that spans more than a few steps, `novahiz task` keeps the plan in SQLite instead of in the conversation. A todo carries its own acceptance criterion, an iteration budget, and, for a `verify` step, a proof that must be present before it can close. `novahiz dispatch` turns the open todos into work packets with exclusive file ownership, so parallel sub-agents do not edit the same file. The gate forces a review every three edits or two finished todos, and the enriched summary is injected on every turn. See [docs/EXECUTION.md](docs/EXECUTION.md).
-
-## Harnesses
-
-The adapter is thin on purpose: the gate logic lives in the CLI. opencode is the supported harness, through the plugin in `adapters/opencode/`. Any harness with a stdio MCP client can use `novahiz_classify`, `novahiz_catalog`, `novahiz_roadmap`, `novahiz_providers`, `novahiz_deps`, `novahiz_step`, `novahiz_list_skills`, `novahiz_gate`, `novahiz_task`, and `novahiz_dispatch`, but the gate only blocks inside opencode. Novahiz also catalogues external components as providers: MCP servers (playwright, security, narsil, context7, sequential-thinking, cron), and skill packs (impeccable), and can run their official install commands. See [docs/HARNESSES.md](docs/HARNESSES.md), [adapters/README.md](adapters/README.md), and [docs/PROVIDERS.md](docs/PROVIDERS.md).
-
-## License
-
-Apache-2.0. See [LICENSE](LICENSE).
+# Novahiz
+
+> **Zero-dependency enforcement layer for AI coding agents** — classifies prompts, assigns execution roadmaps, blocks unsafe edits, and injects session-level skills, all deterministically without model calls.
+
+15 categories, 185 skills, 11 gate rules, 12 MCP providers — all deterministic, all local, all JSON.
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                                                                     │
+│    USER PROMPT  ──▶  CLASSIFIER  ──▶  GATE  ──▶  SAFE OUTPUT      │
+│                                                                     │
+│    "Fix the      3 categories    2 missing     Edit blocked        │
+│     auth bug"    detected         skills        until skills       │
+│                                   required      loaded             │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## What it does
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                        HOW Novahiz WORKS                            │
+│                                                                          │
+│  ┌──────────┐    ┌────────────┐    ┌──────────┐    ┌──────────────┐     │
+│  │  USER    │───▶│  CLASSIFY  │───▶│  INJECT  │───▶│    MODEL     │     │
+│  │  PROMPT  │    │            │    │ ENFORCE  │    │   RESPONSE   │     │
+│  └──────────┘    │ keywords   │    │ block +  │    └──────┬───────┘     │
+│                  │ priority   │    │ roadmap  │           │             │
+│                  │ roadmap    │    │ ledger   │           ▼             │
+│                  └────────────┘    └──────────┘    ┌──────────────┐     │
+│                       │                            │  TOOL CALL   │     │
+│                       │                            │ (edit/write) │     │
+│                       │                            └──────┬───────┘     │
+│                       │                                   │             │
+│                       │         ┌────────────┐            │             │
+│                       └────────▶│    GATE    │◀───────────┘             │
+│                                 │            │                          │
+│                                 │  file path │                          │
+│                                 │  skills    │                          │
+│                                 │  content   │                          │
+│                                 └─────┬──────┘                          │
+│                                       │                                 │
+│                                       ▼                                 │
+│                                 ┌──────────┐                           │
+│                                 │ allow /  │                           │
+│                                 │ BLOCK    │                           │
+│                                 └──────────┘                           │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+**15 categories**, **185 skills**, **11 gate rules**, **12 MCP providers** — all deterministic, all local, all JSON.
+
+---
+
+## Quick start
+
+### Option 1 — One-liner (recommended)
+
+```bash
+npm install -g Novahiz
+```
+
+This installs Novahiz globally and auto-configures opencode (skills, plugin, MCP servers, config). Then verify:
+
+```bash
+npx Novahiz doctor   # 10 health checks
+npx Novahiz classify "fix the auth bug"
+```
+
+### Option 2 — From source
+
+```bash
+git clone https://github.com/novahiz/novahiz.git
+cd novahiz
+npm install && npm run build
+node ./install/install.mjs
+
+# Verify
+npx Novahiz doctor
+```
+
+> Requires **Node.js >= 22.18**. The installer auto-installs opencode if it's missing.
+
+---
+
+## The Classifier
+
+Every user prompt passes through the classifier. It scores keywords against 15 categories and picks the top matches.
+
+```mermaid
+flowchart LR
+    A[User Prompt] --> B[Text Folding<br/>lowercase + strip accents]
+    B --> C{Keyword Scoring<br/>+1.0 per hit<br/>+1.5 multi-word bonus}
+    C --> D[Rank by Score + Priority]
+    D --> E[Top 3 Categories]
+    E --> F[Primary Category<br/>determines roadmap]
+    F --> G[Required Skills<br/>union of all categories]
+    F --> H[Enforced Skills<br/>primary only — gate blocks if missing]
+```
+
+**Example:**
+
+| Prompt | Top Category | Confidence | Skills Required |
+|--------|-------------|------------|-----------------|
+| "fix the auth bug" | `debug` | 0.60 | novahiz-plan, novahiz-analyse, novahiz-implement, novahiz-converge |
+| "add a landing page" | `design-ui` | 0.50 | novahiz-humanizer, anti-AI-design |
+| "create supabase migration" | `database-supabase` | 0.60 | novahiz-supabase, novahiz-postgres, novahiz-plan, novahiz-implement |
+
+---
+
+## The Gate
+
+The gate is the enforcement mechanism. It inspects every file edit and decides: **allow** or **block**.
+
+```mermaid
+flowchart TD
+    A[Tool Call: edit / write / patch] --> B[File Class Detection]
+    B --> C{Rule Matching}
+    
+    C --> D[R1: Content contains prose?<br/>require novahiz-humanizer]
+    C --> F[R3: Prompt was Supabase?<br/>require novahiz-supabase + postgres]
+    C --> G[R4: Prompt was browser?<br/>require novahiz-browser]
+    C --> H[R6: Workflow prompt?<br/>require plan/clarify/analyse/implement/converge]
+    
+    D --> I{Roadmap Enforcement}
+    F --> I
+    G --> I
+    H --> I
+    
+    I --> J{Placeholder Detection<br/>TODO / FIXME / placeholder tokens}
+    
+    J --> K["Check installed skills<br/>(missing → reported, not blocked)"]
+    J --> L["Check loaded skills<br/>(missing → BLOCKED)"]
+    
+    K --> M{All loaded?}
+    L --> M
+    
+    M -->|Yes| N[✅ Allow edit]
+    M -->|No| O[❌ Block edit<br/>list missing skills]
+```
+
+### File classes
+
+| Class | Extensions |
+|-------|-----------|
+| `code` | `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go`, `.rs`, `.java`, `.kt`, `.swift`, `.php`, `.dart`, `.rb` |
+| `design` | `.css`, `.scss`, `.html`, `.vue`, `.svelte`, `.astro` |
+| `text` | `.md`, `.txt`, `.rst` |
+| `config` | `.json`, `.yaml`, `.yml`, `.toml` |
+| `data` | `.csv`, `.sql`, `.db` |
+
+### Gate rules
+
+| Rule | Triggers on | Requires |
+|------|-------------|----------|
+| R1-code-prose | Code or design file whose change contains prose | novahiz-humanizer |
+| R1-docs | Text, data or config file, or a docs-writing prompt | novahiz-humanizer |
+| R3-supabase | A Supabase path or a Supabase prompt | novahiz-supabase, novahiz-postgres |
+| R4-playwright | A browser prompt category | novahiz-browser |
+| R6-Novahiz | A prompt in a workflow category | novahiz-plan, -clarify, -analyse, -implement, -converge |
+| R7-assessment | An assessment prompt | novahiz-assess-intake, -research, -define, -shape, -decide |
+| R8-docs | Edits under `novahiz-docs/**/*.md` | novahiz-docs |
+| R9-code-review | A review prompt or a code file under review | novahiz-code-review |
+| R10-security | An audit or security prompt | novahiz-security |
+| R11-accessibility | A design-ui or audit prompt | novahiz-wcag-audit |
+| R12-web-extract | A research prompt | novahiz-web-extract |
+
+---
+
+## Roadmaps
+
+Each category has an ordered execution roadmap. The gate enforces non-optional `skill` steps.
+
+```mermaid
+flowchart LR
+    subgraph "Feature (code)"
+        A1[advisory: Understand] --> A2[skill: Plan]
+        A2 --> A3[skill: Analyse]
+        A3 --> A4[skill: Implement]
+        A4 --> A5[skill: Converge]
+        A5 --> A6[verify: Verify]
+    end
+    
+    subgraph "Bugfix (debug)"
+        B1[advisory: Reproduce] --> B2[advisory: Isolate]
+        B2 --> B3[skill: Plan]
+        B3 --> B4[skill: Analyse]
+        B4 --> B5[skill: Implement]
+        B5 --> B6[skill: Converge]
+        B6 --> B7[advisory: Prevent]
+    end
+    
+    subgraph "Schema (database-supabase)"
+        C1[skill: Plan] --> C2[skill: Clarify]
+        C2 --> C3[skill: Inspect]
+        C3 --> C4[skill: Load supabase]
+        C4 --> C5[skill: Implement]
+        C5 --> C6[skill: Security]
+        C6 --> C7[skill: Converge]
+    end
+```
+
+| Step Kind | What it means | Gate behavior |
+|-----------|---------------|---------------|
+| `skill` | Load a skill before proceeding | **Blocks** if skill not loaded |
+| `edit` | Make code changes | Allowed |
+| `verify` | Check the work is correct | Advisory |
+| `advisory` | Informational | Never blocks |
+
+---
+
+## Task Ledger
+
+For work that spans more than a few steps, the ledger keeps the plan in SQLite instead of in the conversation.
+
+```mermaid
+flowchart TD
+    A["task new 'Add CSV export'"] --> B[Create task + todos from roadmap]
+    B --> C[Dispatch work packets]
+    C --> D[Each packet = one todo<br/>exclusive file ownership]
+    D --> E[Agent works on todos]
+    E --> F{Review cadence<br/>every N edits}
+    F -->|N reached| G[Force review step<br/>reconcile plan]
+    F -->|N not reached| E
+    G --> E
+    E --> H[All todos done]
+    H --> I[Task complete]
+```
+
+- **Exclusive file ownership** — no two work packets can edit the same file
+- **Iteration budget** — each todo has a max (default: 12) before escalation
+- **Review cadence** — forced review every 3 edits or 2 completed todos
+- **Proof required** — verify steps require evidence before completion
+
+---
+
+## Installed skills
+
+Novahiz ships with 172 skills across all categories:
+
+| Category | Skills | Purpose |
+|----------|--------|---------|
+| `code` | novahiz-code-review, engineering-code-standards, mcp-server-builder, ... | Code quality, patterns, architecture |
+| `debug` | debug-issue, novahiz-analyse, ... | Root cause analysis, code navigation |
+| `review` | novahiz-code-review, review-pr, ... | Structured review, blast radius |
+| `database-supabase` | supabase, supabase-postgres-best-practices, novahiz-postgres, ... | Schema, RLS, migrations, optimization |
+| `design-ui` | anti-AI-design, frontend-design-taste, apple-hig-audit, ... | UI/UX, visual hierarchy, native feel |
+| `docs-writing` | novahiz-humanizer, copywriting, copy-editing, humanizer, ... | Prose, marketing copy, AI de-tell |
+| `browser` | novahiz-browser, playwright-agent, novahiz-web-extract, computer-use, ... | Web automation, screenshots, extraction |
+| `audit` | novahiz-security, narsil-*, dependency-auditor, ai-security, ... | Security, compliance, vulnerability |
+
+Run `npx Novahiz skills --all` to see the full list.
+
+---
+
+## Providers
+
+Novahiz auto-registers external MCP servers based on the prompt category:
+
+| Provider | Purpose | Categories |
+|----------|---------|------------|
+| context7 | Library documentation | all |
+| narsil | Code intelligence, security scan | code, debug, review, audit |
+| novahiz-web-extract | Clean markdown from URLs | research, docs-writing |
+| playwright | Browser automation | browser, design |
+| supabase | Database operations | database-supabase |
+| supabase-postgres-best-practices | Postgres optimization | database-supabase |
+| security | Security orchestration | audit |
+| cron | Scheduled tasks | devops |
+| dart | Dart/Flutter tools | code |
+
+See [docs/PROVIDERS.md](docs/PROVIDERS.md) for full details.
+
+---
+
+## Configuration
+
+```bash
+# Disable the gate (escape hatch)
+NOVAHIZ_GATE=off npx opencode
+
+# Override home directory
+NOVAHIZ_HOME=/path/to/Novahiz npx Novahiz doctor
+
+# Force node version
+NOVAHIZ_NODE=/usr/local/bin/node npx Novahiz doctor
+```
+
+See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for all options.
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `Novahiz init` | One-shot setup |
+| `Novahiz doctor` | 10-check health diagnostic |
+| `Novahiz status` | Current classification + gate state |
+| `Novahiz classify <text>` | Classify a prompt |
+| `Novahiz gate` | Check if an edit is allowed |
+| `Novahiz task new <title>` | Start a tracked task |
+| `Novahiz task status` | Task progress |
+| `Novahiz task done <id>` | Mark a todo complete |
+| `Novahiz report` | Session report |
+| `Novahiz skills` | List loaded or available skills |
+| `Novahiz catalog <query>` | Search the skill catalog |
+| `Novahiz roadmap` | Show execution roadmap |
+| `Novahiz dispatch` | Generate work packets |
+| `Novahiz sync` | Rebuild installed-skills index |
+| `Novahiz clean` | Remove old logs |
+| `Novahiz upgrade` | Pull latest + rebuild |
+| `Novahiz version` | Print version |
+
+See [docs/CLI.md](docs/CLI.md) for full reference.
+
+---
+
+## Documentation
+
+| File | Topic |
+|------|-------|
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design, components, data flow |
+| [docs/CLASSIFICATION.md](docs/CLASSIFICATION.md) | How the classifier works |
+| [docs/GATE.md](docs/GATE.md) | Gate rules, file classes, enforcement |
+| [docs/CATALOG.md](docs/CATALOG.md) | Categories, rules, providers, overrides |
+| [docs/PLUGIN.md](docs/PLUGIN.md) | opencode plugin lifecycle |
+| [docs/CLI.md](docs/CLI.md) | CLI command reference |
+| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | Config files and env vars |
+| [docs/EXECUTION.md](docs/EXECUTION.md) | Task ledger, todos, dispatch |
+| [docs/PROVIDERS.md](docs/PROVIDERS.md) | MCP servers and skill packs |
+| [docs/INSTALL.md](docs/INSTALL.md) | Installation and setup |
+| [docs/ROADMAPS.md](docs/ROADMAPS.md) | Execution roadmaps |
+| [docs/RULES.md](docs/RULES.md) | Gate rules reference |
+| [docs/CONSTITUTION.md](docs/CONSTITUTION.md) | Project principles |
+| [docs/HARNESSES.md](docs/HARNESSES.md) | Harness adapter guide |
+| [docs/TOKENS.md](docs/TOKENS.md) | Token diagnostics |
+
+---
+
+## Philosophy
+
+Novahiz treats skills like **locks** and the prompt like a **key**. The classifier determines which locks exist. The gate checks whether you have the right keys loaded. No key, no edit.
+
+Everything is local, deterministic, and JSON. No cloud calls. No model inference in the decision path. Same prompt + same config = same result, every time.
+
+---
+
+## License
+
+Apache-2.0

package/adapters/README.md

@@ -1,12 +1,12 @@
 # Adapters
 
-Novahiz keeps every decision in the CLI. An adapter only translates a harness event into a `novahiz` call.
+Novahiz keeps every decision in the CLI. An adapter only translates a harness event into a `Novahiz` call.
 
 ## opencode
 
-`adapters/opencode/novahiz.ts` is a plugin. It classifies each user message, injects the roadmap checklist and expected skills, tracks loaded skills per session, and calls `novahiz gate` on `edit`, `write`, `patch`, `apply_patch`, `bash`, and `shell`. The gate is content-aware, so `humanizer` and `impeccable` are required only when the change contains prose or style. It registers the MCP server through the plugin `config` hook, and persists every skill launch with `novahiz session-load`.
+`adapters/opencode/novahiz.ts` is a plugin. It classifies each user message, injects the roadmap checklist and expected skills, tracks loaded skills per session, and calls `Novahiz gate` on `edit`, `write`, `patch`, `apply_patch`, `bash`, and `shell`. The gate is content-aware, so `novahiz-humanizer` is required only when the change contains prose. It registers the MCP server through the plugin `config` hook, and persists every skill launch with `Novahiz session-load`.
 
-`adapters/opencode/agent/novahiz-agent.md` is the primary agent. It carries `permission: { question: allow, plan_enter: allow }`, because opencode denies `question` to every agent by default and only its built-in `build` and `plan` agents re-allow it.
+`adapters/opencode/agent/novahiz.md` is the primary agent. It carries `permission: { question: allow, plan_enter: allow }`, because opencode denies `question` to every agent by default and only its built-in `build` and `plan` agents re-allow it.
 
 ## Other clients
 

package/adapters/opencode/agent/{novahiz-agent.md → novahiz.md}

@@ -10,12 +10,14 @@ permission:
   plan_enter: allow
 ---
 
-You are Novahiz-Agent, the primary agent for the Novahiz deterministic workflow. You run inside opencode with the Novahiz plugin and MCP server active.
+You are Novahiz, the primary agent for the Novahiz deterministic workflow. You run inside opencode with the Novahiz plugin and MCP server active.
+
+Clarification questions must be asked in the same language as the user's input prompt. If the user writes in French, ask in French. If English, ask in English. If Arabic, ask in Arabic. This applies dynamically to all interactive question calls in the Novahiz pipeline.
 
 Work in this order for every request:
 
-1. Classify. Call the `novahiz_classify` MCP tool with the user request, or run `node <novahiz-home>/src/cli.ts classify "<request>"`. Read the returned categories and required skills.
-2. Load skills. Load every required skill with `skill({ name: "<skill>" })` before touching any file. The gate enforces this: `edit`, `write`, `patch`, `apply_patch`, and shell writes are blocked until the required skills are loaded.
+1. Classify. Call the `novahiz_classify` MCP tool with the user request, or run `node NNovahiz-home>/src/cli.ts classify "Nrequest>"`. Read the returned categories and required skills.
+2. Load skills. Load every required skill with `skill({ name: "Nskill>" })` before touching any file. The gate enforces this: `edit`, `write`, `patch`, `apply_patch`, and shell writes are blocked until the required skills are loaded.
 3. Plan. For anything beyond a trivial change, write a short todo list with acceptance criteria.
 4. Execute. Make the change. Prefer small, reversible edits. Keep architecture modular, scalable, and maintainable.
 5. Verify. Run the relevant tests or commands. Report what you ran and what it returned. Never claim a result you did not observe.
@@ -24,7 +26,7 @@ Work in this order for every request:
 Rules:
 
 - Humanizer is required for any text meant for a reader; never for raw navigation or research.
-- impeccable is required for any design or interface change.
+- anti-AI-design and frontend-design-taste are required for design work (R13-design-craft); impeccable is not installed.
 - Load the Supabase skills for any Supabase work.
 - Be honest. Avoid false good ideas. Keep a critical stance. Zero simulation: never pretend to have run, tested, or verified something you did not.
 - Criticize the request when it is inconsistent, ambiguous, risky, or suboptimal, and propose an alternative.

package/adapters/opencode/commands/novahiz-doctor.md

@@ -6,4 +6,4 @@ description: Run Novahiz diagnostics. Arguments: $ARGUMENTS
 
 2. Run `node src/cli.ts doctor` from the Novahiz home.
 
-3. For each failing check, provide the exact fix to run based on the returned details. For example `npm install -g defuddle` when an external CLI is missing, or `node src/cli.ts sync` when the index is stale.
+3. For each failing check, provide the exact fix to run based on the returned details. For example `node src/cli.ts sync` when the index is stale, or reinstall a missing skill when `referenced` fails.