README tells visitors to run npx paragent, but the package was never published

[myselfsiddharth]

Context

README.md's Quick Start — the first thing a visitor is told to run — is:

npx paragent record --fixture --out trajectory.json
npx paragent compile --in trajectory.json --out bundle.json

paragent is not on the npm registry:

$ npm view paragent version
npm error code E404
npm error 404 Not Found - GET https://registry.npmjs.org/paragent - Not found

Every one of those commands fails for every reader who has not cloned the repo. The README's Quick Start is, today, an instruction that cannot work.

How this happened, and why it is not a duplicate of #134

#134 ("Publish to npm so Paragent is installable without cloning") is closed as completed, and the work it names was genuinely done: private: true was removed, files/bin/engines were set, and #155 shipped the paragent binary and a prepack build. What was never done is the publish itself. There is no publish workflow in .github/workflows/ and no release has been cut, so the package was made publishable and then not published.

This is the claim-vs-reality gap docs/INTEGRITY-AUDIT.md category A exists to catch: a closed issue, a shipped bin, and a README that reads as though the last step happened.

Blast radius

• Every visitor. The Quick Start is the README's most-followed path and it 404s.
• Submit Paragent to awesome-lists once the repo is presentable #138 (awesome-lists submission) is blocked by this, not unblocked. Submit Paragent to awesome-lists once the repo is presentable #138 lists "Publish to npm so Paragent is installable without cloning #134 landed (npm)" as an explicit precondition and says an entry whose only instruction is "clone the repo" reads as unfinished. Submitting today would send maintainers to a broken npx command — worse than not submitting. Submit Paragent to awesome-lists once the repo is presentable #138 should not proceed until this closes.

What to do

Two halves; the second is the one that stops this recurring.

1. Publish. Requires an npm account with rights to the paragent name and a token — founder action, not something CI can bootstrap on its own. Confirm the name is actually available or already owned before assuming (a 404 means unpublished, not necessarily unclaimed).
2. Automate it, so "publishable" and "published" cannot diverge again. A release workflow triggered on a tag or a GitHub Release, running npm publish with provenance, gated on the existing ci.yml checks. Store the token as a repository secret; do not commit it anywhere (CONTRIBUTING rule 1).
3. Verify the published artifact is the one the README promises. npm pack locally and confirm the tarball contains dist/src/, contracts/, README.md, LICENSE and nothing else — files is already set, so this is a check, not a change.
4. Decide what version ships. package.json is at 0.1.0. Given docs/README.md and the README's own status section say the thesis is unproven and the gate number is pending, a 0.x release is honest; consider whether the first publish should carry a pre-release tag rather than latest.

If publishing is not wanted yet, then close this by fixing the README instead — replace the npx Quick Start with the clone-and-run path that actually works, and reopen #138's precondition discussion. Either resolution is fine; what is not fine is the current state, where the README documents a command that does not exist.

How to test

npm pack --dry-run          # exactly the files `files` declares
npm view paragent version   # after publish: resolves instead of 404

Then, in a clean directory outside the repo:

npx paragent --version
npx paragent record --fixture --out /tmp/t.json

Both must succeed with no clone present. Run this from a machine that has never built the repo, or the local node_modules will mask a broken package.

Before you open the PR

• Either published and verified from a clean directory, or the README's Quick Start corrected to a path that works
• Release automation added, so this cannot drift again
• Published tarball contents verified against files
• No token committed; secret stored in repository settings
• Submit Paragent to awesome-lists once the repo is presentable #138 unblocked or explicitly re-blocked with the reason
• If a gap between a closed issue and reality is being recorded, add the docs/INTEGRITY-AUDIT.md row