@ainova-systems/intelligence 0.11.0-rc.6 → 0.11.0-rc.8

package/engine/docs/ADAPTERS.md

@@ -1,214 +0,0 @@
-# intelligence-sync: Writing a New Adapter
-
-## Overview
-
-An adapter transforms source prompts (from `intelligence/`) into an IDE-specific format. Each adapter is a single bash file, discovered by filename.
-
-## Where adapters live
-
-`sync.sh` scans two directories, in this order:
-
-| Location | Owner | Survives `update.sh`? |
-|---|---|---|
-| `intelligence/sync/scripts/adapters/` | **upstream** — the built-ins shipped with the engine | No — the engine replaces this directory wholesale on every update |
-| `intelligence/adapters/` (beside `config.yaml`) | **the project** | Yes — updates never touch project content |
-
-Write custom adapters in the project's `intelligence/adapters/`. A file placed in the engine's own `adapters/` is deleted by the next `update.sh`, silently and without a diff to notice. A project adapter whose name matches a built-in **overrides** it (sync prints a `NOTE:` line saying so) — an escape hatch for patching a built-in without forking the engine. An adapter that would serve every project is worth contributing upstream instead.
-
-The umbrella folder is not hardcoded anywhere — `intelligence/` above means "whatever directory holds `config.yaml`".
-
-## Quick Start
-
-1. Copy `intelligence/sync/scripts/adapters/_template.sh` to `intelligence/adapters/<name>.sh`
-2. Replace `<name>` placeholders with your adapter name
-3. Implement the `sync_to_<name>()` function
-4. Add target to `config.yaml`:
-   ```yaml
-   targets:
-     <name>: { enabled: true, output: ".<name>" }
-   ```
-5. Run `bash intelligence/sync/scripts/sync.sh <name>` to test
-
-## Adapter Contract
-
-### Required Function
-
-```bash
-sync_to_<name>(repo_root, config_file, output_dir)
-```
-
-This is called by `sync.sh` for each enabled target.
-
-Parameters:
-- `repo_root` -- absolute path to the project root
-- `config_file` -- absolute path to `config.yaml`
-- `output_dir` -- absolute path to output directory (e.g., `/project/.cursor`)
-
-### Available Library Functions
-
-Source `lib/common.sh` for these utilities:
-
-| Function | Description |
-|----------|-------------|
-| `finalize_output_file(file)` | **Call this on every file you write.** Expands layout tokens (`<umbrella>`, `<module>`) and converts CRLF to LF |
-| `normalize_file_to_lf(file)` | LF conversion only — for intermediate files that are not adapter output |
-| `lint_frontmatter(file)` | Warn about unquoted colons, leading tabs, and literal double quotes inside unquoted values (stderr) |
-| `get_frontmatter_value(key, file)` | Extract YAML frontmatter value |
-| `has_frontmatter(file)` | Check for `---` header |
-| `has_paths(file)` | Check for `paths:` field |
-| `get_model(config, ide, tier)` | Resolve model from `models:` override or default |
-| `get_model_default(ide, tier)` | Hardcoded default for `<ide>:<tier>` |
-| `map_access_to_claude_tools(access)` | Tool string for access level |
-| `map_access_to_claude_disallowed(access)` | Disallowed tools string |
-| `read_yaml_list(config, section)` | Read list from `config.yaml` |
-| `resolve_source_dir(repo_root, src)` | Map a source entry to a local dir — `"$repo_root/$src"` for a path, or a shallow clone for a pack reference (`@<name>[/<subpath>]`) or an inline `git+<url>` spec |
-| `source_is_local_path(src)` | True (0) if a source entry is a plain repo-relative path — i.e. neither of the two below. Use this, not a negated `source_is_remote`, whenever a token is about to be pattern-matched against a real directory |
-| `source_is_pack(src)` | True (0) if a source entry references a pack declared under `packs:` (`@<name>`) |
-| `source_is_remote(src)` | True (0) if a source entry is an inline remote `git+` spec |
-| `get_target_field(config, target, field)` | Read a field from a target's config block |
-
-### Transformation Patterns
-
-Each adapter handles three prompt types. Here's how the built-in adapters approach each:
-
-**Rules:**
-
-intelligence-sync routes rule content based on **scope** (always-on vs path-scoped) and on which channels each IDE actually reads, to avoid duplicating content into multiple places.
-
-| Source | `agents` (AGENTS.md) | `claude` | `cursor` | `copilot` | `codex` | `pi` | `opencode` |
-|--------|----------------------|----------|----------|-----------|---------|------|------------|
-| Always-on (no `paths:`) | inlined as canonical | copied as-is | skipped (Cursor reads AGENTS.md) | skipped (Copilot reads AGENTS.md) | skipped (Codex reads AGENTS.md) | skipped (Pi reads AGENTS.md) | skipped (opencode reads AGENTS.md) |
-| Path-scoped (with `paths:`) | listed by name only | copied as-is | `paths:` → `globs:` in `.mdc` | `paths:` → `applyTo:` in `.instructions.md` | not supported by Codex | copied to `.pi/intelligence-sync/rules/` + surfaced by generated extension | not supported (opencode has no native scoping; users may opt in via `instructions:` globs in `opencode.json`) |
-| Listing | full table in AGENTS.md | n/a | n/a | n/a | n/a | extension prompt snippet | n/a |
-
-**Skills:**
-
-Skills follow the [Agent Skills open standard](https://agentskills.io). All supported tools read `SKILL.md` directly — no semantic transformation needed. Skill directories are copied **in full** via `copy_skill_bundle` in `lib/common.sh`: bundled resources (`references/`, `scripts/`, `assets/`) ship alongside `SKILL.md`, because skill bodies point at them by relative path and a copy without them is broken at runtime. Markdown files are LF-normalized; everything else is copied byte-for-byte.
-
-`copy_skill_bundle` also quotes free-text `SKILL.md` frontmatter (`description`, `argument-hint`) for **every** target, not just the strict-YAML ones: `argument-hint: [pr-number]` is a YAML flow *sequence* unquoted, and Claude Code rejects the skill with "argument-hint must be a string" — it vanishes from the picker with no other signal. Adapters must therefore copy skills through this helper rather than plain `cp`.
-
-| Pattern | Used by | Output location |
-|---------|---------|-----------------|
-| Copy skill dirs in full (SKILL.md + bundled resources) | Claude, Cursor, Copilot, Codex, Pi, opencode | `.claude/skills/`, `.cursor/skills/`, `.github/skills/`, `.agents/skills/` (shared by Codex, Pi, opencode) |
-
-**Agents:**
-
-| Pattern | Used by |
-|---------|---------|
-| Transform frontmatter | Claude (`tier`→`model` via `get_model`, `access`→`tools`/`disallowedTools`), Cursor (`tier`→`model` via `get_model`, `access: readonly`→`readonly: true`) |
-| Transform to `.agent.md` | Copilot (`tier`→`model`, `access: readonly`→restricted `tools` array) |
-| Transform to `.toml` | Codex (`name`, `description`, `model`, `model_reasoning_effort` from tier, `sandbox_mode` from access, `developer_instructions`) |
-| Transform to prompt template | Pi (`.pi/prompts/intelligence-agent-<name>.md`; `readonly` becomes prompt guidance, `full` stays implicit) |
-| Transform to markdown subagent | opencode (`.opencode/agents/<name>.md`; `mode: subagent`, `model` from tier via `get_model`, `permission.edit`/`permission.bash` from access) |
-
-Model names come from `get_model(config_file, ide, tier)` in `lib/common.sh`. Defaults are baked into `get_model_default()`; users override per-IDE/tier under `models:` in `config.yaml`. Sync prints a drift report when an override no longer matches the current default.
-
-### Layout tokens (required)
-
-The engine ships artifacts of its own — the `intelligence-authoring` rule and the `intelligence-architect` agent — and they cannot hardcode the umbrella's folder name, because the project chooses it. They write `<umbrella>` and `<module>` instead, and **every adapter must expand them by calling `finalize_output_file` on each file it writes** (it also does the LF normalization that `normalize_file_to_lf` used to do):
-
-| Token | Expands to |
-|---|---|
-| `<umbrella>` | repo-relative umbrella dir (e.g. `Intelligence`) |
-| `<module>` | repo-relative engine module (e.g. `Intelligence/sync`; CLI setup: `.intelligence/packages/@ainova-systems/sync`) |
-| `<manifest>` | the project's config file name — vendored: `config.yaml`, CLI setup: `intelligence.yaml` (`IS_MANIFEST_NAME`) |
-| `<sync-cmd>` | the sync invocation — vendored: `bash <module>/scripts/sync.sh`, CLI setup: `intelligence sync` (`IS_SYNC_CMD`) |
-
-Values are exported by `sync.sh` (`IS_UMBRELLA_REL`, `IS_MODULE_REL`; `IS_SYNC_CMD` comes from the CLI in CLI mode), derived from the detected layout. Expansion covers frontmatter and body, so `paths: ["<umbrella>/**"]` reaches Claude's `paths:`, Cursor's `globs:` and Copilot's `applyTo:` carrying the project's real folder name. A file written without `finalize_output_file` ships a literal `<umbrella>` into an IDE — CI fails the build if any generated output still contains a token.
-
-### Cleanup Contract
-
-Every adapter MUST follow these rules to stay safe alongside others:
-
-1. **Clean only adapter-owned subpaths.** Never `rm -rf "$output_dir"` — users hand-author siblings (`.claude/settings.json`, `.cursor/settings.json`, `.pi/settings.json`, `.opencode/opencode.json`, `.github/workflows/`, project-specific commands and extensions). Mirror `claude.sh` (deletes only `rules/`, `agents/`, and per-skill subdirs), `pi.sh` (deletes only `.pi/intelligence-sync/`, the named extension file, and `intelligence-agent-*.md` prompt files), or `opencode.sh` (deletes only `.opencode/agents/` wholesale, and inside `.opencode/commands/` only files that carry the `<!-- Generated by intelligence-sync. Do not edit manually. -->` marker — hand-authored sibling commands survive).
-2. **The cleanup block defines what the adapter owns.** It is the same set `/intelligence-uninstall-adapter` removes when the target is turned off: whatever `sync_to_<name>()` deletes on every re-sync, and nothing more. Keep it obvious in the source — an uninstall reads it.
-3. **Use shared helpers for shared dirs.** `.agents/skills/` is read by Codex, Pi, opencode, and any tool implementing the [Agent Skills open standard](https://agentskills.io). All adapters writing there must call `sync_open_skill_dirs`, which owns the full lifecycle (clean per-skill subfolders, recreate the dir, populate). Do NOT duplicate the clean / `mkdir -p` in the adapter — calling sites become divergent and one adapter inevitably drifts. It is also *shared*: an uninstall removes it only when no other open-standard target remains enabled.
-4. **Document owned paths in `.gitignore`.** Each adapter's INIT.md `.gitignore` block lists exactly the paths it writes — no broader. This lets users keep hand-authored content under the same root tracked.
-5. **The output path is validated before you run.** `sync.sh` calls `validate_output_path` for every adapter (including `agents`): the resolved output must stay inside the repo, and must not be the repo root, the intelligence source tree, or any configured source. `..` is canonicalized away first, so a config line cannot walk out of the repository. Adapters never need to re-check this — but they must not write outside the `output_dir` they are handed.
-
-## Example: Minimal Adapter
-
-```bash
-#!/bin/bash
-source "$(dirname "$0")/../lib/common.sh"
-
-sync_to_myide() {
-    local repo_root="$1"
-    local config_file="$2"
-    local output_dir="$3"
-
-    echo "=== MyIDE ==="
-    mkdir -p "$output_dir/rules"
-
-    # Copy rules, strip frontmatter
-    while IFS= read -r src; do
-        [ -z "$src" ] && continue
-        # resolve_source_dir maps a source entry to a local dir: "$repo_root/$src"
-        # for a local path, or a shallow clone for a pack reference (`@<name>`)
-        # or an inline `git+<url>` spec. A pack's url/ref/mirror are read from
-        # config.yaml, which it takes from $IS_CONFIG_FILE (exported by sync.sh)
-        # unless you pass the config as a third argument.
-        local dir
-        dir="$(resolve_source_dir "$repo_root" "$src")"
-        [ -d "$dir" ] || continue
-        for f in "$dir"/*.md; do
-            [ -f "$f" ] || continue
-            awk '
-                BEGIN { in_fm=0; past_fm=0 }
-                { sub(/\r$/, "") }
-                /^---$/ {
-                    if (!past_fm) { in_fm = !in_fm; if (!in_fm) { past_fm=1 }; next }
-                }
-                past_fm || !in_fm { print }
-            ' "$f" > "$output_dir/rules/$(basename "$f")"
-            # Every written file goes through finalize_output_file: it expands
-            # the <umbrella> / <module> layout tokens and normalizes CRLF -> LF.
-            finalize_output_file "$output_dir/rules/$(basename "$f")"
-        done
-    done < <(read_yaml_list "$config_file" "rules")
-}
-```
-
-## Testing
-
-Test your adapter by creating a temporary project with `config.yaml` and running:
-
-```bash
-REPO_ROOT=/path/to/test/project bash intelligence/sync/scripts/sync.sh <name>
-```
-
-Verify the output directory contains correctly transformed files. The sync entry point also runs `lint_frontmatter` over every source file before adapters fire — unquoted YAML colons and leading tabs surface as warnings on stderr.
-
-## Distributing changes
-
-When you ship a new adapter, downstream projects pick it up by running:
-
-```bash
-bash intelligence/sync/scripts/update.sh
-```
-
-`update.sh` clones the upstream repo into a `mktemp -d` directory, shows the diff for `intelligence/sync/scripts/` and `intelligence/sync/INIT.md`, and prompts before overwriting. Project content (`config.yaml`, `rules/`, `agents/`, `skills/`, `adapters/`) is never touched. Pass `--yes` for non-interactive runs; set `REPO_URL=<fork>` to use a fork.
-
-This is exactly why a project's own adapter belongs in `intelligence/adapters/` and not in the engine's `scripts/adapters/`: the first is project content, the second is overwritten by the command above.
-
-## Built-in Adapters Reference
-
-| Adapter | Output | Rules | Skills | Agents |
-|---------|--------|-------|--------|--------|
-| `agents.sh` | `AGENTS.md` (committed) | Always-on inlined; scoped listed | Listed in table | Listed in table |
-| `claude.sh` | `.claude/` | Copy as-is (Claude does not read AGENTS.md) | SKILL.md dirs | tier/access → model/tools |
-| `cursor.sh` | `.cursor/` | Scoped only → `.mdc` + globs | Copy as-is | tier → model |
-| `copilot.sh` | `.github/` | Scoped only → `.instructions.md` | SKILL.md dirs | `.agent.md` |
-| `codex.sh` | `.codex/` + `.agents/skills/` | None (AGENTS.md handles) | SKILL.md dirs in `.agents/skills/` | `.toml` in `.codex/agents/` |
-| `pi.sh` | `.pi/` + `.agents/skills/` | Scoped rules copied + listed by generated extension; always-on via AGENTS.md | SKILL.md dirs in `.agents/skills/` | prompt templates in `.pi/prompts/` |
-| `opencode.sh` | `.opencode/` + `.agents/skills/` | None (AGENTS.md handles always-on; opencode has no native scoping) | SKILL.md dirs in `.agents/skills/`; one slash command per skill in `.opencode/commands/<name>.md` (marker-protected) | markdown subagents in `.opencode/agents/` |
-
-### Notes on `agents.sh`
-
-Unlike IDE adapters, `agents.sh` emits a single committed markdown file intended for humans and generic LLM tooling. It reads a static `header` block from `config.yaml` (under `targets.agents.header`) and appends auto-generated tables (agents, skills) and a list of rules derived from frontmatter. The output carries a "do not edit manually" marker and is regenerated on every sync.
-
-#### Why AGENTS.md inlines always-on rules
-
-AGENTS.md is the canonical project doc — Cursor, Copilot, Codex, Pi, and opencode read it natively. Always-on rule content is inlined automatically so all five tools see the same context from one source. Path-scoped rules are NOT inlined (would balloon AGENTS.md in monorepos); they live in tool-specific channels with native scoping (`.cursor/rules/*.mdc` with `globs:`, `.github/instructions/*.instructions.md` with `applyTo:`) or, for Pi, in generated on-demand rule files surfaced by a small extension. opencode has no first-class path-scoped channel; users who need scoped rules can opt into them via `instructions:` globs in `opencode.json`.
-
-Claude Code does not read AGENTS.md natively (per [open feature request](https://github.com/anthropics/claude-code/issues/6235)) — its adapter copies all rules into `.claude/rules/`. There is no duplication because Claude does not consume AGENTS.md.

package/engine/docs/CLI.md

@@ -1,90 +0,0 @@
-# The intelligence CLI
-
-The product interface: one command owning the whole lifecycle of a project's AI intelligence. Installed from npm (`npm i -g @ainova-systems/intelligence`); implemented in bash (`cli/` in this repo) behind a small Node launcher, reusing the sync engine unchanged underneath.
-
-```bash
-cd your-project
-intelligence init
-intelligence add @ainova-systems/core
-intelligence sync
-```
-
-## The CLI (v2) project layout
-
-```
-project/
-├── intelligence.yaml      # manifest, at the repo root (like package.json)
-├── intelligence.lock      # resolved package state — commit it
-├── intelligence/          # the project's own rules/ agents/ skills/
-├── .intelligence/         # gitignored store: packages/<name>/, backup/
-├── .claude/ .cursor/ …    # generated by sync
-└── AGENTS.md
-```
-
-No engine code lives in the project. The engine's *scripts* ship inside the npm package; the engine's *content* — the authoring rule, both engine agents, every `intelligence-*` meta-skill and the docs — is the package **`@ainova-systems/sync`**: auto-added by `init` (opt out with `--bare`), visible in `list`/`search`, pinned exactly to the bundled engine version, and materialized from the npm bundle without network whenever the pin matches (only a cross-version install reaches git). `intelligence update` never moves it — `intelligence upgrade` does, together with the schema stamp. Removing it (`remove @ainova-systems/sync --force`) drops the meta-content from the outputs while the sync engine itself keeps working. After a fresh clone, `intelligence install` restores the whole store from the lock.
-
-## Commands
-
-| Command | Does |
-|---|---|
-| `init [--targets a,b] [--dir d] [--bare] [--no-sync]` | Enable `agents` (the tool-neutral AGENTS.md) plus every tool DETECTED by repo markers (`.claude`/`CLAUDE.md`, `.cursor`, `.codex`, `.pi`, `.opencode`, `.github/instructions`) or named via `--targets` — a tool is never invented. Writes a minimal self-documenting root manifest, `.gitignore`s the store, installs `@ainova-systems/sync` (unless `--bare`), first sync. No dirs are created. |
-| `add <spec> [--name @s/n] [--no-sync]` | Resolve → fetch → wire sources → manifest entry → lock → sync. Specs: `@scope/name[@range]`, `github:org/repo[#path]`, `git+<url>[@ref][#path]`. |
-| `remove <name> [--force]` | Inverse of add: manifest, sources, lock, store. |
-| `install [--frozen] [--force]` | Restore the store exactly from the lock; resolve manifest packages the lock lacks (`--frozen` refuses instead, and fails on sha drift). |
-| `update [name]` | Re-resolve ranges, refetch what moved, rewrite the lock. `ref:`-pinned packages never move here. |
-| `upgrade` | Bring the project to this CLI's engine: apply v2 schema migrations, move the `@ainova-systems/sync` pin to the bundled version and reinstall it, restamp `sync_version`, sync. |
-| `sync [target]` | Run the bundled engine against the manifest. In a vendored (v1) project it delegates to that project's own engine. |
-| `list` / `status` / `doctor` | Inspect; doctor exits 1 on inconsistencies (unlocked packages, missing store, stale stamp, dead sources). |
-| `registry <list\|add <url> [--force]\|remove <url>>` | Manage the trust list of registries — rare, once per organization. `add` fails closed on a URL with no `index.yaml` (`--force` records it anyway). |
-| `migrate [--dry-run] [--force]` | Convert a vendored setup to the CLI setup. Transactional; see below. |
-
-## Packages
-
-**A package's name is its identity everywhere**: the `packages:` key in the manifest, the store directory (`.intelligence/packages/@scope/name/` — npm's nesting), and the lock key. What a package provides is a convention: whichever of `rules/`, `agents/`, `skills/` exist at its top level get wired into the matching `sources:` sections by `add`.
-
-**Names are global.** The name is the trust anchor a developer reasons with — the same `@scope/name` means the same package in every project, every lock and every conversation. A registry never renames anything, and two versions of one name cannot coexist in a project: intelligence artifacts land in each tool's flat namespace (`.claude/skills/<name>/`, the `AGENTS.md` tables), so duplicates would collide file-by-file. Need pieces of two versions? That is a different package — fork it under a different name. Need to override one artifact? Put a same-named file in your own content dir; project sources are listed after package sources.
-
-**Name → repo resolution: the trust list is the ONLY resolver.** `registries:` in the manifest holds registry repos (git repos with an `index.yaml`), consulted in order — the first to declare the name wins. There is deliberately **no built-in catalog and no `@org/name` → github guessing**: the CLI core knows no vendor, and a name nobody explicitly trusted never turns into an install from an invented URL. A name no trusted registry declares is refused with suggestions. Installs without a registry are always **explicit sources**: `github:org/repo`, `git+<url>[@ref][#path]`. Vendor defaults exist only as lines `init` seeds into the manifest — visible, reviewable, deletable (`doctor` still flags a name whose current resolution url no longer matches the lock).
-
-**Versions are git tags.** Ranges (`^1.2.0`, `~1.2.0`, exact, `latest`) match stable `x.y.z` tags (optional `v` prefix) listed via `git ls-remote` — no clone to resolve. `add` without a range picks the highest stable tag and records `^that`. A branch or commit pin is `ref:`, the escape hatch that ranges never touch. Prerelease-suffixed tags are invisible to ranges by design.
-
-**The lock is the resolved truth.** Per package: requested range, url, path, resolved tag, commit sha. `install` never consults an index or re-resolves a range — offline restore and reproducibility come from the lock alone; `--frozen` makes any divergence fatal (CI).
-
-## Manifest shapes and ownership
-
-The engine reads what it always read (`project:`, `sync_version:`, `sources:`, `targets:`, `models:`, `ignore:`, `submodules:`) through its own parsers. Two blocks are **CLI-owned** and never touched by the engine — their keys are full quoted package names, which engine parsers deliberately cannot read:
-
-```yaml
-packages:
-  "@ainova-systems/core":
-    version: "^0.3.0"        # or: ref: main  /  url: + path: (direct git specs)
-registries:
-  - "https://github.com/acme/intelligence-registry.git"
-```
-
-`project.intelligence_dir` names the content dir when it is not `intelligence/`. `sync_version` stays the frozen schema-contract key, stamped by the CLI with the bundled engine version — an npm prerelease suffix never reaches it.
-
-## How the CLI drives the engine
-
-The engine's CLI mode is an env contract, set by the dispatcher and honored only when `IS_CLI=1` (with every variable unset the engine is byte-identical to the vendored one — CI's `legacy-golden` job proves that on every push):
-
-| Variable | Value in CLI mode |
-|---|---|
-| `CONFIG_FILE` | `<root>/intelligence.yaml` |
-| `REPO_ROOT` | the project root |
-| `IS_UMBRELLA_REL` | content dir (`intelligence`) |
-| `IS_MODULE_REL` | `.intelligence/packages/@ainova-systems/sync` |
-| `IS_MANIFEST_NAME` | `intelligence.yaml` (feeds the `<manifest>` token; vendored default `config.yaml`) |
-| `IS_SYNC_CMD` | `intelligence sync` (expanded for the `<sync-cmd>` token) |
-| `IS_PROTECTED_DIRS` | `<content-dir>:.intelligence` — restores output-path protection for a root manifest |
-| `IS_SUPPRESS_CLI_NOTE` | set to silence the vendored-flow recommendation note |
-
-## migrate: vendored (v1) → CLI (v2)
-
-Fail-closed preconditions (clean worktree unless `--force`; no half-migrated state; project schema not newer than the engine; an older schema is first brought up by the engine's own migration chain). Then **stage** — the manifest is `config.yaml` transformed comment-preservingly (module sources → the `@ainova-systems/sync` package store, `@pack/sub` references → store paths, `packs:` → `packages:` entries keeping their `ref:` pins), mirrored packs are *copied* from their mirrors (network untouched, sha carried from the `.pack` stamp), transient packs fetched — **verify** (staged sources exist; per-adapter `enabled`/`output` equality against the old config) — **commit**: store and manifest move in, a real sync must report `IS_STATUS=ok`, and only then are the vendored module, `config.yaml` (backed up to `.intelligence/backup/`) and the mirrors removed. Any earlier failure rolls back to an untouched project. `--dry-run` stages, verifies, prints, writes nothing.
-
-## Developing and releasing the CLI
-
-- `bash cli/tests/e2e-packages.sh` and `bash cli/tests/e2e-lifecycle.sh` — the hermetic suites CI runs (file:// fixtures).
-- `bash npm/build.sh [version]` assembles `npm/dist/` from the repo (cli + engine + registry index).
-- The `release-npm` workflow (manual dispatch) publishes `<engine>-rc.N` to dist-tag `next` from any ref, and the stable `<engine>` version to `latest` only when dispatched from the matching `v<engine>` tag. Requires the `NPM_TOKEN` secret.