chemenu/docs/reference/commands/links-and-citations.md

Links and citations

Declaring the relationships between pages and the citations that tie a claim to its source, with the generated regions that hold both.

Contents

• xref add
• xref remove
• xref link-source
• links show
• cite id
• cite add
• cite sync

xref add

Declare that A B.

Synopsis

• wikitool xref add --a "<A>" --b "<B>" --rel <label> [--dry-run]

Options

  --a <str>    Exact title of the page that asserts the edge  [required]
  --b <str>    Exact title of the page it points at  [required]
  --rel <str>  Label from instructions/link-taxonomy.md, e.g. depends-on
               [required]
  --dry-run    Preview the change instead of writing
  -h, --help   Show this message and exit.

Examples

tools/wikitool xref add --a "Gitea Actions" --b "Act Runner" --rel depends-on
tools/wikitool xref add --a "Gitea Actions" --b "Act Runner" --rel depends-on --dry-run

Behaviour

• Declares one edge, A <label> B: written into A's related: as - <label>: B and rendered into A's generated links region.
• B is not touched and does not point back - its inbound view is rendered from the graph.
• Idempotent; re-running with a different label relabels rather than appending, since one page asserts one thing about another.
• Refuses before writing when A's type does not declare related: - a source page declares entities:/concepts: instead, and the refusal names them and points at xref link-source.
• Refuses before writing when <label> is not authorised by the source collection's outbound: block for the target's collection; the refusal lists the authorised set and points at instructions/link-taxonomy.md.
• --dry-run reports the edge without writing.

Properties

• Changes files: yes
• Idempotent: yes
• Atomic: Yes - a single write to A; B is never touched, and every refusal happens before it
• Counts toward the session call budget: yes
• Can reach the network: no

Exit codes

• 0 - success
• 1 - Page A or B not found
• 1 - A's type declares no related: field
• 1 - <label> is not authorised for this collection pair, or the source collection authorises no labels into the target's collection at all

See also

• wikitool xref remove - removes a reference
• wikitool links show - the edges out of and into a page
• instructions/link-taxonomy.md - the labels and what each asserts

xref remove

Remove a cross-reference: the inverse of xref add.

Synopsis

• wikitool xref remove --a "<A>" --b "<B>" [--dry-run]

Options

  --a <str>   Exact title of page A (must exist)  [required]
  --b <str>   Title to unlink from A; need not still exist as a page  [required]
  --dry-run   Preview changes instead of writing
  -h, --help  Show this message and exit.

Examples

tools/wikitool xref remove --a "Gitea Actions" --b "act_runner"
tools/wikitool xref remove --a "Gitea Actions" --b "Act Runner" --dry-run

Behaviour

• Clears the reference in both directions: the cleanup command for a deleted or hand-renamed page rather than the strict inverse of a one-directional xref add.
• Clears <B> from every page-ref frontmatter field <A>'s type declares (related:, sources:, entities:, concepts:) plus the matching bullets.
• Also sweeps a page-ref field the type does not declare but some other type does, and drops that key once empty.
• --b need not still exist as a page, so this clears a reference left by a hand-deleted or hand-renamed page without hand-editing frontmatter.
• Idempotent: removing an absent link is a no-op. --dry-run reports without writing.

Properties

• Changes files: yes
• Idempotent: yes
• Atomic: No - writes A then B, both idempotent
• Counts toward the session call budget: yes
• Can reach the network: no

Exit codes

• 0 - success
• 1 - Page A not found (B is allowed not to exist)

See also

• wikitool xref add - declares an edge
• wikitool rm - deletes a page and de-links it

xref link-source

Batch-link a source page to every entity/concept it mentions.

Synopsis

• wikitool xref link-source --source "Source - X" --entities A,B,C [--dry-run]

Options

  --source <str>    Exact source page title, e.g. 'Source - Docker Cheatsheet'
                    [required]
  --entities <str>  Comma-separated entity/concept titles the source mentions
                    [required]
  --dry-run         Preview which pages would be linked instead of writing
  -h, --help        Show this message and exit.

Examples

tools/wikitool xref link-source --source "Source - Docker Cheatsheet" --entities Docker,Podman --dry-run
tools/wikitool xref link-source --source "Source - Docker Cheatsheet" --entities Docker,Podman

Behaviour

• Each target gets the source page in its sources:, and the source page records each target in its own entities: or concepts:. No body bullet is written on either side - sources: is the record.
• Which field a target lands in follows its collection (kb/entities/ -> entities:), so a new collection needs no code change.
• A target whose collection matches no reference field the source type declares is linked one way and named in the output.
• A target that does not exist is skipped and named; the others are still linked, and the run then exits 1.
• A target that is itself a source page is refused, named with the cite add command to use instead, and handled like a missing page: nothing is written for it, the others are still linked, and the run exits 1. link-source means "A mentions X" and writes X.sources += A, which for X = another source would claim the citation in the wrong direction; a citation between two sources has a direction only cite add records.
• Idempotent in both directions. --dry-run reports what would be linked.

Properties

• Changes files: yes
• Idempotent: yes
• Atomic: No - one write per entity plus one for the source page, idempotent per page
• Counts toward the session call budget: yes
• Can reach the network: no

