Publish staging → main: spec fixes #6/#7/#8, CI/deps, governance, get-started rewrite

.github/workflows/links.yml

@@ -28,7 +28,14 @@ jobs:
       - name: Collect external URLs from sources
         run: |
           mkdir -p lychee
-          grep -rhoE 'https?://[^"'\''<>) ]+' data/ src/content/docs/ \
+          # Allow `)` inside URLs (Wikipedia disambiguation titles), then strip
+          # a single trailing `)` only when unbalanced (handles markdown
+          # `[text](url)`). Drop resolver templates containing `{placeholder}`.
+          # Restrict to YAML/MD so lockfiles inside data/ are not scanned.
+          grep -rhoE --include='*.yaml' --include='*.yml' --include='*.md' --include='*.mdx' \
+              'https?://[^]["'\''<>[:space:]]+' data/ src/content/docs/ \
+            | awk '{ n=gsub(/\(/,"&"); m=gsub(/\)/,"&"); if (m>n) sub(/\)$/,""); print }' \
+            | grep -v '[{}]' \
             | sed -E 's/[.,;:]+$//' \
             | sort -u > lychee/urls.txt
           echo "Collected $(wc -l < lychee/urls.txt) unique URLs"

.gitmodules

@@ -2,3 +2,7 @@
 	path = data
 	url = https://github.com/textrefs/registry.git
 	branch = main
+[submodule "github-profile"]
+	path = github-profile
+	url = https://github.com/textrefs/.github.git
+	branch = main

.zenodo.json

