@iowarp/clio-coder 0.4.1 → 0.4.2

package/docs/{performance-methodology.md → process/performance-methodology.md}

@@ -1,5 +1,8 @@
 # Performance Measurement Methodology
 
+> **Visual blueprint:** The source checkout includes the complete
+> [Performance Measurement Methodology visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/performance_methodology_blueprint.html).
+
 Clio Coder treats performance observations as diagnostic evidence, not as a
 reason to weaken behavior. Event ordering, persistence, permissions, terminal
 restoration, accessibility, output contracts, and installed-package behavior
@@ -50,10 +53,10 @@ drop count instead of growing without bound. Append failures and append
 timeouts disable tracing without failing the application. Normal shutdown
 awaits the bounded final flush.
 
-With the instant shell active, textual `[clio:boot]` lines retain timestamps
+With the instant shell active, textual `[clio-coder:boot]` lines retain timestamps
 captured at the Stage 0 commit and Stage 1 committed hydration frame, but their
 stderr output is deliberately deferred until after the TUI stops and terminal
-protocols are restored. The PTY harness detects the visible Stage 0 bytes and
+protocols are restored. The retired PTY harness detected the visible Stage 0 bytes and
 Stage 1 frame directly, then parses those buffered timestamps after process
 exit. This keeps diagnostic output from corrupting the temporary shell without
 changing the measured endpoints.
@@ -65,15 +68,17 @@ CLIO_CODER_INTERACTIVE=1 \
 node dist/cli/index.js
 ```
 
-The deterministic contracts are
-`tests/contracts/render-pipeline-trace.test.ts`. The real built-CLI acceptance
-harness is `tests/smoke/render-trace-pty.test.ts`; it covers first frame, input
-correlation, resize, grouped writes, paused PTY output, adaptive pacing against
-a chunked hermetic provider, a controlled `stdout.write() === false`/`drain`
-boundary, final-frame settlement, and bounded process cleanup. Set
-`CLIO_CODER_PERF_REPORT=1` while running that test to print its observation
-records. Real PTY acceptance is currently unavailable on Windows; the
-fake-stream frame/backpressure contracts remain cross-platform.
+The measurement snapshot below was originally backed by
+`tests/contracts/render-pipeline-trace.test.ts` and
+`tests/smoke/render-trace-pty.test.ts`. Those harnesses and their
+`CLIO_CODER_PERF_REPORT` output switch were retired with the measurement-script
+suite. Their names remain in the dated command transcripts below only to make
+the recorded method auditable; the commands are not current invocations.
+Current correctness coverage lives in
+`tests/contracts/rendering-invariants.test.ts`, and
+`tests/smoke/real-binary-boot.test.ts` exercises the built binary. Neither is a
+replacement glass-latency benchmark. `CLIO_CODER_RENDER_TRACE` remains the
+supported way to capture a live render trace for a fresh measurement campaign.
 
 ## Import-graph method
 
@@ -118,7 +123,7 @@ With `NODE_DISABLE_COMPILE_CACHE=1`, five real-PTY samples produced:
 | 22.22.3 | 1013.9 / 1120.3 ms | 1030.615 / 1136.960 ms | 7.068 ms | 3 |
 | 24.9.0 | 1061.5 / 1082.3 ms | 1079.001 / 1102.019 ms | 6.549 ms | 3 |
 
-The corresponding command was:
+The corresponding historical command was:
 
 ```bash
 NODE_DISABLE_COMPILE_CACHE=1 CLIO_CODER_PERF_REPORT=1 \
@@ -156,13 +161,22 @@ The former 1,054 ms “first TUI paint” figure is not a before value: that mar
 was taken before `startInteractive()` and therefore did not measure a frame.
 It must not be compared numerically with this corrected baseline.
 
-## Graph-cut observations
+## Historical graph-cut observations
+
+Each graph reduction below was measured and committed independently. The
+runtime-graph and V8 harnesses cited throughout this section were later retired,
+so their absence and presence claims are dated evidence from the recorded cuts,
+not maintained release gates. Counts used the import-graph method above with V8
+compile caching disabled and a warm operating-system page cache. An unchanged
+translated-module count could still hide a meaningful bundled-code reduction:
+esbuild represented all bundled sources in one translated Clio chunk.
 
-Each graph reduction is measured and committed independently. Counts below use
-the import-graph method above with V8 compile caching disabled and a warm
-operating-system page cache. An unchanged translated-module count can still
-hide a meaningful bundled-code reduction: esbuild represents all bundled
-sources in one translated Clio chunk.
+Current installed-package smoke coverage is narrower. It packs Clio, runs
+`code_nav` from a foreign working directory, and verifies that a real context
+index evaluates the tree-sitter chunk. It does not reproduce the former
+all-four or all-seven lazy-tool graph checks, Pi closure checks, or worker graph
+exclusion proof. Re-establish those properties with a fresh explicit
+measurement campaign before using them as current release evidence.
 
 ### Node built-in fetch
 
