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 — seven 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-0007 (feat(standard): name works by abbreviation and translated title (#85) #89): a Work MAY carry alternative_labels, a flat list of the other names a scholar searches by — abbreviations (NE, LXX, PI), Latin or Greek titles, and translated titles — published as skos:altLabel. Identity-neutral: no label is a UUID seed input, so a label change never moves an identifier. Two different works MAY claim the same label (Ethics fits Aristotle and Spinoza), which the compiler allows rather than treating as an error. Closes adr: alternate labels and abbreviations for works #85.

ADR-0007 is purely additive and re-mints nothing: the field is optional, and no label has ever been an identity input. 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.
• Works findable by abbreviation and translated title (feat(standard): name works by abbreviation and translated title (#85) #89, closes adr: alternate labels and abbreviations for works #85) — a Work carried exactly one name, and the registry browser built its filter key from preferred_label and key alone, so a scholar who typed NE, EN or Nikomachische Ethik found nothing. The registry holds Aristotle's Nicomachean Ethics, but only under that one English string, and the same gap hit PI and LXX. The optional alternative_labels list is folded into the existing data-reg-item haystack, so the client filter needed no change, and it renders on the work record page. It flows into works.jsonl, /reg/works.json and /id/work/{key}.json untouched, because all three serialize the whole record rather than a field whitelist. Entries are unique within a work, never repeat the preferred_label, and an empty list is rejected — enforced on the authored YAML and again in the canonical Work schema, since that is the shape the standard publishes and a hand-built record must not be able to violate the normative sentence in §6. Two documents had promised this field under the name alt_labels since before the schema existed; the guide now documents the real one. No registry data changes, and no route is added. The matching data/AGENTS.md fix is open as registry#21 and is not in this pin.
• A scholar can resolve a citation without reading the API docs (feat(find): resolve a familiar citation to a canonical reference (#90) #93, closes feat: resolve a familiar citation to a canonical reference at /find/ #90) — every route into the registry assumed you already knew something the citation does not carry. /reg/ filtered works by substring, and /cite/{work}/{locator} needed the work key and the locator grammar up front; neither separated a text from a passage, so Plato Republic 514a reached nothing. /find/ takes the string a scholar already writes and returns the reference: a permanent link, the editions that carry the passage, and a citation to paste. It is a static page that reads the same public endpoints any other client reads — feat: collection endpoints for works and citation systems #83's collections and feat(api): publish an alias index so clients resolve a locator without UUIDv5 (#84) #88's locator index — so it holds no private search index and no server. Resolution runs in two stages, and not by choice. /reg/works.json names a work's preferred citation system and drops additional_systems, so the collection cannot say which systems a work uses; only its alias index can. interpret() therefore picks the work and splits off the locator from the two small collections, and resolveInIndex() decides system and identity once that work's index is fetched. That gap is filed as feat: name every citation system a work uses in the Work record #91. The split also keeps the large fetch lazy: an index runs from 68 KB to 1.12 MB, and instrumenting window.fetch confirms none is requested until a single work is identified. Nothing is guessed, which is the part that matters for citation: a bare locator lists candidates even when only one work matches today, two works sharing a label stay two hits (ADR-0007), one locator valid under two of a work's systems stays a choice (ADR-0005), and fuzzy matching helps find a work but never reaches identity — the index lookup is exact, so no near miss can mint a reference (ADR-0002). Ranking is a fixed seven-tier ladder where only the leading tier decides, so a weak match cannot turn a good one into an ambiguity. The search logic sits in src/lib/find.ts, pure and free of DOM and network, which is what makes it testable under node:test and keeps Zod and the compiler out of the 10.7 KB browser bundle; src/lib/citation.ts is reused for the citation rather than a second format written, its parameters narrowed to the fields it actually reads. The page is deliberately not a Starlight document — a sidebar, a table of contents and a second search box are noise beside one search field — so it uses RecordPage, which gains an optional jsonHref because the finder has no single JSON-LD sibling to advertise. Review caught two strings that spoke for the whole registry from a preferred-system-only check; both now say "main numbering". ADR-0007's deferred abbreviation question is filed as adr: ranked search over alternative labels, and duplicate-hit disambiguation #92, since ranked search is the trigger it named. 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 8bcfdca; staging is now 8bc25ce (feat(find): resolve a familiar citation to a canonical reference (#90) #93). 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 99/99 after feat(find): resolve a familiar citation to a canonical reference (#90) #93, which added thirty-four cases for the finder — every case the spec named, plus one per ambiguity rule; feat(standard): name works by abbreviation and translated title (#85) #89 before it added eleven for alternative labels and feat(api): publish an alias index so clients resolve a locator without UUIDv5 (#84) #88 nineteen for the locator index and the dump resources, and earlier updates to this description cite 65, 54, 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, feat(api): publish an alias index so clients resolve a locator without UUIDv5 (#84) #88, feat(standard): name works by abbreviation and translated title (#85) #89 or feat(find): resolve a familiar citation to a canonical reference (#90) #93 touched registry data, and the data/ pin is still 237e39f. feat(find): resolve a familiar citation to a canonical reference (#90) #93 is the first of these to add routes: /find/ and /get-started/finding-references/, plus the German fallback page Starlight emits for the latter, so a full npm run verify on the merged tree builds 204,364 pages rather than 204,361 — two of them still the OpenAPI operation pages — alongside the same JSON endpoints as before, twelve of them the locator indexes.
• 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.