Publish the pending releases of the five extensions to npm #358

Parent

#328.

What to build

npm serves 2.0.0 of all five @docs.plus/extension-* packages. The repo holds newer work that npm users cannot get. The READMEs are now short start pages, but npm still shows the old 2.0.0 READMEs. extension-hypermultimedia carries an unpublished 2.1.0. extension-inline-code carries an unreleased Safari fix. This issue publishes all five, refreshes Context7, and settles the licence line for the README sample photo.

Acceptance criteria

• The maintainer has chosen path A or path B (see Agent brief), in a comment on this issue.
• No ## [Unreleased] heading is left in the five CHANGELOG.md files. Each one is now a dated version heading.
• npm latest for each package is the new version, and each npm page shows the new README.
• Each published version has its git tag <package-name>@<version> on origin, and a GitHub Release with the same name.
• Path A only: RELEASE_POLICY.md §Status says "Phase 2 — Lockstep active". .github/workflows/lockstep-guard.yml exists. .cursor/docs/extension-version-cutover.md is deleted, and no tracked file names it.
• The Context7 library shows the new READMEs, and the rules in context7.json still match every README Caveats section.
• extensions/extension-hypermultimedia/assets/readme-media/ATTRIBUTION.md states the licence the maintainer grants for sample.jpg.

Blocked by

None — can start now.

Agent brief

Type: HITL — the maintainer rules on path A or B in a comment here. The maintainer also commits, pushes, and publishes with an npm OTP. npm 2FA-on-write needs the OTP, so only the maintainer can publish. An agent does the preparation edits after the ruling.

Category: enhancement

Current behavior: Checked 2026-09-28.

• npm latest is 2.0.0 for all five packages.
• extensions/extension-hypermultimedia/package.json says 2.1.0. Its CHANGELOG has ## [Unreleased] (Documentation and Internal only) above ## [2.1.0] — 2026-09-17. No @docs.plus/extension-hypermultimedia@2.1.0 tag exists. The 2.1.0 entry adds a root export, so it is a minor.
• The other four package.json files say 2.0.0, and each CHANGELOG opens with ## [Unreleased].
• extension-inline-code [Unreleased] has a ### Fixed entry: the input and paste rules load on Safari before 16.4 (commit f9315d69d). That is a behaviour change.
• The [Unreleased] sections of hyperlink, indent and placeholder hold only ### Documentation (and ### Internal for hyperlink).
• git diff '@docs.plus/extension-<name>@2.0.0'..HEAD -- extensions/extension-<name>/src/ is non-empty for all five. For hyperlink, indent and placeholder, the diff is comment edits and moved export lines only.
• release:family finds no no-op package today, so --allow-noop is not needed. It skips the check for hyperlink: npm lists the stray 4.3.0 last, and that version has no git tag (findNoopPackages in scripts/release-family.ts).
• release:family preflight refuses unless all five share one version (checkLockstep in scripts/release-family.ts).
• RELEASE_POLICY.md §Status still says "Phase 1 — Cutover". .cursor/docs/extension-version-cutover.md says "no release:family until Phase 2". Phase 2 starts only with the Trigger D switch-flip commit. That commit also adds .github/workflows/lockstep-guard.yml (RELEASE_POLICY.md §CI Guard).
• README.md, AGENTS.md, extensions/README.md, RELEASE_POLICY.md and .cursor/skills/release-extensions/SKILL.md link to extension-version-cutover.md. .agents/skills/release-extensions/SKILL.md is a second copy of that skill and links to it too.
• The Phase 1 runbook in extension-version-cutover.md hard-codes 2.0.0 in its tag and release steps.
• On the maintainer checkout on 2026-09-28, inline-code had files in src/ newer than its dist/.
• The hypermultimedia README Quickstart loads https://docs.plus/demo-assets/sample-photo.jpg. That URL returns 200.
• assets/readme-media/sample.jpg is byte-identical to apps/webapp/public/demo-assets/sample-photo.jpg. ATTRIBUTION.md lists it as "Maintainer-supplied demo art" with licence "README gallery only". The Quickstart now uses it outside the gallery.

Desired behavior: The maintainer picks one path. For both paths, merge the hypermultimedia [Unreleased] lines into its existing [2.1.0] entry, then set that entry's date to the publish date.