Exit codes

• 0 - success
• 1 - Source page not found
• 1 - A page in --entities does not exist, or a target could not be written; the others were linked
• 1 - A page in --entities is itself a source page; the others were linked
• 1 - The source page itself could not be written after its targets were

See also

• wikitool sources trace - who a source is already linked to
• wikitool xref add - one labelled edge between two pages
• wiki-ingest skill - where a source is linked after it is written

links show

Show the edges out of and into a page.

Synopsis

• wikitool links show --page "<Title>" [--json]

Options

  --page <str>  Exact page title  [required]
  --json        Print the edges as JSON
  -h, --help    Show this message and exit.

Examples

tools/wikitool links show --page "Act Runner"
tools/wikitool links show --page "Act Runner" --json

Behaviour

• Shows the declared graph around one page in both directions: the edges it asserts (from its own related:, with labels) and the edges other pages assert about it.
• The inbound half is computed across the corpus on every call, never stored, so it is complete.
• --json prints both halves as JSON.
• Read-only; exempt from the Iteration Budget Gate.

Properties

• Changes files: no
• Idempotent: yes
• Atomic: Read-only
• Counts toward the session call budget: no
• Can reach the network: no

Exit codes

• 0 - success
• 1 - Page not found

See also

• wikitool xref add / wikitool xref remove - change the outbound edges
• wikitool search - finds the exact title

cite id

Print the deterministic footnote id cite add would use for this (title, file) pair.

Synopsis

• wikitool cite id --title "Source - X" [--file <qualifier>]

Options

  --title <str>  Source page title, e.g. 'Source - Docker Cheatsheet'
                 [required]
  --file <str>   Qualifier for a multi-file source, e.g. 'storage-model.md'
  -h, --help     Show this message and exit.

Examples

tools/wikitool cite id --title "Source - Docker Cheatsheet"

Behaviour

• Prints the footnote id cite add would use for this (title, file) pair.
• A preview only: it does not check that the id is free on any given page.
• Never fails; safe to retry freely. Read-only and exempt from the Iteration Budget Gate.

Properties

• Changes files: no
• Idempotent: yes
• Atomic: Read-only
• Counts toward the session call budget: no
• Can reach the network: no

Exit codes

• 0 - success

See also

• wikitool cite add - writes the definition

cite add

Upsert a [^cite-id]: [[Source - X]] definition in a page's footnotes region.

Synopsis

• wikitool cite add --page "<Title>" --source "Source - X" [--file <qualifier>] [--dry-run]

Options

  --page <str>    Exact title of the page to add a citation on  [required]
  --source <str>  Exact title of the source page being cited, e.g. 'Source - X'
                  [required]
  --file <str>    Qualifier for a multi-file source, e.g. 'storage-model.md'
  --dry-run       Preview instead of writing
  -h, --help      Show this message and exit.

Examples

tools/wikitool cite add --page "Docker" --source "Source - Docker Cheatsheet"
tools/wikitool cite add --page "Docker" --source "Source - Docker Cheatsheet" --file part-2

Behaviour

• Upserts a [^cite-id]: [[Source - X]] definition in the page's generated footnotes region, creating the region between <!-- wikitool:footnotes --> markers if absent.
• Reuses the id when the page already cites this exact source/file pair, so a repeat changes nothing.
• Adds Source - X to the page's frontmatter sources: - except on Source - X itself: a source page citing one of its own raw files (--file) gets the definition and leaves sources: untouched, since a page never lists its own title there.
• A source page may cite another source page this way - cite add is the command that records a citation between two sources, in the direction it was made.
• Prints the [^cite-id] marker; pasting it into the prose is a manual, editorial step.
• --dry-run reports without writing.

Properties

• Changes files: yes
• Idempotent: yes
• Atomic: Yes - single file write
• Counts toward the session call budget: yes
• Can reach the network: no

Exit codes

• 0 - success
• 1 - The page is not found
• 1 - The source page is not found - citing it would be a dangling reference

See also

• wikitool cite sync - prunes and re-orders the region
• wikitool cite id - previews an id

cite sync

Reconcile each page's footnotes region against its actual [^id] references.

Synopsis

• wikitool cite sync [--page "<Title>" | --all] [--dry-run]

Options

  --page <str>  Sync just this page
  --all         Sync every page under kb/
  --dry-run     Report what would change instead of writing
  -h, --help    Show this message and exit.

Examples

tools/wikitool cite sync --page "Docker"
tools/wikitool cite sync --all --dry-run

Behaviour

• Prunes definitions nothing references any more, re-renders the region in first-reference order, and reports every [^id] reference left with no definition.
• An undefined-reference report is not a failure: fix the reference, or run cite add, and re-run.
• A page still carrying the pre-4.0.0 undelimited footnote block is converted to a marked region in the same pass.
• Each page's re-render is idempotent; safe to retry freely. --dry-run reports without writing.

Properties

• Changes files: yes
• Idempotent: yes
• Atomic: No - one write per page, each idempotent
• Counts toward the session call budget: yes
• Can reach the network: no

Exit codes

• 0 - success
• 1 - Neither or both of --page/--all given, or the page is not found
• 1 - A page write failed partway

See also

• wikitool cite add - writes a definition