novahiz 0.9.3 → 0.9.6

package/CHANGELOG.md

@@ -3,6 +3,257 @@
 All notable changes to Novahiz are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [Unreleased]
+
+## [0.9.6] - 2026-10-15
+
+### Added
+
+- **`PRODUCT.md` and `DESIGN.md`** - the product context and the visual-system
+  record `impeccable` asks for, both written from sources in the repository
+  (`README.md`, `docs/CONSTITUTION.md`, `src/render.ts`) with anything they do
+  not settle marked "not determined" instead of guessed. `novahiz doctor` runs
+  from a project now finds both instead of two `fail` rows; when doctor runs
+  from the Novahiz home both rows are skipped by design
+  (`impeccableChecks` returns early when `cwd === home`).
+
+- **`when.pathExcludes`** - a rule-level *negative* selector, the counterpart of
+  `pathGlobs`. A rule carrying it never applies to a matching path, whatever the
+  other selectors say. With `match: "any"` a prompt category alone fired on any
+  file, so `design-ui` demanded the frontend design skills on unit tests, and
+  inclusion-only selectors could not express "never on tests" (`**/*.tsx` also
+  matches `tests/Foo.test.tsx`). Applied to the five design-scoped rules
+  (R11-accessibility, R13-design-craft, R14-impeccable, R16-stitch-fidelity,
+  R17-wireframe), which now skip `**/tests/**`, `**/__tests__/**`,
+  `**/*.test.*` and `**/*.spec.*`. R9-code-review and R10-security are
+  untouched — a test is still code — and R15-token-economy keeps its own
+  `**/tests/token-economy.test.ts` target.
+
+### Changed
+
+- **The installer states its own limit** - `install.mjs` now prints that
+  `deps --install` is an install-only pass: packs already present are left
+  untouched, and `/novahiz-skills-update` (`deps --install --update`) is what
+  refreshes them. Installation and update stay separate commands by choice — a
+  reinstall must not overwrite local skill edits — but the choice was previously
+  only written down in `docs/PROVIDERS.md`, not shown to the person installing.
+
+### Fixed
+
+- **`doctor` no longer advises a command that cannot help** - the "Referenced
+  skills" row counted every absent non-shipped skill as a pack skill and
+  answered "run /novahiz-skills-update, or novahiz deps --install". Measured on
+  the 0.9.5 install: the 7 skills it named are `eas-app-stores`, `eas-hosting`,
+  `eas-observe`, `eas-simulator`, `eas-update`, `eas-update-insights`,
+  `eas-workflows`, referenced as `defaultSkills` by the `test` and `devops`
+  categories, while `catalog/providers.json` ships four skill packs only
+  (`flutter-skills`, `dart-skills`, `expo-skills`, `impeccable`) and the expo
+  command names 20 `expo-*` skills, no `eas-*`. `deps --install` accordingly
+  returned `install: []` and exited 0 - nothing to install. The row now reads
+  each pack's `install` argv (`--skill` list, or `--skill *` resolved to the
+  repo's leading segment, so `dart-lang/skills` covers `dart-*`), and skills no
+  pack can deliver are named as such instead of being sent after a command that
+  installs nothing. New `tests/doctor-referenced-skills.test.ts` pins the
+  contract - eight cases, none existed before.
+
+## [0.9.5] - 2026-10-15
+
+> 0.9.4 was prepared on 2026-10-14 but never tagged nor published to npm
+> (the registry went straight from 0.9.3 to 0.9.5). Its changes are included
+> here and remain described under their own heading below.
+
+### Added
+
+- **Wireframe-first design pipeline** - new `novahiz_wireframe` MCP tool and
+  `src/wireframe.ts` module
+  (`init/screen/section/sections/plan/review/index/attach/mark/status`).
+  Each screen gets a subfolder of ordered, annotated sections plus a
+  regenerated `INDEX.md`; `attach` returns the whole wireframe as the
+  attachment block fed to `impeccable shape`. `sections` creates a whole
+  batch in one call (one `INDEX` rebuild instead of one per section, existing
+  names skipped); `plan` classifies the screen and says whether it needs
+  several sections and why; `review` reports the sections that were
+  forgotten and gates approval (`mark` refuses while `verdict != pass`).
+  Sections are renumbered from the highest existing index instead of
+  `length + 1`. Gate rule `R17-wireframe` and the `wireframe` roadmap step
+  (before `impeccable-shape`) make the sequence mandatory on `design-ui`
+  work and on screen/page/component paths. New skill `novahiz-wireframe`,
+  tested by `tests/wireframe.test.ts`.
+- **`novahiz deps` reports real dependency health** - the single provider
+  check is replaced by a four-part `dependencyReport`: toolchain probing
+  (node, npm, npx, uv, python), local MCP entrypoint `existsSync`, npm home
+  health (declared deps resolved + lockfile present), and provider
+  prerequisites. `novahiz_deps` returns the same shape.
+- **Core toolchain bootstrap** - `deps --install` can now install `uv` and
+  Python on win32 / darwin / linux. The argv lives in `src/deps.ts`
+  (`coreBootstrap`), not in the catalog, and runs through a plain spawn:
+  `runScript`'s allowlist deliberately refuses shells and package managers,
+  so catalog data can never widen it. `--core-only` installs only toolchain
+  and npm health; the installer uses it when providers are declined.
+- **Idempotent provider installs** - a new `installedWhen` field on a
+  provider lists skill ids whose combined presence marks the pack already
+  installed; when all of them are on disk the install command is skipped, so
+  a second `deps --install --yes` runs nothing. Providers without the field
+  keep the historical always-run behaviour.
+- **Gate rule `R18-skill-craft`** - `novahiz-skill-craft` is now actually
+  required on any `SKILL.md` edit, matching what its own description
+  already promised.
+- **Skills `novahiz-prd` and `novahiz-skill-craft`** ship in the package.
+- **Commands `novahiz-obsidian` and `novahiz-obsidian-audit`**, plus
+  `bin/veille-mensuelle.ps1`.
+- **A real refresh path for the provider skill packs** - `deps --install
+  --update` and a per-provider `update` command in `catalog/providers.json`.
+  `deps --install` drops every pack whose `installedWhen` markers are all on
+  disk, so it could only fill gaps: `/novahiz-skills-update` called it and
+  therefore refreshed nothing, which is why flutter/dart/expo were never
+  actually updated. `updateCommands()` reads the provider's `update` command
+  instead and applies no `installedWhen` gate. For the skills CLI that command
+  is the upstream `skills update -g -y`, already present in the pinned
+  `skills@1.7.0`. An identical argv shared by several providers is deduplicated
+  and records the packs it covers under `covers`, in the dry-run plan and in
+  the result, so a skipped pack can no longer be mistaken for an updated one.
+  `/novahiz-skills-update` gained an explicit step 4 running it.
+- **The Flutter skill pack is installed from its official repository** -
+  `flutter/agent-plugins` is now recorded as `flutter/skills`, the name used by
+  the Flutter blog post *Introducing Skills for Dart and Flutter*. The two
+  resolve to the same repository (identical `main` HEAD `0ef3972` and branch
+  list), so this is a provenance correction, not a source change.
+
+### Fixed
+
+- **`tests/plugin-warmstart.test.ts` failed `tsc --noEmit`** with three real
+  type errors: the `editor` parameter shadowed the `editor` binding, making
+  `typeof editor` self-referential (TS2502), and `await cleanup()` was called
+  on the `void | Cleanup` union without a guard (TS2349, twice). The previous
+  session reported this file as type-clean; that report was wrong.
+- **`Agent harness copy outdated`** — the last non-blocking `doctor` failure —
+  is repaired by `node install/install.mjs --yes` alone. Only the rewrite of
+  `novahiz.config.json` is gated on `--force`; the plugin, agent and command
+  copies are not, so a plain run refreshes them while the config reports
+  `Existing config preserved`.
+
+### Changed
+
+- **`novahiz sync` is now listed in `--help`** - the command existed
+  (`case "sync"` → `commandSync()`), and both `gate.ts:498` and
+  `gate-repair.ts:87` pointed users at it, but it was missing from the help
+  output.
+- **The installer no longer backs up the published package inside its own
+  home** - the home is a copy of what npm already holds, so preserving its
+  previous version only accumulated `*.novahiz-bak` (235 of the 320 found by
+  the audit). Backups are kept only where they carry something that exists
+  nowhere else: `catalog/` (user-edited configuration) and the files written
+  into the opencode config dir, which are exactly what `novahiz uninstall`
+  restores (`uninstall.mjs:53`).
+- **`scripts` is part of `CORE_ITEMS`** - `package.json` copied into the home
+  declares `ci:local = node scripts/ci-local.mjs`, but the directory was
+  never copied, so `npm run ci:local` failed there.
+- **Windows PATH staleness is no longer reported as a missing dependency** -
+  the parent process may predate the install (opencode started before uv or
+  Python landed), so its inherited PATH hides binaries that ARE on disk.
+  `toolchainStatus` reloads PATH from the registry (Machine + User) once and
+  re-probes. `python` is probed with `--version` rather than `where python`,
+  because the `WindowsApps` execution alias answers on machines without any
+  Python.
+- **The installer asks about providers by default** (`true` instead of
+  `false`) and adds a `--no-deps-install` flag. Automatic dependency
+  installation now defaults to on (`autoInstall !== false`); when providers
+  are declined the toolchain and npm health still install, being system
+  dependencies rather than optional providers.
+- **`npm install` runs with `--ignore-scripts`** and `npm_config_global=false`,
+  scoped to the Novahiz home, so nothing in the home re-enters the
+  installer.
+
+### Notes
+
+- `novahiz deps` and the `novahiz_deps` tool change their JSON contract:
+  `{node, platform, dependencies}` becomes
+  `{node, platform, toolchain, dependencies, entrypoints, npm}`, and the
+  dry-run `plan` becomes `{core, npm, bootstrap, install}`. Anything parsing
+  the old shape must be updated.
+
+## [0.9.4] - 2026-10-14
+
+### Fixed
+
+- **No absolute machine path is shipped any more** - the tree handed to every
+  member of the community carried the drive letters, the folders and the
+  account name of the machine Novahiz was developed on, so the system was
+  broken on arrival for anyone else.
+  - `adapters/opencode/instructions.md` (the system prompt injected into every
+    session), `skills/novahiz-browser/SKILL.md` and
+    `skills/browser-session/SKILL.md` pointed the Playwright profile at a
+    hardcoded `C:\Users\<account>\.opencode\playwright-profile`. The profile
+    rule was unusable and the browser profile wrong for every other user. All
+    three now use `~/.opencode/playwright-profile`.
+  - `docs/TOKENS.md`, `docs/audit-2026-09-25.md`,
+    `mcp/argus/IMPLEMENTATION-SUMMARY.md` and
+    `mcp/stitch-template/recommandation.md` presented absolute paths as
+    instructions to run. They now use `~` or `<NOVAHIZ_HOME>`.
+  - The placeholders shipped to the agent were corrupted:
+    `node NNovahiz-home>/src/cli.ts classify "Nrequest>"` and
+    `skill({ name: "Nskill>" })` in `adapters/opencode/agent/novahiz.md`. They
+    are restored to `<Novahiz-home>`, `<request>` and `<skill>`, so the first
+    step of the pipeline is executable as written.
+
+- **Home resolution no longer yields a ghost home** - `src/cli.ts`,
+  `src/commands/upgrade.ts` and `src/commands/second-memory.ts` built the home
+  from `process.env.HOME || process.env.USERPROFILE || ""`. When both are
+  absent - a Windows service, the gate daemon child, a container - the joined
+  result was a path relative to the cwd, so `detectTarget`, `runSync` and the
+  Stitch recommendation all operated silently on a directory that does not
+  exist. All three now resolve through `NovahizHome()` or `homedir()`.
+
+- **The C3 index guard fires on Windows** - `src/gate.ts` compared the
+  protected `build/installed-skills.json` and `build/catalog.json` suffixes
+  spelled with `/` against a path carrying the platform separator, so the guard
+  never triggered on Windows. Those two files define what the gate requires and
+  were editable like ordinary build output on the platform most of the
+  community installs on. The path is now normalised before comparison.
+
+- **The gate daemon stops flashing a console window on Windows** -
+  `adapters/opencode/novahiz-plugin.ts` spawned it without `windowsHide: true`,
+  the only spawn site in the file missing it.
+
+- **Duplicated `NOVAHIZ_HOME` reads** in `src/spec.ts` and `install/lib.mjs`
+  collapse into one canonical read. A user who exported the older variable name
+  silently kept the default home while believing they had redirected it.
+
+- **`novahiz doctor` stops failing at home root on project context** -
+  `src/commands/doctor.ts` resolved `PRODUCT.md` and `DESIGN.md` against the
+  novahiz home, producing two permanent rows no command could close. The rows
+  are scoped to a project directory and remain unchanged inside one.
+
+- **A plan that declares its dependencies by label no longer wedges** -
+  `src/ledger.ts` resolved each dependency by todo id only, while
+  `novahiz task plan` accepts labels ("T2", "P5"). Every label-declared
+  dependency read as unfinished and blocked its dependent step for the whole
+  life of the task. Resolution now accepts both, and fails closed on an
+  unknown or ambiguous reference.
+
+### Added
+
+- **A persistent gate daemon** (`src/gate-daemon.ts`, wired in
+  `adapters/opencode/novahiz-plugin.ts`) replaces one Node process spawn per
+  gate call. Every request re-executes `commandGate`, which re-reads
+  `rules.json`, `categories.json` and the skill index from disk, so no verdict
+  can go stale; any daemon failure returns as `spawnError` and the existing
+  deny path applies unchanged. Measured on this machine: one-shot median 331 ms
+  against 8.1 ms warm.
+
+### Changed
+
+- **Portability is enforced by a test** - `tests/portability-paths.test.ts`
+  fails the build on an absolute machine path, a machine account name, an MCP
+  command the catalog cannot resolve to an absolute path, or a regression of
+  the C3 guard. It ships a negative proof: an injected path makes it fail by
+  file and line.
+
+- **`.novahiz-install.json` and `novahiz.config.json` are no longer tracked** -
+  the install manifest embedded the absolute paths and the account name of the
+  machine that ran the installer, and was published with them. Both are
+  machine-local state regenerated on demand, and are now ignored.
+
 ## [0.9.3] - 2026-10-11
 
 ### Changed

