novahiz 0.1.0

package/catalog/rules.json

@@ -0,0 +1,112 @@
+[
+  {
+    "id": "R1-code-prose",
+    "description": "Load humanizer when code or design changes contain prose, and fix any AI writing pattern immediately (not-X-but-Y contrasts, forced triads, excessive dashes, empty phrases, marketing jargon, superlatives).",
+    "when": {
+      "fileClasses": [
+        "code",
+        "design"
+      ],
+      "contentMatches": [
+        "prose"
+      ]
+    },
+    "require": [
+      "humanizer"
+    ]
+  },
+  {
+    "id": "R1-docs",
+    "description": "Load humanizer on text, documentation, and written content.",
+    "when": {
+      "fileClasses": [
+        "text",
+        "data",
+        "config"
+      ],
+      "promptCategories": [
+        "docs-writing"
+      ]
+    },
+    "require": [
+      "humanizer"
+    ]
+  },
+  {
+    "id": "R2-style",
+    "description": "Load impeccable on visual style files.",
+    "when": {
+      "pathGlobs": [
+        "**/*.css",
+        "**/*.scss",
+        "**/*.sass",
+        "**/*.less",
+        "**/*.styl",
+        "**/*.html",
+        "**/*.vue",
+        "**/*.svelte",
+        "**/*.astro"
+      ]
+    },
+    "require": [
+      "impeccable"
+    ]
+  },
+  {
+    "id": "R2-styled-component",
+    "description": "Load impeccable on components whose changes touch styling.",
+    "when": {
+      "pathGlobs": [
+        "**/*.jsx",
+        "**/*.tsx"
+      ],
+      "contentMatches": [
+        "style"
+      ]
+    },
+    "require": [
+      "impeccable"
+    ]
+  },
+  {
+    "id": "R3-supabase",
+    "description": "Load Supabase skills on any Supabase task.",
+    "when": {
+      "pathGlobs": [
+        "**/supabase/**",
+        "**/migrations/**"
+      ],
+      "promptCategories": [
+        "database-supabase"
+      ]
+    },
+    "require": [
+      "supabase",
+      "supabase-postgres-best-practices"
+    ]
+  },
+  {
+    "id": "R4-playwright",
+    "description": "Load playwright-agent on any task using Playwright or navigating to a local server.",
+    "when": {
+      "promptCategories": [
+        "browser"
+      ]
+    },
+    "require": [
+      "playwright-agent"
+    ]
+  },
+  {
+    "id": "R5-design",
+    "description": "When working on a design or UI task, load the impeccable skill and follow its workflow.",
+    "when": {
+      "promptCategories": [
+        "design-ui"
+      ]
+    },
+    "require": [
+      "impeccable"
+    ]
+  }
+]

package/docs/ARCHITECTURE.md

