chemenu/docs/reference/commands/guideline-export.md

Guideline export

Writing the generated GUIDELINES.md into the repositories the wiki has captured.

export guidelines

Render the guideline pages into one generated GUIDELINES.md, or push it into the captured repositories that opted in (Guideline Push Gate).

Synopsis

• wikitool export guidelines [--field <predicate> ...] [--kind/--subtype/--collection/--tag <v>] - Prints the file to stdout; no network.
• wikitool export guidelines <predicates> --push [--bundle <raw-bundle> ...] [--confirm TOKEN] - Writes it into the captured repositories, behind the gate.

Options

  -f, --field <str>   Frontmatter predicate, repeatable (AND) - the same forms
                      as `search --field`.
  --kind <str>        Shorthand for --field kind=<value>.
  --subtype <str>     Shorthand for --field subtype=<value>.
  --collection <str>  Shorthand for --field collection=<value>.
  --tag <str>         Shorthand for --field tags=<value>.
  --push              Write the file into the captured repositories (Guideline
                      Push Gate).
  --bundle <path>     Only the repository of this captured bundle under raw/;
                      repeatable.
  --confirm <str>     The token from a prior exit 42, once a human has approved
                      it.
  -h, --help          Show this message and exit.

Examples

tools/wikitool export guidelines --tag guideline
tools/wikitool export guidelines --tag guideline --push
tools/wikitool export guidelines --confirm <token> --push --field tags=guideline    # re-run after exit 42, once the user approved every diff

Behaviour

• Selects pages with search's own predicates and no text: --field (repeatable, AND), --kind, --subtype, --collection, --tag. Which filter selects this instance's guidelines is written down in kb/CONVENTIONS.md.
• Renders mechanically: line 1 is <!-- wikitool:export kind=guidelines instance=<origin URL without userinfo, or local> commit=<newest commit touching a selected page> - generated, do not edit by hand -->; then each page sorted by title, as # <title> and its text without frontmatter, the generated links and footnote blocks, citation markers ([^id], legacy ^[[...]]), with [[Title|Text]] as Text and [[Title]] as Title. A leading H1 of the page is replaced by the title heading. Code is never rewritten. LF endings, no timestamp: the same pages give the same bytes.
• Refuses before printing or pushing anything: no predicate, no match, an unknown field, any page under kb/ with unreadable frontmatter, uncommitted changes in kb/ or types/ (untracked files included), or no git checkout.
• --push targets every captured repository - each (repo, ref) from a _capture.json under raw/, --bundle narrowing it. A target is skipped with its reason when its ref rule is a tag pattern, it cannot be reached or has no such branch, its root has no GUIDELINES.md (not opted in), its GUIDELINES.md has no export header (hand-written), or the header names another instance=. A header line alone is the opt-in.
• Guideline Push Gate: --push without a matching --confirm fetches and builds everything, pushes nothing, and exits 42 with each target's status (new, changed, unchanged, skipped), the diff for every target it would write, and the re-run line. The token digests URL, branch, old tip and new blob of every target to write.
• With a matching token, each target gets exactly one commit on the fetched tip changing only GUIDELINES.md, authored as the instance checkout's user.name/user.email, pushed without force; one line per target: unchanged, written <old> -> <new>, skipped (<reason>), rejected (<reason>) or failed (<reason>).
• Nothing to write (every target unchanged or skipped) ends with exit 0 and no gate. A second run after a successful one finds every target unchanged.
• The target repository's own AGENTS.md points at the file (Claude Code: @GUIDELINES.md); that belongs to the repository, not to this command.

Properties

• Changes files: yes
• Idempotent: yes
• Atomic: Per target - one commit pushed without force, or nothing; targets already written stay written when a later one fails
• Counts toward the session call budget: yes
• Can reach the network: yes
• Gates: guideline-push - see exit codes and gates

Exit codes

• 0 - success
• 0 - A target was skipped - tag rule, not reachable, not opted in, hand-written file, another instance's file
• 1 - No predicate, no page matches, a malformed predicate or an unknown field
• 1 - A page under kb/ has unreadable frontmatter, kb/ or types/ has uncommitted changes, or the instance is not a git checkout
• 1 - --push with no user.name or user.email in the instance checkout's git configuration - checked before any target is fetched
• 1 - --bundle names no captured bundle under raw/, or --bundle/--confirm was given without --push
• 1 - A target rejected the push (its branch moved since the fetch) or a git call failed - the other targets were still served
• 42 - Guideline Push Gate: --push without --confirm, or with a token that does not match the current set of targets

See also

• wikitool search - the same predicates, to preview the selection
• wikitool raw capture - how a repository becomes a target
• instructions/gates.md - the gate procedure