docs: document preferred and additional citation systems - #11
Merged
Conversation
The parent repo's compiler now mints a qualified
`/cite/{work}/{system}/{locator}` alias for every reference and the bare
`/cite/{work}/{locator}` only for the work's preferred system (ADR-0005).
Record what that means for authoring here: the top-level `citation_system:`
is the preferred one, further systems go under `additional_systems:`, and
`reference_status:` on a fallback block defaults to `draft` rather than
inheriting the work's status. Also state that locators may not contain `/`.
No data changes — the compiler derives `preferred_citation_system_key`
from the existing top-level `citation_system:`.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
There was a problem hiding this comment.
🟢 Ready to approve
The change is limited to documentation updates that are consistent with the stated intent (“no data changes”) and introduces no code or schema modifications.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Pull request overview
Updates the registry’s authoring guidance (AGENTS.md) to document the semantics of preferred vs. additional citation systems (per ADR-0005), clarifying how /cite/ aliases and reference_status behave without changing any registry data.
Changes:
- Document that the top-level
citation_systemis the preferred system and is used to mint the short/cite/{work_key}/{locator}alias. - Document how
additional_systemsare represented and how their aliases differ (qualified/cite/{work_key}/{citation_system_key}/{locator}only). - Document
reference_statusblock behavior and the prohibition on/in locators due to alias grammar/validation.
File summaries
| File | Description |
|---|---|
| AGENTS.md | Adds explicit authoring rules for preferred/additional citation systems, reference status inheritance, and locator constraints. |
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 0
- Review effort level: Lite
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
This was referenced Aug 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Authoring-guidance follow-up to textrefs/textrefs.org ADR-0005 (issue textrefs/textrefs.org#60). No data changes — the compiler derives
preferred_citation_system_keyfrom the existing top-levelcitation_system:, so every work file compiles unchanged.What the parent repo now does, and what this records here:
citation_system:is the work's preferred system. It mints the short/cite/{work_key}/{locator}alias and is published aspreferred_citation_system_key. Changing it retargets that alias to a different reference — allowed, since/cite/aliases are presentational, but worth calling out in a PR.additional_systems:, each with its owncitation_system:,resolvers:, and locators. Those references get only the qualified/cite/{work_key}/{citation_system_key}/{locator}alias.reference_status:sets one block's reference status. The top-level block inherits the work's status; anadditional_systemsblock defaults todraftand never inheritsactive, so adding a fallback system never promotes data by accident./— the alias grammar distinguishes the two forms by segment count alone.Depends on textrefs/textrefs.org#63; merge that first so the linked authoring guide describes the same format.
🤖 Generated with Claude Code