@@ -181,11 +195,11 @@ Ten full-entry imports changed as follows:
 | 22.22.3 | 670.680 / 803.053 ms | 605.907 / 646.730 ms | lower in this sample |
 | 24.9.0 | 656.781 / 674.592 ms | 668.652 / 896.238 ms | no reproducible timing improvement; host noise dominated |
 
-The cut is justified by the deterministic graph and package-size reduction,
+At that cut, the justification was the deterministic graph and package-size reduction,
 not by claiming a universal boot saving. Localhost transport contracts cover
 methods, headers, bodies, redirects, streamed UTF-8 truncation and cancellation,
 external abort, timeout, HTTP preview errors, binary rejection, and transport
-errors on Node 22 and Node 24. The packed-install test invokes `web_fetch`
+errors on Node 22 and Node 24. The then-current packed-install test invoked `web_fetch`
 through a real installed headless tool turn from a foreign working directory
 and asserts that neither the packed chunks nor the installed dependency tree
 contains userland Undici.
@@ -203,12 +217,12 @@ per-workspace FIFO plus a cross-process file lease. The artifact and its state
 metadata commit under that lease, shutdown drains admitted session work, and a
 reset cannot be overtaken by an older build.
 
-The deterministic runtime-graph test locates the generated tree-sitter chunk by
-its bundled source marker, never its hash. V8 coverage proves that nested
+The retired deterministic runtime-graph test located the generated tree-sitter chunk by
+its bundled source marker, never its hash. V8 coverage proved that nested
 `context index --help` reaches the built index command without evaluating that
 chunk or creating `.clio-coder`, while a real one-file build evaluates it and
 extracts a generator declaration the regex fallback does not recognize. The
-same proof runs against an installed tarball from a foreign working directory.
+same proof ran against an installed tarball from a foreign working directory.
 
 The after-Undici graph was the before point for this cut. The translated module
 count changed from 1,332 files (54 Clio chunks) to 1,336 (58 Clio chunks): the
@@ -233,7 +247,7 @@ operating-system page cache on the same WSL2 host, produced:
 These are local import observations, not a universal startup saving or a CI
 threshold. `npm pack --dry-run --json` at this slice reports 6.08 MB packed,
 36.65 MB unpacked, and 1,095 entries. The independently blocking
-evidence is the source-built and installed runtime-coverage contract plus the
+evidence at that cut was the source-built and installed runtime-coverage contract plus the
 coordinator's generation-order, reset-resurrection, lease-failure, demand,
 incremental, wiki, refresh, and shutdown suites.
 
@@ -241,16 +255,16 @@ incremental, wiki, refresh, and shutdown suites.
 
 `context`, `code_nav`, `verify`, and `web_fetch` now register immutable schema
 and policy surfaces while importing their implementations only after registry
-admission. The runtime-graph harness makes a real tool-capable provider request
-and asserts that all four schemas were serialized while every implementation
-file stayed absent from V8 coverage. Four fresh processes then invoke one tool
-each, assert its implementation is covered and its semantic result reaches the
-provider, and assert the other three remain absent. The exact same harness runs
-against an installed tarball from a foreign working directory. A second copied
-install deletes the emitted `web_fetch` implementation by stable behavior
-provenance and proves the resulting tool error names the missing chunk and the
-two standard reinstall commands. No hash, size, source-map, or timing value is
-used as a correctness assertion.
+admission. The retired runtime-graph harness made a real tool-capable provider
+request and asserted that all four schemas were serialized while every
+implementation file stayed absent from V8 coverage. Four fresh processes then
+invoked one tool each, asserted its implementation was covered and its semantic
+result reached the provider, and asserted the other three remained absent. The
+same harness ran against an installed tarball from a foreign working directory.
+A second copied install deleted the emitted `web_fetch` implementation by
+stable behavior provenance and proved the resulting tool error named the
+missing chunk and the two standard reinstall commands. No hash, size,
+source-map, or timing value was used as a correctness assertion.
 
 The after-codewiki graph is the before point for this cut. Translated modules
 changed from 1,336 files (58 Clio chunks) to 1,357 files (79 Clio chunks), as
