@cosyte/cli 0.0.2 → 0.0.4

package/CHANGELOG.md

@@ -7,33 +7,237 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Versions and publishing are managed with [Changesets](https://github.com/changesets/changesets);
 this file is maintained by hand (Changesets handles the version bump and publish only).
 
+The released sections below were reconstructed on 2026-08-04. Until then every entry sat under
+`Unreleased`, including entries describing releases that had already shipped, so each published
+tarball carried a changelog calling its own contents unreleased. Those tarballs are immutable and
+still do. Each entry was assigned to the release whose tag first contains it, read off `v0.0.1`,
+`v0.0.2` and `v0.0.3`; no entry text was rewritten to fit a section.
+
 ## [Unreleased]
 
 ### Fixed
 
-- **The public surface now states that `0.0.1` is published and uninstallable (ASSETS-P8).** `0.0.1`
-  published on 2026-07-29 with all ten `file:vendor/*.tgz` dependency specifiers intact. `vendor/` is
-  not in `files` and there is no `bundledDependencies`, so every install route (`npm i`, `npm i -g`,
-  `npx`) fails with `ENOENT` on `node_modules/@cosyte/cli/vendor/cosyte-fhir-0.0.0.tgz`. Reproduced
-  in a clean directory. A published version is immutable (ADR 0001), so `0.0.1` stays broken and the
-  fix must ship as a later version.
-  - `README.md` gains a **"Known issue"** section stating what fails, the exact error, why, and that
-    a source checkout is the only workaround. `docs-content/installation.md` gains the same under
-    **"Installing fails today"**. Both copies of the broken `npx`-based MCP registration snippet are
-    annotated (`README.md` and `docs-content/mcp.md`).
-  - **Four false claims corrected.** (1) `README.md` said "not yet published to npm"; it is
-    published. (2) It described swapping the vendored sibling deps for real `@cosyte/*` npm ranges as
-    a step still to come "at that flip"; the flip already happened without the swap, which is the
-    defect. (3) The same "not yet published" claim appeared in **three** `docs-content/` pages. (4)
-    The `redact`/`deid` terminal diagnostic, the `--help` text, three JSDoc blocks that compile into
-    `dist/*.d.ts`, and **five** docs pages said `@cosyte/deid` was unpublished, unshipped, or unbuilt;
-    it is published at `0.0.2`, and the accurate statement is that the CLI does not wire it yet. Every
-    count here was re-derived by census of the base tree, not estimated.
-  - **The "all eight formats" claim was checked and is correct**: `CosyteFormat` and `OP_SUPPORT` both
-    enumerate exactly eight.
-  - `RELEASING.md` records that the documented dependency-swap step was skipped, that a green
-    `npm publish --dry-run` cannot catch this (it packs a tarball but never resolves its deps from a
-    registry), and adds a checklist step to install the published version from outside the repo.
+- **The shipped documentation sidebar was off the canonical IA spine, and it was holding up the
+  docs site's deploy (CLI-SIDEBAR-IA-NONCANONICAL).** `docs-content/sidebars.json` declared two
+  top-level categories that are not on the spine, **"MCP server"** and **"Reference"**. The docs
+  site lints the sidebar it receives from each package's released `docs-content.tar.gz`, and in
+  strict mode a non-canonical top-level label grades as an error, so this package failed that gate
+  and the site stopped deploying. Pre-existing since the pages were authored; it surfaced only once
+  an unrelated build failure stopped masking it.
+  - Both categories are removed and their pages folded into categories this package already had, so
+    **no page left the navigation and none was orphaned** (verified: the nine documents in
+    `docs-content/` and the nine referenced by the sidebar are the same nine). **`mcp`** and
+    **`reference-commands`** join **Guides**, next to `guides-overview`, both being task-oriented:
+    what to run and what comes back. **`limitations`** joins **Troubleshooting**, next to
+    `troubleshooting`, which is where the documentation standard puts known limitations.
+  - The categories this package ships are now `Installation`, `Quickstart`, `Core Concepts`,
+    `Guides` and `Troubleshooting`, in that order, under the `intro` document.
+  - **"Reference" was deliberately NOT renamed to "API Reference".** That category is injected by
+    the docs site, and a hand-authored one is refused outright rather than warned about, so the
+    rename would have traded a failing check for a differently failing one. Whether and where the
+    site adds it is the site's decision, not this package's, and this package neither authors nor
+    positions it.
+  - Verified against the site's own linter rather than by inspection, with the sidebar shipped in
+    the previous release as a **negative control**: that one produces two errors and this one
+    produces no findings. **Only a new release can clear the gate**, because it reads the sidebar
+    out of the released artifact and published releases are immutable, so the previous release
+    keeps its non-canonical sidebar permanently. That is reported without gating once a release is
+    no longer current.
+  - Documentation-artifact change only: no command, flag, exit code, diagnostic code or export
+    moves, and no page content was rewritten.
+
+- **The pre-commit PHI gate never saw a `git mv` into a scan root
+  (PHI-SCAN-RENAME-BLIND-AT-PRECOMMIT).** `scripts/phi-scan.ts --staged` listed the index with
+  `git diff --cached --name-only --diff-filter=AM`. Rename detection is on by default, so
+  `git mv <path> test/__fixtures__/<name>` stages as a **two-path `R100` record**, and `R` and `C`
+  are in neither `AM` nor `AMT`: the status filter deleted the record outright and the destination
+  was never enumerated. Measured on this repo, both shapes walking through the
+  `pnpm phi-scan --staged` pre-commit hook at **exit 0**: a regular file carrying a value this
+  scanner's own floor catches (`:100644 100644 <sha> <sha> R100`), and a symbolic link
+  (`:120000 120000 <sha> <sha> R100`, index mode `120000` under the scan root). `git mv` is an
+  ordinary developer action, not crafted input, and the pre-commit hook is the gate it walked
+  through.
+  - **`--no-renames` is the remedy, and it costs the record stride nothing.** The destination
+    arrives as a single-path `A` and the source as a `D` the filter drops, so the enumeration is a
+    strict **superset** of the previous one. Verified under `diff.renames` set to `true`, `copies`,
+    `false` and `1`, and under `diff.renameLimit=1`: no `R` or `C` record survives in any of them,
+    which makes the two-field record stride structural rather than conditional. `copies` is not
+    hypothetical; it produces a live `C100` here.
+  - **The destination mode was never read at all.** The route enumerated with `--name-only` and read
+    content with `git show :<path>`, and git stores a symbolic link as its **target path** under
+    mode `120000`, so the scan was handed the path text and never the target's bytes. It now lists
+    with `--raw -z` and **refuses** (exit `2`) any in-scope entry whose destination mode is not a
+    regular blob. A refusal names the entry's own repo-relative path and an engine-owned token for
+    its kind, and **never the link target**, which is working-tree text that can itself carry PHI.
+    Every offender is named, not just the first. That guarantee is about a **refusal** and does not
+    extend to a hit; see the linked-scan-root residual below.
+  - **`T` (typechange) is now in the filter**, because replacing a _tracked_ regular fixture with a
+    link is neither an add nor a modify (`:100644 120000 <sha> <sha> T`), so `--diff-filter=AM`
+    deleted the record before any mode could be read. The reverse direction, a link replaced by a
+    real file, is now scanned as the file it became.
+  - **Each scan root's own path is in scope**, not just its contents. Git records no index entry for
+    a directory, so an entry at exactly `test/__fixtures__` or `src` is that root replaced by a blob
+    or a link, and a prefix test requiring the trailing slash let it through while the whole corpus
+    went unscanned.
+  - **The all-mode walk gets the same refusal.** A scanner whose pre-commit half refuses a link
+    while its CI half silently drops one is not one a developer can reason about. The walk
+    enumerates `Dirent.isFile()`, an lstat answer, so a link (and a linked _directory_, which
+    `isDirectory()` also answers false for) fell out of the loop silently. The `.md` exemption
+    deliberately does not reach a link: it is a judgement about a file whose bytes the walk could
+    have read, and a link's name is no evidence about what is on the other side of it. A gitignored
+    entry stays out of scope, by the same rule that already excludes a gitignored fixture.
+  - **Two pre-existing exit-code defects fixed with it.** A missing or unreadable allow-list, and an
+    unreadable scan root, both threw past every handler and exited **1** with a raw stack trace. `1`
+    is this contract's code for _hits found_, so a caller branching on the exit code read a broken
+    invocation as a PHI finding and a caller branching on "not 0" read it as the gate working.
+    Neither was true. Both are now exit `2` with a diagnostic.
+  - **Stated rather than left to be inferred, both pre-existing and neither closed here.** The
+    staged route still does not enumerate `D` (a deletion has no staged blob to scan) or `U` (an
+    unmerged path has no single one). The `U` half costs nothing that can reach a commit, and that
+    was measured rather than assumed: `git commit` refuses an unmerged index outright. Under `src/`
+    the staged route still covers only `.ts` files while the all-mode walk covers every non-`.md`
+    file, so the CI sweep is what covers the difference; widening the staged half is a scope
+    decision and was not taken here.
+  - **The refusal rule is scoped to an _enumerated_ entry, and the unqualified version of it is
+    false.** It covers an entry the walk reached beneath a root it had already opened, and a staged
+    record in scope per the boundary rule, which under `src/` is `.ts` files only, so a staged link
+    at `src/notes.json` is under a scan root and `--staged` still exits 0 over it while the all-mode
+    sweep refuses it. Three shapes escape the rule, all pre-existing, all measured, none
+    closed here: **(1)** a scan root that is itself a **live** link is followed by the all-mode walk,
+    because `existsSync` and `readdirSync` both resolve, so the walk reads files no commit contains
+    and reports their values under a **fabricated in-repo path** that holds no such file (the
+    **dangling** direction is the mirror image: it reports clean over a corpus it never opened);
+    **(2)** an **ancestor** of a scan root is in neither route's scope, so staging `test` as a link
+    leaves `--staged` at exit 0 and the walk then follows it; **(3)** paths mode follows an
+    explicitly named link, because `statSync` resolves. The `--staged` half of shape (1) **is**
+    closed here. Closing the rest needs a refuse-a-scan-that-observed-nothing rule plus a decision
+    about how far above a scan root to look, which is its own change.
+  - `test/scripts/phi-scan.test.ts` builds throwaway git repositories for all of it, because these
+    are properties of what `git diff --cached` reports and cannot be reproduced by scanning a path.
+    **16 of its 34 tests run red against the scanner on `a7a92f8`**; the 18 that stay green are the
+    pre-existing floor tests, the deliberate controls (an ordinary staged hit, a clean pass, a
+    staged link outside both roots, an ignored link, and a check that the payload under test is
+    something this scanner would otherwise catch), and the four that **pin the disclosed residuals
+    above**. Those four are green on both trees by design: they pin behaviour this change does not
+    alter, so that the scoped wording of the refusal rule cannot quietly revert to the absolute one.
+    Synthetic values only.
+  - **No change to the CLI's runtime surface**: no command, flag, exit code, diagnostic code or
+    export moves. This is repository tooling.
+
+## [0.0.3] - 2026-08-03
+
+### Changed
+
+- **FHIR support is unavailable in an npm-installed copy, and now says so instead of crashing.**
+  `@cosyte/fhir` is not on the npm registry, so it cannot be declared as a dependency at all;
+  measured, declaring it alongside `@cosyte/transform` (which requires it) fails the whole install
+  with `ERESOLVE`. `@cosyte/transform` is therefore skipped by npm as an unresolvable optional
+  dependency. Both were previously loaded with a bare `await import()`, which in an installed copy
+  would have surfaced a raw resolver error and a stack frame, so FHIR `parse`/`inspect`/`fmt`/`validate`
+  and `convert` now degrade to a value-free `CLI_PARSER_UNAVAILABLE` (exit `69`) with a diagnostic that
+  says the package is not on the registry rather than "install it". **Neither diagnostic says "install
+  it", and that is deliberate**: `npm install @cosyte/transform` fails `E404` on its own
+  `@cosyte/fhir` peer, so `loadOptional()`'s stock wording ("install it to use this format, it is an
+  optional dependency") would point a user at a command that cannot succeed. New
+  `loadOptionalPackage(detail, load)` under `loadOptional`, exported on the `.` subpath.
+  `@cosyte/fhir` is retained as a `devDependency` on the vendored tarball so this repo's own FHIR and
+  `convert` tests still run; note that `devDependencies` **are** published, so that one
+  `file:vendor/*.tgz` specifier does remain in the manifest, harmlessly, because a consumer never
+  installs a dependency's `devDependencies` (verified: the install exits `0`). HL7 v2, `map-codes` and
+  the six breadth formats are unaffected and work from a plain install.
+
+- **Documented a pre-existing defect that this release makes reachable for the first time:
+  `--omit=optional` produces an install in which the `cosyte` command does not run at all.** The
+  install exits `0`, then every invocation, `--version` included, fails with `ERR_MODULE_NOT_FOUND` on
+  `@modelcontextprotocol/sdk` and a raw stack trace, because the built `dist/bin/cosyte.mjs` imports
+  the SDK statically at the top level rather than only on the `mcp` path. Verified identical on the
+  base commit, so it is not introduced here; it simply could not be hit before, because the package
+  could not be installed at all. `docs-content/` now says not to use that flag instead of implying it
+  is a supported way to slim the install. **The code defect is not fixed here** and needs its own
+  change: it also falsifies the "a plain `cosyte parse` never pulls it" claim in `src/bin/cosyte.ts`.
+
+- **The docs no longer tell you to run `npx @cosyte/cli …`, which never worked.** Separate from the
+  packaging defect and not fixed by it: `npx` runs the executable whose name matches the package
+  name's last segment, which would be `cli`, and this package ships `cosyte` and `cosyte-mcp`, so the
+  short form fails with `could not determine executable to run`. Reproduced on the published `0.0.2`
+  and on the fixed tarball, whose `bin` block is byte-identical. `README.md`, `docs-content/installation.md`
+  and both MCP registration snippets now use `npx --package @cosyte/cli cosyte …` /
+  `npx -y --package @cosyte/cli cosyte-mcp`, each measured working. A `cli` bin alias would fix the
+  short form and is deliberately not added, because `npm install -g` would then claim a command named
+  `cli` on the user's `PATH`.
+
+### Fixed
+
+- **`@cosyte/cli` can be installed from npm again (CLI-UNINSTALLABLE-MANIFEST).** `0.0.1` and `0.0.2`
+  both published with all ten `@cosyte/*` sibling packages declared as `file:vendor/*.tgz` local
+  paths. `vendor/` is not in `files` and there is no `bundledDependencies`, so the tarball shipped
+  none of them and every install route died on the first: `ENOENT ...
+node_modules/@cosyte/cli/vendor/cosyte-fhir-0.0.0.tgz`. The siblings are now real registry ranges:
+  `@cosyte/hl7` (`^0.0.7`) and `@cosyte/terminology` (`^0.0.9`) as hard `dependencies`, and the six
+  breadth parsers plus `@cosyte/transform` (`^0.0.4`) as `optionalDependencies`. Verified the way a
+  dry-run cannot: the packed tarball was installed in a clean directory outside the repo (exit `0`),
+  then both bins were run and the `.` subpath imported under ESM and CJS.
+
+- **`VERSION` and `cosyte --version` now report the release you are running (CLI-VERSION-DRIFT).**
+  `src/core/version.ts` exported `"0.0.0"` while `package.json` said `0.0.2`, and the constant's own
+  doc comment claimed it was "synced with `package.json#version` on release by the Changesets
+  `version` script" when no such step existed. Confirmed in the published tarball: `@cosyte/cli@0.0.2`
+  ships `VERSION = "0.0.0"` in `dist/index.mjs` and `dist/index.cjs`. It reached two user-visible
+  surfaces, `cosyte --version` and the MCP server's advertised `serverInfo.version`. `scripts/sync-version.mjs`
+  (ported from `@cosyte/transform`) now runs inside the `version` script, and `test/sanity.test.ts`
+  compares the export against `package.json` so a skipped sync goes red rather than shipping.
+  **The two assertions that let five bad releases through the sibling packages are fixed here, not
+  just the value:** `docs-content/installation.md` asserted `typeof VERSION` (true of every wrong
+  value) and now asserts the exact version, which the sync script keeps in step; and the declaration's
+  `: string` annotation, which the sync script's pattern keys on, is pinned by its own test, so
+  dropping it fails at `pnpm test` instead of silently at release time.
+
+- **The `attw` publish gate no longer exits 0 on an untyped pack (ATTW-FALSE-GREEN-PORT).** The
+  `attw` script was the bare CLI (`attw --pack . --profile node16`), and
+  `@arethetypeswrong/cli@0.18.4`'s `getExitCode.js` opens with `if (!analysis.types) return 0`,
+  returning before the problem list is read. So a tarball carrying no declarations at all printed
+  "This package does not contain types." and **exited 0**, and `verify.sh` propagated that 0 as a
+  pass. Reproduced on this package with zero concurrency and the real `--profile node16`
+  invocation, twice: with `dist/` removed, and with all ten of the build's declaration files
+  deleted and its JS left in place. The second is the realistic window, because `tsup` writes JS in
+  one pass and declarations in a later one; instrumented on one build here at a 10ms poll, all
+  eight `.mjs`/`.cjs` files appeared on a single poll at 4.92s and all ten declarations on a single
+  later poll at 11.82s, a 6.90s interval. That interval moves with load (7.85s on a busier box);
+  the ordering, and the ten declarations landing together, do not. Not answered with a lock or a
+  build queue: the gate is now able to report that its own inputs were missing, whatever removed
+  them.
+  - `scripts/attw.mjs` (ported from the fix shipped in `@cosyte/terminology`) runs two nets around
+    the real binary. A **preflight** that every relative path `package.json` promises exists and is
+    non-empty, naming the missing file; and a **post-check** that promotes the untyped sentence to a
+    failure, which catches declarations that are on disk but excluded from the tarball. Every
+    argument this repo passes is forwarded, so `--profile node16` keeps its exact meaning: measured
+    here, without it `@cosyte/cli/mcp` fails `node10` resolution and `attw` exits 1.
+  - **The preflight also walks `bin`, which the ported original did not**, because this is a `bin`
+    package and the sibling it came from ships no executable. Measured: with `dist/bin/cosyte.mjs`
+    deleted and everything else built, `attw --pack . --profile node16` printed every subpath green
+    and exited 0 over a tarball with no `cosyte` command in it.
+  - **`--quiet`, `-q`, `--format`, `-f` and `--config-path` are refused by option name and not by
+    value**, as is a `.attw.json` setting `quiet` or `format` (`readConfig()` applies it after
+    argv). Each was measured here to remove the untyped sentence from the output while still
+    exiting 0. `--config-path` is refused on a measurement rather than the inference the original
+    recorded. **Two limits are disclosed rather than closed**, both measured: the match is on an
+    exact argv token, so commander's attached and clustered short forms `-fjson` and `-Pf json` get
+    through (`-qP` does not; the wrapper treats an empty transcript as a failure), and a declared
+    path not starting with `.` is skipped by the preflight. The invocation this replaced exited 0
+    on the same pack with no arguments at all.
+  - **A correction to the ported message.** `files: ["dist"]` packs all ten declarations `tsup`
+    emits while `package.json` names only four; the shared `dist/io-<hash>.d.*` **and the four
+    `dist/bin/*.d.*`** ride along unnamed, and `analysis.types` is true if the tarball carries any
+    declaration. Measured on this tree: losing the four declared declarations gives "No types"
+    problems and **exit 1** while any of the other six survives, and only losing all ten gives the
+    untyped sentence and **exit 0**. So a partial declaration loss is caught by `attw` itself and
+    only a total one is the false green. The preflight reports both outcomes instead of asserting
+    the exit 0, which the inherited wording would have done falsely.
+  - `test/scripts/attw-gate.test.ts` pins all of it against the real binary, including attw's own
+    exit 0, a negative control on a well-formed package, that a genuine attw failure still fails
+    with attw's own status, and that the profile flag survives the wrapper in both directions.
+  - `scripts/verify.sh` in the meta-repo is unchanged; its propagation was never at fault.
+
 - **The route to an installable release, recorded in `RELEASING.md` and verified against the
   registry.** `@cosyte/hl7` (`0.0.3`), `@cosyte/terminology` (`0.0.4`) and all six breadth parsers
   would swap to real ranges today. `@cosyte/fhir` is unpublished (`FHIR-NPM-NAME`, an npm E403
@@ -44,6 +248,15 @@ this file is maintained by hand (Changesets handles the version bump and publish
   routed through a guarded loader to degrade to `CLI_PARSER_UNAVAILABLE` (exit `69`) rather than
   crash. `loadOptional()` cannot be reused unchanged: it takes a `CosyteFormat`, and `"transform"` is
   not one, and its diagnostic hardcodes the word "parser". Not undertaken here.
+  - **Superseded by the two `0.0.3` entries above**: the swap and the loader change were both
+    carried out. Two claims that entry made did not survive
+    contact: the "name similarity" reading of the `@cosyte/fhir` `E403` was **retracted across the
+    ecosystem on 2026-08-03** (the cause is unexplained; do not assert one), and "npm tolerates an
+    `optionalDependency` that fails to resolve" is true only in isolation. Declaring **both**
+    `@cosyte/fhir` and `@cosyte/transform` optional fails the install outright with `ERESOLVE`, which
+    is why `@cosyte/fhir` ended up not declared at all rather than declared optional.
+
+## [0.0.2] - 2026-07-31
 
 ### Added
 
@@ -84,6 +297,36 @@ this file is maintained by hand (Changesets handles the version bump and publish
   would be a wasted line. The wording is the one eight sibling packages already carry, confirmed
   against both rendered PNGs here rather than copied on trust.
 
+### Fixed
+
+- **The public surface now states that `0.0.1` is published and uninstallable (ASSETS-P8).** `0.0.1`
+  published on 2026-07-29 with all ten `file:vendor/*.tgz` dependency specifiers intact. `vendor/` is
+  not in `files` and there is no `bundledDependencies`, so every install route (`npm i`, `npm i -g`,
+  `npx`) fails with `ENOENT` on `node_modules/@cosyte/cli/vendor/cosyte-fhir-0.0.0.tgz`. Reproduced
+  in a clean directory. A published version is immutable (ADR 0001), so `0.0.1` stays broken and the
+  fix must ship as a later version.
+  - `README.md` gains a **"Known issue"** section stating what fails, the exact error, why, and that
+    a source checkout is the only workaround. `docs-content/installation.md` gains the same under
+    **"Installing fails today"**. Both copies of the broken `npx`-based MCP registration snippet are
+    annotated (`README.md` and `docs-content/mcp.md`).
+  - **Four false claims corrected.** (1) `README.md` said "not yet published to npm"; it is
+    published. (2) It described swapping the vendored sibling deps for real `@cosyte/*` npm ranges as
+    a step still to come "at that flip"; the flip already happened without the swap, which is the
+    defect. (3) The same "not yet published" claim appeared in **three** `docs-content/` pages. (4)
+    The `redact`/`deid` terminal diagnostic, the `--help` text, three JSDoc blocks that compile into
+    `dist/*.d.ts`, and **five** docs pages said `@cosyte/deid` was unpublished, unshipped, or unbuilt;
+    it is published at `0.0.2`, and the accurate statement is that the CLI does not wire it yet. Every
+    count here was re-derived by census of the base tree, not estimated.
+  - **The "all eight formats" claim was checked and is correct**: `CosyteFormat` and `OP_SUPPORT` both
+    enumerate exactly eight.
+  - `RELEASING.md` records that the documented dependency-swap step was skipped, that a green
+    `npm publish --dry-run` cannot catch this (it packs a tarball but never resolves its deps from a
+    registry), and adds a checklist step to install the published version from outside the repo.
+
+## [0.0.1] - 2026-07-29
+
+### Added
+
 - **Phase 7: release hardening (the final roadmap phase; the CLI is feature-complete).** No new
   runtime command surface: this phase is publish-readiness.
   - **Fuzz gate over the two input boundaries.** `test/fuzz.property.test.ts` fuzzes the terminal
@@ -104,6 +347,7 @@ this file is maintained by hand (Changesets handles the version bump and publish
     honest per-(format, operation) support matrix, the PHI-default posture), a man-page-style
     `docs-content/reference-commands.md`, and `RELEASING.md` (the one-package-two-bins publish,
     provenance/OIDC, the vendored-`file:`→npm dep swap, and the two standing founder stops).
+
 - **Phase 6: six more formats + streaming + shell completion (ADR 0025).** The `cosyte` CLI now wraps
   **all eight cosyte formats**, routed through a single lazy **per-format adapter registry**
   (`src/core/parsers.ts`) that replaces the old per-command `hl7 ? : fhir` branches and makes support
@@ -162,6 +406,7 @@ parse` invocation never loads it; the core works with the SDK absent (`--omit=op
     (`createMcpServer`, `startStdioServer`, `dispatchTool`, `TOOL_DEFS`, and the MCP result types) on the
     `./mcp` subpath. `redact`/`deid` (gated on `@cosyte/deid`) and `map-codes` are deliberately not
     exposed as tools yet.
+
 - **Phase 4: `convert` / `map-codes` (the consumer-of-consumers commands).** Two commands that wrap
   the higher-layer libraries; the CLI adds **no** mapping or terminology logic of its own.
   - **`convert <file|-> --to fhir [--json] [--quiet]`**: **HL7 v2 → FHIR R4** via
@@ -192,6 +437,7 @@ parse` invocation never loads it; the core works with the SDK absent (`--omit=op
     lazy-loaded per command, so the `parse` fast path never loads them).
   - **ADR `0023`**: wire `@cosyte/transform` + `@cosyte/terminology`; the deliberate 2 → 4 cap raise
     (amends ADR 0021).
+
 - **Phase 3: `validate` / `inspect` / `fmt`.** Three commands over the two wired parsers
   (HL7 v2 + FHIR R4), each a thin wrapper that re-implements no library logic.
   - **`validate <file|-> [--profile] [--json] [--quiet]`**: parse + run the wrapped parser's own
@@ -218,6 +464,7 @@ parse` invocation never loads it; the core works with the SDK absent (`--omit=op
     helpers (behavior-preserving). New programmatic exports: `validateCommand`, `inspectCommand`,
     `fmtCommand`, `resolveInput`, `parseFailureResult`, `formatHl7Position`, `errorResult`. No new
     runtime dependencies: stays within the cap of 2.
+
 - **Phase 2: PHI posture hardened + `redact`/`deid` + `--unsafe-show-values`.**
   - **`--unsafe-show-values`**: a global, opt-in, PHI-exposing flag, resolved once and order-
     independently and funnelled through a **single chokepoint** (`core/phi.ts`), so the "a value
@@ -238,28 +485,35 @@ parse` invocation never loads it; the core works with the SDK absent (`--omit=op
   - New `CLI_NOT_IMPLEMENTED` diagnostic code and `EXIT.UNAVAILABLE` (`69`); new programmatic exports
     (`PhiPosture`, `VALUE_FREE`/`SHOW_VALUES`, `extractPhiPosture`, `unsafeInputSuffix`, `deidStatus`,
     `redactCommand`).
+
 - **Phase 1: the `cosyte parse` foundation.** Reshaped the scaffold from a library skeleton into a
   **`bin` package**: `package.json#bin` maps `cosyte` → `dist/bin/cosyte.mjs` (a shebang entry over a
   testable `core`), argument-parsed with Node's built-in `util.parseArgs` + a hand-rolled subcommand
   dispatcher (**no third-party CLI framework**).
+
 - **`cosyte parse <file|->`**: reads a file argument or stdin (`-`); **autodetects the format by
   content** (HL7 v2 `MSH` framing, FHIR JSON `resourceType`): conservative and fail-safe (a confident
   single match parses; ambiguity/no-match is a data error asking for `--format`, never a guess); routes
   to the wrapped parser (**lazy-loaded** per format); emits the parsed model as **typed JSON on
   stdout**. Flags: `--format`, `--json`, `--quiet`, `--no-color`.
+
 - **The exit-code contract** (`sysexits.h`-grounded, documented, tested): `0` success · `2` usage ·
   `65` data/parse error (`EX_DATAERR`) · `66` no input (`EX_NOINPUT`) · `70` internal (`EX_SOFTWARE`).
   The CLI never exits `0` on input it could not handle.
+
 - **Value-free diagnostic channel** with stable `CLI_*` codes (`CLI_FORMAT_UNDETECTED`,
   `CLI_FORMAT_AMBIGUOUS`, `CLI_FORMAT_UNSUPPORTED`, `CLI_NO_INPUT`, `CLI_EMPTY_INPUT`,
   `CLI_PARSE_FAILED`, `CLI_USAGE`, `CLI_INTERNAL`). **stdout is the data channel; every stderr line is
   value-free**: code + position only, never a field value. No temp files, no file logging.
+
 - **Programmatic `core` API** (the `.` subpath): `detectFormat` / `classifyCandidates` /
   `detectionError`, `EXIT`, `CLI_CODES` / `CliError`, `run`, `parseCommand`, `VERSION`.
+
 - **Runtime dependencies (ADR 0021):** `@cosyte/hl7` (`46d50eb`, v0.0.1) and `@cosyte/fhir` (`7a099b2`,
   v0.0.0) as **hard, first-party** deps (an `npx` bin cannot peer-depend) vendored as `pnpm pack`
   tarballs under `vendor/` until PUB-FLIP (`pnpm vendor:refresh`; umbrella ADR 0008). Capped at **2**
   by the umbrella `verify-policy.json`; third-party CLI-core runtime deps stay **zero**.
+
 - **ADRs:** `0021` (developer-tooling tier is a `bin` that hard-depends on first-party siblings;
   third-party runtime deps minimized) and `0022` (one repo, two bins: the CLI and the future
   `cosyte-mcp` MCP server over one core; the web playground is out of scope).
@@ -322,6 +576,7 @@ parse` invocation never loads it; the core works with the SDK absent (`--omit=op
   surrounding guarantees (value-free stderr, the never-a-fake `CLI_FORMAT_UNSUPPORTED`, the gated
   `redact`, the exit-code contract) are worded exactly as strongly as before. Internal traceability
   stays where the convention puts it: this file, the changesets, the commits and the roadmap.
+
 - **A dependency-budget figure left `src/core/deid.ts` too.** The module said wiring `@cosyte/deid`
   "would breach the CLI's runtime-dep cap (2)". Only the number was stale: the cap has been 4 since
   `convert`/`map-codes` landed, and the constraint itself still holds, because the package declares
@@ -330,10 +585,12 @@ parse` invocation never loads it; the core works with the SDK absent (`--omit=op
   constraint lapsed. The reasons that actually ground the refusal to ship a built-in redactor are
   untouched: `@cosyte/deid` is unpublished, the wrapped parsers expose no de-identification API, and
   a partial scrub would present a false-safety impression.
+
 - **`CosyteFormat`'s documentation no longer understates autodetection.** It read as though content
   detection recognised only HL7 v2 and FHIR, with the other six accepted by `--format` but "not yet
   wired", which has not been true since all eight formats gained signatures. The stale sentence is
   removed rather than restated.
+
 - **A gate now enforces the public-surface rule, which is why the class stops regrowing.**
   `scripts/check-no-internal-refs.sh` (`pnpm check:no-internal-refs`, on the `verify.sh cli` ladder)
   plus `.github/workflows/no-internal-refs.yml` port the shape of `hl7`'s gate
@@ -352,6 +609,7 @@ parse` invocation never loads it; the core works with the SDK absent (`--omit=op
   purpose, as it is in `hl7` and `ncpdp`: it ships inside the npm tarball, yet the convention names it
   as one of the places identifiers belong. That contradiction is ecosystem-wide, and it is recorded
   here rather than settled by one repo.
+
 - **`redact`/`deid` no longer names an internal tracking identifier on any consumer surface.** The
   `CLI_NOT_IMPLEMENTED` text printed when de-identification is unavailable carried an internal work
   item that means nothing to anyone running the command, and the same identifier reached the
@@ -360,25 +618,24 @@ parse` invocation never loads it; the core works with the SDK absent (`--omit=op
   `@cosyte/deid`, which is unpublished, and the CLI ships no built-in redactor because a partial
   scrub would present a false-safety impression. The stable `CLI_NOT_IMPLEMENTED` code and the exit
   `69` are unchanged.
+
 - **`CLI_PARSER_UNAVAILABLE`'s message no longer cites an internal decision record.** The error
   raised when an optional per-format parser is not installed pointed at an ADR number, which is
   meaningless to a caller; it now just names the package to install. The stable
   `CLI_PARSER_UNAVAILABLE` code and the exit `69` are unchanged. The same sweep removed the
   remaining roadmap-phase language from `README.md` and `docs-content/troubleshooting.md`.
+
 - **The CI checks are now binding on `main`.** `ci / verify (22, ubuntu-latest)`,
   `ci / verify (24, ubuntu-latest)`, `ci / actionlint` and `codeql / analyze (javascript-typescript)`
   are required status checks, each pinned to the `github-actions` app, alongside branch deletion and
   force-push protection. They were advisory before: a red check could not stop a merge. Dependabot
   now watches the npm and GitHub Actions dependency surfaces weekly, which nothing did previously.
+
 - **Reshaped the package from the parser-library scaffold to a `bin` package.** Removed the archetype
   stubs (`parseCli`, `WARNING_CODES`, `FATAL_CODES`); replaced the library `src/index.ts` and the
   round-trip property test with the command tree, the programmatic `core` API, and command-contract /
   autodetection / PHI-leak / equivalence tests. Rewrote `docs-content/` and `README.md` for the CLI.
 
-### Deprecated
-
-### Removed
-
 ### Fixed
 
 - **README + guides now describe the shipped Phase-3 command surface.** The `README.md` and
@@ -387,10 +644,12 @@ parse` invocation never loads it; the core works with the SDK absent (`--omit=op
   and the gated `redact`/`deid`) over the two wired parsers (HL7 v2 + FHIR R4). The pre-alpha,
   not-yet-published-to-npm status is unchanged (accurate), and the `npx`/`npm install -g` examples now
   carry a "not on npm yet" caveat (docs-only; README-ORG-SWEEP).
+
 - **`phi-scan` now scans the real fixture directory.** The scanner's fixture root pointed at a
   nonexistent `test/fixtures/`; it now walks `test/__fixtures__/` (and the same path in the staged
   filter), so the PHI commit-gate actually covers the CLI's synthetic fixtures.
 
-### Security
-
-[Unreleased]: https://github.com/cosyte/cli/commits/main
+[Unreleased]: https://github.com/cosyte/cli/compare/v0.0.3...HEAD
+[0.0.3]: https://github.com/cosyte/cli/compare/v0.0.2...v0.0.3
+[0.0.2]: https://github.com/cosyte/cli/compare/v0.0.1...v0.0.2
+[0.0.1]: https://github.com/cosyte/cli/releases/tag/v0.0.1

package/README.md

@@ -22,10 +22,9 @@ It is a thin, honest skin over libraries that already own correctness ([`@cosyte
 and owns two disciplines of its own: a documented **exit-code contract** and a **value-free
 diagnostic** posture.
 
-## Known issue: `0.0.1` is published but cannot be installed
+## Known issue: `0.0.1` and `0.0.2` are published but cannot be installed
 
-**`@cosyte/cli@0.0.1` is on npm and `npm install @cosyte/cli` fails.** It ends in an `ENOENT`, like
-this:
+**`npm install @cosyte/cli@0.0.1` and `@0.0.2` both fail.** They end in an `ENOENT`, like this:
 
 ```
 npm error code ENOENT
@@ -33,26 +32,33 @@ npm error path node_modules/@cosyte/cli/vendor/cosyte-fhir-0.0.0.tgz
 npm error enoent ENOENT: no such file or directory
 ```
 
-`npx @cosyte/cli …` and `npm install -g @cosyte/cli` fail the same way, and so does the `npx`-based
-MCP server registration below. There is no workaround from the consumer side. **Nothing is wrong with
-your setup, and re-running it will not help.**
+`npx` and `npm install -g` fail the same way on those two versions, and so does the `npx`-based MCP
+server registration below. There is no workaround from the consumer side. **Nothing is wrong with your
+setup, and re-running it will not help.**
 
-**Why.** The published manifest declares its ten `@cosyte/*` sibling packages as local file paths
+**Why.** Those manifests declared the ten `@cosyte/*` sibling packages as local file paths
 (`file:vendor/*.tgz`) rather than as npm version ranges. Those tarballs live in the git repository and
-are deliberately not part of the published package, so npm resolves the paths against a directory that
-does not exist in your `node_modules` and stops at the first one. It is a packaging defect in that
-release, not a fault in any command.
-
-**A published version is immutable, so `0.0.1` will stay broken.** The fix has to arrive as a later
-version, and it is blocked on something outside this package: `@cosyte/fhir` is not on npm yet (its
-name was rejected by the registry as too similar to an existing package, which is a naming problem
-rather than missing work), and `@cosyte/transform` is on npm but currently fails to install for the
-same reason, because it peer-depends on `@cosyte/fhir`. `@cosyte/hl7` and `@cosyte/terminology` are
-published and would swap over today. Until the naming issue is resolved, run the CLI from a source
-checkout (`pnpm install && pnpm build`, then invoke `dist/bin/cosyte.mjs`).
-
-> **Status:** pre-alpha (`0.0.x`), published to npm at `0.0.1`, which **cannot be installed** (see
-> above). The `cosyte` command wraps **all eight
+are deliberately not part of the published package, so npm resolved the paths against a directory that
+does not exist in your `node_modules` and stopped at the first one. It was a packaging defect in those
+releases, not a fault in any command.
+
+**A published version is immutable, so `0.0.1` and `0.0.2` stay broken: install a later version.** The
+sibling packages are now declared as real npm ranges, and the resulting tarball has been installed from
+outside this repository and exercised, which is the check a `npm publish --dry-run` cannot perform.
+
+**One dependency could not be made real, and it costs you FHIR support.** `@cosyte/fhir` is not on the
+npm registry, so it cannot be a dependency of this package at all; `@cosyte/transform` is on npm but
+requires it, so npm skips that too. In an installed copy:
+
+- FHIR `parse` / `inspect` / `fmt` / `validate` and the `convert` command report a value-free
+  `CLI_PARSER_UNAVAILABLE` and exit `69`. They never guess, and they never blame your input.
+- HL7 v2, `map-codes`, and the six breadth formats (X12, C-CDA, DICOM, NCPDP, ASTM, MLLP) all work.
+
+To use the FHIR commands today, run the CLI from a source checkout (`pnpm install && pnpm build`, then
+invoke `dist/bin/cosyte.mjs`), where the FHIR library is supplied locally.
+
+> **Status:** pre-alpha (`0.0.x`). `0.0.1` and `0.0.2` are on npm and **cannot be installed** (see
+> above); a later version fixes that. The `cosyte` command wraps **all eight
 > cosyte formats** (**HL7 v2**, **FHIR R4**, **X12**, **ASTM**, **NCPDP SCRIPT**, **C-CDA**, **DICOM**,
 > and **MLLP**) plus the `@cosyte/transform` and `@cosyte/terminology` higher-layer libraries, with
 > conservative content-format autodetection and a documented exit-code contract:
@@ -82,25 +88,40 @@ checkout (`pnpm install && pnpm build`, then invoke `dist/bin/cosyte.mjs`).
 >
 > The CLI is **feature-complete**: an argv+stdin+MCP fuzz gate, an exit-code golden matrix, a
 > built-package smoke of both bins, and a clean `npm publish` dry-run. Those gates cover the code, and
-> the code is not what is broken. The one release step they do not cover is the dependency swap
-> described above, which is why `0.0.1` published green and still cannot be installed: a dry-run
-> builds the tarball but never resolves it from a registry. **The swap is blocked, not scheduled**,
-> and it stays blocked until `@cosyte/fhir` can be published under a name npm accepts, which also
-> unblocks `@cosyte/transform`. See [RELEASING.md](./RELEASING.md).
+> the code was never what was broken. The one release step they do not cover is the dependency swap
+> described above, which is why `0.0.1` and `0.0.2` published green and still cannot be installed: a
+> dry-run builds the tarball but never resolves it from a registry. **That swap has now been made**,
+> and installing the packed tarball from outside the repository is a release step in its own right.
+> `@cosyte/fhir` is the one dependency it could not cover, which is why FHIR support is absent from an
+> installed copy rather than merely deferred. See [RELEASING.md](./RELEASING.md).
 
 ## Run it
 
-> **None of the commands in this section work today.** `@cosyte/cli` is on npm, but every install
-> route fails with the `ENOENT` described in [the known issue](#known-issue-001-is-published-but-cannot-be-installed)
-> above. They are recorded here as the shape install will take once a fixed version can ship. Until
-> then, run it from a local checkout (`pnpm install && pnpm build`, then invoke `dist/bin/cosyte.mjs`).
+> **These commands do not work yet, and the reason is now only that no fixed version has shipped.**
+> The newest version on npm is `0.0.2`, and it is one of the two that cannot be installed. The
+> packaging defect is fixed in this repository and proven by installing the packed tarball outside it,
+> but a published version is immutable, so the fix reaches you only in the next release. Until then,
+> run it from a source checkout: `pnpm install && pnpm build`, then invoke `dist/bin/cosyte.mjs`.
 
 ```bash
-npx @cosyte/cli parse message.hl7   # no install; format autodetected → HL7 v2
-npm install -g @cosyte/cli          # or put `cosyte` on your PATH
-cosyte --help
+npm install -g @cosyte/cli          # put `cosyte` on your PATH
+cosyte parse message.hl7            # format autodetected → HL7 v2
 ```
 
+Or without installing, using `npx`:
+
+```bash
+npx --package @cosyte/cli cosyte parse message.hl7
+```
+
+> **`npx @cosyte/cli …` (the short form) does not work, and this is not the packaging defect above.**
+> It fails with `could not determine executable to run`. When a package ships more than one
+> executable, `npx` runs the one whose name matches the package name's last segment; that would be
+> `cli`, and this package ships `cosyte` and `cosyte-mcp`. Naming the executable explicitly with
+> `--package` is the supported form, and it works. A `cli` executable is deliberately **not** added as
+> an alias: `npm install -g` would then put a command called `cli` on every user's `PATH`, which is far
+> too generic a name to claim.
+
 ## `cosyte parse`
 
 Read a file (or stdin via `-`), autodetect the format by content, and print the parsed model as typed
@@ -274,15 +295,16 @@ subprocess**, not a hosted endpoint. Register it in an MCP client's config:
 ```json
 {
   "mcpServers": {
-    "cosyte": { "command": "npx", "args": ["-y", "@cosyte/cli", "mcp"] }
+    "cosyte": { "command": "npx", "args": ["-y", "--package", "@cosyte/cli", "cosyte-mcp"] }
   }
 }
 ```
 
-> This registration **does not work yet**: `npx` has to install the package first, and that install
-> fails with the `ENOENT` described in
-> [the known issue](#known-issue-001-is-published-but-cannot-be-installed) above. To run the MCP
-> server today, point `command` at a built local checkout's `dist/bin/cosyte-mcp.mjs` instead.
+> **`--package` is required, and the shorter `["-y", "@cosyte/cli", "mcp"]` does not work**: it fails
+> with `could not determine executable to run`, for the `npx` executable-selection reason described
+> under [Run it](#run-it) above. This also needs a version that can be installed at all, so not
+> `0.0.1` or `0.0.2`. The `convert` tool reports `CLI_PARSER_UNAVAILABLE` from an npm install, because
+> the FHIR library is not on the registry.
 
 `cosyte mcp` and the standalone `cosyte-mcp` bin both start the stdio server. It exposes four tools
 (`parse`, `validate`, `inspect`, `convert`), each calling the same command the terminal runs, so the CLI