chemenu/docs/reference/commands/finding-and-checking.md

# Finding and checking

Searching the wiki, checking its health, and preparing the weekly review of projects and commitments.

<!-- wikitool:toc -->
## Contents

- [`lint`](#lint)
- [`search`](#search)
- [`review`](#review)
<!-- /wikitool:toc -->

<!-- wikitool:reference-commands -->
## `lint`

Run structural lint checks against kb/.

**Synopsis**

- `wikitool lint [--json] [--markdown out.md] [--full] [--fail-on-error]`

**Options**

```text
  --json             Print the raw findings as JSON and write no report
  --markdown <path>  Write the markdown report here instead of the default
                     reports/Lint Report <date>.md
  --full             Print the whole report instead of only the sections with
                     findings
  --fail-on-error    Exit non-zero if hard errors were found
  -h, --help         Show this message and exit.
```

**Examples**

```bash
tools/wikitool lint
tools/wikitool lint --json
tools/wikitool lint --fail-on-error
```

**Behaviour**

- Structural and provenance checks over `kb/`: broken wikilinks, wikilinks wrapped across a line break, dangling frontmatter references, orphan pages, index drift, schema gaps, duplicate titles, title mismatches, uncovered raw files, broken `raw_files:` refs, raw files claimed by more than one source page, unmarked provenance, citation/frontmatter drift, and unbalanced generated-region markers.
- Unportable Titles is a hard finding, and hard at every `kb_version`: a page whose title is not a valid file name on Windows and macOS (forbidden character, reserved name, trailing dot or space), or that collides with another page by case or Unicode normalization. `wikitool rename` is the fix.
- Wrapped Wikilinks is a hard finding: a `[[...]]` with a line break inside it. The link graph reads it as the title it folds to (the break and its indentation become one space), so it is not also a broken link unless that title is missing; the fix is to put it back on one line.
- Broken Anchors is advisory: a `[[Page#Section]]` whose page exists but has no heading the anchor names (any level, compared without case, inline-code backticks or extra whitespace; every segment of a nested `[[Page#A#B]]`). The link still reaches the page, so nothing else reports it - typically a section that was promoted to a page of its own or renamed. A missing page is Broken Wikilinks instead.
- Pages nested more than one directory below their collection are a hard finding - the generated catalog folds these into their area silently rather than merely reading it.
- Edges whose label is missing or not authorised by the source collection's `outbound:` are both hard once `kb_version` has reached the release that introduced labelled edges, and advisory below it.
- Advisory only: `see-also` edges whose reverse direction already carries a specific label - never migration-gated.
- Advisory only: a collection past the catalog's per-area shard threshold that has no areas to shard, reported with the split its subtype field would produce, and only when that split puts every resulting area at or under the threshold.
- Advisory only: source pages sitting in the `unclassified` catalog slot.
- Advisory only: Long Paths - a file under `kb/` or `raw/` whose path below the instance root is over 160 UTF-16 code units, the budget that keeps a Windows checkout without long paths working. Reported as `{path, length}`; a corpus over the budget breaks no lint run. `wikitool rename` is the fix for a page.
- Advisory only: quote-limit overages (>2 blockquotes/page).
- Advisory only: Unfilled Template Sections - a page with at least one `##` section whose non-blank lines are all template placeholders (content starting with `TODO`, after an optional list marker, checkbox, table cell or bold field label), reported as `{page, sections}`. Code, generated regions and footnote definitions do not count; an empty section, or one placeholder beside written lines, is no finding. Writing the section from the page's sources or retiring the page is the fix - not a mechanical one.
- Prints only the sections that found something and always writes the full report to `reports/Lint Report <date>.md` (or `--markdown`), naming the path. `--full` prints everything; `--json` prints the findings and writes nothing.
- Exits 0 whatever it finds unless `--fail-on-error` is passed.

**Properties**

- Changes files: yes
- Idempotent: yes
- Atomic: Writes one report file (single atomic write) unless `--json`
- Counts toward the session call budget: yes
- Can reach the network: no

**Exit codes**

- `0` - success
- `1` - Only with `--fail-on-error`: hard findings exist

**See also**

- `wiki-lint` skill - the procedure that runs this
- `wikitool move --reconcile` - fixes Misplaced and Nested Pages
- `wikitool rename` - fixes Unportable Titles and, for a page, Long Paths
- `wikitool log status` - whether a full lint is due

## `search`

Find pages in `kb/` by text and/or frontmatter.

**Synopsis**

- `wikitool search ["<text>"] [--field <predicate> ...] [--kind/--subtype/--collection/--tag <v>] [--regex] [--limit N] [--sort [-]<field>] [--backend <name>] [--matches] [--json]`

**Options**

```text
Arguments:
  text  Text to search for. Omit it to run a pure frontmatter query.

Options:
  -f, --field <str>   Frontmatter predicate, repeatable (AND). Forms:
                      field=value, field~substring, 'field>=value', 'field:*'
                      (present), '!field' (absent).
  --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>.
  --regex             Treat the query as a regex. Off by default: terms are
                      literal.
  --limit <int>       Maximum number of results. 0 for no limit. A capped result
                      says so.  [default: 50]
  --sort <str>        Sort by a result field; prefix with '-' to reverse, e.g.
                      -modified.
  --backend <str>     Search backend(s), comma-separated. Default 'rg' (or
                      $WIKITOOL_SEARCH_BACKEND).
  --matches           Print the matching lines under each result.
  --json              Print the results as JSON.
  -h, --help          Show this message and exit.
```

**Examples**

```bash
tools/wikitool search "act runner"
tools/wikitool search --field entity_type=system --field '!sources'
tools/wikitool search "docker" --collection entities --limit 10 --json
```

**Behaviour**

- Finds pages in `kb/` without reading the catalog. Text search runs through a pluggable backend (`rg` today).
- `--field` predicates are evaluated on frontmatter - `f=v`, `f~substring`, `'f>=v'`, `'f:*'` (present), `'!f'` (absent) - repeatable and ANDed. With no text this is a pure structured query.
- One hit per line, ` | `-separated as `score | kind/subtype | title | path | summary`. **Title and path are never truncated** - the title is the identifier `touch`/`xref`/`cite` take. The summary, the one lossy field and the only one that may contain the separator, goes last, so splitting on `" | "` with `maxsplit=4` is unambiguous.
- Scope is pages: the backend walks `kb/` but drops the kb-root meta files, every `COLLECTION.md` and every generated `INDEX.md` - a hand-run grep over `kb/` can add none of them but those.
- `--limit` defaults to 50 (`0` for no limit), and **a truncated result says so**: `50 of 182 result(s)` in the table, `total`/`truncated`/`limit` beside `count` in `--json`, where `count` stays the number of results in the payload. `api.search` and the MCP `search` tool carry the same default and the same fields.
- A page whose frontmatter does not parse can match no positive predicate, so it is **named** rather than dropped: `--json` always carries an `unreadable` list of `{path, reason}` (usually empty), and the table form writes the same lines to stderr.
- An unknown field name is reported with the list of fields that do exist - never answered with an empty result, which would read as "no such pages".
- `--regex` is applied by `rg` alone, whose engine is linear; the ranking boosts for title and summary are literal-containment only, so a non-literal pattern is ranked by match count.
- `rg` is killed after 30 s and reported as a failure.
- Read-only, and **exempt from the Iteration Budget Gate**.

**Properties**

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

**Exit codes**

- `0` - success
- `1` - `rg` is not installed
- `1` - `rg` did not finish within 30 s
- `1` - A malformed `--field` predicate, or an unknown `--backend`
- `1` - An unknown field name; the error lists the fields that exist

**See also**

- `wikitool links show` - the edges around a page once found
- `wiki-query` skill - answering a question from the wiki

## `review`

The GTD weekly review.

**Synopsis**

- `wikitool review [--json]`

**Options**

```text
  --json      Print the findings as JSON.
  -h, --help  Show this message and exit.
```

**Examples**

```bash
tools/wikitool review
tools/wikitool review --json
```

**Behaviour**

- Joins the configured task-tracker provider against `kb/gtd/` project pages over the case-normalized project name, at read time, storing nothing - not even a `reports/` file.
- **stalled**: a tracker project with zero open items whose `kb/` page is `state: active`; `dormant`/`completed`/`abandoned` never fire.
- **waiting-overdue**: a `WAITING` item whose `follow_up_at` is older than `thresholds.stalled_waiting_days`.
- **unpaged-project**: a tracker project with no matching `kb/` page, older than `thresholds.unpaged_project_weeks`.
- **no-open-loop**: a `kb/` page `state: active` with no matching tracker project, or one with zero open items - the reverse direction of unpaged-project, so a rename on either side surfaces on both.
- **someday-stale**: a someday/maybe item untouched for longer than `thresholds.someday_stale_months`.
- A value a provider genuinely cannot supply - a `WAITING` item with no `follow_up_at`, a tracker project with no determinable creation date - is its own finding (`waiting_no_follow_up`/`project_age_unknown`) rather than a silent skip.
- Thresholds come from the tracker configuration, never from the schema.
- The tracker configuration is read from `.wikitool-tasks.json`, or from the file `WIKITOOL_TASKS_CONFIG` names when that variable is set (so one checkout can be run against several trackers in turn). A set variable that names no file is an error, never "no tracker configured".
- Text output is one `[check] project: message` line per finding, preceded by a `Source:` line naming which access path answered and, for `superproductivity`'s `access: "snapshot"`, the snapshot's age. `--json` carries the same findings plus `checks_run`/`checks_skipped`/`kb_project_count`/`complete`/`source` (`{"kind": ..., "detail": ...}` or `null`).
- A provider that cannot be reached mid-run degrades only the checks that needed the failing call; the report is printed in full, then exit 1 follows - never rendered as if it were complete.
- Re-reads everything fresh on every call, so nothing is ever stale to re-fetch.
- Read-only, and **exempt from the Iteration Budget Gate**.

**Properties**

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

**Exit codes**

- `0` - success
- `1` - No `.wikitool-tasks.json`, or a malformed one - a clear "no tracker configured" message
- `1` - `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken
- `1` - The provider was reachable at config-parse time but a read call failed mid-run; the full report (findings plus which checks ran) was printed first

**See also**

- `gtd-weekly-review` skill - turns the findings into decisions
- `wikitool task list` / `wikitool task close` - act on an item
- `wikitool new project` - a project page and its tracker project
<!-- /wikitool:reference-commands -->