@@ -258,7 +272,7 @@ the split surfaces and dynamic-import boundaries create more, smaller generated
 modules. The evaluated Clio JavaScript nevertheless fell from 5,015,343 to
 4,929,030 bytes. The four discoverable implementation entries total 104,804
 bytes (`context` 33,919; `web_fetch` 24,979; `verify` 24,063; `code_nav`
-21,843) and are absent until invoked. Total built JavaScript rose from 99 files
+21,843) and were absent until invoked. Total built JavaScript rose from 99 files
 and 5,812,402 bytes to 125 files and 5,840,309 bytes because the package must
 ship every first-use path. `npm pack --dry-run --json` reports approximately
 6.09 MB packed, 36.69 MB unpacked, and 1,127 entries, versus the previous
@@ -272,12 +286,12 @@ operating-system page cache on the same WSL2 host, produced:
 | 22.22.3 | 525.656 / 539.633 ms | 545.576 / 565.551 ms | no timing improvement in this sample |
 | 24.9.0 | 539.056 / 574.139 ms | 553.733 / 582.703 ms | no timing improvement in this sample |
 
-The cut is justified by the deterministic absence/presence contract and the
-smaller evaluated graph, not by a startup-time claim. Registration, listing,
-provider serialization, and a safety-rejected call are separately held against
-loading in the registry contract; surface parity, single-flight first use,
-ordinary exception semantics, and Clio-owned versus external missing-module
-diagnostics are covered there as well.
+At that cut, the justification was the deterministic absence/presence contract
+and the smaller evaluated graph, not a startup-time claim. Separate registry
+contracts then held registration, listing, provider serialization, and a
+safety-rejected call against loading; they also covered surface parity,
+single-flight first use, ordinary exception semantics, and Clio-owned versus
+external missing-module diagnostics.
 
 ### Narrow Pi API registration and dispatch
 
@@ -293,14 +307,14 @@ Bedrock ambient credentials. A configured external runtime activates a dynamic
 bridge before plugin evaluation; it deliberately restores the shared Pi
 registry universe only for that plugin-bearing process.
 
-The source-built and installed-tarball foreign-working-directory harness runs
-real OpenAI-compatible turns under V8 coverage. It proves `compat.js` and
-`legacy-api-aliases.js` are absent, the invoked OpenAI implementation is
-present, and unrelated Anthropic, Bedrock, Google, Mistral, OAuth, and image
-implementation files remain absent. It also proves `providers/all` and sample
-unconfigured provider catalogs remain absent. A separate fresh-process contract
-registers a known-API override from an out-of-tree module and proves its result
-wins after the bridge; the installed-tarball lane repeats that semantic and
+The retired source-built and installed-tarball foreign-working-directory
+harness ran real OpenAI-compatible turns under V8 coverage. It proved
+`compat.js` and `legacy-api-aliases.js` were absent, the invoked OpenAI
+implementation was present, and unrelated Anthropic, Bedrock, Google, Mistral, OAuth, and image
+implementation files remained absent. It also proved `providers/all` and sample
+unconfigured provider catalogs remained absent. A separate retired
+fresh-process contract registered a known-API override from an out-of-tree
+module and proved its result won after the bridge; the installed-tarball lane repeated that semantic and
 coverage proof from a foreign working directory.
 
 The after-lazy-tools graph is the before point for this cut. Translated modules
@@ -322,9 +336,9 @@ operating-system page cache, and the same WSL2 host as the preceding cuts:
 | 24.9.0 | 553.733 / 582.703 ms | 522.001 / 554.388 ms | lower in this sample |
 
 These are local import observations, not a startup guarantee or CI threshold.
-The independently blocking evidence is the absence/presence graph contract,
-credential parity, plugin registry identity, provider behavior suites, and the
-installed foreign-cwd turn.
+The independently blocking evidence at that cut was the absence/presence graph
+contract, credential parity, plugin registry identity, provider behavior
+suites, and the installed foreign-cwd turn.
 
 ### Lazy orchestrator controls and worker graph separation
 
@@ -345,18 +359,18 @@ settlement. Monitor and steer use the same immutable-surface loader as the
 earlier four lazy tools. The worker entry imports the core bootstrap directly
 and therefore never registers or evaluates these orchestrator-only runners.
 
-The V8 coverage harness now advertises all seven lazy tool schemas in one real
-provider request, proves every implementation root absent, and invokes each in
-a fresh process. For the three orchestrator controls it recursively follows the
-emitted static-import graph, classifies the surface/worker-shared closure, and
-proves the whole runner-exclusive closure absent before admission and present
-after invocation. The three discoverable runner entries total 113,983 bytes
+The retired V8 coverage harness advertised all seven lazy tool schemas in one
+real provider request, proved every implementation root absent, and invoked
+each in a fresh process. For the three orchestrator controls it recursively
+followed the emitted static-import graph, classified the surface/worker-shared closure, and
+proved the whole runner-exclusive closure absent before admission and present
+after invocation. The three discoverable runner entries totaled 113,983 bytes
 (`dispatch` 83,800; `monitor` 27,209; `steer` 2,974). A separate run of the real