@@ -0,0 +1,82 @@
+# Architecture
+
+Novahiz has one core and thin adapters. The core holds every decision. An adapter only translates between a harness and the core.
+
+## Components
+
+### Spec (source of truth)
+
+Three versioned JSON files under `catalog/`:
+
+- `categories.json` lists categories with keywords and required skills.
+- `rules.json` lists pre-edit rules with conditions and required skills.
+- `overrides.json` carries manual skill curation.
+
+`src/spec.ts` loads them. Nothing secret or machine-specific lives here.
+
+### Catalog
+
+`src/catalog.ts` walks the skill roots, parses each `SKILL.md` frontmatter, merges the overrides, and writes:
+
+- `build/installed-skills.json`, a flat list of installed skill ids. The adapter reads this to avoid requiring a skill that is not present.
+- rows in SQLite for querying and reporting.
+
+### Classifier
+
+`src/classify.ts` folds the prompt (lowercase, accents removed), counts keyword matches per category, sorts by score and priority, keeps the top categories, and returns their required skills. The function is pure. Same input, same output.
+
+### Gate
+
+`src/gate.ts` maps a file path to a class (code, text, design, data, config). It applies each rule whose conditions match the file class, a path glob, or a detected prompt category. Required skills that are not installed are reported separately and do not block. Required skills that are installed but not loaded in the session block the call.
+
+### CLI
+
+`src/cli.ts` is the entry point: it parses `argv`, resolves the `--home` override, and dispatches. The commands themselves live in `src/commands/`, one module for the large ones (`clean`, `doctor`, `gate`, `hook`, `report`, `task`, `tokens`) and `inspect.ts` for the read-only ones. The primitives they all share (`Parsed`, `parse`, `print`, `emit`, `flagOn`, `humanMode`, `confirm`, `dbPathFor`) live in `src/commands/context.ts`, a leaf module that imports nothing from the command modules. Commands return JSON, which is the only integration surface an adapter needs.
+
+### opencode adapter
+
+`adapters/opencode/novahiz.ts` is a plugin. It runs the CLI for classification and gating, tracks loaded skills per session in memory, and injects enforcement text through `experimental.chat.system.transform`. The gate call runs in `tool.execute.before`, which can throw and cancel the tool call.
+
+### content rules and roadmaps
+
+`src/content.ts` provides `changeText`, `hasProse`, and `hasStyle`. Rules in `catalog/rules.json` use them through `when.contentMatches` and `when.contentExcludes`, so `humanizer` and `impeccable` are required only for prose and style changes. `when.match` combines class, path, and category selectors.
+
+Each category carries a `roadmap`. The classifier returns the category order, the primary category, the union of required skills, and the roadmaps. The gate adds the primary roadmap `skill` steps to its requirements. `src/db.ts` stores step progress in `roadmap_progress`.
+
+### Execution ledger
+
+`src/ledger.ts` stores a task and its todos in SQLite (`tasks`, `todos`). Each todo has a kind, a status, an acceptance criterion, an iteration budget, an owner glob, and a proof. `startTodo` enforces dependencies and the budget; `completeTodo` requires a proof on a `verify` step. The plan is mutable: `amendTodo`, `insertTodo`, `dropTodo`, and `reorderTodos` adjust it, and `reviewTask` applies a whole diff in one transaction and bumps `revision`. `reviewDue` reports when the cadence (`edits` or `todos`) is reached, and `revisionSignals` derives concrete reasons to revise from the ledger. `buildWorkPackets` turns the open todos into sub-agent work packets with file ownership, and `traceCheck` verifies that an edit targets an in-progress todo that owns the file. `commandGate` records each edit and blocks edits while a review is due, so the plan is reconciled before work continues.
+
+## Data flow
+
+1. The user sends a message. `chat.message` classifies it, stores the categories and required skills for the session, and reads the active ledger task.
+2. `experimental.chat.system.transform` adds a short enforcement block to the system prompt, including the ledger summary and any review signal.
+3. The model calls `skill` to load a skill. The adapter records it for the session.
+4. The model calls `edit`, `write`, or `patch`. The adapter runs `novahiz gate` with the file path, the session categories, and the loaded skills.
+5. If the gate blocks, the adapter throws and the model sees the list of missing skills or the review reason.
+
+## Determinism
+
+The only inputs to a gate decision are the spec files, the file path, the prompt categories, and the loaded skills. The classifier reads the same spec. There is no network call and no model in the decision path. The adapter keeps state per session in memory.
+
+## Portability
+
+The core runs on Node with no dependencies. A new harness adapter needs two things: a way to run `novahiz classify` and `novahiz gate`, and a pre-tool hook that can abort a call. When the harness has no such hook, the classifier and the system-prompt injection still work, but the gate cannot block.
+
+## Installer
+
+`install/install.mjs` copies the core, the bundled skills, and the plugin into place. It backs up any user file it overwrites (`*.novahiz-bak`) and records what it created in `.novahiz-install.json`, so `install/uninstall.mjs` can restore and reverse.
+
+## MCP server
+
+`mcp/novahiz-tools/index.mjs` exposes `novahiz_classify`, `novahiz_catalog`, `novahiz_roadmap`, `novahiz_providers`, `novahiz_deps`, `novahiz_step`, `novahiz_list_skills`, `novahiz_gate`, `novahiz_task`, and `novahiz_dispatch` over stdio using newline-delimited JSON-RPC. It has no dependencies and reuses the core modules directly. The opencode plugin registers it through the plugin `config` hook.
+
+## Providers
+
+`catalog/providers.json` lists external MCP servers with their purpose and the categories they serve. `src/providers.ts` maps categories to providers and builds MCP entries. The classifier returns the relevant providers, the enforcer injects them, and the plugin registers the missing ones on startup. See [PROVIDERS.md](PROVIDERS.md).
+
+## Next
+
+- Optional embedding tie-break for the classifier.
+- A catalog enrichment pass that fills `stars` from a source.
+- More content matchers beyond prose and style.

