docs: changelog section for 3.0.0; version-agnostic install line

[lukefwalton]

What & why

Release prep for 3.0.0, docs only. The [Unreleased] entries since 2.1.0 become ## [3.0.0] - 2026-10-08 with a lead that says what the release is (the archive substrate under two consumers; since 8 October the retrieval under Ask the Archive, with an unpublished novel as a private entity; paper.md describes it) and where the alpha sits. The CONTRACT entry no longer says nothing in it is implemented. The README's install sentence names the package rather than the alpha, so the release workflow's metadata sync (package.json, lockfile, .zenodo.json, CITATION.cff, the README baseline line) is the only version bump.

Cutting the release after this merges: Actions → release on main with bump major (on the v3.0.0-alpha.1 baseline that finalizes to 3.0.0). The workflow builds and smoke-imports the package, tags, creates the GitHub release Zenodo archives, and publishes to npm under latest through the trusted publisher. I will dispatch it once this is merged unless you say otherwise.

Two things I left alone on purpose: the CITATION.cff / .zenodo.json title ("An AI that Says 'I Don't Know'") is your branding and the abstract is already in the substrate's terms; and #28 (the demo book's committed gists from a keyed demo:build) stays open, since the layer is built and tested keyless and the release does not depend on it.

Checklist

• npm test passes without an API key (the offline CI gate) — no hidden
  dependency on live calls
• npm run typecheck passes
• No change that makes the eval pass by special-casing a question (fixes go
  into the corpus, scoring, or prompt)
• A boundary stays structural (a type, not a checker someone must remember),
  if this touches the no-leak path (not touched)
• Touched the prompt / retrieval / validation / repair? Ran the relevant
  npm run eval subset (not touched)
• Read against .github/STANDARDS.md — the rubric a PR is judged by

🤖 Generated with Claude Code

https://claude.ai/code/session_01F2ti456guy1bXVmjA3fBTV

---

Generated by Claude Code

[surmado-code-review]

Automated Checks (advisory, non-blocking)

✅ All checks passed.

---

Standards Compliance

No direct §1 boundary, §2 eval, or runtime-path regression is visible here; this appears to be docs-only release prep.

🟡 [UNVERIFIED] The standards-sensitive part is the wording in CHANGELOG.md and README.md:

• CHANGELOG.md: phrasing like “archive substrate under two consumers” and “an unpublished novel as a private entity” should stay aligned with:

  • §3 Architecture: consumers are consumers; their behavior should not read like part of the substrate contract.
  • §5 Security & Performance: custody/confidentiality must not be overstated. “Private entity” is fine if it still clearly means the served disclosure boundary, not secrecy from embedding/drafting providers.

• CHANGELOG.md / docs/CONTRACT.md references: the change from a “not yet implemented” note to an “implemented” note should be narrowly factual per §6 README changes: factual, not pitch-deck. The risk is release prose implying more of the contract is shipped or guaranteed than the current package/export surface actually enforces.

• README.md: the install line moving to npm install @lukefwalton/answer-engine is the right direction, but it should still match the actual publish/import path used by the release workflow smoke-import path described in the PR.

Summary

This is docs-only 3.0.0 release prep: promoting the changelog out of [Unreleased], updating the implementation-status wording around the contract, and making the README install line version-agnostic. No code paths appear to change; the main review risk is whether the new prose is precisely aligned with the repo’s contract/custody language.
Reviewer: most of the risk is in the factual wording of CHANGELOG.md / README.md, especially substrate-vs-consumer framing and privacy/custody claims.

What to pay attention to

• CHANGELOG.md release lead — This is the highest-judgment part because it’s easy for release notes to blur “what the library guarantees” with “what Ask the Archive currently does.”
• Any mention of the unpublished novel / private entity — Check that it describes the disclosure boundary accurately and does not imply stronger confidentiality than the standards allow.
• README.md install sentence — Make sure the package name and wording match the actual release/import story and won’t age poorly on the next version bump.

Things I noticed

• No 🔴 red flags are visible from the material provided.
• 🟡 [UNVERIFIED] Because the actual diff body isn’t attached here, I can’t confirm whether the implementation-status wording was updated everywhere with the same level of precision. That’s the one thing I’d sanity-check before merge.

Good patterns

• The version-agnostic install line is a good maintenance change; it reduces needless README churn on future releases.
• The PR is cleanly scoped to release-docs prep and explicitly avoids pulling unrelated open issues into the release.

Suggested improvements

1. If it isn’t already there, make the changelog lead point readers to docs/CONTRACT.md as the contract and to consumer examples separately, so the substrate/consumer distinction stays crisp.
2. Consider phrasing the README install sentence as “latest published npm release” rather than naming 3.0.0 in prose, to avoid the docs ever reading ahead of the registry during release cutover.

Questions for the author

• Can you confirm the new changelog prose about the unpublished novel/private entity is framed in terms of the served disclosure boundary, not broader confidentiality from providers?
• Did you check for any remaining user-facing references to the alpha install path outside README.md, or was that the only place still carrying release-specific install wording?

---

Surmado Code Review (v1.5-mt, review #2 on bf098db) is an automated review, designed to work alongside human judgment.

Want to change your STANDARDS.md or YML? Edit it directly, or tune it with our AI agent Scout.

Comment /rerun-review on this PR to re-review the current code with your latest STANDARDS.md and config — costs 1 additional PR credit (limit 3/hour per PR).

[lukefwalton]

Both questions, answered from the diff.

Consumer framing: the 3.0.0 lead says "one retrieval contract under two consumers" and names Ask the Archive as where the substrate is deployed, with the novel described as "served as a private entity", which is the disclosure boundary (a locator hit, never text), not a secrecy claim. The contract bullet now reads "landed as documentation first; the implementation followed in the steps below, and the gold suite's semantics gated each one", which is narrowly true of the five steps listed under it.

Other alpha mentions: I grepped README.md, CHANGELOG.md, paper.md, and docs/CONTRACT.md. The install line was the only forward-looking one. bf098db fixes one more I had missed: the release paragraph said the alpha "is that release ... (the concept DOI resolves to it)", which stops being true the moment 3.0.0 lands; it now states what holds for every release. The remaining mentions are history (the first publish, the CLI upload, the baseline line the release workflow itself bumps) and stay.

---

Generated by Claude Code