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.

Content complete; one mechanical step left. This PR is staging → main,
so it picks up whatever staging holds at merge time. Every bullet below has
landed; none carries a pending marker. Nothing in #68 §0 is outstanding
any more. The association's founding record landed with #124 (819fcb9) and
its announcement with #142.

staging is now ba908c7 (#143), eleven commits past the 56cab1b
this description named before — the founding documents, the announcement,
the published ontology, and seven site, compiler and standard fixes. All are
described below.

The only step left: dispatch github-pages on ba908c7, then approve and
merge. Nothing further is queued for staging; if it moves again, repeat
the dispatch on the new tip first.

What it ships

86,397 references across 23 works and 13 citation systems, all at status: draft — 86,477 records in total, plus 172,838 aliases.

That is up from ~39,200 when this PR was opened, in two steps. The resolver review completed the New Testament (John only → 27 books) and the Tanakh (Genesis only → 39 books), taking it to 67,959 across 12 works, so the baseline covers two complete biblical corpora rather than one book of each. The second-wave works (#96) then added Dante's Divina Commedia (14,233 lines, the canonical count), Hume's Treatise and first Enquiry, and eight Nietzsche works — 23 works and 86,397 references.

references.jsonl is 69 MB (72,591,804 bytes) and the alias table is 17 MB (17,521,319 bytes); the built site is 259,811 pages. Both are far inside GitHub's 2 GB asset limit, but neither is a trivial upload — see Verification.

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.

Their follow-up checklists were refreshed before the tag (#110): twelve boxes were unchecked for work that had shipped, ADR-0006 still read Proposed although it is implemented, and seven deferred items existed only inside decisions/ — each now carries an issue (#103–#109). ADR-0006's last substantive follow-up also landed: specification §10 now states that an isReferencedBy target stays a lookup alias rather than leaving it to a code comment. All eight remaining unchecked boxes carry a tracker.

The ontology is published (2d71119, #127, closes #108) — ADR-0006's last follow-up action, and the one published claim in the standard that nothing backed. The v1 context has used tr: terms since the bootstrap, and every one of them dereferenced to nothing. All 17 are now defined in src/lib/ontology.ts and served at /ontology/ (HTML) and /ontology.json (JSON-LD). Where an established term already fitted it is reused rather than minted, as #108 asked: key is dcterms:identifier and locator is skos:notation. The published context stays inside JSON-LD 1.0, so every processor can still read it — which is why RDF reification of MappingAssertion is not here: it needs "@version": 1.1 and a term-scoped context, which a 1.0 processor rejects outright, and it needs a decision record of its own (#135). jsonld.expand under both processing modes expands a record identically, and jsonld.toRDF on the built dist/ontology.json types every term in the default graph.

license_url publishes as dcterms:rights, not dcterms:license (c360c02, #137, closes #129) — a normative correction to §9, and the reason it is in this release rather than after it: the tag freezes the specification text, and §9 described a field that no record in the registry uses. license and license_url both expanded to an IRI-typed dcterms:license, so the 50,047 targets carrying both published two IRIs on one predicate with no way for a consumer to rank them. §9 called license_url the licence text for licences outside the SPDX list; in fact every value is a rights statement about the target — provider terms pages (41,193), an imprint (31,167), terms pages (23,213 and 7,954) — so the predicate was wrong on all 104,427 targets that carry the field, not only on the overlap. DCMI recommends referring to a rights statement by URI, dcterms:rights declares no domain to violate, and license keeps dcterms:license, so the two now say different things and no data is dropped. standard/schema/context.test.ts fails whenever any two context terms share a predicate, which is the shape of this bug rather than this instance of it. No ADR: the documented meaning matched no record, so this is a correction and not a choice between defensible options.

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@7d10919, 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;
• alternative_labels seeded on all twelve works then registered, the Perseus editions on the Republic and the Nicomachean Ethics corrected, the Greek OCT resolvers added and the three Wikisource targets dropped (chore(data): bump the registry pointer to 455bb27f #95, registry#21/feat(deps)!: Astro 7 / Starlight 0.41 + all deps to latest (#20) #29/feat(site)!: minimal static templates for reference pages #30/v0.1.0 status: everything is a draft (on purpose) — release staged, review invited #31). This is what makes ADR-0007's EXACT_ALTERNATIVE_LABEL tier live: /find/ resolves NE 1094a1 to the Nicomachean Ethics where before the pin it reached the New Testament, because ne is a literal prefix of new testament;
• the second-wave works (chore(data): bump the registry pointer to 7d109195 #96, registry#38/deps: upgrade to Astro 7.1 #39/discussion: should TextRefs register the association in ROR (and when)? #40): Dante's Divina Commedia, Hume's Treatise and first Enquiry, and eight Nietzsche works, with three new citation systems (dante-cantica-canto-verse, hume-section-paragraph, hume-book-part-section-paragraph). Every extent was harvested from the provider and checked against an external total rather than typed. One conscious exception: the Dante Lab resolver is plaintext HTTP, because dantelab.dartmouth.edu presents a certificate for CN=*.herokuapp.com. Closes registry#34, Build(deps): Bump dompurify from 3.4.7 to 3.4.12 #36 and Build(deps): Bump sharp, @astrojs/starlight, astro, starlight-blog and starlight-llms-txt #37.

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 references were reachable from their work index at the time (67,959; now 86,397), 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 landed as registry#21 and is 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.
• A deprecated record renders as a tombstone (fix: link-check extraction, deprecated tombstones, orphaned component, docs label (#3, #99, #48) #101, landed — closes Decide what a deprecated record page shows: ADR-0004 calls it a tombstone, the templates do not #99) — deprecated is one of the three tombstone statuses in the model, and ADR-0004, specification.md:284, the Status enum comment and RETIRED_STATUSES in the compiler all say so, yet both record templates tested withdrawn and blocked only. A deprecated record therefore rendered with no banner at all, presented exactly like an active one, and dropped its superseded_by link even though the compiler accepts the field on that status and the .json sibling publishes it. A reader following the identifier saw no successor and no notice. The decision behind the fix: the three statuses stay one tombstone category with one presentation, and the user-facing copy carries the difference. They differ in reach, not in kind — a deprecated record is retained and still resolves, while a withdrawn or blocked record is additionally excluded from Work mapping projections — so reusing the withdrawn wording would have stated something false about a record that still resolves, and giving deprecated its own banner class would have split a category the model keeps whole. Latent, not live: no record in the registry is deprecated today, so nothing was mis-rendered, and the cost would have landed the first time a promoted record was corrected. No spec change is needed; the templates were the half that disagreed. The copy still lives in two templates, and Single-source the draft and tombstone banner copy #100 single-sources it after the tag. No registry data changes.
• The orphaned CitationBox.astro is gone (fix: link-check extraction, deprecated tombstones, orphaned component, docs label (#3, #99, #48) #101, landed — closes Delete the orphaned CitationBox.astro #48) — no consumers since feat(site)!: minimal static templates for reference pages #30 inlined Chicago and COinS rendering against src/lib/citation.ts. Identical dist/ output.
• The registry compiles once per build, not twice (4d1c708, perf(site): compile the registry once per build, not twice #139, closes Every build compiles the registry twice #131) — Astro loads astro.config.mjs in a module graph of its own, separate from the one the pages render in, so src/lib/registry.ts was instantiated twice in one process and its module-level memo was never shared. Compiling the real registry costs ~2.6s and materialises 86,397 references, so every build and every dev start paid that twice, in time and in memory. Building the sitemap predicate lazily — what the issue proposed — does not help: two module graphs never share a module variable, whenever the first call happens; laziness moves the second compile rather than removing it. The memo now sits on globalThis under Symbol.for('textrefs.compiledRegistry'), the one scope both graphs agree on. Lifetime is unchanged (the process, exactly as before), so no new staleness. Instrumented builds confirm 2 calls → 1, with 259,812 pages both times. Two module graphs cannot be simulated under node:test, so nothing asserts the cross-graph sharing directly; what is tested is the footgun the change creates — the fixture short-circuit must stay above the cache, and src/lib/registry.test.ts fails when the two lines are swapped, its runtime jumping from 0.3ms to 871ms as the real compile happens.
• Redirects and untranslated fallbacks leave the sitemap (257f17e, fix(site): keep redirects and untranslated fallbacks out of the sitemap #136, closes Draft /cite/ alias pages are indexed and listed in the sitemap #128) — three rules now decide what the sitemap advertises, and only the first is about noindex, so src/lib/noindex.ts becomes src/lib/sitemap.ts. ADR-0003's draft-record rule is unchanged and still derived from record status, so it narrows on its own as records reach active. A /cite/ alias is a redirect to a canonical /id/ URL, and a search engine treats a redirect in a sitemap as an error; aliases are now excluded by route whatever their record's status, which drops 172,794 entries to 0. A /de/ page with no source file is a Starlight fallback that serves an English body under <html lang="de"> with no robots meta, so advertising it offers a crawler mislabelled duplicate content; the set is read from src/content/docs/de/ and grows on its own as pages are translated, taking /de/ entries from 35 to 5 — exactly the Association pages that AGENTS.md says are bilingual. The robots meta tag still goes on a draft alias page, which ADR-0003 requires independently of the sitemap. Seven new tests in src/lib/sitemap.test.ts.
• A whole-query label beats a split match in /find/ (d9239bd, fix(site): let a whole-query label beat a split match in /find/ #138) — interpret ranked the whole query only when the split found nothing, so any split hit permanently hid a better whole-query match. Nietzsche's registered labels include MA, MA I, MA II/1 and MA II/2; splitting MA II/1 leaves MA, the label of a different work, so the query landed on that work and reported II/1 as an invalid passage. The whole query is now ranked whenever a locator was split off, and wins at an equal or better tier: a match that explains the entire input beats one that had to discard a token. A spelling guess still never displaces a real hit — a fuzzy whole-query match is offered only when the split found nothing at all, which is the previous behaviour exactly. A sweep over the real registry takes every label of every work to its own work, 114/116 → 116/116, and the "label + locator" sweep stays 93/93, so no query that already worked was disturbed.
• The resolver-target licence and rights render correctly (ba908c7, fix(site): render the resolver-target licence and rights correctly #143, closes Resolver-target licence tag shows a full URL instead of an SPDX identifier #133 and Reference pages never render license_url, hiding rights for 54,380 targets #144) — two defects in one block of the reference-page template, both of which the tag would otherwise freeze into the first citable baseline. The licence chip showed a URL: specification §9 requires a published license to be the canonical SPDX IRI so dcterms:license has a single IRI-typed range, and the chip — written when license held a bare identifier — put that IRI in a tag the width of a word. It now reads CC-BY-SA-3.0 and links to the SPDX page. SPDX_LICENSE_BASE is exported from scripts/compile.ts, because the compiler mints the IRI and spdxLicenseLabel reverses it, so the two cannot drift; a value without the canonical prefix is returned unchanged, which the compiler cannot emit but a template must not turn into an empty chip. The rights statement was never rendered at all: fix(standard): publish license_url as dcterms:rights, not dcterms:license #137 split license (dcterms:license) from license_url (dcterms:rights) and the page kept only the first half. Of 172,376 resolver targets, 27,803 carry an SPDX licence alone, 50,047 carry both, and 54,380 carry a rights statement and no licence — two providers, die-bibel.de/impressum (31,167) and sefaria.org/terms (23,213), both with access: open. So the NA28 and BHS rows showed one open chip and nothing else, which a reader can fairly take as "freely usable" when the registry recorded the opposite. license_url now renders as a Rights chip beside the licence chip rather than instead of it, since suppressing one would re-flatten the distinction fix(standard): publish license_url as dcterms:rights, not dcterms:license #137 had just established in the data model. The label is Rights because it is the one word true of all six license_url values in the registry without inspecting any of them and it matches the predicate — an Impressum is not "terms", and a hostname would repeat the provider link in the same row; rel="license" stays on the SPDX link alone. Each chip carries an aria-label naming its provider, because a page holds several targets and a screen reader would otherwise announce several identical Rights links. The fixture registry gained one licensed target and one rights-only target: it had neither, so no fixture-backed build rendered either chip and npm run verify:fast could not have caught either bug. The published JSON-LD is unchanged — verified against the built dump. The registry-side half is license_url on SuttaCentral and NINJAL targets is a CC deed, not a provider rights statement registry#42, deferred past the tag.
• 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).

API audit follow-ups (#111)

An audit of the live site against the ReSed API-design criteria found ten items (#111). Five
landed on staging on 2026-08-31, in three PRs. Two were published claims the site did not
meet, which is why they are in this release rather than after it: a tagged baseline should not
name a URL that returns 404.

• The OpenAPI contract is published (5914e26, fix(api): publish the contract and correct the 404 declaration (#113, #112) #117, closes fix(api): publish the OpenAPI contract at /api/openapi.yaml #112) — the site
  description advertised /api/openapi.yaml, and only the rendered HTML at /api/ existed.
  starlight-openapi reads the file at build time and copies nothing. A static endpoint now
  serves it, with ?raw inlining the source at build time rather than duplicating it in
  public/, so cmp proves the built body byte-identical to api/openapi.yaml. A client can
  generate code and run contract tests against the same file the docs render.
• The declared 404 matches the served 404 (5914e26, fix(api): publish the contract and correct the 404 declaration (#113, #112) #117, closes fix(api): declare the 404 response as text/html, not JSON #113) — every
  record path declared 404 as application/json against the Error schema, and a static host
  cannot build a per-path body. One edit to the shared NotFound response covers all 12 paths.
  Error stays, marked reserved for the dynamic resolver the contract already announces, and
  RegistryObject gained the same kind of comment, so no schema is unreachable without a stated
  reason.
• The generated JSON Schema is published (0607ec6, feat(standard): publish the generated JSON Schema at /schemas/v1/ (#115) #118, closes feat(standard): publish the generated JSON Schema at /schemas/v1/ #115) —
  specification.md §14 stated that a normative JSON Schema is published at
  /schemas/v1/textrefs.schema.json while ROADMAP.md called the same path planned. The
  document is now generated from the canonical Zod schemas with z.toJSONSchema() on every
  build; the specification text is unchanged, and the roadmap item moved to done in both halves
  of the mirrored pair. Three corrections to the raw Zod output are documented in the generator:
  additionalProperties: false is dropped, because a served body carries a JSON-LD @context
  and §15 allows extensions; format: "iri" replaces "uri", because RFC 3986 rejects the
  non-ASCII resolver targets that 1219 references carry; and the §6 alternative_labels rules
  travel into the document as uniqueItems, with the half that compares two members stated in
  the field description. All 86477 records of the current pin validate against it.
• /dump/ has an index (cf3a416, feat(site): add the /dump/ index and robots.txt (#116, #114) #119, closes feat(site): add a /dump/ index page #116) — datapackage.json is the
  entry point for bulk access and a reader could not guess it. The page listed all six artifacts
  with the size and sha256 hash of each. astro build runs before scripts/compile.ts, so the
  page cannot read the descriptor from dist/; it called the same pure functions the compiler
  calls, over the same registry, so the table and datapackage.json could not drift. fix: address PR #4 review findings before v0.1.0 (#120) #121
  narrowed this: computing the figures cost ~90 MB of serialization and hashing per build, to
  render numbers the descriptor already publishes as machine-readable data. The page now lists the
  files and links to the descriptor for the sizes and the hashes. See the review section below.
• robots.txt exists and names the bulk route (cf3a416, feat(site): add the /dump/ index and robots.txt (#116, #114) #119, closes feat(site): add robots.txt and state the bulk-access route #114) —
  the site gave crawlers no guidance. It names the sitemap and tells a bulk consumer to read
  /dump/ instead of crawling thousands of record pages, and the Bulk tag in the contract now
  states the GitHub Pages soft limits. Nothing is disallowed: draft record pages already carry
  noindex and stay out of the sitemap. It is an endpoint rather than public/robots.txt, so
  the Sitemap: line follows SITE_DOMAIN and a preview deployment cannot advertise the
  production sitemap.

Four routes are added: /api/openapi.yaml, /dump/, /robots.txt, and
/schemas/v1/textrefs.schema.json. No registry data changes, and no record IRI moves.

The five findings that stay open are tracked in #111: G2 (/cite/ and /find/ absent from the
contract), G6 (no stated HTTP versioning policy), G7 (the no-query-parameter choice is unstated),
G9 (the German hreflang alternate on record pages 404s), and G10 (the production 404 page
carries a draft banner). None is a false published claim, and each needs a decision before code.

Two checks belong after the deploy, because a static host decides them: curl -sI https://textrefs.org/api/openapi.yaml must return 200 with text/yaml — the value the contract
records, confirmed against two live GitHub Pages deployments rather than assumed — and
curl -sI https://textrefs.org/id/work/does-not-exist.json must return 404 with text/html.

Review follow-ups (#120, #121)

A review of this PR found six defects across the finder, the contract, the docs, the build and the
minimal pages. #121 fixed them and landed on staging as
56cab1b, which closes #120. Every finding was reproduced
before it was fixed.

• /find/ matched a fragment of a name — tier 6 compared the query against one joined string,
  so includes accepted any fragment of any name: ant sits inside Dante, and interpret
  carried that fragment through to locator resolution. The haystack is now a set of normalized
  tokens, and membership is exact.
• /find/ resolved a typo straight to a passage — interpret treated every tier alike, so a
  single fuzzy hit returned resolvable. The page tells the reader "Nothing is guessed", so that
  claim was false. A fuzzy leading tier now returns work-matches, which already meant "never
  resolved further", and the page renders it as "Did you mean …?". Republik still finds the
  Republic; it asks first.
• The contract rejected data the site publishes — Iri declared format: uri, and RFC 3986
  forbids the non-ASCII characters that registered resolver targets carry. iri is a defined
  format in the JSON Schema 2020-12 vocabulary that OpenAPI 3.1 uses, and
  standard/schema/json-schema.ts already applied this exact correction to the generated schema;
  the OpenAPI document was the last place still saying uri. New api/openapi.test.ts validates
  real non-ASCII targets against the parsed contract, because nothing else in the build checked
  data against it.
• Permanence was promised for draft records — every record in this release is draft, which
  carries no persistence promise under ADR-0004, and the get-started pages promised permanence
  anyway. finding-references.md, how-it-works.md, url-layout.md, get-started/index.md and
  the /reg/ front page now reserve "permanent" for an active record. The normative pages
  already did.
• /dump/ recomputed the whole dump on every build — see the corrected bullet above. The new
  DUMP_MANIFEST carries the file list with no body, and a test locks it to what dumpResources
  produces, so the page and the descriptor still cannot disagree about which files exist. The
  verify snippet on the same page printed no hash: grep -A2 stops five lines short of the field
  in the descriptor order. It uses jq now.
• The minimal record pages ran a second visual system — record.css invented a palette and
  used system-ui, against AGENTS.md. Colours already flowed through custom properties, so only
  the token block changed. The file is served unbundled from public/ and cannot import
  brand.css, so both files now carry a comment naming the other.

Fuzzy matching is kept, but stripped of authority: a near miss offers, and never applies.
#120 asked whether the tier earns its place; cutting it is a small follow-up. The STE rewrite of
the get-started introduction is the one acceptance criterion #121 does not meet; it is a style
question, not a false published claim, so it is deferred to #122 and does not block the tag. #120
is closed.

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.

• The tombstone projection rule is stated correctly (990fc4f, docs(standard): state the tombstone projection rule correctly #140) — specification §11 and two code comments said a deprecated record is retained and still resolves "while a withdrawn or blocked record is additionally excluded from Work mapping projections". The compiler excludes all three: RETIRED_STATUSES is {deprecated, withdrawn, blocked} and the projection loop skips every one. §6 already said this correctly, so the specification contradicted itself, and both comments cited the constant that disagreed with them. The two halves of the sentence were attached to the wrong statuses: the projection rule covers all three, and the additional rule for withdrawn and blocked is the dependency rule — a live record may not depend on them (TOMBSTONE_STATUSES). §11 now says that, in all three places. Prose only: scripts/compile.test.ts has carried deprecated mappings are excluded from the projection throughout, so the behaviour was correct and covered; the comments now point at that test rather than restating it. The user-visible tombstone banner is unchanged and was never wrong.

• F36 has shipped (819fcb9, docs(association): finalise the founding documents and limit Board members to expense reimbursement (#123) #124) — the :::caution[Non-binding translation] aside is on all four English association pages: statutes.md, mission.md, governance.md and expenses.md. It arrived with the statutes batch, as this description predicted; see the Association section below.

• The repository's agent instructions load at all (41f2d31, chore(agents): track CLAUDE.md and document the GitHub workflow #141, closes feat: close the AGENTS.md and CI hardening gaps #125 A1 and A3) — CLAUDE.md was untracked, and Claude Code reads CLAUDE.md and ignores AGENTS.md, so a fresh clone loaded no agent instructions. It is tracked now, holding the single line @AGENTS.md. AGENTS.md also gained the five GitHub workflow rules that governed this release but lived only in CONTRIBUTING.md and in habit — sign every commit, branch from staging for content, branch from main for infrastructure, open every PR from the maehr fork, squash-merge only — plus the warning that the Update-branch button and --allow-update-branch both produce an unsigned commit, which the main ruleset's required_signatures then rejects. npm run check:links is documented; package.json had defined it and no instruction file named it. Two Markdown files outside the site build; no source file, workflow or repository setting changes.

Association

The last content item in #68 §0, and the reason this PR waited: a first citable baseline should
freeze the association as a record, not as a description. Both halves are now on staging.

• The founding documents are final (819fcb9, docs(association): finalise the founding documents and limit Board members to expense reimbursement (#123) #124, closes docs(association): align Art. 15 with tax authority feedback #123) — the association was founded on 2 September 2026. Statutes Art. 22 carries the adoption date and the place-and-date line, and names both signatories: Moritz Mähr as president, Luz Christopher Seiberth as recording officer. ZGB Art. 60 requires the statutes in written form, and the cantonal tax office asked for the signed statutes and the signed founding minutes. The Arbeitsentwurf aside is gone from the four German documents, because they are no longer working versions under legal reservation, and "in Gründung befindlich" / "in formation" is gone from the association index, the mission and README.md.
• Art. 15 limits Board members to expense reimbursement (docs(association): finalise the founding documents and limit Board members to expense reimbursement (#123) #124, closes docs(association): align Art. 15 with tax authority feedback #123) — the Cantonal Tax Office of Zürich objected that Art. 15 was broader than the governance model presented in the tax-exemption application: as written it left room to pay board members for special or operational services. Board members now serve in an honorary capacity and may claim only their effective expenses and cash outlays. Art. 20 requires that a regulation not contradict the statutes, so the expense regulation and the governance regulation moved with it — in both languages.
• Tax exemption is assured, not yet decided (docs(association): finalise the founding documents and limit Board members to expense reimbursement (#123) #124) — on 27 August 2026 the Cantonal Tax Office of Zürich assured the association of tax exemption on grounds of public benefit, on condition that it was founded as presented. It was, and the signed statutes and founding minutes were submitted on the founding day. An assurance is not a rechtskräftige Verfügung, so both association index pages state that donations become tax-deductible only after the legally binding decision. Nothing published here claims more than that.
• The announcement (bdd1d60, docs(blog): announce the founding of the association #142) — a blog post at /blog/2026/09/association-founded/, in the same terms. English only: AGENTS.md limits the German mirror to legally relevant Association pages, and the binding German documents are already published. blog/2026/06/hello-world.md still says "an association in formation" and stays unchanged, because it is a dated post and a historical record.

The German texts are legally binding; the English versions are convenience translations and now
say so on every page (F36, above).

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.
• The link check reports real errors (fix: link-check extraction, deprecated tombstones, orphaned component, docs label (#3, #99, #48) #101, landed — closes Link Checker Report #3) — the Link Checker Report listed 17, and twelve were an extraction bug rather than a broken link. The workflow stripped one unbalanced ) and then stripped trailing punctuation, in that order, so a URL ending a markdown link inside a sentence or a bold run kept its ) and lychee checked a truncated address — …/Republic_(Plato, …/4.0/), …/arks.org/)**. The trim now runs as a loop until the string stops changing, percent-encoded resolver templates (%7B/%7D) are dropped alongside the literal {} ones, and iso.org and loc.gov join the excludes because both answer a bot with 403. 17 errors → 3. The three that remain are blob/main links to ADR-0001, ADR-0002 and ADR-0006, which main does not carry yet — merging this PR resolves them, since it brings all seven ADRs to main. Re-run the Links workflow after the tag to confirm zero.

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. Dispatched on staging at 56cab1b (fix: address PR #4 review findings before v0.1.0 (#120) #121) on 2026-08-31, which is now eleven commits stale. staging is at ba908c7 and nothing further is queued, so dispatching on that SHA is the last action before approval — and it must name the SHA that is actually merged. See #68, correction 2.
• The full npm run verify is green on the tree merged as ba908c7 (2026-09-03, real registry): 0 astro check errors, 137/137 tests, 259,813 pages, all internal links valid, and the compiler reports 13 system(s), 23 work(s), 86397 reference(s), 44 mapping(s); 172838 alias(es); 86477 records in dump. That branch was cut from 41f2d31 and does not carry docs(blog): announce the founding of the association #142, which adds the announcement post, so the tip figure is one or two pages higher. Re-run the full gate on ba908c7 itself before the tag if an exact page count matters for the release notes. Earlier: on the branch merged as cf3a416 (2026-08-31), the full npm run build reports 259,812 pages in 1m 43s and the same compiler line as below. That tree carries three of the four new routes; /schemas/v1/textrefs.schema.json came afterwards with feat(standard): publish the generated JSON Schema at /schemas/v1/ (#115) #118, and no full build has run on staging at 0607ec6 yet — npm run verify:fast is green there. The figures in the rest of this bullet are the earlier run on a5764fb (2026-08-27), before any of the four routes: the full npm run verify is green — 0 errors, 0 warnings from astro check, 99/99 tests, 259,811 pages built in 3m 2s, and the compiler reports 13 system(s), 23 work(s), 86397 reference(s), 44 mapping(s); 172838 alias(es); 86477 records in dump. All six dump artifacts emit and match release.yml's globs — works.jsonl, citation-systems.jsonl, references.jsonl, mappings.jsonl, aliases.json, datapackage.json at version 0.1.0.
• release.yml has still never run, and the payload has grown. references.jsonl is now 69 MB rather than the 54 MB this description carried before chore(data): bump the registry pointer to 455bb27f #95 and chore(data): bump the registry pointer to 7d109195 #96, and the built site is 259,811 pages rather than 204,361. Do the workflow_dispatch dry run the workflow already supports before tagging, and check the timeout headroom against the current build, not the old one. A failure here happens after the tag is already public.
• npm test is 137/137 on staging at ba908c7, measured locally on 2026-09-03 against the real registry. The nineteen cases added since 56cab1b cover the ontology (feat(standard): publish the TextRefs ontology #127), the shared-predicate guard in standard/schema/context.test.ts (fix(standard): publish license_url as dcterms:rights, not dcterms:license #137), the sitemap's three rules (fix(site): keep redirects and untranslated fallbacks out of the sitemap #136), the /find/ whole-query regression and its over-correction guard (fix(site): let a whole-query label beat a split match in /find/ #138), the fixture short-circuit above the registry cache (perf(site): compile the registry once per build, not twice #139), and spdxLicenseLabel (fix(site): render the resolver-target licence and rights correctly #143) — the canonical IRI, a value without the prefix, the bare prefix, and a look-alike prefix on another host. The announcement (docs(blog): announce the founding of the association #142) adds no test, and the Rights chip carries no logic to unit-test; the fixture covers it in every build. Historically, npm test was 118/118 at 56cab1b: fix: address PR #4 review findings before v0.1.0 (#120) #121 added nine cases — the token haystack, the fuzzy tier that asks rather than resolves, the non-ASCII IRI against the parsed OpenAPI contract, and the DUMP_MANIFEST lock. It was 109/109 at 0607ec6, where feat(standard): publish the generated JSON Schema at /schemas/v1/ (#115) #118 added ten cases for the published JSON Schema — the dialect and $id the specification names, the union, the output-mode resolver_targets rule, one record of each type, a served body with its @context, a non-ASCII IRI target, the uniqueItems rule, the documented gap that no keyword expresses, and an unknown type. It was 99/99 after feat(find): resolve a familiar citation to a canonical reference (#90) #93 (unchanged by fix: link-check extraction, deprecated tombstones, orphaned component, docs label (#3, #99, #48) #101, which touches templates, a workflow and a config, none of them under test), 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. 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; the counts moved afterwards, when chore(data): bump the registry pointer to 455bb27f #95 and chore(data): bump the registry pointer to 7d109195 #96 advanced the data/ pin to 7d10919. feat(find): resolve a familiar citation to a canonical reference (#90) #93 added the /find/ and /get-started/finding-references/ routes, plus the German fallback page Starlight emits for the latter.
• 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.

[maehr]

@julsraemy @flicksolutions @stephenhart8 — this is ready for your review.

What we are asking for

Please review the decisions and the specification, not the code. The implementation has had its own pass: CI is green on every commit, a review round in #120 found six defects that #121 fixed, and the code sections in the description above are there as evidence, not as a reading list.

What we cannot check ourselves is whether the model is right. Concretely:

• The seven ADRs in decisions/. ADR-0004 collapses the lifecycle to draft → active. ADR-0005 gives every work one preferred citation system, which decides what a bare /cite/ alias means. ADR-0006 replaces the SKOS mapping relations with prov:alternateOf and dcterms:isReferencedBy, chosen by what the target is rather than by confidence. ADR-0007 adds alternative_labels. ADR-0001 came out of Julien's pre-release review and is the one already shaped by outside input.
• standard/specification.md — in particular §6 (Work), §9 (resolver targets, license and license_url), §11 (tombstones), the §13 worked example, and §14 (validation).
• The published vocabulary — /ontology/ and public/contexts/v1.jsonld. All 17 tr: terms are defined for the first time, and terms that had an established equivalent were remapped to it: key is dcterms:identifier, locator is skos:notation.
• api/openapi.yaml — whether the contract is one a client would actually want to call.

Reading the rendered site is a fair substitute for reading the diff: /standard/, /api/, /find/ and any record page under /reg/.

Why the timing matters

v0.1.0 is the first tag, so nothing here is a migration yet. Every record is status: draft and carries no persistence promise, and no identifier has ever been published. A model change costs nothing today and costs a documented migration after the tag — that argument is why ADR-0005 and ADR-0006 are in this release rather than the next one, and it applies equally to anything you find now.

So a "this is wrong" is more useful than a "this is fine", and a question about something that merely reads oddly is worth raising.

State

Content-complete. staging is at ba908c7, all four checks pass, and the full gate against the real registry reports 0 type errors, 137/137 tests, 259,813 pages and every internal link valid. What remains is a Pages dispatch and one maintainer approval.

The release ships 86,397 references across 23 works and 13 citation systems. The full detail is in the description above; the community-facing summary is discussion #31.

No deadline is being imposed here. Say if you want more time, and the tag waits.