-built worker entry proves both those roots and their runner-exclusive closures
-absent. The complete proof repeats from an installed tarball in a foreign
+built worker entry proved both those roots and their runner-exclusive closures
+absent. The complete proof repeated from an installed tarball in a foreign
 working directory; stable behavior markers, rather than chunk hashes or file
-sizes, identify each entry. Shared dispatch-domain modules are reported as
-shared and are not misrepresented as runner-exclusive savings.
+sizes, identified each entry. Shared dispatch-domain modules were reported as
+shared and were not misrepresented as runner-exclusive savings.
 
 The after-Pi graph is the before point for this cut. Translated modules changed
 from 1,289 files (80 evaluated Clio chunks) to 1,307 files (98 Clio chunks), as
@@ -383,7 +397,11 @@ and the dispatch reservation, approval, gate, detach, monitor, and steer suites.
 
 ## Adaptive stream-pacer observations
 
-`terminal.smoothStreaming` is presentation-only. `off` is the exact existing
+This subsection preserves the dated results and method of the retired
+fake-clock and PTY performance harnesses. It does not describe a currently
+runnable test command.
+
+`interface.smoothStreaming` is presentation-only. `off` is the exact existing
 16 ms coalescer and remains the 0.3.3 default. `auto` uses the pacer only on a
 capable local TTY with no accessibility, remote/multiplexer, CI, or observed
 backpressure signal. `on` requests pacing, but frame construction still stops
@@ -392,13 +410,13 @@ event bus: canonical events, persistence, replay/export, tool formation, and
 cumulative tool state remain synchronous while one presentation queue owns
 only derived visible text/thinking mutations.
 
-The deterministic fake-clock contracts cover semantic classification, FIFO
+The deterministic fake-clock contracts covered semantic classification, FIFO
 generation/epoch ordering, abort and stale-admission rejection, grapheme
 clusters, fractional arrival credit, event-loop suspension, catch-up, the
 oldest-visible deadline, absolute queue byte/grapheme bounds, idle shutdown,
 folded-thinking fidelity, reset/discard accounting, mode changes, final-frame
 settlement, fullscreen frozen scrolling through resize, and bounded no-drain
-cleanup. The PTY arm uses a built CLI, a four-delta localhost provider, a
+cleanup. The PTY arm used a built CLI, a four-delta localhost provider, a
 4 KiB reply, an 80x24 `xterm-256color` PTY whose reader is paused, and a
 test-only writable shim that makes exactly one real child `stdout.write()`
 return `false` before emitting a delayed `drain`. This is deterministic
@@ -414,7 +432,7 @@ five observations; they are diagnostic observations, not timing gates.
 | 22.22.3 | 5.530 / 8.896 ms | 62.909 / 70.274 ms | 37.798 / 56.412 ms | 403.809 / 426.570 ms |
 | 24.9.0 | 5.468 / 7.225 ms | 67.878 / 74.021 ms | 27.901 / 35.750 ms | 402.582 / 418.783 ms |
 
-The command was:
+The historical command was:
 
 ```bash
 NODE_DISABLE_COMPILE_CACHE=1 CLIO_CODER_PERF_REPORT=1 \
@@ -455,7 +473,7 @@ the same compile-cache-disabled, warm-page-cache method. Stage 1 remains a full
 hydration endpoint; the earlier visible/editor-ready Stage 0 does not erase or
 rename that work.
 
-The command was run five times for each explicit Node binary:
+The historical command was run five times for each explicit Node binary:
 
 ```bash
 NODE_DISABLE_COMPILE_CACHE=1 CLIO_CODER_PERF_REPORT=1 \
