groundwork 0.4.0 — the explorer and the plans index

groundwork fixed my plans rotting; it did nothing about them sprawling. The design-system plan for one of our products is 200 files — spine docs, two sub-plans, 96 design mockups — and the plan board only answers "what's the status." Finding where a decision lives across 200 files meant opening documents one at a time.

Version 0.4.0 ships two new views for that.

groundwork explorer

Writes an artifact/explorer.html for the plan — a file browser for the whole folder, as one self-contained HTML file.

• Left tree, grouped by kind — spine, sub-plans, artifact, designs, drafts — with a drift dot on files changed since the last groundwork write, a lock badge on frozen designs, and an unreg flag on files on disk that were never registered in .groundwork.json.
• Right viewer, dispatched by type — Markdown renders inline with the generated regions visibly boxed and a Raw toggle; HTML artifacts and designs open as live previews with a Source sub-tab; images get a lightbox; JSON, code, and SVG render read-only. Files stay open as closeable tabs, with a metadata rail showing IDs, fence inventory, drift, and copy-path.
• Full-text search, no server — filename and content matching over every embedded document, with highlighted snippets. The bodies are embedded in the file, so search needs no index step and no localhost.
• A sibling to the board, not a replacement — board.html, the living spec, and designs/*.html open as iframe tabs. The explorer is the navigational shell that contains them.
• Profile-aware default view — design-system plans open gallery-first (a lazy-loaded grid of live mockup thumbnails), content plans open media-first, software and general open as the tree.

Fully offline by construction: React, the Markdown renderer, and the sanitizer are inlined and pre-transpiled, so the file opens air-gapped, in Claude Desktop, or double-clicked. Served or opened in the Ikenga shell, previews load live; as a lone file, embedded text still renders everything and previews degrade to a labeled placeholder. One honest constraint: embedding works against a 768 KB budget, spine-first — files past the line are referenced instead of embedded (they still preview live; they don't travel inside the lone file or appear in full-text search), and the header tells you exactly how many.

groundwork plans-index

Writes a plans/_index.html one level up: a card per plan with a work-package progress bar, profile chip, drift indicator, and drill-in buttons to that plan's explorer, board, and spec. Buttons disable when the artifact doesn't exist yet, so the index doubles as a "what still needs generating" view. Aggregate stats, search, profile filters, and sort across the top. It reads the plans it lists and never writes into them.

The bookkeeping stays boring

Re-running is idempotent — a checksum decides what changes on disk, like the rest of the skill. Backfill a whole project with generate_explorer.py --all-under plans/ --missing-only; keep one live with the watch script, which regenerates on edit and reloads the served page.

Like the board, the explorer is an Ikenga artifact: it stands alone in any browser and lights up inside the shell — theme tracking, send-file-to-chat. You never need the shell.

Try it

The templates render with sample data, fully offline:

Docs: the explorer. Install: