# 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.

<!-- wikitool:toc -->
## Contents

- [`xref add`](#xref-add)
- [`xref remove`](#xref-remove)
- [`xref link-source`](#xref-link-source)
- [`links show`](#links-show)
- [`cite id`](#cite-id)
- [`cite add`](#cite-add)
- [`cite sync`](#cite-sync)
<!-- /wikitool:toc -->

<!-- wikitool:reference-commands -->
## `xref add`

Declare that A <rel> B.

**Synopsis**

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

**Options**

```text
  --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**

```bash
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**

```text
  --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**

```bash
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**

```text
  --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**

```bash
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**

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

**Examples**

```bash
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**

```text
  --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**

```bash
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**

```text
  --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**

```bash
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**

```text
  --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**

```bash
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
<!-- /wikitool:reference-commands -->