• Path A — start Phase 2 and ship one family release at 2.1.0.
  1. Prepare the Trigger D switch-flip change that RELEASE_POLICY.md §Trigger D describes. Set §Status to "Phase 2 — Lockstep active", and update its "npm state" row.
  2. Write .github/workflows/lockstep-guard.yml as RELEASE_POLICY.md §CI Guard specifies.
  3. Delete .cursor/docs/extension-version-cutover.md. Remove or repoint every mention of it in the files listed above.
  4. Set the other four package.json versions to 2.1.0. Rename each [Unreleased] to ## [2.1.0] — <date>.
  5. A minor needs a ### Highlights section (RELEASE_POLICY.md §CHANGELOG Style Guide). Add one to each new 2.1.0 entry.
  6. The maintainer commits and pushes, then runs bun run release:family.
• Path B — stay in Phase 1 and publish each package on its own. Follow the Phase 1 runbook in .cursor/docs/extension-version-cutover.md. Replace 2.0.0 with each package's own version in the tag and release steps. Skip step 9 (the hyperlink 4.3.0 deprecation is done).
  • Hypermultimedia ships 2.1.0.
  • Inline-code ships 2.0.1 for its fix.
  • Hyperlink, indent and placeholder ship 2.0.1 with Documentation-only entries, so npm shows the new README.
  • Bump each package.json and rename each [Unreleased] to ## [<version>] — <date>.

For either path, after the publish:

1. The maintainer presses Refresh on https://context7.com/docs-plus/docs.plus (the tab name is unverified). Then compare the rules in context7.json with each README Caveats section.
2. The maintainer states a licence for sample.jpg, for example the repo licence or a named Creative Commons licence. Write it in ATTRIBUTION.md in place of "README gallery only". Note that the same file ships as apps/webapp/public/demo-assets/sample-photo.jpg.

Where to start: RELEASE_POLICY.md (§Status, §Trigger D, §No-op releases, §CHANGELOG Style Guide, §CI Guard). .cursor/skills/release-extensions/SKILL.md. scripts/release-family.ts (checkLockstep, checkBuildArtifacts, checkGitState, findNoopPackages). .cursor/docs/extension-version-cutover.md (Phase 1 runbook). The five extensions/extension-*/package.json and CHANGELOG.md files. context7.json.

Line numbers are hints as of 2026-09-28; the agent searches by symbol.

Rules that apply:

• AGENTS.md §Release Safety: no NPM_TOKEN in CI, never git push --tags, no new release scripts, no generated CHANGELOG entries, stable-only releases.
• .cursor/skills/release-extensions/SKILL.md §Extension Package Contract: a root re-export is a minor, not a patch. Resolve [Unreleased] before build, pack and publish. At each release, compare the context7.json rules with the README Caveats.
• .cursor/skills/release-extensions/SKILL.md §Extension Version Doctrine and §Release And Publish.
• RELEASE_POLICY.md §CHANGELOG Style Guide.
• extensions/CLAUDE.md §Extension Workflow.
• Prose follows .cursor/skills/tech-writer/SKILL.md §Simplified English.
• No new tests. This issue changes no extension logic.

Verify: The agent runs these after the preparation edits. Each must pass:

bash scripts/build-extensions.sh
EXTENSION_DIST_READY=1 bash scripts/run-tests.sh --extensions
bash scripts/extension-preflight.sh
git grep -n 'extension-version-cutover'   # path A only: no output

Build all five first. The release:family preflight fails when a dist/ is missing, or when a src/ file is newer than dist/.

Path A only: after the maintainer commits and pushes, the maintainer runs bun run release:family --dry-run. Its preflight needs a clean tree whose HEAD matches origin/main, so the agent cannot run it before the push.

After the publish, run this for each package:

curl -s https://registry.npmjs.org/-/package/@docs.plus/extension-<name>/dist-tags
git ls-remote --tags origin '@docs.plus/extension-<name>@<version>'
gh release view '@docs.plus/extension-<name>@<version>'

latest must show the new version, the tag must exist on origin, and the release must exist. Open each npm page. Check that the new README shows and its images load.

Out of scope

• Any source change to an extension. This issue publishes what is on main.
• The legacy HMarzban/* repositories.
• A @next dist-tag or a soak window. Releases are stable-only.