wiki-browser

Wiki-style server (Go) that serves the orcha repo's .html and .md files in a browser, with GitHub-flavored Markdown rendering, mermaid, and full-text search. Designed to run on a Raspberry Pi.

Brainstorming specs

Read docs/superpowers/spec-design-system.html before writing one — it defines the tokens, components, and section order to use. Copy its <style> block verbatim.

Visual verification with playwright-cli

Most UI changes (chrome layout, mermaid rendering, mobile breakpoints, sidebar overlay, search dropdown, theme toggle) cannot be verified by reading the diff — you have to load the page in a real browser and look. This project ships the playwright-cli skill for exactly this. Use it before claiming a UI change works.

The full reference is in .claude/skills/playwright-cli/SKILL.md. Quick recipe:

# Make sure no leftover sessions are around.
playwright-cli list
playwright-cli close-all   # if any are running

# Start the wiki-browser binary in the background, point Chromium at it.
nohup ./dist/wiki-browser -config=wiki-browser.yaml >/tmp/wb.log 2>&1 &
disown
playwright-cli open --browser=chromium http://localhost:8080/doc/<some-path>
playwright-cli resize 1440 900    # or 375 812 to test the mobile breakpoint

To inspect the actual rendered DOM (e.g. computed styles, iframe contents, SVG dimensions), use eval with a function — not a bare expression. The SKILL.md shows playwright-cli eval "document.title" but that form errors with "result is not a function" in the current build. Always wrap as () => ...:

playwright-cli eval "() => document.title"

# Reading inside the iframe (same-origin, so contentDocument works):
playwright-cli eval "() => {
  const f = document.getElementById('wb-content');
  const svg = f.contentDocument.querySelector('pre.mermaid svg');
  return { width: svg.getBoundingClientRect().width, viewBox: svg.getAttribute('viewBox') };
}"

To capture a visual:

playwright-cli screenshot --filename=/tmp/wb-check.png
# then Read the file in Claude Code; it renders the image inline.

When iterating on a CSS or template change: rebuild the binary (make build), restart the server (pkill -f 'dist/wiki-browser'; nohup ./dist/wiki-browser …), then playwright-cli reload. Templates and static assets are baked into the binary via embed.FS, so there is no hot reload — restart is mandatory.

When you're done, leave the browser running so the next prompt can poke at it, or close cleanly:

playwright-cli close