1 Fork 0

Table of Contents

Types, instructions and docs

Contents
types list
types describe
instructions sync
instructions verify
instructions list
docs verify
docs toc
docs prerequisites
docs contract
docs reference

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Generated from docs/reference/commands/types-instructions-and-docs.md at v10.1.0 – edit the repository, not this wiki.

Types, instructions and docs

The page types, the instruction and skill layer, and the documentation checks and generators that keep the docs in step with the code.

types list
types describe
instructions sync
instructions verify
instructions list
docs verify
docs toc
docs prerequisites
docs contract
docs reference

`types list`

List every type-spec under types/.

Synopsis

wikitool types list [--json]

Options

  --json      Print raw findings as JSON
  -h, --help  Show this message and exit.

Examples

tools/wikitool types list
tools/wikitool types list --json

Behaviour

Lists every type-spec under types/: name, schema path, subtype field, and description - which page types exist, without reading types/*.md directly.
Never fails; read-only and safe to retry freely.

Properties

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

Exit codes

0 - success

See also

wikitool types describe <name> - one type's full contract

`types describe`

Print one type's full contract.

Synopsis

wikitool types describe <name> [--json]

Options

Arguments:
  name  Type name, e.g. 'entity' (see `types list`)  [required]

Options:
  --json      Print raw findings as JSON
  -h, --help  Show this message and exit.

Examples

tools/wikitool types describe source
tools/wikitool types describe project --json

Behaviour

Prints one type's full contract: required and optional frontmatter fields with enums, its subtype field (if any), and its authoring body.
Where the type-spec declares guidance:, the stack-owned types/<name>.guidance.md is composed in, so a root: kb type's contract reads as one answer even though it may live in two files. --json reports it separately as guidance/guidance_path, absent for a type with none.
The generated table-of-contents region a long type-spec (or guidance file) carries is stripped from this output.
Read-only.

Properties

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

Exit codes

0 - success
1 - Unknown type name

See also

wikitool types list - every type
wikitool new <type> - scaffolds a page of the type

`instructions sync`

Publish every instructions/<name>/SKILL.md into the harness skill directories.

Synopsis

wikitool instructions sync [--force]

Options

  --force     Replace a target directory whose contents differ from the source
              and was not generated by sync. Without this, sync refuses instead
              of deleting content it did not create.
  -h, --help  Show this message and exit.

Examples

tools/wikitool instructions sync

Behaviour

Publishes every instructions/<name>/SKILL.md into .agents/skills/ and .claude/skills/ as copies, and deletes published skills whose source is gone.
Each published SKILL.md is its source plus one generated line directly under the frontmatter: the language: of kb/CONVENTIONS.md and a pointer to AGENTS.md § Conversation language, so the agent has the value in context when the task begins. The frontmatter and every other file are copied unchanged. With no language declared, the SKILL.md is copied unchanged too, and the success message says so.
Both targets are gitignored, so a fresh clone runs this once.
Re-running repairs a drifted copy: the source always wins.
--force is required only to replace a target directory that is not a published skill at all (no SKILL.md in it).
Each copy is idempotent, so a re-run converges even after a partial failure.

Properties

Changes files: yes
Idempotent: yes
Atomic: No - one directory copy per skill per target (.agents/skills/, .claude/skills/); each copy is idempotent, so a re-run converges even after a partial failure
Counts toward the session call budget: yes
Can reach the network: no

Exit codes

0 - success
1 - No skills found under instructions/
1 - A target directory is not a published skill (no SKILL.md) and --force was not passed

See also

instructions/bootstrap.md - the fresh-clone procedure that runs this
wikitool instructions verify - checks the copies match

`instructions verify`

Check the instruction layer.

Synopsis

wikitool instructions verify

Options

  -h, --help  Show this message and exit.

Examples

tools/wikitool instructions verify

Behaviour

Flat instructions validate against types/instruction.schema.yaml, and each SKILL.md carries the frontmatter its harness reads.
No SKILL.md carries a relative markdown link: sync copies it to a different depth than the source, so a SKILL.md references a target as a repo-root-relative plain path instead (instructions/CONTRACT.md § "A skill's outbound reference is a plain path, not a link").
Every published copy is what sync would write from its source: byte-identical, except for the generated language line in SKILL.md that the current language: of kb/CONVENTIONS.md calls for. Missing every copy is reported as "run sync", not as drift - that is a clean checkout.
No instruction is left that nothing references; one marked manual: true must instead not be linked from AGENTS.md, CLAUDE.md or a skill.
Nothing under instructions/dev/ is referenced from outside it; a  block is exempt (instructions/CONTRACT.md).
Read-only.

Properties

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

Exit codes

0 - success
1 - Nothing found under instructions/ at all, or a malformed instruction or SKILL.md
1 - A SKILL.md carries a relative markdown link
1 - A published copy drifted from its source - including a language line that belongs to an earlier language: (the message names it as such)
1 - An instruction nothing references, or a manual: true one that IS linked from AGENTS.md, CLAUDE.md or a skill and so risks running implicitly
1 - Something under instructions/dev/ is referenced from outside it and outside a dist:strip block

See also

wikitool instructions sync - publishes the copies
instructions/CONTRACT.md - the rules this checks

`instructions list`

List the flat instructions with their descriptions.

Synopsis

wikitool instructions list [--json]

Options

  --json      Print the listing as JSON
  -h, --help  Show this message and exit.

Examples

tools/wikitool instructions list
tools/wikitool instructions list --json

Behaviour

Lists the flat instructions with their descriptions - how the instruction layer is discovered; search covers kb/ only.
Never fails: an empty instructions/ prints "No instructions found." Read-only and safe to retry freely.

Properties

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

Exit codes

0 - success

See also

wikitool search - the same question for kb/

`docs verify`

Check the docs that mirror the code.

Synopsis

wikitool docs verify

Options

  -h, --help  Show this message and exit.

Examples

tools/wikitool docs verify

Behaviour

Checks the docs that mirror the code. The name is about documentation parity, not the docs/ directory - it reads that only for its layout and its generated reference pages, and never requires one.
Commands: every command has a cli_contract record and is listed in cli_contract.GROUPS, in both directions; every command's non-hidden flags appear in its record's SYNOPSIS and vice versa; tools/CONTRACT.md's generated  region matches what docs contract would write; no command's rendered --help/-h text cites an issue number.
Collections: every directory under kb/ has a COLLECTION.md and no directory outside it does; every collection declares profile: and a required_by_stack: that agrees with the stack's own list.
Types: every type the stack lists (currently source and project) has a type-spec of that name whose schema requires the field the stack list names (raw_files:/state:); every file under types/ declaring type: types/type-spec.md validates against types/type-spec.schema.yaml; every subtype template types/<type>.<value>.md (any <value> but guidance) sits beside a type-spec declaring subtype_field:, names a value that field's schema enum allows, and carries no frontmatter; no pre-migration type: entity blocks are left in the contracts.
kb/CONVENTIONS.md, if it exists at all, names all three tool-owned section headings; every stage contract is present.
The .gitignore canaries clear in both directions: nothing ignored under raw//kb/, incoming/ ignored, everything ignored under reports/ and the published skill directories, .wikitool-local.json ignored and wikitool.json tracked.
A wikitool.json at the root holds every value in the place its tier allows - no secret and no private field as plain text, no checkout field at all except as a reference - and a well-formed schema and instance_id. The local file is not read.
No .md/.template file dist export would ship cites an issue number. A  region is exempt: the check reads the export plan's text, from which it is already gone.
Every reference file docs toc covers carries the current table-of-contents region for its own headings - missing and stale are one check.
Every relative markdown link in one of those reference files resolves to an existing file. A target's #anchor suffix is stripped first, and code fences and inline code spans are masked before scanning, so link syntax shown as an example is not mistaken for a real reference.
Every file under docs/ sits in one of its areas - tutorials/, how-to/, reference/, explanation/ or dev/ - never directly in docs/ or in another directory.
AGENTS.md § Gates names exactly the gates in cli_contract.GATES (the bold entry names, - **<Name>.**), and every gate in that register that ends in exit 42 is declared by at least one command record. A record naming a gate outside the register fails when wikitool starts, not here.
If docs/ exists: every generated region of the human reference under docs/reference/ matches what docs reference would write, every cli_contract.GROUPS entry has its page under docs/reference/commands/, and no page there belongs to no group. That includes the four configuration regions in docs/reference/configuration.md. The skill catalogue and the page types are checked only in the origin repo (no .wikitool-release.json): they describe the stack's shipped defaults, which an instance's own type-specs and instructions may differ from.
INSTALL.md carries one generated  region per platform value of tools/prerequisites.txt (prerequisites-<platform> for a platform-specific one), each current; and the  markers in instructions/setup-instance.md and INSTALL.md name the same set of keys, so a question the agent asks is never one the human guide leaves out, nor the reverse.
VERSION parses and the newest versioned CHANGES.md entry names it. An entry that crosses the compatibility boundary from the last release carries **Breaking Change:**, has a migration document or **Migration:** none required, and its **Migration:** line names every required migration document targeting it.
The newest versioned CHANGES.md entry is at most 32 000 bytes (UTF-8) as version notes prints it, and each of its ### sections is exactly one paragraph of at most 1 000 bytes, heading line excluded. Older entries and a changelog with no versioned entry are not checked.
Read-only.

Properties

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

Exit codes

0 - success
1 - A command, contract, or type-form mismatch
1 - VERSION and the newest CHANGES.md entry disagree, or a boundary-crossing entry lacks its breaking line, its migration, or the migration document's path
1 - The newest CHANGES.md entry is over 32 000 bytes, or one of its ### sections has more than one paragraph or a paragraph over 1 000 bytes
1 - The  region of tools/CONTRACT.md is stale
1 - A type-spec's own frontmatter fails its schema
1 - A subtype template types/<type>.<value>.md has no type-spec with a subtype_field: beside it, names a value outside that field's enum, or carries frontmatter
1 - wikitool.json holds a secret or private value as plain text, or a value its tier puts elsewhere
1 - A shipped .md/.template cites an issue number
1 - A region of the human reference under docs/reference/ is stale
1 - A page of the human reference is missing or lacks its marker pair, or a page under docs/reference/commands/ belongs to no group
1 - A reference file's table-of-contents region is missing or stale
1 - A file sits directly in docs/, or in a directory there that is not one of its five areas
1 - AGENTS.md § Gates and cli_contract.GATES disagree, or a register gate that ends in exit 42 is declared by no command record
1 - A reference file's relative markdown link does not resolve to an existing file
1 - An INSTALL.md prerequisites region is stale
1 - An INSTALL.md prerequisites region is missing, or names a platform no tool has
1 - A setup question is marked in one of instructions/setup-instance.md and INSTALL.md but not the other

See also

wikitool docs toc - regenerates tables of contents
wikitool docs contract - regenerates the commands region
wikitool docs reference - regenerates the human reference
wikitool docs prerequisites - regenerates INSTALL.md's prerequisites lists
wikitool instructions verify - the same kind of check for instructions/

`docs toc`

Create, refresh or remove the generated table-of-contents region.

Synopsis

wikitool docs toc [--apply]

Options

  --apply     Write changes; default is dry-run (preview only)
  -h, --help  Show this message and exit.

Examples

tools/wikitool docs toc
tools/wikitool docs toc --apply

Behaviour

Creates, refreshes or removes the generated table-of-contents region on every reference file over 100 lines: AGENTS.md, every stage contract, kb/CONVENTIONS.md, every kb/*/COLLECTION.md, every flat instructions/**.md file, every types/*.md type-spec, and every docs/ page - each together with the <name>.template it ships as, where one exists.
The scope is computed from those categories rather than listed, so a file added later is in scope without a code change.
Out of scope: every SKILL.md, the human docs at the root and beside the code (README.md, CHANGES.md, INSTALL.md, tools/README.md), and every subtype template types/<type>.<value>.md - new copies it into a page, so it never carries a region whatever its length.
Dry-run by default (prints which files would change); --apply writes. Idempotent: a re-run after an interruption converges rather than doubling a region.
If docs verify still reports a stale region after --apply, the file's ## headings changed in between; run it again.

Properties

Changes files: yes
Idempotent: yes
Atomic: --apply rewrites each named file in place, one at a time and idempotently, so a re-run after an interruption converges rather than doubling a region; the dry-run form is read-only
Counts toward the session call budget: yes
Can reach the network: no

Exit codes

0 - success
0 - Never fails on content: a file with no ## heading, or one at or under the threshold, is simply left without a region

See also

wikitool docs verify - checks every region is current

`docs prerequisites`

Regenerate INSTALL.md's prerequisites lists from tools/prerequisites.txt.

Synopsis

wikitool docs prerequisites [--apply]

Options

  --apply     Write changes; default is dry-run (preview only)
  -h, --help  Show this message and exit.

Examples

tools/wikitool docs prerequisites
tools/wikitool docs prerequisites --apply

Behaviour

Rewrites each  region in INSTALL.md (tools every platform needs) and  region (tools only that platform needs) from the manifest: one list item per tool, its label and minimum version. The manifest's reason field stays out - it explains a tool to whoever reads the preflight's own output, while the region only says what to install.
Never places a region: where a list belongs in the human guide is that guide's own decision. A region the manifest calls for but the file lacks is an error naming the marker pair to add.
Dry-run by default (says whether the file would change); --apply writes.
docs verify checks the result stays current.

Properties

Changes files: yes
Idempotent: yes
Atomic: Yes - every region is rewritten in one file write
Counts toward the session call budget: yes
Can reach the network: no

Exit codes

0 - success
1 - INSTALL.md is missing, or lacks a region the manifest calls for

See also

wikitool docs verify - checks every region is current

`docs contract`

Regenerate tools/CONTRACT.md's  region.

Synopsis

wikitool docs contract [--apply]

Options

  --apply     Write changes; default is dry-run (preview only)
  -h, --help  Show this message and exit.

Examples

tools/wikitool docs contract
tools/wikitool docs contract --apply

Behaviour

Rebuilds the region from every cli_contract record: the index (one line per command, GROUPS order) followed by each ### group's commands as #### <path> man-page-shaped sections.
Dry-run by default (says whether the file would change); --apply writes.
docs verify checks the result stays current.

Properties

Changes files: yes
Idempotent: yes
Atomic: Yes - the whole region is rewritten in one file write
Counts toward the session call budget: yes
Can reach the network: no

Exit codes

0 - success
1 - tools/CONTRACT.md is missing

See also

tools/README.md § Adding a command - how a command gets its record
wikitool docs reference - the same records, rendered for a person under docs/reference/
wikitool docs verify - checks the region is current

`docs reference`

Regenerate the human reference under docs/reference/.

Synopsis

wikitool docs reference [--apply]

Options

  --apply     Write changes; default is dry-run (preview only)
  -h, --help  Show this message and exit.

Examples

tools/wikitool docs reference
tools/wikitool docs reference --apply

Behaviour

Rewrites the generated region of every page of the human command reference from the cli_contract records: one docs/reference/commands/<group>.md per cli_contract.GROUPS entry (), the overview in docs/reference/commands/README.md (), and the gates and exit-42 causes in docs/reference/exit-codes.md ().
Also, in the origin repo only, the skill catalogue docs/reference/skills.md (: one row per shipped instructions/<name>/SKILL.md, its description split at the sentence starting "Use when") and the page types docs/reference/page-types.md (: one section per root: kb type-spec, from what types describe reads). Both describe the stack's shipped defaults. In an instance - a tree with .wikitool-release.json - they are left alone and the output says so: an instance's adopted type-specs and own instructions may differ, and rewriting a shipped page there would block the next dist upgrade.
Also the shapes of the four hand-written configuration files in docs/reference/configuration.md, one region each (, -remotes, -tasks, -upload) inside the hand-written section on that file, rendered from the records in chemenu.config_shapes the loaders read the files with. Those records ship with tools/, so these regions are written and checked in an instance as well. Several regions in one page are refreshed one after the other into the same text.
Renders each command's summary, synopsis, options, examples, notes, properties in words, exit codes with their causes and see-also - but not the ON FAILURE reactions or NEVER, which address an agent; tools/CONTRACT.md keeps those.
Refreshes the table of contents of each page it writes in the same step.
Never creates a page or places a region: a page's title and one-sentence head are written by hand. A group's page is named after the group - lower case, every run of other characters one hyphen.
Dry-run by default (lists the pages that would change); --apply writes.
docs verify checks the result stays current.

Properties

Changes files: yes
Idempotent: yes
Atomic: --apply rewrites each page in place, one at a time and idempotently, so a re-run after an interruption converges; the dry-run form is read-only
Counts toward the session call budget: yes
Can reach the network: no

Exit codes

0 - success
1 - A reference page is missing, or lacks its region's marker pair

See also

wikitool docs contract - the same records, rendered for an agent into tools/CONTRACT.md
wikitool docs verify - checks every reference region is current
tools/README.md § Adding a command - how a command gets its record