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.

Contents

• lint
• search
• review

lint

Run structural lint checks against kb/.

Synopsis

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

Options

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

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

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

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

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

Examples

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