torben/chemenu
1
1 Fork 0
Code Issues 40 Pull Requests Actions Packages Releases 41 Wiki Activity
Files
db8f90c229d8fe46da84637c7e1d56be42f54f3d
chemenu/docs/reference/commands/catalog-and-log.md
T
torbenandClaude Opus 5.5 53383e7e9b
CI / verify (push) Successful in 6m11s
Details
CI / pwsh (push) Successful in 2m0s
Details
Release / release (push) Successful in 35s
Details
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
2026-10-06 21:29:01 +02:00

4.4 KiB
Raw Blame History

Catalog and log

The generated catalog of the wiki and its append-only operations log.

Contents

index rebuild

Regenerate the catalog from every page's frontmatter.

Synopsis

  • wikitool index rebuild [--dry-run]

Options

  --dry-run   Print what would be written instead of writing it
  -h, --help  Show this message and exit.

Examples

tools/wikitool index rebuild
tools/wikitool index rebuild --dry-run

Behaviour

  • Rewrites kb/index.md as a map: statistics, one row per collection and per area, and links to the shards - no page rows.
  • Writes the page tables to a generated INDEX.md in each collection. An area with more than 50 rows gets its own INDEX.md in its directory.
  • Deletes stale shards - an INDEX.md of a collection or area that no longer exists - in the same pass.
  • Warns about every page nested more than one directory below its collection; it is still catalogued, folded into its area.
  • --dry-run prints every file it would write and every stale shard it would remove, and writes nothing.

Properties

  • Changes files: yes
  • Idempotent: yes
  • Atomic: No - each catalog file (the map plus one shard per collection/area) is rewritten independently, then stale shards are removed; an interruption can leave some regenerated and others not
  • Counts toward the session call budget: yes
  • Can reach the network: no

Exit codes

  • 0 - success
  • 1 - An I/O error while writing or removing a catalog file (rare)

See also

  • wikitool search - finds a page without reading the catalog
  • wikitool lint - its Nested Pages finding is what the warning previews
  • instructions/publish-cycle.md - where a write session runs this

log append

Append a formatted entry to kb/log.md.

Synopsis

  • wikitool log append --op ingest|query|lint|create|update|delete|rename|move --title "..." [--body "..."|--body-file path]

Options

  --op <str>          ingest|query|lint|create|update|delete|rename|move
                      [required]
  --title <str>       Brief description, e.g. a source path  [required]
  --body <str>        Optional multi-line details
  --body-file <path>  Read the body from a file instead of --body
  -h, --help          Show this message and exit.

Examples

tools/wikitool log append --op ingest --title "raw/articles/docker-cheatsheet.md" --body "Created [[Docker]]; updated [[Container]]."
tools/wikitool log append --op lint --title "2026-09-26" --body-file lint-summary.md

Behaviour

  • Appends one entry to kb/log.md: a ## [YYYY-MM-DD] <op> | <title> heading, the body if one is given, and a --- separator.
  • Not idempotent: every successful run appends a new entry, including a repeated one.

Properties

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

Exit codes

  • 0 - success
  • 1 - --op is not one of ingest, query, lint, create, update, delete, rename, move
  • 1 - --body-file is missing, not a readable file, or not valid UTF-8

See also

  • wikitool log status - counts the ingests logged since the last lint
  • instructions/publish-cycle.md - where a write session runs this

log status

Read-only: count ingest entries logged since the last lint entry.

Synopsis

  • wikitool log status

Options

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

Examples

tools/wikitool log status

Behaviour

  • Counts the ingest entries in kb/log.md after the most recent lint entry, or since the start of the log if it was never linted, and the total number of entries.
  • At 10 or more it prints that the wiki-lint skill is due next - the every-10-sources full lint of the Maintenance Schedule.
  • Read-only; 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
  • 0 - kb/log.md is missing or empty - reported as nothing logged, not a failure

See also

  • wikitool log append - writes the entries this counts
  • wiki-lint skill - what the threshold asks for
  • tools/CONTRACT.md § Maintenance schedule - the cadence this reports on
Reference in new issue View Git Blame Copy Permalink