package/docs/CONSTITUTION.md

@@ -0,0 +1,60 @@
+# Novahiz Constitution
+
+## Core Principles
+
+### I. Deterministic by Construction
+The same prompt and the same rule set must always produce the same result. Every classification and gate decision runs in code, with no model vote, no random sampling, and no hidden state.
+- Classification, gating, and roadmap selection are pure functions of the prompt, the catalog, the rules, and the loaded skills.
+- Catalog ranking uses a deterministic lexical score. No embeddings, no sampling.
+- A feature that cannot be made deterministic is rejected or isolated behind an explicit opt-in.
+Rationale: the value of the tool is that enforcement is predictable and reproducible. A model judgement inside the decision path breaks that contract.
+
+### II. No Runtime Dependencies
+The shipped runtime relies only on the Node standard library and `node:sqlite`. No third-party runtime package is allowed.
+- No new `dependencies` in `package.json`. Dev-only tooling (TypeScript, types, test helpers) is permitted, and pinned.
+- Node 22.18 is the floor, because the sources run through type stripping.
+- A need that would pull in a native or remote dependency gets a design change, not a dependency.
+Rationale: auditability and simple installation. The tool is meant to be read and trusted end to end.
+
+### III. Enforce Before Writing
+The gate blocks file mutations until the skills required by the prompt's category are loaded. Advice that can be ignored is not enforcement.
+- `edit`, `write`, `patch`, `apply_patch`, and shell writes are gated. Read-only tools are not.
+- Rules are content-aware: `humanizer` is required only for prose, `impeccable` only for interface and style.
+- A block states what is missing and why. A silent or unexplained block counts as a bug.
+Rationale: the tool exists to make quality gates unavoidable. A gate that can be waved through is theatre.
+
+### IV. Harness-Agnostic Core
+All decision logic lives in the CLI and the MCP surface. Adapters stay thin.
+- No harness-specific logic appears in the core modules. opencode is the only adapter today.
+- An adapter may classify input, call the CLI, and translate the result into that harness's hook contract. Nothing more.
+- A new harness is added by writing an adapter, never by branching the core.
+Rationale: one rule set governs every harness. Duplicated logic drifts, and a drifted guarantee is no guarantee.
+
+### V. Tested and Non-Destructive
+Every core capability has a test, and the installer never removes user data.
+- `tsc --noEmit` returns 0 and the full test suite passes before any commit.
+- The installer copies and backfills. It never deletes a file. Machine-specific state (`novahiz.config.json`, the SQLite database) stays local and out of version control.
+- A change that cannot be confirmed by a test is described as unverified, never claimed as done.
+Rationale: the enforcement promise is only as strong as the evidence behind it. Verifiable behavior is the product.
+
+## Additional Constraints
+
+- Versioned configuration is code. Changes to `catalog/categories.json`, `catalog/rules.json`, and `catalog/overrides.json` go through review like source.
+- The published package ships `src`, `adapters`, `catalog`, `install`, `bin`, `mcp`, `skills`, `docs`, `tsconfig.json`, `README.md`, `NOTICE.md`, `novahiz.config.example.json`, and `LICENSE`. It never carries secrets, the local database, or machine-specific config.
+- License is Apache-2.0. The source is public. Anything derived from bundled third-party skills keeps its own attribution.
+
+## Development Workflow
+
+- Run `npx tsc --noEmit` and `node --test` locally. Both must be green before a commit.
+- Dogfood the rules. Load `humanizer` for prose changes and `impeccable` for interface changes, because the gate requires it of everyone.
+- Commit messages describe the behavior change, not the file touched.
+- Before 1.0 the public interface may move. Such changes are called out in the commit and, when relevant, in the README.
+
+## Governance
+
+- This constitution supersedes other practices. When a habit conflicts with a principle, the principle wins, or the principle is amended. It is never worked around.
+- An amendment requires a written rationale, a version bump under the policy below, and a Sync Impact Report at the top of this file stating what changed and what it affects.
+- Versioning: MAJOR for a backward-incompatible removal or redefinition of a principle; MINOR for a new principle or section; PATCH for clarifications and wording.
+- Compliance is checked on every pull request. Reviewers confirm that the change respects the principles, that tests were run, and that no runtime dependency slipped in.
+
+**Version**: 1.0.0 | **Ratified**: 2026-09-11 | **Last Amended**: 2026-09-11

package/docs/EXECUTION.md

@@ -0,0 +1,79 @@
+# Execution ledger
+
+A long task fails in a predictable way: the plan lives in the conversation, the conversation gets compacted, and the agent starts improvising. The ledger moves the plan into SQLite. It survives compaction, it carries a proof per step, and it forces the plan to be revised as the work changes.
+
+## Model
+
+Two tables in the same database as the catalog.
+
+A task holds `id`, `title`, `status` (`active`, `done`, `abandoned`), `session_id`, `created_at`, `updated_at`, and four fields for the living plan: `revision`, `reviewed_at`, `edits_since_review`, `todos_since_review`.
+
+A todo holds `id`, `task_id`, `seq`, `label`, `kind` (`read`, `edit`, `verify`, `delegate`), `status` (`pending`, `in_progress`, `done`, `blocked`, `dropped`), `acceptance`, `proof`, `owner`, `depends_on`, `iterations`, `max_iterations`, `updated_at`.
+
+## Rules that keep it honest
+
+A todo enters `in_progress` only through `start`. Its dependencies must be `done` or `dropped` first. Each start increments `iterations`. The todo allows exactly `max_iterations` starts (12 by default) and the attempt after that fails. This is the loop guard.
+
+A `verify` todo cannot be completed without a proof. The proof is the command you ran and its result, so a test step needs a real test line, not an assertion that it passed.
+
+The task closes itself when every todo is `done` or `dropped`.
+
+## Work packets
+
+`dispatch` turns the pending and in-progress todos into work packets. Each packet carries an objective (the acceptance criterion, or the label), the kind, the owned files, the budget, and the dependencies.
+
+File ownership is a glob on the `owner` field. When two packets own the same file, `dispatch` reports it as a conflict. Parallel sub-agents only help when the lots are independent, so the conflict list is the check to run before splitting the work.
+
+## The living plan
+
+The plan is not frozen. `amend`, `insert`, `drop`, and `reorder` adjust it while it runs.
+
+`review` applies a diff in one transaction: additions, amendments, removals, and a new order. It increments `revision`, records `reviewed_at`, and resets the cadence counters to zero.
+
+The cadence is the forcing function. Every 3 edits or 2 finished todos, a review is due. While a task is active and a review is due, the gate blocks edits and blocks `task start`, so the plan is reconciled before the work continues.
+
+Signals are the reasons to revise, computed from the ledger and not from a model:
+
+- `missing_acceptance`: an edit todo that has no acceptance criterion.
+- `unowned`: an edit todo that owns no file.
+- `parallel`: more than one todo in progress at once.
+- `budget`: an in-progress todo that reached its iteration budget.
+- `blocked`: a todo that is blocked and needs a decision.
+- `ready`: a pending todo whose dependencies are all done, so it can start now.
+
+## Configuration
+
+In `novahiz.config.json`:
+
+```json
+"ledger": { "enabled": true, "review": { "edits": 3, "todos": 2 } }
+```
+
+When no task is active, the ledger does not change gate behavior. The review enforcement only applies to an active task.
+
+## CLI
+
+```
+node src/cli.ts task new --title "Add the CSV export"
+node src/cli.ts task plan --task <id> --json '[{"label":"read the parser","kind":"read"},{"label":"write the exporter","kind":"edit","acceptance":"csv round-trips","owner":"src/export.ts"}]'
+node src/cli.ts task start --id <todo>
+node src/cli.ts task done --id <todo> --proof "node --test tests/export.test.ts -> 4 pass"
+node src/cli.ts task block --id <todo> --reason "missing fixtures"
+node src/cli.ts task status --session <id>
+node src/cli.ts task review --task <id> --json '{"amendments":[{"id":"<todo>","acceptance":"..."}],"additions":[...]}'
+node src/cli.ts task insert --label "handle the BOM" --position start
+node src/cli.ts task drop --id <todo> --reason "out of scope"
+node src/cli.ts task reorder --task <id> --order <id,id,...>
+node src/cli.ts task signals --task <id>
+node src/cli.ts dispatch --task <id>
+```
+
+`task status`, `task resume`, and `task current` print the summary plus a review line and any signal. The adapter injects that summary into the enforcement block on every turn, so the plan stays in front of the model after compaction.
+
+## MCP
+
+`novahiz_task` exposes the same actions over stdio, and `novahiz_dispatch` returns the work packets and conflicts. Both open the same database.
+
+## What it does not do
+
+The gate forces the act of review, not its quality. The signals come from the ledger, so they point at real gaps, but the gate cannot judge whether an amendment is wise. That part stays with you.

package/docs/HARNESSES.md

@@ -0,0 +1,38 @@
+# Harnesses
+
+Novahiz keeps its decisions in the CLI. A harness integration is a thin adapter that calls it. opencode is the supported harness; the MCP server stays usable from any other client.
+
+## opencode
+
+- Skill and plugin: `~/.config/opencode/skills/` and `~/.config/opencode/plugins/`.
+- Slash commands: `~/.config/opencode/commands/` (`novahiz-plan`, `novahiz-clean`, `novahiz-doctor`, `novahiz-status`).
+- MCP: the plugin registers the Novahiz server through the plugin `config` hook, so `opencode.jsonc` is not edited.
+- Gate: the plugin calls `novahiz gate` on `edit`, `write`, `patch`, `apply_patch`, `bash`, and `shell`.
+
+The plugin exists twice. `adapters/opencode/novahiz.ts` in the repository is the source; `~/.config/opencode/plugins/novahiz.ts` is what opencode runs. Editing the source changes nothing until the installer recopies it, and a stale copy keeps the old behaviour without an error. After an update, run the installer and restart opencode. `novahiz doctor` reports this as the `adapter` check.
+
+The agent exists twice as well: `adapters/opencode/agent/novahiz-agent.md` is the source and `~/.config/opencode/agent/novahiz-agent.md` is what opencode loads. Both are compared by the `agent` check.
+
+opencode denies the `question` tool to every agent by default. Only the built-in `build` and `plan` agents re-allow it, so a custom primary agent inherits the denial unless it asks. `novahiz-agent` therefore carries `permission: { question: allow, plan_enter: allow }`. Drop that block and the pipeline can no longer ask a clarifying question or validate a plan, and the `agent` check fails.
+
+Source: opencode plugin docs (`~/.config/opencode/plugins/`).
+
+## Other clients
+
+Any harness with a stdio MCP client can use the same server, `mcp/novahiz-tools/index.mjs`, for `classify`, `catalog`, `roadmap`, `providers`, `deps`, `step`, `list_skills`, `gate`, `task`, and `dispatch`. Register it with that client's own MCP command. Novahiz writes no other harness's configuration.
+
+## What the installer does
+
+`node install/install.mjs` installs the opencode integration:
+
+- Skills into `~/.config/opencode/skills/`, the plugin into `~/.config/opencode/plugins/`, the agent into `~/.config/opencode/agent/`, and the four slash commands into `~/.config/opencode/commands/`.
+- The Novahiz MCP server, registered by the plugin at startup rather than written into `opencode.jsonc`.
+- A skill that already exists in `~/.agents/skills` is skipped rather than copied twice, because the catalog scans both roots and two copies make it describe one version while the harness loads the other. `--force-skills` overrides.
+
+Run it non-interactively:
+
+```
+node install/install.mjs --yes
+```
+
+Every file the installer writes is backed up first as `<file>.novahiz-bak` and tracked in `.novahiz-install.json`. `node install/uninstall.mjs` restores the backups and removes what it created. `--only <dir>` scopes that to one directory, and `--purge` also removes the Novahiz home.

package/docs/INSTALL.md

@@ -0,0 +1,123 @@
+# Install
+
+Novahiz needs Node.js 22.18 or later. There are no runtime dependencies.
+
+## Quick install
+
+Clone the repository into the Novahiz home and run the installer:
+
+```
+git clone https://github.com/novahiz/novahiz ~/.config/novahiz
+node ~/.config/novahiz/install/install.mjs
+```
+
+On Windows, the same command works in PowerShell. If you cloned somewhere else, pass the target home:
+
+```
+node /path/to/novahiz/install/install.mjs --home ~/.config/novahiz
+```
+
+The installer runs `git`-free and never deletes your files. When run in a terminal it is interactive: it prints the plan and the provider list, then asks before writing anything or installing packages. It:
+
+1. Copies the core, the bundled skills, and the plugin into place.
+2. Merges `skills/` into your opencode skills directory, skipping any skill that another scanned root already provides.
+3. Drops the opencode plugin into the plugins directory.
+4. Writes `novahiz.config.json` only if it does not exist.
+5. Builds the catalog with `sync`.
+6. Verifies provider dependencies, and installs them when you confirm or `--install-providers` is set.
+7. Installs the Novahiz agent into `~/.config/opencode/agent/novahiz-agent.md` and the four slash commands into `~/.config/opencode/commands/`.
+
+Restart opencode afterward. The plugin registers the Novahiz MCP server automatically, so you do not edit `opencode.jsonc` by hand. See [HARNESSES.md](HARNESSES.md) for the exact paths.
+
+## Options
+
+- `--home <path>` installs the core to a custom location.
+- `--scope project` targets `./.opencode` instead of the global config.
+- `--dry-run` prints the actions and writes nothing.
+- `--no-skills` skips the bundled skills.
+- `--force-skills` recopies a bundled skill even when another scanned root already provides it.
+- `--install-providers` runs the provider dependency bootstrap and install commands.
+- `--force` rewrites `novahiz.config.json` (the previous file is backed up as `novahiz.config.json.novahiz-bak`).
+- `--yes` skips every prompt. Use it in scripts and CI, where there is no terminal to answer.
+- `--interactive` forces the prompts even when the output is not a terminal.
+
+## What it touches
+
+The installer merges `skills/` into your opencode skills directory, then writes the plugin, the agent, and the slash commands. It skips a skill that already exists in `~/.agents/skills` or another root the catalog scans, because two copies of one skill make the catalog describe one version while the harness loads the other. Pass `--force-skills` to copy anyway. Any file it overwrites is copied first to `<file>.novahiz-bak`, and the list is stored in `.novahiz-install.json`. It never deletes a file it did not create. `node install/uninstall.mjs` restores the backups and removes what the installer created; `--only <dir>` scopes that to one directory, and `--purge` also removes the Novahiz home.
+
+## Maintenance
+
+Two commands keep the install healthy:
+
+```
+node ~/.config/novahiz/src/cli.ts doctor
+node ~/.config/novahiz/src/cli.ts clean --dry-run
+```
+
+`doctor` runs nine checks: Node version, `npx`, the installed-skills index, the referenced skills, the external CLIs the skills call, a gate smoke test, the ledger database, whether the installed plugin copy matches the source, and whether the installed agent grants the `question` tool. It exits non-zero when a blocking check fails, so it works as a pre-flight in scripts.
+
+`clean` trims old rows from the ledger, `novahiz.sqlite`. Targets are `logs` (default), `roadmap`, `sessions`, `tasks`, and `all`; flags are `--days N` (default 30), `--dry-run`, `--apply`, `--vacuum`, and `--json`. Without `--apply` on a terminal it prints the plan and asks; without a terminal it prints the plan and exits 1, so a script cannot delete by accident.
+
+Both accept `--json` for a machine-readable result and `--pretty` to force the human layout; with neither, they detect a terminal.
+
+Any key you omit from `novahiz.config.json` falls back to its default, so a file that sets only `skillRoots` is valid. `novahiz.config.example.json` lists every key with its default and stays a superset of what you normally write.
+
+## Verify
+
+```
+node ~/.config/novahiz/src/cli.ts check
+node ~/.config/novahiz/src/cli.ts classify "ajoute une migration supabase avec une policy rls"
+node ~/.config/novahiz/src/cli.ts gate --file src/hero.css --tool edit
+```
+
+The last command should report missing skills and exit with code 2.
+
+### Exit codes
+
+`novahiz` uses three. `0` means success. `1` means the command failed, and the reason goes to stderr on a single line prefixed with `novahiz:`, whether the cause is a missing config, a corrupt database, an unknown command, or a numeric flag out of range. `2` means the gate refused an edit and listed the skills it wants loaded.
+
+## Update
+
+```
+cd ~/.config/novahiz
+git pull
+node install/install.mjs
+```
+
+## Uninstall
+
+```
+node ~/.config/novahiz/install/uninstall.mjs
+```
+
+The uninstaller restores the files it backed up, deletes the files it created (based on `.novahiz-install.json`), and prunes the directories it emptied. Options:
+
+- `--only <dir>` scopes the whole run to one directory, so removing one integration leaves the others and their manifest entries untouched.
+- `--keep-config` keeps `novahiz.config.json`.
+- `--purge` also removes the Novahiz home directory when the installer created it.
+- `--dry-run` prints the actions and removes nothing.
+
+## Other clients
+
+Any harness with a stdio MCP client can use the server for `classify`, `list_skills`, and `gate`:
+
+```
+node ~/.config/novahiz/mcp/novahiz-tools/index.mjs
+```
+
+Register it with that client's own MCP command. Novahiz does not write another harness's configuration, so there is no hook to install and no gate outside opencode. See [adapters/README.md](../adapters/README.md) for the full picture.
+
+## Publish
+
+The package is ready for npm. Tag a release to publish:
+
+```
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The release workflow runs the tests and publishes with provenance. It needs an `NPM_TOKEN` repository secret. To publish by hand instead:
+
+```
+npm publish --access public
+```

package/docs/PROVIDERS.md

@@ -0,0 +1,128 @@
+# Providers
+
+A provider is an external component Novahiz can provision and reference: an MCP server, a skill pack, or a command pack. Novahiz does not vendor them. It stores the official install command and, when you ask, runs it during installation.
+
+## Licensing
+
+Novahiz references providers, it never vendors them. Each entry lists the upstream `license`, and the installer runs the official install command on your machine, so you install the upstream package under its own terms. That holds for every open-source license, copyleft included.
+
+## Registry
+
+`catalog/providers.json` is the versioned source of truth. Each entry:
+
+```json
+{
+  "id": "playwright",
+  "label": "Playwright browser",
+  "kind": "mcp",
+  "transport": "local",
+  "command": ["npx", "-y", "@playwright/mcp@latest"],
+  "install": ["npx", "-y", "@playwright/mcp@latest", "--help"],
+  "source": "https://github.com/microsoft/playwright-mcp",
+  "license": "Apache-2.0",
+  "categories": ["browser", "design-ui"],
+  "purpose": "Navigate, screenshot, and interact with web pages in a real browser."
+}
+```
+
+- `kind`: `mcp`, `skill`, or `commands`.
+- `command` and `transport`: for `mcp` providers, how to start or reach the server. The opencode plugin registers these.
+- `install`: the official install or warm-up command. This is what the installer runs.
+- `source`: the upstream project.
+- `license`: the upstream SPDX identifier.
+- `categories`: which categories the provider serves. This drives the mapping from a prompt to its tooling.
+
+## Bundled providers
+
+MCP servers:
+
+| Id | Purpose | Categories |
+| --- | --- | --- |
+| `playwright` | Browser automation | browser, design-ui |
+| `security` | SAST/DAST and compliance | audit |
+| `narsil` | Code intelligence | code, debug, review, audit |
+| `context7` | Library docs | code, research |
+| `sequential-thinking` | Structured reasoning | planning, debug, audit |
+| `cron` | Scheduling | devops, general |
+
+Skill and command packs:
+
+| Id | Kind | Install | Categories |
+| --- | --- | --- | --- |
+| `impeccable` | skill | `npx -y impeccable install --providers=opencode --scope=global` | design-ui |
+
+## Mapping
+
+`classify` returns a `providers` list: every provider whose categories intersect the selected categories (any kind). The opencode enforcer injects that list under `Outils pour cette tache`.
+
+```
+node src/cli.ts classify "ouvre la page web et capture un screenshot"
+node src/cli.ts providers --category design-ui
+```
+
+## Registration and install
+
+- MCP servers: the opencode plugin registers every enabled `mcp` provider through the plugin `config` hook, calling `novahiz providers --mcp-json` and merging any server whose key is missing. Existing configuration always wins, so host-specific settings (a Chrome profile path, for example) are preserved.
+- Skill and command packs: Novahiz runs their official `install` command, it does not reimplement it.
+
+Control it in `novahiz.config.json`:
+
+```json
+{
+  "providers": {
+    "autoRegister": true,
+    "autoInstall": false,
+    "disabled": ["cron"]
+  }
+}
+```
+
+- `autoRegister`: register missing MCP servers on startup.
+- `autoInstall`: run the official install commands during `node install/install.mjs`.
+- `disabled`: provider ids to skip.
+
+Run the install commands on demand:
+
+```
+node src/cli.ts providers --install
+node install/install.mjs --install-providers
+```
+
+Installation is opt-in on purpose. The commands download third-party packages, including a large Rust binary for `narsil`, so `autoInstall` defaults to `false`. Enabling it means you trust each upstream listed in `source`.
+
+## Dependencies
+
+Each provider declares its prerequisites in `requires` (the executable it needs) and, when it can be bootstrapped, a per-platform `bootstrap` command. No provider currently declares a `bootstrap`; `novahiz deps --install` supports the field for future entries.
+
+- `npx` based providers need `npx`, which ships with Node.
+
+`novahiz deps` checks every prerequisite and reports what is missing. `novahiz deps --install` first bootstraps a missing prerequisite through its official installer, then runs each provider's install command. The installer runs the check on every install and, when `providers.autoInstall` is true or `--install-providers` is passed, runs the installs too.
+
+## Troubleshooting
+
+Check the `narsil` binary before wiring it into a harness:
+
+```
+narsil-mcp --version
+narsil-mcp tools list
+```
+
+Run `tools list` instead of the bare command. Without a subcommand `narsil-mcp` starts a stdio MCP server and blocks the shell, which looks like a hang.
+
+Common fixes:
+
+- Stale index: rerun with `--reindex`, or clear the default index directory at `~/.cache/narsil-mcp` and reindex. On Windows that directory sits under your user profile.
+- Wrong tree: pass `--repos <path>` or set `NARSIL_REPOS`, and use `--discover <dir>` when you do not know the path.
+- Cache noise while debugging: `--no-cache` skips the cache, and `--cache-ttl <seconds>` moves the default 1800 second window.
+- Slow startup: `--preset minimal` trims the tool surface. The default preset exposes the full set.
+
+Confirm the tool count with `narsil-mcp tools list` afterwards, then rerun `novahiz deps` to recheck the prerequisite.
+
+## Tools
+
+- `novahiz providers` lists providers, optionally by `--category` or a query.
+- `novahiz providers --mcp-json` prints the MCP entry map.
+- `novahiz providers --install` runs the official install commands.
+- `novahiz deps [--install]` checks prerequisites and bootstraps or installs missing ones.
+- MCP `novahiz_providers` and `novahiz_deps` expose the list and the dependency status over stdio.
+- `novahiz report` lists the provider ids.