docs: resolve the consistency audit before v0.1.0 (#79)

[maehr]

Resolves the documentation consistency audit in #79 — 40 of its 41 findings — and the related-systems rework in #81. All of it is intended for the v0.1.0 baseline.

Closes #81.

Branched from 37faf37, the audit's own baseline, so every line number in the issue resolves.

Why this lands before the tag

package.json, CITATION.cff and CHANGELOG.md are all at 0.1.0, but no tag exists yet. Once cut, these docs become a citable baseline. Four findings (A1, A3, A4, D22) would otherwise freeze wrong statements into the published API contract and the spec's headline example, and F32/F33 mislead contributors today by publishing the wrong branching model.

Commits

Commit	Findings
fix(standard) spec	A1, A2, A4–A7, B9, B10, B12
fix(api) OpenAPI + BCP 47	A3, D22, A6
docs(community) mirrors	F32–F35, G37–G39, D26
docs(standard) json-ld/versioning/index	A2, A8, B11, D24, G40, G41
docs(get-started) examples	C13–C19, D20–D25, E27–E31
docs(get-started) plain language	readability pass
docs(get-started) related standards	#81
docs(standard) license and language rules	review findings

Notable changes

A1 — §13's worked example and the §5 class diagram omitted the required preferred_citation_system_key, so the spec's flagship example failed Work.safeParse. Verified both ways: it parses now, and did not before.

A3 / D22 — the OpenAPI document advertised application/json for the alternate link where the implementation emits application/ld+json, and omitted Work.creators entirely. Adds a Creator component mirroring the Zod discriminated union.

A6 — BCP 47 is now actually enforced. §14 required validators to check language-tag syntax, but all three layers had only minLength: 2. Adds a shared LanguageTag (RFC 5646 langtag + privateuse well-formedness) to standard/schema/common.ts, wires it into the published and source schemas, and mirrors it as an OpenAPI pattern. All 12 language values in the registry still validate. The unenforceable presence clause was removed from §14's validator list only; §9 keeps it as an authoring obligation.

A2 — the two senses of "tombstone". ADR-0004 defines a tombstone as deprecated, withdrawn or blocked, but the compiler's TOMBSTONE_STATUSES is deliberately narrower (withdrawn, blocked) for the Work projection and the live-reference invariant. The definition and the code are both correct and unchanged; the dependent prose in json-ld.md and the OpenAPI descriptions was wrong for deprecated and now names the real filter.

C13–C15 — the "compiled registry record" blocks in how-it-works.md now match dist/dump/ field for field: SPDX IRIs instead of bare ids, draft instead of active, real modified dates, and the John.3.16 example regains its second resolver target.

F32 / F33 — the published contributing page told contributors to branch from and PR against main, and omitted the entire Branching model section. The actual infrastructure integrates on staging: Dependabot targets it, and the registry's validate workflow checks out parent/staging. The release checklist is resynced from 7 stale steps to the canonical 9.

#81 — related systems, grouped by layer. The page framed every neighbouring standard as an identifier scheme, but the systems it listed sit on different layers. It is now seven sections — canonical reference and text APIs, persistent identifiers, bibliographic and authority models, edition and fragment addressing, digital surrogates, editorial conceptual models, platforms — each with a framing sentence and the same four-column table. Adds IIIF Presentation API, W3C Web Annotation, BIBFRAME, IFLA LRM and RAMEN, plus URN:NBN, which Appendix B of the spec already listed and this page did not. The title changes to "Related standards and systems"; the URL does not. IIIF and Web Annotation are documented as resolver_targets, consistent with the ADR-0006 test that already governs TEI anchors — nothing is added to Appendix B, because making IIIF a MappingAssertion target is a modelling decision that wants its own ADR.

Review findings. Two threads from the automated review, both fixed in ac81fd4: §9's license bullet stated the bare SPDX identifier as the requirement on the published field, where every example in the section and §14 item 10 carry the IRI; and LanguageTag's comment implied the excluded grandfathered tags are the i- forms. The regex rejects all 17 irregular tags and accepts all 9 regular ones, which a new test now locks.

Verification

npm run verify green — format, astro check, 25/25 tests, 204,350 pages, all internal links valid, 67,959 references compiled with no rejections. The two commits added since carry the test count to 30/30, verified with npm run verify:fast.

Checked specifically:

• the corrected §13 Work passes Work.safeParse, and fails without the added key;
• grep -c '"status":"active"' dist/dump/references.jsonl → 0;
• LanguageTag accepts all 12 registry languages plus grc-Grek and zh-Hant-TW, rejects e n, english!, e, and splits the 26 grandfathered tags 9 accepted / 17 rejected;
• every external link added for docs: add more systems like IIIF #81 returns 200, and the Appendix B anchor the URN:NBN row targets exists in the built HTML;
• for the plain-language commit, every fenced code block is byte-identical to the preceding commit and every heading is unchanged, both verified programmatically — the rewrite cannot have re-broken the values just corrected.

Scope notes

F36 is deliberately excluded — the legal-reservation notice missing from the English association pages belongs with the statutes batch, which is being handled separately.

B12 swept wider than filed. The audit listed three "equivalence" sites for MappingAssertion; there were nine. Fixing only three would have left spec §4 contradicting §5. The three remaining uses describe citation-system-to-citation-system equivalence, a different and correct sense, and were left alone.

The plain-language pass is inspired by the rule intent of ASD-STE100. That specification and its Approved Word dictionary are copyrighted and are not used here, so this is an approximation and not a conformance claim.

Follow-ups, not in this PR

• Rename TOMBSTONE_STATUSES to make the narrow sense self-documenting in code — a refactor, not a docs fix.
• F36, with the statutes batch.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Resolves the documentation consistency audit for the v0.1.0 baseline by aligning the TextRefs standard docs, get-started guides, and community docs with the current implementation and published registry output, while also tightening schema validation and the published OpenAPI contract.

Changes:

• Introduces a shared LanguageTag validator (BCP 47 well‑formedness) and wires it into canonical schemas, authoring validation, OpenAPI, and tests.
• Updates the standard docs (spec/versioning/JSON‑LD/index) to correct mapping/tombstone semantics and bring worked examples in line with published output.
• Refreshes community and repo docs (contributing/roadmap/readme/agents) to reflect the current branching/release workflow and verification commands.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
standard/schema/work.ts	Clarifies Work mapping projection semantics (withdrawn/blocked filter).
standard/schema/common.ts	Adds LanguageTag shared Zod validator.
standard/schema/canonical-reference.ts	Uses LanguageTag for resolver-target language.
scripts/source-schema.ts	Enforces LanguageTag at authoring parse time.
scripts/compile.test.ts	Adds tests covering language-tag acceptance/rejection.
api/openapi.yaml	Aligns alternate media type, adds Creator, and adds language-tag pattern.
src/content/docs/standard/specification.md	Fixes normative statements/examples around mappings, tombstones, SPDX/license, vocabularies.
src/content/docs/standard/versioning.md	Clarifies tag vs spec versioning and invariant-check timing; mapping wording update.
src/content/docs/standard/json-ld.md	Corrects vocabulary table and mapping projection description.
src/content/docs/standard/index.md	Updates overview wording and vocab list; v0.1.0 baseline note.
src/content/docs/get-started/index.md	Adjusts intro copy and vocabulary list; example description tweaks.
src/content/docs/get-started/use-cases.md	Plain-language readability edits.
src/content/docs/get-started/url-layout.md	Plain-language edits and tighter URL-prefix explanations.
src/content/docs/get-started/related-systems.md	Refines comparison table and guidance on where identifiers belong.
src/content/docs/get-started/mappings-and-resolver-targets.md	Updates mapping vs resolver-target guidance and examples.
src/content/docs/get-started/how-it-works.md	Updates compiled-record examples to match published dump semantics/fields.
src/content/docs/get-started/authoring.md	Restructures authoring guidance; clarifies templates, statuses, and defaults.
src/content/docs/community/contributing.md	Adds branching model + release checklist updates; verification comment update.
src/content/docs/community/roadmap.md	States canonical roadmap source is root ROADMAP.md.
ROADMAP.md	Status wording update (“in progress” → “done”).
README.md	Expands layout documentation and updates verify command description.
CONTRIBUTING.md	Updates verify:fast comment to include tests.
AGENTS.md	Updates command descriptions and clarifies roadmap mirroring.
.github/ISSUE_TEMPLATE/conformance_failure.yml	Makes failing-cases field optional and updates guidance text.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.