package/README.md

@@ -314,7 +314,7 @@ Deux pièces complémentaires : la session consomme moins sans perdre en puissan
 
 ## Skills installées
 
-Novahiz livre 94 skills couvrant toutes les catégories — 46 dans le cœur du dépôt, les autres dans les packs officiels installés par défaut au setup :
+Novahiz livre 95 skills au total — le cœur du dépôt, plus les packs officiels installés par défaut au setup :
 
 | Catégorie | Skills | Objectif |
 |-----------|--------|----------|
@@ -327,9 +327,11 @@ Novahiz livre 94 skills couvrant toutes les catégories — 46 dans le cœur du
 | `browser` | novahiz-browser, browser-session, novahiz-web-extract, ... | Automatisation web, captures, extraction |
 | `audit` | novahiz-security, package-risk-audit, llm-threat-review, ... | Sécurité, conformité, vulnérabilités |
 | `expo` | expo-overview, expo-router, expo-module, expo-dev-client, ... | Expo / React Native : routes, modules natifs, builds |
-| `devops` | eas-workflows, eas-app-stores, novahiz-release, ... | CI/CD, déploiements, releases versionnées |
+| `devops` | novahiz-release, novahiz-init, ... | Releases versionnées, onboarding, installation |
 
-Lancer `npx novahiz skills --all` pour voir la liste complète.
+Le décompte exact se relit à tout moment : `novahiz sync` (index) et `novahiz doctor` (ligne `Referenced skills`). `npx novahiz skills --all` donne la liste complète.
+
+> Les skills `eas-*` (workflows, stores, hosting, observe, update) sont des packs **payants** upstream : elles ne sont pas installées par défaut et `novahiz doctor` les exclut de `Referenced skills` par conception.
 
 ---
 