@@ -464,13 +482,13 @@ NODE_DISABLE_COMPILE_CACHE=1 CLIO_CODER_PERF_REPORT=1 \
   tests/smoke/render-trace-pty.test.ts
 ```
 
-The built-CLI PTY suite additionally covers immediate typing, multiple
+The retired built-CLI PTY suite additionally covered immediate typing, multiple
 submit-before-hydration admissions, a retained post-submit draft, resize across
 hydration, Ctrl+C on both sides of attachment, SIGTERM during hydration,
 injected Stage 1 failure, protocol-query single execution, raw-mode
 restoration, diagnostics, and bounded process cleanup. The fake lease contract
 checks object identity, FIFO admission, epoch rejection, signal-delegate
-transfer, and idempotent close. PTY receipt is still not literal glass latency.
+transfer, and idempotent close. PTY receipt was still not literal glass latency.
 
 ## Reporting checklist
 

package/docs/{scientific-validation.md → process/scientific-validation.md}

@@ -1,11 +1,11 @@
 # Clio Coder Scientific Validation Contracts
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Clio Coder Scientific Validation Contracts visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/validation_blueprint.html).
 
 Scientific software development cannot treat simple file presence as proof of correctness. A simulation script that crashes on rank 48, or writes out NetCDF arrays filled with `NaN`s, may still successfully write a file to the disk. 
 
-Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. In v0.4.0, the session rigor resolver does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
+Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. Currently, the session rigor resolver does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
 
 This advisory convention is separate from the executable project verifier catalog at `.clio-coder/verifiers.yaml`. The verifier catalog has a strict version-1 schema and admits exact argv vectors to the `verify` tool. Scientific validation contracts and handbook expectations do not grant command authority: prose such as `validators: ["python tools/check_grid.py"]` remains guidance until the project owner confirms the equivalent argv, cwd, timeout, and tags in `verifiers.yaml`. The executable catalog does not interpret numerical tolerances or artifact expectations; it only runs the explicitly declared process vector through safe-exec.
 
@@ -95,7 +95,7 @@ Comparing floating-point values in scientific computations must accommodate roun
 
 ## Common Scientific Artifact Families
 
-The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in v0.4.0:
+The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in the current source tree:
 
 - **`HDF5` / `NetCDF` / `Zarr`:** Multi-dimensional scientific array files.
 - **`FITS`:** Flexible Image Transport System (used in astrophysics).

package/evals/README.md

@@ -1,5 +1,5 @@
 # Reference evals
 
-These suites exercise Clio's one evaluation engine: run the deterministic built-in authority corpus with `clio-coder eval run --suite evals/behavioral-machinery.yaml`, or select a configured model target for `behavioral-model.yaml`, `behavioral-model-negative-control.yaml`, and `tracked-metrics-baseline.yaml`. The graders and fixtures beside the suites are versioned inputs; `behavioral-machinery-baseline.json` is retained as reference evidence, not as a release gate.
+These suites exercise Clio's one evaluation engine from a source checkout: run the deterministic built-in authority corpus with `node dist/cli/index.js eval run --suite evals/behavioral-machinery.yaml --clio-coder-entry dist/cli/index.js`, or select a configured model target for `behavioral-model.yaml`, `behavioral-model-negative-control.yaml`, and `tracked-metrics-baseline.yaml`. The npm archive keeps these inputs for inspection and reproducibility, but the deterministic TypeScript driver uses the repository development toolchain. The graders and fixtures beside the suites are versioned inputs; `behavioral-machinery-baseline.json` is retained as reference evidence, not as a release gate.
 
-The single-system boundary is the engine under `src/domains/eval`: suites, verdict validation, artifact envelopes, comparison, and reporting belong there, while `evals/` contains only runnable reference inputs and their deterministic drivers. In v0.5.0, external-benchmark adapters such as SWE-bench and Terminal-Bench should translate their cases and grader observations into this engine's suite, execution, and verdict contracts, then consume its artifacts and comparison reports instead of adding a parallel harness.
+The single-system boundary is the engine under `src/domains/eval`: suites, verdict validation, artifact envelopes, comparison, and reporting belong there, while `evals/` contains source-checkout reference inputs and deterministic drivers. In v0.5.0, external-benchmark adapters such as SWE-bench and Terminal-Bench should translate their cases and grader observations into this engine's suite, execution, and verdict contracts, then consume its artifacts and comparison reports instead of adding a parallel harness.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.4.1",
-	"description": "Coding agent for HPC and scientific-software developers, part of IOWarp's CLIO ecosystem of agentic science.",
+	"version": "0.4.2",
+	"description": "The terminal coding agent for people who maintain the code that science runs on, with user-chosen models and inspectable evidence.",
 	"keywords": [
 		"ai",
 		"agentic-ai",
@@ -52,7 +52,8 @@
 		"src/**",
 		"skills/**",
 		"evals/**",
-		"docs/*.md",
+		"docs/**/*.md",
+		"!docs/html/**",
 		"README.md",
 		"CHANGELOG.md",
 		"CONTRIBUTING.md",
@@ -82,7 +83,8 @@
 		"ci": "npm run typecheck && npm run lint && npm run skills:check && npm run build && npm run test && npm run test:trace-viewer",
 		"ci:release": "npm run ci && node scripts/check-release.mjs",
 		"install:local": "bash scripts/install-local.sh",
-		"prepublishOnly": "npm run ci:release",
+		"smoke:real-home": "bash scripts/smoke-real-home.sh",
+		"prepublishOnly": "CLIO_CODER_RELEASE_CONTEXT=publish npm run ci:release",
 		"skills:pin": "node --import tsx scripts/pin-skills.ts",
 		"skills:check": "node --import tsx scripts/pin-skills.ts --check"
 	},
@@ -90,9 +92,9 @@
 		"@anthropic-ai/claude-agent-sdk": "0.3.186"
 	},
 	"dependencies": {
-		"@earendil-works/pi-agent-core": "0.84.0",
-		"@earendil-works/pi-ai": "0.84.0",
-		"@earendil-works/pi-tui": "0.84.0",
+		"@earendil-works/pi-agent-core": "0.84.4",
+		"@earendil-works/pi-ai": "0.84.4",
+		"@earendil-works/pi-tui": "0.84.4",
 		"@silvia-odwyer/photon-node": "^0.3.4",
 		"grok-mermaid": "0.2.2",
 		"ollama": "0.6.3",

package/skills/README.md

@@ -12,7 +12,7 @@ Clio's engine discovers *runtime* skills from these roots (see
 - extension roots
 - `~/.agents`, `~/.claude`, `~/.codex`, `~/.config/opencode`, `~/.copilot` → their `skills/` subdir
 - `<clio-config>/skills` (per-user)
-- project `.agents` / `.claude` / `.codex` / `.opencode` / `.github` → their `skills/` subdir (model-visible only with `CLIO_CODER_TRUST_PROJECT_SKILLS=1`; untrusted by default)
+- project `.agents` / `.claude` / `.codex` / `.opencode` / `.github` → their `skills/` subdir (model-visible only when `integrations.projectResources.trustProjectImports` is true; untrusted by default)
 - `.clio-coder/skills` (per-project)
 
 This repo's `skills/` directory is **not** one of those roots, so nothing here
@@ -22,10 +22,10 @@ auto-loads. That gap is deliberate.
 |---|---|---|
 | Location | a discovery root above | `skills/<category>/<name>/` in this repo |
 | Author | any user or harness | Clio authors, reviewed |
-| Provenance | none required | `clio:` block with `registry-id` + `source-url` + `audit: pass` |
+| Provenance | none required | `clio-coder:` block with `registry-id` + `source-url` + `audit: pass` |
 | Auto-loaded | yes | no, as it must be installed |
 
-"Approved" is visible in the frontmatter: a maintainer set `clio.audit: pass`
+"Approved" is visible in the frontmatter: a maintainer set `clio-coder.audit: pass`
 and a `version`. A skill a user wrote themselves carries none of those fields.
 
 ## Catalog
@@ -105,7 +105,8 @@ loads, Clio enforces that declaration at tool admission until the turn (or
 worker run) ends: calls outside the merged surface are blocked with reason
 code `skill_surface`, with `context` and `ask_user` always admitted. A
 skill can narrow its tool surface but never grant tools the host would not
-allow. Full semantics: docs/safety-model.md, "Skill tool surface narrowing".
+allow. See [Skill tool surface narrowing](../docs/architecture/safety-model.md#skill-tool-surface-narrowing)
+for the full semantics.
 
 ## Install (activate a marketplace skill)
 
@@ -140,8 +141,8 @@ teammate cloning it gets the same behavior.
 
 | Set | Scope | Why |
 |---|---|---|
-| `context-prime`, `context-handoff` | user | Session boundaries follow the operator across every repo; a handoff written in one project is read at the start of the next. |
-| `find-skills`, `skill-craft` | user | Discovery and authoring are things you do to your toolkit, not things a project does. Installing `find-skills` at user scope is also what makes the Clio copy outrank the compat-root one. |
+| `context-prime`, `context-handoff` | user | The workflow is useful in every repo, while each handoff remains scoped to the project where it was written. |
+| `find-skills`, `skill-craft` | user | Discovery and authoring are things you do to your toolkit, not things a project does. A user install outranks copies in shared user compatibility roots. |
 | `credentials` | user | Credential handling is a personal-machine discipline; a repo does not get to define it. |
 | `clio-coder-dev`, `clio-coder-test` | project, in this repo only | They describe Clio's own source tree. Elsewhere they are noise. |
 | `--category git` | project, where `git-master` is used | Branch, PR, and worktree conventions are the repository's, and the recipe binds them by name. |
@@ -150,8 +151,11 @@ teammate cloning it gets the same behavior.
 | `--category coding` | project | `tdd` and `coding-standards` follow the language and the test seams of the checkout. |
 | `--category workflow` | either | `grill-me` and `cut-it` travel with the operator; `design-council` is worth pinning per project when the project has recurring design forks. |
 
-When both scopes carry the same name, project wins: `.clio-coder/skills` outranks the
-user root, which outranks every compat root.
+Collision precedence from lowest to highest is extension, shared user
+compatibility roots, the Clio user root, project compatibility roots,
+`.clio-coder/skills`, then an explicit CLI skill path. Project compatibility
+roots are model-visible only after the project-import trust opt-in; their
+collision rank is still above the user root.
 
 After install, confirm Clio sees it:
 
@@ -176,21 +180,23 @@ both route through `clio-coder skills`. A community skill of the same name is
 commonly present in the compat roots (`~/.agents/skills`,
 `~/.claude/skills`) and drives the external `npx skills` installer, which
 bypasses Clio. Compat roots stay enabled, and the loader resolves name
-collisions by precedence: the Clio user root and `.clio-coder/skills` outrank the
-compat roots. Install the catalog copy so it wins:
+collisions by the precedence above. A user install beats the shared user
+compatibility copy. A project install beats both project and user
+compatibility copies. Install at the scope where the catalog copy must win:
 
 ```bash
