torbenandClaude Sonnet 5.5
05c6697d3d
Files changed: - CHANGES.md - VERSION - docs/explanation/architecture.md - docs/reference/commands/catalog-and-log.md - docs/reference/commands/git.md - instructions/publish-cycle.md - instructions/session-setup.md - instructions/wiki-query/SKILL.md - tools/CONTRACT.md - tools/chemenu/commands/git_publish.py - tools/chemenu/commands/log_append.py - tools/chemenu/dist_templates/log.md - tools/chemenu/tests/test_git_publish.py Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
159 lines
4.7 KiB
Markdown
159 lines
4.7 KiB
Markdown
# Catalog and log
|
|
|
|
The generated catalog of the wiki and its append-only operations log.
|
|
|
|
<!-- wikitool:toc -->
|
|
## Contents
|
|
|
|
- [`index rebuild`](#index-rebuild)
|
|
- [`log append`](#log-append)
|
|
- [`log status`](#log-status)
|
|
<!-- /wikitool:toc -->
|
|
|
|
<!-- wikitool:reference-commands -->
|
|
## `index rebuild`
|
|
|
|
Regenerate the catalog from every page's frontmatter.
|
|
|
|
**Synopsis**
|
|
|
|
- `wikitool index rebuild [--dry-run]`
|
|
|
|
**Options**
|
|
|
|
```text
|
|
--dry-run Print what would be written instead of writing it
|
|
-h, --help Show this message and exit.
|
|
```
|
|
|
|
**Examples**
|
|
|
|
```bash
|
|
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|lint|create|update|delete|rename|move|query --title "..." [--body "..."|--body-file path]`
|
|
|
|
**Options**
|
|
|
|
```text
|
|
--op <str> ingest|query|lint|create|update|delete|rename|move (query:
|
|
legacy, no longer written by the stack) [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**
|
|
|
|
```bash
|
|
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.
|
|
- `query` is a legacy value: older versions wrote one entry per read-only query. It is still accepted so existing logs and an instance's own instructions keep working, but the stack no longer writes it - a read is not an operation on the wiki.
|
|
|
|
**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**
|
|
|
|
```text
|
|
-h, --help Show this message and exit.
|
|
```
|
|
|
|
**Examples**
|
|
|
|
```bash
|
|
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
|
|
<!-- /wikitool:reference-commands -->
|