chore(release): v0.1.0 — first citable baseline

[maehr]

Release v0.1.0 — first citable baseline

Publishes staging → main as v0.1.0 (0.0.1 → 0.1.0: pre-1.0 breaking spec changes). This is the first tagged release; after merge, main is tagged v0.1.0, release.yml builds the dump and creates the GitHub Release, and Zenodo mints the concept DOI. Community announcement with the full story: discussion #31.

Tracked in #68, which carries the merge sequence and the pre-tag checklist.

What it ships

67,959 references across 12 works and 10 citation systems, all at status: draft — 68,005 records in total. That is up from ~39,200 when this PR was opened: the resolver review completed the New Testament (John only → 27 books) and the Tanakh (Genesis only → 39 books), so the baseline covers two complete biblical corpora rather than one book of each.

references.jsonl is 53.6 MB and the alias table is 12.9 MB; the built site is 204,361 pages plus 68,019 JSON endpoints.

Standard — six ADRs adopted (decisions/)

• ADR-0001: dcterms:conformsTo replaces target_kind (target_kind: prefer a dereferenceable IRI + dct:conformsTo over an enumerated scheme list #6) — mapping targets drop the curated scheme-label column; an optional conforms_to IRI carries the conformance claim, following Linked Art practice.
• ADR-0002 (feat(spec)!: seed CanonicalReference UUIDs from the semantic identity tuple (ADR-0002) #21): CanonicalReference UUIDs seed from the semantic identity tuple (work_key, citation_system_key, locator) — computable offline; normalization_version removed from the data model (adr: purpose of deterministic UUIDs (compiler reproducibility vs. offline minting) #15).
• ADR-0003 (feat(spec): draft lifecycle with retractable pre-promotion identity (ADR-0003) #23): draft lifecycle tier below candidate. The identifier-persistence promise attaches at promotion (expert review), not publication. Drafts may be corrected or retracted without tombstones (adr: review lifecycle and ephemeral draft state (retractable pre-promotion identity) #22). Superseded by ADR-0004.
• ADR-0004 (feat(standard)!: collapse record lifecycle to draft → active (ADR-0004) #62): collapses the lifecycle to draft → active — promotion grants recommendation and identifier permanence in a single expert-review gate, since nothing ever treated candidate differently from active except the recommendation.
• ADR-0005 (feat(standard)!: preferred citation system and qualified /cite/ aliases (ADR-0005) #63): every Work names a preferred citation system, which mints the bare /cite/{work}/{locator} alias; fallback systems get qualified /cite/{work}/{system}/{locator} aliases. Closes adr: Introduce a preferred Citation system #60.
• ADR-0006 (docs(decisions): decide mapping relation vocabulary (ADR-0006) #67): replaces the SKOS mapping relations with prov:alternateOf (another entity denoting the same work) and dcterms:isReferencedBy (a document about the work), chosen by what the target is rather than by confidence. closeMatch is removed outright. Closes standard: owl:sameAs instead of skos:exactMatch #58 and standard: replace skos:closeMatch to link to URL pages #59.

ADR-0005 and ADR-0006 both re-mint IRIs. Landing them before the first tag costs nothing — every record is draft under ADR-0004 and no identifier has ever been published. After the tag the same change would cost a documented migration against a baseline people may already cite. That timing argument is why they are in v0.1.0 rather than v0.2.0 (#68 §2).

Registry

The data/ submodule is pinned to textrefs/registry@237e39f, carrying:

• the ADR-0006 reclassification of every mapping (registry#13);
• the resolver review (registry#20): six resolver targets that did not address the cited passage removed, NA28, BHS, SuttaCentral and NINJAL added, and the New Testament and Tanakh completed. Closes registry#16–docs: add ORCID for Luz Christopher Seiberth #19.

Compiler and site

• Locator variable mapping (feat(compile): map locator variables into a provider's own vocabulary (#71) #72, closes feat(compile): map locator variables into a provider's own vocabulary #71) — a resolver can translate a canonical locator value into a provider's own vocabulary (OSIS John → die-bibel.de's USFM JHN) instead of forcing a second citation system into existence.
• Prototype-safe resolver expansion (fix: release hardening before v0.1.0 (#46, #47, #49, #50) #75) — every lookup on the path to a resolver URL is own-property only, so a locator value of toString skips the entry instead of expanding Object.prototype's method into a published URL.
• Draft pages excluded from the sitemap (fix: release hardening before v0.1.0 (#46, #47, #49, #50) #75, closes Draft record pages are listed in the sitemap #47) — the third leg of ADR-0003's noindex rule. The predicate keys on record status, not route prefix, so it narrows as records are promoted. Incidentally cut the production build from 7m47s to 3m47s.
• Non-SPDX licences fail the build (fix: release hardening before v0.1.0 (#46, #47, #49, #50) #75, closes Non-SPDX license values are silently dropped from the published JSON-LD #46) — previously dropped from the published record with only a console warning.
• Retired mapping assertions no longer project onto Work (fix(compile): stop projecting retired mapping assertions onto Work (#45) #86, closes Mapping projection uses a denylist, so draft and deprecated mappings emit unqualified direct edges #45) — the direct alternateOf / isReferencedBy edges excluded only withdrawn and blocked, so a deprecated mapping still emitted a live, unqualified edge, against the standard's own definition of the three states for records that have left active use. The allowlist on draft that Mapping projection uses a denylist, so draft and deprecated mappings emit unqualified direct edges #45 also proposed was declined: TextRefs' guarantees attach to CanonicalReference, and the Work projection is enrichment that never claimed review — the docs now say so rather than implying a promise the standard does not make. No published byte changes today, since every record is draft, so this closes the hole before the first demotion rather than fixing a visible defect.
• Collection endpoints for works and citation systems (feat(api): add works and systems collection endpoints (#83) #87, closes feat: collection endpoints for works and citation systems #83) — every operation in the contract read one record by its own identifier, so a client had to know a key before it could fetch anything. Registry discovery was a build-time privilege: only the /reg/ browser could call loadWorks() and loadSystems(). /reg/works.json and /reg/systems.json now serve one @context and one @graph of records, sorted by key, in every status, and /reg/ advertises both through link rel="alternate". The contract also documents the five /dump/ artifacts the compiler has always written and Pages has always served but the OpenAPI never mentioned. RegistryObject stays unreferenced on purpose: it mirrors the exported Zod union in standard/schema/index.ts, so routing the collections through it would have widened both responses to a union a client must narrow. No registry data changes.
• Resolve a reference by work and locator (feat(api): publish an alias index so clients resolve a locator without UUIDv5 (#84) #88, closes feat: resolve a reference by work and locator without computing its UUID #84) — the only public handle on a reference was its UUIDv5. A client that knew a passage as work, citation system and locator had to re-implement the seed ADR-0002 fixes before it could ask a single question; the compiler already built the answer but published it only as /cite/ meta-refresh HTML. Each work now carries a locator index at /reg/work/{key}/aliases.json, mapping locator to reference UUID grouped by citation system key, so a client resolves a passage in two fetches and parses JSON alone. The complete alias table ships at /dump/aliases.json and is registered in datapackage.json with a byte count and a sha256: hash — the artifact data/README.md and data/.gitignore have both named all along while no code wrote it. Values are bare UUIDs rather than IRIs, which halves the largest file, and the index carries no @context: it is a lookup table, not JSON-LD, and the contract says so. Largest emitted index is tanakh at 1.12 MB (566 KB gzipped), under the agreed 2 MB cap, so it is not paginated — paginating would force a client to fetch every page to find one locator. writeDump() split into pure halves so a JSON resource fits beside the four JSONL ones, and the alias keys are sorted so the body and its hash depend on registry content alone rather than on the order the compiler visited the work files. release.yml gained the matching glob: aliases.json matched neither existing pattern and fail_on_unmatched_files is set, so a tagged release would otherwise have shipped a descriptor listing a resource that was not in the release. All 67,959 references are reachable from their work index, and the four JSONL bodies are byte-identical to before. No registry data changes.
• Minimal static templates for reference pages (feat(site)!: minimal static templates for reference pages #30), draft flagging and noindex (feat(site): draft records flagged + noindexed (ADR-0003 follow-up) #26), CitationSystem pages listing works (fix(site): list works instead of references on CitationSystem pages (#55) #56, closes feat: CitationSystem pages should list works instead of references #55), inline whitespace fixes (fix(site): add explicit whitespace between inline elements #54, closes docs: Missing whitespace around inline elements on registry pages #53).

Documentation

• Consistency audit (docs: resolve the consistency audit before v0.1.0 (#79) #80, resolves 40 of the 41 findings in docs: consistency audit — 41 findings across the standard, get-started, and mirrored root docs #79) — every documentation file checked against the schemas, the compiler, the published context, the OpenAPI contract and the compiled registry output. Four findings would otherwise have frozen wrong statements into a citable baseline: §13's flagship Work example was invalid against Work.safeParse for want of preferred_citation_system_key, the OpenAPI document described the advertised <link rel="alternate"> type as application/json where the HTML emits application/ld+json and omitted Work.creators, and §14 required BCP 47 validation that all three schema layers implemented as minLength: 2. That last one is now a shared LanguageTag (RFC 5646 langtag + privateuse), mirrored as an OpenAPI pattern.

  The audit's media-type finding touched only that prose. The response media types stayed application/json, and feat(api): add works and systems collection endpoints (#83) #87 confirmed that this is the correct declaration rather than an oversight: the site is static, so GitHub Pages derives every Content-Type from the file extension and discards the header the Astro APIRoute sets. On the live site /id/work/plato.republic.json returns application/json; charset=utf-8 and /dump/works.jsonl returns application/octet-stream. Declaring application/ld+json would have described a response no client receives. The contract now states the rule and tells clients to parse by documented shape rather than by response header.

• The published contributing page described the wrong branching model (docs: resolve the consistency audit before v0.1.0 (#79) #80) — it told contributors to branch from and PR against main, and omitted the branching section entirely, while the infrastructure integrates on staging. Fixed in both halves of the mirrored pair, and the release checklist is resynced to the canonical 9 steps.

• Related standards and systems (docs: resolve the consistency audit before v0.1.0 (#79) #80, closes docs: add more systems like IIIF #81) — the related-systems page framed every neighbouring standard as an identifier scheme. It is now grouped by the layer each system addresses, and adds IIIF Presentation API, W3C Web Annotation, BIBFRAME, IFLA LRM, RAMEN, and URN:NBN — the last of which Appendix B already listed and the page did not.

• F36 is deliberately not in this release branch yet — the legal-reservation notice missing from the English association pages ships with the statutes batch, alongside the association's founding record.

Release plumbing

• CITATION.cff carries version and date-released (chore(release): v0.1.0 metadata — CITATION.cff, changelog, checklist fixes #76, closes CITATION.cff carries no version or date-released #51), and the maintainer release checklist that omitted them is fixed.
• CHANGELOG.md regenerated with git-cliff --tag v0.1.0.
• versioning.md no longer claims a Frictionless schema the compiler does not emit; tracked in datapackage.json omits the Frictionless schema field descriptors versioning.md requires #74.
• All dependencies current (chore(deps): refresh all dependencies before v0.1.0 #73) — Astro 7.2.1, Starlight 0.41.7, plus the transitive advisories behind ten dependabot PRs. TypeScript stays on 6.x because astro check rejects 7.x.
• The unused github-profile submodule is gone (fix: release hardening before v0.1.0 (#46, #47, #49, #50) #75, closes github-profile submodule has no consumer #50), so the tag does not freeze a dependency nothing reads.

Spec version vs tag

The tag is v0.1.0; the specification stays at 0.1.0-draft with maturity: working-draft. These are deliberately different things — ADR-0004 and ADR-0006 both declined a spec bump under the working-draft clause, and 0.x releases stay working-draft by the maturity ladder. All registry data is draft and carries no persistence promise until expert review promotes it.

Verification

• data and linkcheck re-run automatically as staging moves; both were green on 0df2b27 and on every tip since.
• github-pages must be dispatched on staging for the final SHA before merge. The ruleset requires a deployment for the SHA being merged, and Pages only auto-runs on push to main — so this is repeated every time staging moves. Latest deployment is 37faf37; staging is now 8bcfdca (feat(api): publish an alias index so clients resolve a locator without UUIDv5 (#84) #88). See #68, correction 2.
• Locally: npm run build:data emits all six dump artifacts matching release.yml's globs — works.jsonl, citation-systems.jsonl, references.jsonl, mappings.jsonl, aliases.json, datapackage.json at version 0.1.0 — and validate-data reports 68,005/68,005 records valid. Every bytes and sha256: in the descriptor was re-checked against the file on disk.
• npm test is 54/54 after feat(api): publish an alias index so clients resolve a locator without UUIDv5 (#84) #88, which added twelve cases for the locator index and seven for the dump resources; earlier updates to this description cite 35, 31, 30 and 25. The record counts are unchanged — none of docs: resolve the consistency audit before v0.1.0 (#79) #80, fix(compile): stop projecting retired mapping assertions onto Work (#45) #86, feat(api): add works and systems collection endpoints (#83) #87 or feat(api): publish an alias index so clients resolve a locator without UUIDv5 (#84) #88 touched registry data, and the data/ pin is still 237e39f. A full npm run verify on the merged tree builds 204,361 pages, two of them the new OpenAPI operation pages, alongside 68,019 JSON endpoints, twelve of them the new locator indexes. Astro's page count covers HTML only, so the earlier 204,359 figure moves by two rather than by fourteen.
• Zenodo webhooks confirmed active on release events for both repositories.

[Copilot]

Pull request overview

Updates the onboarding and contribution/deploy documentation to support a new long-lived staging branch workflow, while also adding an org-level .github repository as a git submodule.

Changes:

• Rewrites the Get Started page copy around the “single passage identity, many editions” narrative.
• Documents a main (production) + staging (batching) branching/publishing model in CONTRIBUTING.md.
• Adds a github-profile submodule pointing at textrefs/.github.

Reviewed changes

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

File	Description
src/content/docs/get-started/index.md	Reframes the Get Started explanation and adjusts link placement.
CONTRIBUTING.md	Adds branching/deploy workflow guidance for main/staging and PR targeting.
.gitmodules	Registers the new github-profile submodule for the org .github repo.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.