-clio-coder skills install find-skills --user   # or --project for one repo
+clio-coder skills install find-skills --user
+clio-coder skills install find-skills --project  # strongest discovered project copy
 ```
 
 ## Publishing: the marketplace index
 
 `npm run skills:pin` writes two files. `registry.yaml` pins content hashes and
 is what drift is measured against. `skill-marketplace.json` is the published
-index: one entry per skill with `name`, `description`, `sourceUrl` (the
-skill's own `clio.source-url`), `version`, `audit`, and `category`. It carries
-no hashes, because duplicating them into a second published artifact only
-creates a way for the two to disagree.
+index: one entry per skill with `name`, `description`, optional `triggers`,
+`sourceUrl` (the skill's own `clio-coder.source-url`), `version`, `audit`, and
+`category`. It carries no hashes, because duplicating them into a second
+published artifact only creates a way for the two to disagree.
 
 A Clio install anywhere points at it and gets bare-name installs from this
 catalog:
@@ -216,12 +222,12 @@ The frontmatter contract has two layers, and the split is the point:
 - **Core keys stay community-standard.** `name`, `description`, `version`,
   `license`, and `allowed-tools` mean exactly what Claude Code and other agent
   loaders expect. No Clio-specific key ever lives at the top level.
-- **Everything Clio-specific nests under one reserved `clio:` mapping.**
+- **Everything Clio-specific nests under one reserved `clio-coder:` mapping.**
   Registry identity, provenance, audit and eval status, agent bindings, model
   guidance — all of it.
 
 The invariant this buys: a Clio skill dropped into any `.claude/skills`
-directory loads and works in Claude Code, which ignores the `clio:` block as
+directory loads and works in Claude Code, which ignores the `clio-coder:` block as
 an unknown key. Loaded by Clio Coder, the same file carries its full
 marketplace metadata. One file, no forks, no lossy export.
 
@@ -230,7 +236,9 @@ Required shape for every catalog skill:
 ```yaml
 ---
 name: <name>                  # lowercase, hyphens, matches the folder
