# 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 -->