Summary
Adopt inline hyperlinks on claim text (rather than footnote-style Citations sections) as the default citation convention in OKF concept bodies. This couples each claim directly to its supporting evidence, eliminating the mental mapping step between a claim in the body and a citation at the bottom.
Motivation
OKF's current Citations section is a separate block at the bottom of a concept file. This works for academic citation conventions where a numbered reference list is expected, but it breaks the coupling between a claim and its evidence. A reader (human or agent) encountering a claim must scroll to the bottom, find the citation, and mentally map it back to the claim. For agent consumers, this means an extra parse-and-join step to reconstruct the claim-to-source mapping.
Proposal
Recommend inline citation as the primary convention. Inline citations SHOULD be placed on the claim text itself: [the specific claim](url) rather than claim text ([source](url)). The link reads as part of the sentence and the evidence is adjacent to the assertion.
The existing Citations section remains available for:
- Grouped references that support multiple claims
- Sources that are cited indirectly (e.g., see also)
- Bibliographic metadata too long for inline placement
Relationship to Spec
This does not require a spec change. It is a best-practice convention for body content. Permissive consumers read the body regardless of citation style. Informed consumers can extract citation graphs by parsing inline links instead of cross-referencing a separate section.
Complementary Mechanism
Inline citations handle claim-level evidence. The proposed SOURCES body section (issue #92) handles file-level provenance between concepts. Together they form a complete evidence chain: every sentence-level claim traces to a URL, and every file-level claim traces to supporting files one layer deeper.
Filed by Jasper (AI agent on behalf of Magnus Hedemark)
Summary
Adopt inline hyperlinks on claim text (rather than footnote-style Citations sections) as the default citation convention in OKF concept bodies. This couples each claim directly to its supporting evidence, eliminating the mental mapping step between a claim in the body and a citation at the bottom.
Motivation
OKF's current Citations section is a separate block at the bottom of a concept file. This works for academic citation conventions where a numbered reference list is expected, but it breaks the coupling between a claim and its evidence. A reader (human or agent) encountering a claim must scroll to the bottom, find the citation, and mentally map it back to the claim. For agent consumers, this means an extra parse-and-join step to reconstruct the claim-to-source mapping.
Proposal
Recommend inline citation as the primary convention. Inline citations SHOULD be placed on the claim text itself:
[the specific claim](url)rather thanclaim text ([source](url)). The link reads as part of the sentence and the evidence is adjacent to the assertion.The existing Citations section remains available for:
Relationship to Spec
This does not require a spec change. It is a best-practice convention for body content. Permissive consumers read the body regardless of citation style. Informed consumers can extract citation graphs by parsing inline links instead of cross-referencing a separate section.
Complementary Mechanism
Inline citations handle claim-level evidence. The proposed SOURCES body section (issue #92) handles file-level provenance between concepts. Together they form a complete evidence chain: every sentence-level claim traces to a URL, and every file-level claim traces to supporting files one layer deeper.
Filed by Jasper (AI agent on behalf of Magnus Hedemark)