-description: Use when ...     # triggers only, third person, <=1024 chars
+description: <one sentence>   # what it does, plus "Not for X; use Y" routing, <=1024 chars
+triggers:                     # the phrases a user types that should reach it
+  - <phrase>
 version: 0.1.0
 license: Apache-2.0
 allowed-tools:                # optional; community-standard tool narrowing
@@ -248,7 +256,7 @@ clio-coder:
 ---
 ```
 
-Field semantics inside `clio:`:
+Field semantics inside `clio-coder:`:
 
 - `registry-id` names the audited catalog a skill claims membership of; it is
   content, participates in the pinned hash, and survives installs.
@@ -280,16 +288,16 @@ Field semantics inside `clio:`:
 `requires: [skill:<name>, ...]` stays top-level: Clio's loader consumes it for
 dependency warnings, and other harnesses ignore it like any unknown key.
 
-Legacy flat keys (`registry-id`, `source-url`, `audit` at the top level) are
-still read by the loader as a fallback for copies installed before the nested
-form existed; the catalog itself must use the nested form, and `npm run
+The deprecated nested `clio:` mapping and legacy flat keys (`registry-id`,
+`source-url`, `audit` at the top level) are still read as fallbacks for older
+installed copies. The catalog itself must use `clio-coder:`, and `npm run
 skills:check` enforces that.
 
 ### Versioning policy
 
-`version` describes the skill as a working instrument, and the pinned hash
-already records every byte, so the version only moves when the thing an
-operator runs changes:
+`version` describes the skill as a working instrument. The registry separately
+hashes the normalized contents of `SKILL.md`; it does not hash sibling files.
+Move the version whenever the workflow an operator runs changes:
 
 | Change | Version |
 |---|---|
