feat: docs reference generates a human command reference under docs/reference/ from the command records, one page per group plus exit codes and gates; toc never lands inside another generated region (#188)
Files changed: - CHANGES.md - README.md - VERSION - docs/reference/README.md - docs/reference/commands/README.md - docs/reference/commands/catalog-and-log.md - docs/reference/commands/content-migrations.md - docs/reference/commands/distribution-and-versioning.md - docs/reference/commands/finding-and-checking.md - docs/reference/commands/git.md - docs/reference/commands/guideline-export.md - docs/reference/commands/instance-health.md - docs/reference/commands/links-and-citations.md - docs/reference/commands/pages.md - docs/reference/commands/provenance.md - docs/reference/commands/raw-material-and-uploads.md - docs/reference/commands/telemetry.md - docs/reference/commands/types-instructions-and-docs.md - docs/reference/commands/workshop-runs-and-session-budget.md - docs/reference/exit-codes.md - instructions/dev/doc-pull-through.md - tools/CONTRACT.md - tools/README.md - tools/chemenu/cli.py - tools/chemenu/cli_contract.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/reference_doc.py - tools/chemenu/tests/test_reference_doc.py - tools/chemenu/toc.py Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
This commit is contained in:
torbenandClaude Opus 5.5 committed
1 parent
01c888d3cd
commit
53383e7e9b
29 files changed
+5079
-29
No files matched your search
@@ -0,0 +1,376 @@
|
||||
# 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 -->
|
||||
Reference in new issue
Block a user