@@ -17,7 +17,8 @@
     },
     {
       "name": "Seiberth, Luz Christopher",
-      "affiliation": "TextRefs"
+      "affiliation": "TextRefs",
+      "orcid": "0000-0002-5606-0964"
     }
   ],
   "keywords": [

CITATION.cff

@@ -13,8 +13,8 @@ authors:
   - family-names: Seiberth
     given-names: Luz Christopher
     email: luz@seiberth.de
+    orcid: 'https://orcid.org/0000-0002-5606-0964'
     affiliation: TextRefs
-    # ORCID: TBD
 repository-code: 'https://github.com/textrefs/textrefs.org'
 url: 'https://textrefs.org'
 license:

CONTRIBUTING.md

@@ -26,12 +26,11 @@ A contribution does not create a claim to acceptance, prioritization, publicatio
 
 ## Review tracks
 
-Changes are routed to one of two tracks:
+Changes are routed to one of three tracks:
 
 - **Technical review** — typos, formatting, broken links, minor metadata, `last_checked` updates, uncontested aliases, build / tooling fixes. Needs automated validation and one technical reviewer.
 - **Expert review** — new works, new citation systems, new corpora, contested mappings, changes to deterministic ID inputs, status changes (`active` / `deprecated` / `withdrawn` / `blocked`). Needs technical validation, a documented rationale with sources, and at least one expert reviewer.
-
-The Board reserves decisions on legal or policy-sensitive matters (takedowns, blocking, licence policy).
+- **Board reservation** — takedowns, blocking, licence policy, and other legal or policy-sensitive matters. Decided by the Association Board.
 
 ```mermaid
 flowchart TD
@@ -91,13 +90,25 @@ The commit-msg hook (commitlint) rejects non-conforming messages, so a plain `gi
 
 The changelog is generated from this history via `npm run changelog` (git-cliff).
 
+## Branching model
+
+The production site (`textrefs.org`) is built and deployed from `main`. To keep `main`'s history low-noise while still allowing many small content edits, day-to-day docs/blog/copy work batches on a long-lived `staging` branch and is squash-merged into `main` to publish.
+
+- `main` — production source. Pushes here auto-deploy via `.github/workflows/pages.yml`. Release tags (`vX.Y.Z`, `vYYYY.MM.N`) are cut from `main`.
+- `staging` — long-lived batching branch for docs, blog posts, copy, registry-pointer bumps, and other content edits. Does **not** auto-deploy. Edits accumulate here as many small commits.
+- To publish: open a PR `staging → main` and squash-merge. The squash-commit lands on `main` as one conventional commit (so `git-cliff` stays clean) and triggers the production deploy.
+- Manual preview / ad-hoc deploy: from the GitHub Actions UI, run the **Pages** workflow via `workflow_dispatch` and pick `staging` (or any branch) as the ref. This deploys that ref to production until the next push to `main`. There is no separate preview URL — GitHub Pages serves a single site per repo, so manual staging deploys temporarily replace production. Use sparingly.
+- Infrastructure changes (CI, release workflow, build tooling, deploy config) target `main` directly so they are not gated on the next staging-to-main snapshot.
+
+Squash merging is the only enabled merge style on the canonical repo, so `staging`'s noisy history is collapsed into a single conventional-commit message on `main` and `git-cliff` still produces a clean `CHANGELOG.md`.
+
 ## Submitting a pull request
 
-1. Branch from `main`.
+1. Branch from `staging` for content/docs/blog; branch from `main` for infra, CI, or release-workflow changes.
 2. Keep PRs focused — one logical change per PR.
 3. Link related issues in the PR description.
 4. Include local verification results: `npm run verify:fast` for routine work, or `npm run verify` plus `npm run validate:data` for registry-data, standard, release, production-build, or CI changes.
-5. Open the PR against `main`. GitHub requests `@textrefs/maintainers` by default via `.github/CODEOWNERS`; maintainers may add technical or expert reviewers based on the track.
+5. Open the PR against the branch you started from (`staging` or `main`). GitHub requests `@textrefs/maintainers` by default via `.github/CODEOWNERS`; maintainers may add technical or expert reviewers based on the track.
 
 ## Project layout
 
@@ -112,7 +123,7 @@ Two release trains. The Zenodo–GitHub webhook MUST be enabled once per reposit
 1. Bump `version` in `package.json` to match the new tag.
 2. `npm run changelog` to regenerate `CHANGELOG.md`.
 3. Update spec page frontmatter `maturity:` if the release transitions the ladder.
-4. Commit, open PR, merge to `main`.
+4. Open a PR `staging → main` and squash-merge it. The squash message should be a conventional commit (`docs(release): vX.Y.Z` or similar) so the changelog stays clean.
 5. Tag `vX.Y.Z[-pre]` on `main`; push the tag.
 6. Verify the GitHub Release fires and Zenodo mints the version DOI.
 7. Fill the concept DOI into `CITATION.cff` `identifiers:` and the badge in `README.md` (once, after the first release).

decisions/ADR-0001-conforms-to-replaces-target-kind.md

@@ -0,0 +1,57 @@
+# ADR-0001: Replace `target_kind` with `dcterms:conformsTo`
+
+- **Status:** Proposed
+- **Date:** 2026-06-09
+- **Deciders:** @maehr
+- **Tags:** spec
+
+## Context and problem statement
+
+`MappingAssertion.target.target_kind` was introduced as an OPTIONAL human-readable scheme hint (`"cts"`, `"wikidata"`, `"doi"`, …). The spec already says validators MUST NOT key behaviour off it and the IRI in `identifier` is authoritative. Issue [#6](https://github.com/textrefs/textrefs.org/issues/6) observes that a field with no normative weight, accompanied by Appendix B's enumerated list of "known" scheme labels, is upkeep without payoff: every new scheme means another table row to police.
+
+Linked Art's [digital integration model](https://linked.art/model/digital/) handles the same problem with `conforms_to` pointing at the relevant specification (e.g. the IIIF profile URI), letting the IRI carry the conformance claim without a curated label registry.
+
+## Decision drivers
+
+- The field is already non-normative; the IRI is authoritative.
+- Appendix B's label column would otherwise grow indefinitely.
+- Pre-v1.0.0 — breaking field renames are still acceptable.
+- Want to align with established Linked Data practice rather than invent a TextRefs-specific convention.
+
+## Considered options
+
+1. **Replace `target_kind` with `conforms_to`** — drop the field, introduce an optional `target.conforms_to` typed as `dcterms:conformsTo` in the JSON-LD context, accepting an IRI or array of IRIs.
+2. **Deprecate `target_kind`, keep accepting it** — add `conforms_to` alongside, mark `target_kind` deprecated. Smoother for downstream consumers; carries the dead field into v1.
+3. **Leave `target_kind` as-is** — no change. Fails to address the upkeep concern that prompted the issue.
+
+## Decision
+
+We choose **Option 1**. The replacement happens before v1.0.0 freezes the schema, so a clean break is preferable to carrying a deprecated field into the stable surface. `target.conforms_to` is OPTIONAL; the registry will not synthesise values where none are known. Multiple IRIs are allowed via array form so a target can claim conformance to several specifications.
+
+In the JSON-LD context, `conforms_to` maps to `dcterms:conformsTo` with `@type: @id` so the value is treated as an IRI reference.
+
+## Consequences
+
+### Positive
+
+- One less curated label registry to maintain.
+- IRIs are self-describing; conformance claims are dereferenceable.
+- Aligns with Linked Art's established pattern.
+
+### Negative / trade-offs
+
+- Breaking rename for any downstream consumer that read `target_kind`. Acceptable pre-v1.0.0.
+- Coordinated change across two repos (`textrefs/textrefs.org` schema/docs, `textrefs/registry` YAML data).
+
+### Follow-up actions
+
+- [x] Update spec §10 and Appendix B.
+- [x] Update the v1 JSON-LD context.
+- [x] Update Zod schema, compile pipeline, and in-tree fixture.
+- [x] Migrate `data/works/*.yaml` in `textrefs/registry` (carried by registry PR #1).
+- [x] Bump `data/` submodule pointer to the migrated registry commit.
+
+## Links
+
+- Related issues / PRs: textrefs/textrefs.org#6, textrefs/textrefs.org#5, textrefs/registry#1
+- External references: [Linked Art — Digital Integration](https://linked.art/model/digital/), [DCMI Terms — conformsTo](http://purl.org/dc/terms/conformsTo)

lychee.toml

@@ -33,6 +33,7 @@ exclude = [
 	"^https?://([a-z0-9-]+\\.)*linkedin\\.com",
 	"^https?://([a-z0-9-]+\\.)*twitter\\.com",
 	"^https?://([a-z0-9-]+\\.)*x\\.com",
+	"^https?://([a-z0-9-]+\\.)*opencollective\\.com",
 	"^https?://localhost(:\\d+)?(/|$)",
 ]