@@ -305,11 +313,11 @@ a broken link or a typo in a step. Nothing in this catalog is 1.0: a major bump
 is reserved for a skill whose triggers change enough that an operator relying on
 the old one would be surprised.
 
-Metadata changes do not bump because `registry.yaml` pins a
-provenance-stripped hash, so content edits are already caught byte-exactly, and
-raising a version for an `eval-status` line would make the number mean two
-different things at once. The trade is deliberate: the version is coarse, the
-hash is exact, and drift detection uses the hash.
+Lifecycle metadata changes do not bump the workflow version. The normalized
+`SKILL.md` hash catches non-stripped frontmatter and body edits; install fields
+such as `source-url` and `audit` are stripped. A sibling `references/`,
+`scripts/`, or `evals.md` change is represented by the required version change
+inside `SKILL.md`, because sibling bytes are not hashed directly.
 
 ## Claude Code interop
 
@@ -317,7 +325,7 @@ The invariant is that a catalog skill dropped unmodified into `.claude/skills`
 loads and runs in Claude Code. Verified against Claude Code 2.1.231:
 `skills/git/ship` copied into a scratch project's
 `.claude/skills/`, invoked headlessly, loaded through the `Skill` tool and
-answered a question about its own body. The `clio:` block is an unknown
+answered a question about its own body. The `clio-coder:` block is an unknown
 frontmatter key there and is ignored.
 
 **`allowed-tools` means the opposite thing in each harness, and that is the one
@@ -353,7 +361,7 @@ The rest of the surface, read from the same build:
 | `allowed-tools` | Grants, as above. Accepts a YAML list or one comma/space-separated string, same as Clio. |
 | `disallowed-tools` | Not read. A Clio denial is not enforced there. |
 | `requires:` | Not read; ignored as an unknown key, so a dependency warning is Clio-only. |
-| `clio:` | Not read; ignored as an unknown key. This is the invariant. |
+| `clio-coder:` | Not read; ignored as an unknown key. This is the invariant. |
 | Unparseable frontmatter | The per-skill load is wrapped in a bare catch: the skill is skipped silently, with no diagnostic. Clio warns instead. |
 | Size | No cap on SKILL.md. Clio rejects over 1 MiB and warns over 50 KiB, the activation delivery cap. |
 | `references/`, `scripts/` subfolders | Not enumerated at load time; they are files the body tells the model to read, which works in both. |
@@ -370,7 +378,7 @@ A skill is "approved for the marketplace" when a maintainer:
 1. Reviews `SKILL.md` against [`skill-craft`](meta/skill-craft/) (trigger-only
    description, checkable completion criteria, progressive disclosure, pruning
    pass, evals present).
-2. Confirms it carries the frontmatter spec above with `clio.audit: pass`.
+2. Confirms it carries the frontmatter spec above with `clio-coder.audit: pass`.
 3. Sets / bumps `version`.
 
 Each skill ships an `evals.md` recording the baseline scenarios it was tested
@@ -396,10 +404,11 @@ catalog where any skill is missing the required frontmatter, `audit: pass`, or
 its `evals.md`, declares a tool name Clio does not have, or carries a
 `source-url` that no longer ends with its catalog path. `npm run skills:check`
 (run in CI) fails on any drift between the catalog and either generated file,
-`registry.yaml` or `skill-marketplace.json`. Pinned hashes are provenance-stripped
-(install-lifecycle stamps like `installed-at` do not count as drift; content
-and registry-identity edits do), so a copy installed via `clio-coder skills install`
-still verifies against its audited source at activation.
+`registry.yaml` or `skill-marketplace.json`. Each pin covers the normalized
+`SKILL.md`, not the whole skill directory. Install-lifecycle stamps such as
+`installed-at` do not count as drift; body, version, and registry-identity
+edits do. A copy installed via `clio-coder skills install` therefore still
+verifies against its audited source at activation.
 
 A skill may declare typed dependencies with `requires: [skill:<name>, ...]`
 frontmatter; the loader warns at load time when a required skill is not

package/skills/coding/ast-grep/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: ast-grep
-description: Use when a code search needs structure, not text — "find all async functions without error handling", "find calls with this argument shape", "find X inside Y" — or when grep returns too much noise to filter. Writes and tests ast-grep rules, then scans the codebase. Search only; never rewrites code. Not for plain string or filename lookups; use grep or find.
+description: "Structural code search with ast-grep rules: finds code by shape when grep on text is too noisy, and never rewrites it. Not for plain string or filename lookups; use grep or find."
 triggers:
   - structural code search
   - ast-grep rule
   - find calls with this argument shape
   - find code inside a function
   - grep returns too much noise
-version: 0.1.1
+version: 0.2.0
 license: Apache-2.0
 allowed-tools:
   - bash