@@ -348,9 +350,22 @@ Novahiz auto-enregistre les serveurs MCP externes selon la catégorie du prompt
 | novahiz-scheduler | `mcp/clepsydre/index.mjs` (local, zéro dépendance) | Apache-2.0 | devops |
 | dart | `dart mcp-server` (Dart SDK) | BSD-3-Clause | code, debug, design-ui, flutter |
 
-Packs de skills (installés depuis les dépôts officiels, jamais vendorés, et livrés **par défaut** au setup via `providers.autoInstall`) : `flutter/agent-plugins` (10 skills), `dart-lang/skills` (15 skills), `expo/skills` (19 skills, le groupe `expo-*` seulement ; les services payants `eas-*` exclus), `pbakaus/impeccable` (1 skill, la skill design upstream `impeccable`).
+Packs de skills (installés depuis les dépôts officiels, jamais vendorés, et livrés **par défaut** au setup via `providers.autoInstall`) : [`flutter/skills`](https://github.com/flutter/skills) (10 skills), `dart-lang/skills` (15 skills), `expo/skills` (19 skills, le groupe `expo-*` seulement ; les services payants `eas-*` exclus), `pbakaus/impeccable` (1 skill, la skill design upstream `impeccable`).
+
+**`git` est requis** par le CLI officiel des skills : sans lui, l'installation des packs échoue silencieusement et les skills manquent au premier lancement. `novahiz doctor` le nomme (ligne `git (skill packs)`).
+
+### Installer, puis mettre à jour : deux étapes distinctes
+
+`deps --install` ne **remplit que les trous**. Dès qu'un pack est présent, sa commande d'installation est écartée (marqueur `installedWhen` satisfait) — sinon une seconde passe réinstallerait inutilement 45 skills. Conséquence directe : **cette même commande ne peut jamais rafraîchir un pack déjà installé.**
+
+```
+novahiz deps --install          # installe ce qui manque (packs absents)
+novahiz deps --install --update # rafraîchit tout depuis upstream
+```
+
+`--update` exécute la commande `update` déclarée par chaque provider — pour le CLI des skills, la sous-commande officielle `skills update -g -y`, qui parcourt les quatre sources (dart, flutter, expo, impeccable) en une passe. Contrairement à l'installation, **elle n'est jamais écartée** : rafraîchir un pack à jour est exactement le travail demandé.
 
-**`git` est requis** par le CLI officiel des skills : sans lui, l'installation des packs échoue silencieusement et les skills manquent au premier lancement. `novahiz doctor` le nomme (ligne `git (skill packs)`), et **`/novahiz-skills-update`** — ou `novahiz deps --install` — réinstalle proprement tous les packs depuis leurs providers officiels. Voir [docs/PROVIDERS.md](docs/PROVIDERS.md).
+`/novahiz-skills-update` enchaîne les deux. Chaque plan porte `step: "update"` et, quand une même commande couvre plusieurs packs, la liste `covers` — on ne peut donc pas confondre un pack écarté et un pack mis à jour. Voir [docs/PROVIDERS.md](docs/PROVIDERS.md).
 
 Dépôts upstream et provenance complète des providers MCP et plugins opencode : [docs/PROVIDERS.md](docs/PROVIDERS.md), [docs/HARNESSES.md](docs/HARNESSES.md), [NOTICE.md](NOTICE.md).
 
@@ -396,6 +411,7 @@ Voir [docs/CONFIGURATION.md](docs/CONFIGURATION.md) pour toutes les options.
 | `novahiz roadmap` | Afficher la roadmap d'exécution |
 | `novahiz dispatch` | Générer des work packets |
 | `novahiz sync` | Reconstruire l'index des skills installées |
+| `novahiz deps --install [--update]` | Installer les packs de skills manquants, ou les rafraîchir tous avec `--update` (voir [Providers](#providers)) |
 | `novahiz clean` | Supprimer les vieux logs |
 | `novahiz upgrade` | Pull du dernier + rebuild |
 | `novahiz version` | Afficher la version |

package/adapters/opencode/agent/novahiz.md

@@ -16,8 +16,8 @@ Clarification questions must be asked in the same language as the user's input p
 
 Work in this order for every request:
 
-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.
+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.
 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.

package/adapters/opencode/commands/novahiz-obsidian-audit.md

@@ -0,0 +1,28 @@
+---
+description: Audit AND auto-fix the whole Obsidian data arborescence: structure, links, coherence. Runs doctor --apply (category by category), then sync --apply, then lint. Arguments: $ARGUMENTS
+---
+
+1. Locate the Novahiz home: `NOVAHIZ_HOME` if set, otherwise `~/.config/novahiz`. The CLI is `<home>/src/cli.ts`.
+
+2. Run `node src/cli.ts second-memory doctor --apply $ARGUMENTS` from the Novahiz home. This **auto-fixes** everything category by category: missing folders created, MOCs created, links repaired, root notes relocated, naming fixed. Every moved file is backed up first. Pass `--no-plugins` to skip the mandatory plugin check, `--json` for structured output.
+
+3. The command exits 1 while issues remain and 0 when the vault is clean. For each `[fail]` check:
+    - `skeleton` — the vault is missing `INDEX.md`, `STRUCTURE.md` or a system folder: auto-recreated by `doctor --apply`.
+    - `arborescence` — a note sits at the vault root, a folder has no `_MOC.md`, a child MOC is not linked from its parent, a domain is only partially materialised, or `INDEX.md → ## Categories` does not list exactly the active domains. Auto-fixed by `doctor --apply`.
+    - `links` — broken wikilinks or orphans: auto-fixed by `doctor --apply` (runs the `fix` repairs).
+    - `plugins` — a mandatory community plugin is missing or disabled: auto-fixed by `doctor --apply`.
+    - `outside-tree folders` (warn) — a top-level folder is not in `catalog/vault-structure.json`. Doctor does not move folders: report them and migrate their notes by hand.
+    - `memory` (warn) — project memory has pending changes: auto-fixed by `sync --apply` below.
+
+4. Then the **global coherence pass** — from the project directory, beyond what doctor checks structurally:
+    - `node src/cli.ts second-memory sync --apply`: pending slot pulls/pushes AND `novahiz-docs/` mirror drift are auto-applied. Mirror drift means the repo docs moved ahead of the vault.
+    - Verify the active project's binding exists (`vault.json` at the memory root `sync` uses —
+    `project-memory/vault.json` or `~/.config/project-memory/vault.json`) and its chain is
+    materialised (`Code/<branch>/<project>/{docs,journal,decisions}/`). A memory root without a binding
+    means `project-init` never ran: notes then fall back to content-keyword routing and may
+    land in `Inbox` or a wrong branch. Report every note found outside the bound chain, but
+    NEVER move a note automatically — propose the move and wait for consent.
+    - Consistency across the three layers (repo `novahiz-docs/` ↔ vault `docs/` chain ↔ vault `memory/` chain): same project folder spelling everywhere, no duplicate project folders (a leftover `general/` or old-chain folder next to the real one), no empty bound folder left after a rebind.
+    - When doctor passes but something still looks off, run the strict pass: `node src/cli.ts second-memory lint`.
+
+5. Report what the audit found, what was actually repaired (with the backup location), what remains — including coherence suggestions you did not apply. Never claim a repair you did not run.

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

@@ -0,0 +1,27 @@
+---
+description: Initialize Obsidian vault structure for the active project. Arguments: $ARGUMENTS
+---
+
+1. Locate the Novahiz home: `NOVAHIZ_HOME` if set, otherwise `~/.config/novahiz`. The CLI is `<home>/src/cli.ts`.
+
+2. If `$ARGUMENTS` is `init` (or empty), first run the preview from the project directory (the active project — its cwd gives the name, its dependencies the routing):
+
+   `node src/cli.ts second-memory project-init --dry-run --json`
+
+   Show the routed chain and the mirrored files. Unless the user only wanted the preview, run it for real:
+
+   `node src/cli.ts second-memory project-init --json`
+
+   Extra flags when the routing must be forced: `--project <name>`, `--domain <Domain> --branch <Branch>` (both together).
+
+3. What it does — additive and idempotent, nothing existing is overwritten:
+   - creates the project chain `Code/<branch>/{memory,docs}/<project>/` (folders, `_MOC.md` links at every level, `INDEX.md` entry, domain activated whole);
+   - writes the routing binding in a `vault.json` sidecar at the memory root `sync` uses
+   (`project-memory/vault.json` in the project, or `~/.config/project-memory/` when that
+   global root exists — future `second-memory sync` runs send this project's slots and doc
+   mirror to the bound chain instead of guessing by content keywords);
+   - mirrors `novahiz-docs/*.md` into the docs chain (source of truth stays the repo).
+
+4. Exit codes: 0 created or nothing to do; 1 when the vault is absent (run `node src/cli.ts second-memory init` first), when routing is impossible from the project signal (rerun with `--domain`/`--branch`), or on an unknown flag.
+
+5. Report the bound chain (`Code/.../<project>/`), the binding line, and every file created or mirrored. If the branch picked by the keywords looks wrong, rerun with `--domain <D> --branch <B>` before any note exists. Never claim a folder you did not create.

package/adapters/opencode/commands/novahiz-skills-update.md

@@ -1,5 +1,5 @@
 ---
-description: Reinstall every optional skill pack (dart, flutter, expo, impeccable) cleanly from their official providers. Arguments: $ARGUMENTS
+description: Install any missing skill pack and refresh every installed pack (dart, flutter, expo, impeccable) from their official providers. Arguments: $ARGUMENTS
 ---
 
 1. Locate the Novahiz home: `NOVAHIZ_HOME` if set, otherwise `~/.config/novahiz`.
@@ -9,21 +9,38 @@ description: Reinstall every optional skill pack (dart, flutter, expo, impeccabl
    silently. If git is missing, tell the user to install it first
    (Windows: `winget install Git.Git`) and stop.
 
-3. Reinstall/update every provider from the official registry
-   (`catalog/providers.json` - dart-lang/skills, flutter/agent-plugins,
+3. Install whatever pack is missing from the official registry
+   (`catalog/providers.json` - dart-lang/skills, flutter/skills,
    expo/skills, pbakaus/impeccable, plus the provider MCP servers):
 
    `node <home>/src/cli.ts deps --install --yes`
 
-4. Refresh the Impeccable CLI and engine from npm (official package):
+   This step only *fills gaps*. Every pack already on disk is skipped by
+   design (`installedWhen` satisfied), so it can never bring an installed
+   pack up to date — that is what step 4 is for.
+
+4. Refresh the installed packs from upstream. This is the real update: it
+   runs each provider's `update` command, which for the skills CLI is the
+   upstream `skills update -g -y` subcommand and covers dart, flutter, expo
+   and impeccable in one pass:
+
+   `node <home>/src/cli.ts deps --install --update --yes`
+
+   Confirm the JSON reports `"step": "update"` with `"ok": true` (a shared
+   command lists every provider under `covers`). If it reports
+   `"step": "install"` instead, the `--update` flag did not reach the CLI —
+   stop and say so rather than reporting an update that never ran.
+
+5. Refresh the Impeccable CLI and engine from npm (official package):
 
    `npm install -g impeccable`
    `impeccable install --global --yes --force`
 
-5. Realign the skill index:
+6. Realign the skill index:
 
    `node <home>/src/cli.ts sync`
 
-6. Verify with `node <home>/src/cli.ts doctor`: the `Referenced skills` row
+7. Verify with `node <home>/src/cli.ts doctor`: the `Referenced skills` row
    must show every pack present (the 7 `eas-*` paid-service skills stay
-   excluded by design). Report what was reinstalled.
+   excluded by design). Report what was installed and what was updated,
+   separately — never call a skipped pack an update.

package/adapters/opencode/instructions.md

@@ -30,11 +30,11 @@ Do **not** consult it for trivial edits, unrelated questions, or when the prompt
 
 Playwright uses a **persistent profile** that preserves data across sessions (cookies, localStorage, sessionStorage, history, logged-in sessions).
 
-**Profile folder:** `C:\Users\hiz\.opencode\playwright-profile`
+**Profile folder:** `~/.opencode/playwright-profile`
 
 ### Rules
 1. **NEVER use Chrome or Chromium** — Use only Microsoft Edge via the Playwright MCP server (`--browser=msedge`). Never launch `chrome.exe`, `chromium`, or any Chromium-based process manually or programmatically. All browser automation goes through the MCP tools (`playwright_browser_*`). If Edge is not installed, fall back to another non-Chromium browser (Firefox, WebKit) via the Playwright MCP server.
-2. Never disable `--user-data-dir` in the Playwright MCP config. The profile must always point to `C:/Users/hiz/.opencode/playwright-profile`.
+2. Never disable `--user-data-dir` in the Playwright MCP config. The profile must always point to `~/.opencode/playwright-profile`.
 3. Never purge this folder without explicit user consent.
 4. Never launch Playwright with an ephemeral context (without user-data-dir) for tasks requiring persistence.
 5. If the profile is corrupted or causes issues, inform the user and propose a backup before any reset.