Documentation Explorer

A local React/TypeScript app for exploring Markdown documents as a treemap. Filter by filename, text, or review status, drill into folders, and read rendered Markdown with Mermaid diagrams, highlighted code, and review comments.

Run

Install Bun, then run:

git clone https://git.celilo.computer/celilo/documentation-explorer.git
cd documentation-explorer
bun install --frozen-lockfile
CELILO_REPO=/path/to/celilo bun run dev

Open http://127.0.0.1:4179. The app scans the selected checkout every two seconds. Edit documentation in its source repository. The server's only write saves review comments and status from the reader. Set PORT to change the port. Restart after changing the app's source.

The current configuration targets Celilo: CELILO_REPO defaults to /Users/pbanka/hobby/celilo. The interface follows the system's light or dark appearance.

Press t to find a document by part of its path. In a document, click to place a read-only cursor; arrows and Shift-arrows move and select, Enter comments on the selection (or the cursor's block), and Cmd+Enter saves. Esc never closes the comment dialog; use Cancel. The cursor stays on screen: scrolling the page brings it to the nearest visible line. A document opens with the cursor at its start, or on the section a link points to. Hovering a link shows where it points, with an issue or pull request's title above its URL. A link to a file that is not Markdown, such as source code, opens that file as plain text in a new tab. On the map, Alt-click opens the file under the pointer without zooming. The map's zoom and settings (filters, search, COLOR, AREA) are part of the URL, so a refresh or a shared link shows the same view. Back and Forward step through zoom levels and documents; changing a setting adds no step. A URL without settings always opens the default map; the explorer remembers nothing between visits. To find documents with review comments, press "With comments" above the map, or set COLOR to "Review comments": blue grows stronger with more comments, and grey means none. COLOR "File type" picks out README.md, CHANGELOG.md, AGENTS.md, and SKILL.md files, each in its own colour.

Press Graph, above the map, to see the same documents as a graph of their links. Each document is a circle that grows with the number of documents linking to it, and each link between two shown documents is an arrow. The layout settles by itself. Drag a document and its neighbours follow; drag empty space to pan, and scroll or pinch to zoom. The ten most-linked documents are labelled, and every document once you zoom in. Click a document to focus it: it stays put, its neighbours gather in a ring around it, the rest dims, and the sidebar lists what it links to and what links to it, counting documents the filters hide. Click a neighbour, in the graph or the list, to move the focus; Back steps through earlier focuses. Read, a double-click, Enter, or Alt-click opens the focused document, and Back to map returns to the graph as you left it. Esc clears the focus, and t finds a document and focuses it. In the reader, Show in graph opens the graph focused on that document, resetting only the filters that would hide it. The filters, search, and COLOR apply to the graph; panning, zooming, and dragging never change the URL.

The reader marks uncommitted changes, compared with git's HEAD and including staged ones, and counts them at the top of the page. Green bars mark added passages and amber bars changed ones; list items and table rows are marked one by one. A red triangle in the margin marks where text was removed; hover it to read the removed text. Inside a changed passage the changed words are highlighted (hover a replacement to read what it replaced), a small red notch marks removed words, and a link whose target changed is highlighted whole. Re-wrapping alone highlights nothing, and a passage more than half rewritten keeps just its bar. n jumps to the next change, briefly shows which one it reached, such as "Change 7 of 13", and announces removed text when it lands on it. A document git has never committed says so instead. Review comments, replies, and status changes never count as changes. On the map, "Uncommitted" shows only documents with uncommitted changes, and COLOR "Uncommitted changes" colours new, changed, and committed documents apart.

Agents answer review comments with replies: HTML comments whose first word is REPLY, written directly after the comment they answer. The reader shows a reply as an Agent card, its text rendered as Markdown, and groups adjacent comments and replies into a thread. A thread whose last card is a reply waits on you. The top of the page counts those threads, such as "2 replies waiting"; press the count, or ]r and [r, to step through them, and inbox rows show the same count. Follow up on a waiting reply's card, or i on it, answers inside its thread. Resolve, on a thread's last card, removes the whole thread. Approve removes the threads left, which all end in a reply, after a confirmation.

bun run docs answers questions about a repository's core documentation (every Markdown document with a review status, apart from generated files, changelogs, changesets, agent instruction files, and skills). The commands are core, pending (with why: not approved, an open thread, or any change git has not committed, approvals and deletions included), cites <file>, and homeostasis, which exits 0 only when nothing is pending and HEAD is origin/main, 1 when not, and 2 on bad usage or an error. Add --repo <path> (default $CELILO_REPO) and --json.

Press Inbox in the header to work through the documents waiting on you: draft, in-review, revised, and amended. Documents in review come first, then revised ones (an agent has answered your comments), then modified ones (uncommitted changes, or new). The list sits beside the reader, and its outbox shows the reviewed documents waiting on an agent. An agent's edit or reply sets revised, which brings a document back to the inbox. In the inbox, Mark reviewed and Approve open the next document, and ]d and [d step through the list. In a window 1050px wide or narrower the list hides, giving the document the full width.

Press Shortcuts in the header for every key binding. The cursor also takes vim keys:

Keys	Action
h j k l	Character and line moves
w b e	Next word, previous word, word end
0 $ / { }	Line start and end / previous, next paragraph
gg G	Document start and end
A count, such as 5j	Repeats the motion
v / Esc	Visual mode on and off; motions extend
i	Comment (Enter); follows up a waiting reply
y	Copy the selection
Y	Copy the document's path (or press ⧉)
]c [c	Next and previous comment
]r [r	Next and previous waiting reply
n	Next uncommitted change
]d [d	Next and previous inbox document
d	Done: Approve, or Mark reviewed if a thread waits on an agent

Build

bun run build

build rescans the selected repository and writes a self-contained snapshot to dist/index.html. It works offline from file://, including Mermaid and embedded local images. Rebuild to refresh it. Nothing is written to the selected repository, and dist/ is not tracked.

Verify changes

Authored scripts and configuration use TypeScript. The server, builds, tests, TypeScript compiler, and ESLint run through Bun. Lasertag's CLI is the sole Node runtime exception, invoked explicitly by check:styles. Lasertag 0.7.0's TypeScript 7 client accesses Node's private stdout._handle.fd; under Bun 1.4.2 the check fails and can remain running. Keep Node installed for that check.

bun run test
bun run typecheck
bun run check:styles
bun run test:browser

Browser tests use a temporary repository and require Playwright Chromium: bunx --no-install playwright install chromium. They cover filters, document rendering, review comments and conflicts, live updates, theme changes, the graph view, and mobile layouts.

Styles use Lasertag CSS Modules. The reader deliberately styles Markdown's generated HTML; its scoped ownership exception is documented in its stylesheet. The direct vscode-jsonrpc 8 development dependency keeps Mermaid's Langium deep imports working alongside Lasertag's separate version 9 dependency.

Maintenance boundaries

• Review status comes only from document frontmatter. reviewed means approval is pending; passing checks or moving a file does not grant approval. The reader's one status button and the d (done) key are the app's only status changes. Both mark reviewed while a thread waits on an agent and approve once none does. Approving removes the threads left, which all end in an agent's reply, after a confirmation naming them, and never over text written since. d always asks for confirmation. Approving returns to the map, or in the inbox opens the next document. Review comments remain in the original Markdown. The only write is PUT /api/document, a compare-and-swap replacement of a scanned document. It refuses a non-loopback Host, a foreign Origin, and non-JSON bodies; see docs/adr/0001-review-comments-inline-in-source.md. Two reads also refuse a non-loopback Host: GET /api/file serves a file Git lists (tracked, or new and unignored) as plain text, and GET /api/issue fetches the title of an issue a document links to from GitHub's or Gitea's API, keeping it until restart. Neither runs in the built snapshot.
• The live catalog reads Git-tracked and unignored Markdown, excluding symlinks.
• Mermaid rendering is serialized because its configuration is shared. Theme changes must preserve the open document and redraw its diagrams. Keep HTML sanitization and the offline reader working when changing rendering.
• Checks currently run locally; this repository has no CI workflow. The browser suite uses fixtures, so also check the standalone HTML with real documents after changes to packaging. Do not commit source tarballs into Celilo; keep app source history in this repository.

Source history

The first three commits recover the source snapshots previously archived inside Celilo. Their commit messages identify the original revisions. Subsequent work is maintained here as ordinary source commits; Celilo links to this repository.