sdtk-wiki — Command Reference

Project memory CLI. Guide: SDTK-WIKI.

npm install -g sdtk-wiki-kit   # included in sdtk-kit
sdtk-wiki --help

Workspace

sdtk-wiki init --no-open                # index your project docs into the atlas graph

init/atlas build index your repo's own docs in place into a local knowledge graph; .sdtk/wiki holds the graph + machine state; legacy .sdtk/atlas stays readable.

Removed in 0.10.0 (moved to SDTK-BRAIN)

sdtk-wiki ingest, compile, discover, enrich, and the wiki * pipeline namespace — the personal second-brain pipeline — were deprecated in 0.8.0 and are removed as of 0.10.0. They live in the standalone sdtk-brain tool (npm i -g sdtk-brain-kit). The old names print a pointer and exit 2.

Archive tier (0.10.0)

Add repo-relative path fragments to archive in .sdtk/wiki/graph/config.json (same matching rules as excludes, empty by default) and rebuild — matched docs get trust_zone: "archive" and rank lower in search/query/ask (score halved, never hidden). Hits carry a tier: archive | current label.

Atlas

Pure Node graph build + browser viewer. This is the canonical builder; sdtk-spec atlas is a compatibility namespace that forwards here.

sdtk-wiki atlas build
sdtk-wiki atlas open      # serves the viewer; stays alive until Ctrl+C
sdtk-wiki atlas watch     # rebuild on change
sdtk-wiki atlas status
sdtk-wiki atlas build --workspace brain=~/my-vault   # multi-workspace switcher

--workspace name=path registers another store (e.g. an SDTK-BRAIN vault) in the graph config; the viewer then shows a switcher so you can move between your project wiki and your vault.

What gets indexed 0.17.0

Extension	Handling
.md, .txt	indexed directly
.docx, .xlsx, .pptx	converted to markdown, then indexed
.doc, .xls, .ppt	not indexed — pre-2007 binary formats; re-save to index
anything else	not a source; ignored

Office support needs no configuration and adds no dependency. Word headings become markdown headings, Word and Excel tables become markdown tables, and each sheet or slide becomes its own section — so chunking, retrieval and page generation treat an .xlsx exactly like a .md. PowerPoint speaker notes are indexed and always labelled, so a citation can never imply text was on screen when it was only in the notes.

Scan roots decide what is even looked at

This is the one that bites. If your project has a docs/ directory, that directory alone is the default scan root. A .docx in reports/, or at the repo root, is never discovered — so it cannot be reported as skipped either.

sdtk-wiki atlas build --scan-root docs --scan-root reports   # repeatable
sdtk-wiki atlas build --scan-root .                          # the whole project

Since 0.18.1 the build says so rather than leaving you to guess:

[atlas] Note: 2 Office file(s) are outside the scan root(s) and were NOT indexed — deck.pptx, reports/plan.xlsx.
[atlas]       Scan roots: docs. Add one with: sdtk-wiki atlas build --scan-root <dir>

sdtk-wiki init --scan-root <dir> persists the choice so you do not pass it every build. If Office files are not appearing, check the version first — Office indexing landed in sdtk-wiki-kit 0.17.0 (sdtk-kit 1.49.0); earlier versions scan markdown only and drop .docx without a word. sdtk update fixes that.

A corrupt or password-protected file skips that file alone, with its reason, and the rest of the build proceeds.

Starting over 0.19.0

Re-pointing the scan roots does not remove what the previous build generated. The old pages stay on disk, and because search scans the pages directory while ask grounds on the graph, the two disagree: ask is clean, search keeps returning documents that are no longer sources. reset clears them.

sdtk-wiki reset                          # show what would be removed; change nothing
sdtk-wiki reset --yes                    # remove it
sdtk-wiki reset --yes --scan-root docs   # remove it, and re-point the wiki at docs/
sdtk-wiki atlas build

It is plan-only by default — --yes applies. It removes only generated artifacts (graph contents, pages, provenance, raw, reports, queries, logs, manifest.json) and reports anything under .sdtk/wiki it does not recognise instead of deleting it.

Never removed:

Path	Why
.sdtk/wiki/PROJECT_MEMORY.md	authored by you, not generated — commit it
unrecognised files under .sdtk/wiki	reported, left in place
wiki/	human-facing pages — opt in with --include-wiki-dir
.sdtk/atlas	legacy workspace — opt in with --include-legacy
your source documents	reset clears the index, never the repo it indexed

Scan roots survive a plain reset, so it clears the index without forgetting which folders the wiki is built from. Running it twice is a no-op the second time.

If a build crashes 0.19.1

A page's filename comes from its title — usually the document's first # heading. Nothing bounded that heading's length, so a converted document (a docx table flattened to markdown is the common source) with a single-line "heading" hundreds of characters long produced a filename over the filesystem's limit, and the write failed. Titles are now truncated to 80 characters before becoming part of a filename; the file stays unique regardless, via a content-hash suffix. A page that still can't be written for some other reason — permissions, a locked file — is skipped with a warning instead of aborting the run: one hostile document no longer costs you every other page.

If a build does throw for any other reason, atlas status says so instead of reading identically to a project that was never built:

Built:             no (last attempt failed)

Failed at:         2026-08-11T05:42:27Z
Error:             EISDIR: illegal operation on a directory, open '...'

That comes from .sdtk/wiki/logs/last-build-error.json, written on any thrown build error and cleared by the next successful build (or by sdtk-wiki reset).

Backlog board 0.20.0

A third dashboard tab beside Pipeline and Quality Gates, reading governance/ai/core/IMPROVEMENT_BACKLOG.md. One card per issue, columns TODO / IN_PROGRESS / IN_REVIEW / BLOCKED, with DONE behind a toggle (it is usually two-thirds of the table).

Read-only by design. The markdown file stays the single source of truth — the board never writes to it. Status moves when you or an agent edits the row.

Status cells follow a fixed grammar so a key can select a column while the detail stays readable:

<KEY>[ (<free-text sub-state>)]      KEY ∈ TODO | IN_PROGRESS | IN_REVIEW | BLOCKED | DONE

IN_PROGRESS (coding)      IN_REVIEW (PR open)      BLOCKED (gated on BK-371)

The sub-state shows on the card, so an issue reads IN_PROGRESS · coding then IN_PROGRESS · QA testing without adding a column. A BLOCKED sub-state that names another issue becomes a link to it.

Clicking a card lists the plan documents cited in its Notes. Write them with labels and they render as labels:

Controller: `governance/ai/reviews/shared/..._SPEC_R1_....md` · Impl: `..._IMPL_PLAN_R1_....md`

Documents open in the same dialog the Docs view uses — rendered markdown, header bar, Expand, ESC to close — so a document looks identical wherever it was opened from. Content comes through the note route, which serves any file under the project root, so review and planning documents open even when they sit outside the scan roots the graph indexes.

Only documents that actually exist become links. Notes cite plenty of things that are not openable paths — bare filenames named in prose (Added \DESIGN_SYSTEM.md` generation…`), stale paths, glob patterns — and on this repo that is 46% of the citations. Those still appear on the card, marked as referenced-but-not-a-file, because a button that 404s is worse than plain text.

Anything the parser cannot classify is reported on the board, never dropped: a backlog view that silently discards rows is worse than no view.

Query & search

sdtk-wiki query "<graph query>"
sdtk-wiki search "<text>"
sdtk-wiki lint

search/query ground on the union of the atlas pages and any compiled wiki content — every hit carries a store: atlas|wiki label.

Ask

sdtk-wiki ask "How does the payment flow handle retries?"

Ranks passages from the built graph against the question. A built graph is the only hard requirement — without one it fails closed.

Free returns the top passages verbatim with citations: no model, no key, no network.

Pro (wiki.ask entitlement) reformulates the question and writes an answer grounded in those passages, refusing with NOT IN SOURCES rather than guessing. Only this tier invokes a model (an explicit external call). A missing entitlement degrades to the free tier and says so; it does not error.

Also available in the Atlas viewer.

Kanban

sdtk-wiki kanban   # local human-in-the-loop task board

Maintenance

sdtk-wiki lint
sdtk-wiki maintain --mode safe   # lint-only health pass since 0.10.0
sdtk-wiki update

(discover/enrich and the wiki * pipeline verbs were removed in 0.10.0 — see the callout above.)

Safe/review modes propose changes; nothing destructive runs without an explicit apply.

Not in this release

No web fetch, no destructive prune, no query history list/show/delete. SDTK-WIKI installs no skills — it is entirely CLI-driven.