wiki-browser v1 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build wiki-browser v1: a Go binary that serves the orcha repo's .md and .html files in a browser with GitHub-flavored Markdown rendering, mermaid diagrams, full-text search, and HTMX-driven chrome.

Architecture: One Go process. The HTTP server returns a chrome shell (HTMX-driven; sidebar, search topbar) that hosts an <iframe>. The iframe loads standalone content documents — Markdown rendered server-side, authored HTML served byte-identical. Filesystem walker (fsnotify) keeps a SQLite FTS5 index in sync. Pure Go (no CGO) so the binary cross-compiles to ARM from a dev box.

Tech Stack: Go 1.22+, modernc.org/sqlite (FTS5), github.com/yuin/goldmark + github.com/alecthomas/chroma/v2, github.com/fsnotify/fsnotify, github.com/bmatcuk/doublestar/v4, HTMX, mermaid.js, gopkg.in/yaml.v3. Tests use the standard testing package + github.com/google/go-cmp/cmp. End-to-end iframe test uses github.com/chromedp/chromedp.

Spec: ../specs/2026-05-09-wiki-browser-design.html. Read it once before starting; this plan assumes you've seen it.

File map

wiki-browser/
├── cmd/wiki-browser/main.go          ← entrypoint
├── deploy/wiki-browser.service       ← systemd unit
├── docs/superpowers/                 ← spec + this plan (already exist)
├── go.mod, go.sum
├── Makefile                          ← build / test / cross-compile
├── README.md
├── wiki-browser.example.yaml         ← config example
└── internal/
    ├── config/                       ← Load + validate YAML
    ├── walker/                       ← scan + fsnotify watch + debounce
    ├── render/                       ← MD/HTML → Document; LRU cache
    ├── index/                        ← FTS5 schema, Reindex/Remove/Search
    ├── nav/                          ← sidebar HTML from walker output
    └── server/                       ← routes, templates, embed.FS root
        ├── templates/                ← shell, content_md, search_results, nav
        ├── static/                   ← CSS, chrome.js, content.js, htmx, mermaid
        └── content/                  ← _welcome.md, _404.md, _search-offline.md

Test data is under each package's testdata/ (Go convention; go test ignores files there).

Conventions used by every task

• Module path: github.com/getorcha/wiki-browser. (Adjust in Task 1 if the user wants a different path.)
• Logging: log/slog with the JSON handler in production, text handler in tests. Always wrap returned errors with fmt.Errorf("...: %w", err).
• Tests: standard testing. For complex value comparisons use github.com/google/go-cmp/cmp. For golden-file tests, accept a -update flag that rewrites the golden output. Use t.TempDir() for fixture trees — Go cleans them up automatically.
• Commits: one per task at the end. Single-line message, no Co-Authored-By trailer (per repo convention). Format: wiki-browser: <imperative summary>.
• Run from cwd: all commands assume cwd is /home/volrath/code/orcha/wiki-browser.

Phase 0 — Bootstrap

Task 1: Project bootstrap

Files:

• Create: go.mod

• Create: README.md

• Create: .gitignore

• Create: wiki-browser.example.yaml

• Step 1: Initialize the Go module

go mod init github.com/getorcha/wiki-browser

Expected: writes go.mod with go 1.22 (or higher).

• Step 2: Add core dependencies

go get gopkg.in/yaml.v3
go get github.com/bmatcuk/doublestar/v4
go get github.com/fsnotify/fsnotify
go get github.com/yuin/goldmark
go get github.com/yuin/goldmark-highlighting/v2
go get github.com/alecthomas/chroma/v2
go get modernc.org/sqlite
go get github.com/google/go-cmp/cmp
go get github.com/chromedp/chromedp
go get golang.org/x/sync/singleflight
go get golang.org/x/net/html
go mod tidy

Expected: go.sum populated; no errors.

• Step 3: Write the README

# wiki-browser

Wiki-style server (Go) for the orcha repo. Serves every `.md` and `.html` file as a browseable wiki with GitHub-flavored Markdown rendering, mermaid diagrams, and full-text search. Designed to run on a Raspberry Pi.

See [`docs/superpowers/specs/2026-05-09-wiki-browser-design.html`](docs/superpowers/specs/2026-05-09-wiki-browser-design.html) for the design.

## Quick start

```bash
cp wiki-browser.example.yaml wiki-browser.yaml
$EDITOR wiki-browser.yaml          # set `root` to the repo you want to serve
make run
# open http://localhost:8080

Build for the Pi

make build-arm64
scp dist/wiki-browser pi:/home/pi/bin/

See deploy/wiki-browser.service for the systemd unit.

- [ ] **Step 4: Write `.gitignore`**

/dist/ /wiki-browser-index.db /wiki-browser.yaml *.test *.out

- [ ] **Step 5: Write `wiki-browser.example.yaml`**

```yaml
# wiki-browser config — copy to wiki-browser.yaml and edit `root`.
listen: ":8080"
title: "Orcha wiki"
root: "/home/volrath/code/orcha"
extensions: [".md", ".html"]
index_db: "./wiki-browser-index.db"
exclude:
  # User-configurable additions on top of baked-in defaults
  # (.git, node_modules, .worktrees, .obsidian, .claude, tmp-* are always excluded).
  - "www/**"
  - "marketing/**"

• Step 6: Verify the module builds (empty)

go build ./...

Expected: no output, no errors. (There's nothing to build yet, but go build ./... succeeds when there are no .go files.)

• Step 7: Commit

git add go.mod go.sum README.md .gitignore wiki-browser.example.yaml
git commit -m "wiki-browser: bootstrap Go module, README, and example config"

Phase 1 — Core packages

Task 2: Config — Load and validate YAML

Files:

• Create: internal/config/config.go

• Test: internal/config/config_test.go

• Create: internal/config/testdata/valid.yaml

• Create: internal/config/testdata/missing-root.yaml

• Step 1: Write the failing tests

// internal/config/config_test.go
package config_test

import (
	"path/filepath"
	"testing"

	"github.com/getorcha/wiki-browser/internal/config"
	"github.com/google/go-cmp/cmp"
)

func TestLoad_valid(t *testing.T) {
	got, err := config.Load(filepath.Join("testdata", "valid.yaml"))
	if err != nil {
		t.Fatalf("Load: %v", err)
	}
	want := &config.Config{
		Listen:     ":8080",
		Title:      "Orcha wiki",
		Root:       "/tmp",
		Extensions: []string{".md", ".html"},
		IndexDB:    "./wiki-browser-index.db",
		Exclude:    []string{"www/**", "marketing/**"},
	}
	if diff := cmp.Diff(want, got); diff != "" {
		t.Errorf("Load() mismatch (-want +got):\n%s", diff)
	}
}

func TestLoad_appliesDefaults(t *testing.T) {
	got, err := config.Load(filepath.Join("testdata", "minimal.yaml"))
	if err != nil {
		t.Fatalf("Load: %v", err)
	}
	if got.Listen != ":8080" {
		t.Errorf("Listen default not applied: got %q", got.Listen)
	}
	if got.IndexDB != "./wiki-browser-index.db" {
		t.Errorf("IndexDB default not applied: got %q", got.IndexDB)
	}
	if !cmp.Equal(got.Extensions, []string{".md", ".html"}) {
		t.Errorf("Extensions default not applied: got %v", got.Extensions)
	}
}

func TestLoad_missingRootFails(t *testing.T) {
	_, err := config.Load(filepath.Join("testdata", "missing-root.yaml"))
	if err == nil {
		t.Fatal("expected error for missing root, got nil")
	}
}

func TestLoad_unreadableRootFails(t *testing.T) {
	_, err := config.Load(filepath.Join("testdata", "bad-root.yaml"))
	if err == nil {
		t.Fatal("expected error for unreadable root, got nil")
	}
}

Test fixtures:

# internal/config/testdata/valid.yaml
listen: ":8080"
title: "Orcha wiki"
root: "/tmp"
extensions: [".md", ".html"]
index_db: "./wiki-browser-index.db"
exclude:
  - "www/**"
  - "marketing/**"

# internal/config/testdata/minimal.yaml
title: "Minimal"
root: "/tmp"

# internal/config/testdata/missing-root.yaml
title: "no root"

# internal/config/testdata/bad-root.yaml
title: "bad root"
root: "/path/that/definitely/does/not/exist"

• Step 2: Run tests, expect compile failure (no implementation yet)

go test ./internal/config/... -v

Expected: build error referencing config.Load, config.Config.

• Step 3: Implement config.go

// internal/config/config.go
package config

import (
	"fmt"
	"os"
	"path/filepath"

	"gopkg.in/yaml.v3"
)

// Config is the typed view of wiki-browser.yaml.
type Config struct {
	Listen     string   `yaml:"listen"`
	Title      string   `yaml:"title"`
	Root       string   `yaml:"root"`
	Extensions []string `yaml:"extensions"`
	IndexDB    string   `yaml:"index_db"`
	Exclude    []string `yaml:"exclude"`
}

// Load reads the YAML file at path, applies defaults, and validates.
func Load(path string) (*Config, error) {
	raw, err := os.ReadFile(path)
	if err != nil {
		return nil, fmt.Errorf("read %s: %w", path, err)
	}
	c := &Config{}
	if err := yaml.Unmarshal(raw, c); err != nil {
		return nil, fmt.Errorf("parse %s: %w", path, err)
	}
	c.applyDefaults()
	if err := c.validate(); err != nil {
		return nil, fmt.Errorf("validate %s: %w", path, err)
	}
	return c, nil
}

func (c *Config) applyDefaults() {
	if c.Listen == "" {
		c.Listen = ":8080"
	}
	if c.IndexDB == "" {
		c.IndexDB = "./wiki-browser-index.db"
	}
	if len(c.Extensions) == 0 {
		c.Extensions = []string{".md", ".html"}
	}
}

func (c *Config) validate() error {
	if c.Root == "" {
		return fmt.Errorf("root is required")
	}
	abs, err := filepath.Abs(c.Root)
	if err != nil {
		return fmt.Errorf("root: abs: %w", err)
	}
	c.Root = abs
	info, err := os.Stat(abs)
	if err != nil {
		return fmt.Errorf("root %s: %w", abs, err)
	}
	if !info.IsDir() {
		return fmt.Errorf("root %s: not a directory", abs)
	}
	for _, ext := range c.Extensions {
		if len(ext) == 0 || ext[0] != '.' {
			return fmt.Errorf("extension %q must start with '.'", ext)
		}
	}
	return nil
}

• Step 4: Run tests, expect pass

go test ./internal/config/... -v

Expected: 4 tests PASS.

• Step 5: Commit

git add internal/config go.mod go.sum
git commit -m "wiki-browser: config package — Load + validate YAML"

Task 3: Walker — exclude-pattern matcher

The walker needs to know which paths to skip. Default excludes are baked into the binary; user excludes from config layer on top.

Files:

• Create: internal/walker/exclude.go

• Test: internal/walker/exclude_test.go

• Step 1: Write the failing tests

// internal/walker/exclude_test.go
package walker

import "testing"

func TestExcludeMatcher_defaultsAlwaysApply(t *testing.T) {
	m := NewExcludeMatcher(nil)
	for _, p := range []string{
		".git/HEAD",
		"node_modules/foo/index.js",
		".worktrees/feature/file.md",
		".obsidian/workspace.json",
		".claude/skills/x.md",
		"orcha/tmp-ui-sandbox/index.html",
	} {
		if !m.Match(p) {
			t.Errorf("default exclude should match %q", p)
		}
	}
}

func TestExcludeMatcher_userPatterns(t *testing.T) {
	m := NewExcludeMatcher([]string{"www/**", "marketing/**"})
	cases := map[string]bool{
		"www/index.html":              true,
		"www/de/page.html":            true,
		"marketing/slides/index.html": true,
		"docs/orcha-controlling.html": false,
		"feature-specs/Approval.md":   false,
	}
	for p, want := range cases {
		if got := m.Match(p); got != want {
			t.Errorf("Match(%q) = %v, want %v", p, got, want)
		}
	}
}

func TestExcludeMatcher_doesNotMatchUnrelated(t *testing.T) {
	m := NewExcludeMatcher(nil)
	for _, p := range []string{
		"docs/plan.md",
		"feature-specs/Tax.md",
		"PRODUCT_ROADMAP.md",
	} {
		if m.Match(p) {
			t.Errorf("should not match %q", p)
		}
	}
}

• Step 2: Run, expect failure

go test ./internal/walker/... -v -run TestExcludeMatcher

Expected: undefined NewExcludeMatcher.

• Step 3: Implement exclude.go

// internal/walker/exclude.go
package walker

import "github.com/bmatcuk/doublestar/v4"

// DefaultExcludes are baked into every walker; users cannot opt out.
// They exist purely to keep the index sane on any repo (not orcha-specific).
var DefaultExcludes = []string{
	"**/.git/**",
	"**/node_modules/**",
	"**/.worktrees/**",
	"**/.obsidian/**",
	"**/.claude/**",
	"**/tmp-*/**",
}

// ExcludeMatcher decides whether a repo-relative path should be skipped.
type ExcludeMatcher struct {
	patterns []string
}

// NewExcludeMatcher returns a matcher that combines DefaultExcludes with user.
func NewExcludeMatcher(user []string) *ExcludeMatcher {
	p := make([]string, 0, len(DefaultExcludes)+len(user))
	p = append(p, DefaultExcludes...)
	p = append(p, user...)
	return &ExcludeMatcher{patterns: p}
}

// Match returns true if path should be excluded.
// path is repo-relative, slash-separated.
func (m *ExcludeMatcher) Match(path string) bool {
	for _, pat := range m.patterns {
		ok, _ := doublestar.Match(pat, path)
		if ok {
			return true
		}
		// Also match against any prefix segment so a directory itself can be skipped:
		// e.g. pattern "**/.git/**" should match the literal directory ".git".
		if ok2, _ := doublestar.Match(pat, path+"/_"); ok2 {
			return true
		}
	}
	return false
}

• Step 4: Run, expect pass

go test ./internal/walker/... -v -run TestExcludeMatcher

Expected: 3 tests PASS.

• Step 5: Commit

git add internal/walker/exclude.go internal/walker/exclude_test.go go.mod go.sum
git commit -m "wiki-browser: walker — default + user exclude matcher"

Task 4: Walker — initial scan

Walk the tree, apply excludes and extension filters, return a sorted list of repo-relative paths.

Files:

• Create: internal/walker/walker.go

• Test: internal/walker/walker_test.go

• Step 1: Write the failing test

// internal/walker/walker_test.go
package walker_test

import (
	"os"
	"path/filepath"
	"testing"

	"github.com/getorcha/wiki-browser/internal/walker"
	"github.com/google/go-cmp/cmp"
)

func writeTree(t *testing.T, files map[string]string) string {
	t.Helper()
	root := t.TempDir()
	for p, contents := range files {
		full := filepath.Join(root, p)
		if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
			t.Fatal(err)
		}
		if err := os.WriteFile(full, []byte(contents), 0o644); err != nil {
			t.Fatal(err)
		}
	}
	return root
}

func TestScan_returnsOnlyMatchingExtensions(t *testing.T) {
	root := writeTree(t, map[string]string{
		"docs/a.md":          "# a",
		"docs/b.html":        "<h1>b</h1>",
		"docs/skip.txt":      "ignore me",
		"feature-specs/x.md": "x",
	})
	w, err := walker.New(walker.Options{
		Root:       root,
		Extensions: []string{".md", ".html"},
	})
	if err != nil {
		t.Fatal(err)
	}
	got := w.Files()
	want := []string{
		"docs/a.md",
		"docs/b.html",
		"feature-specs/x.md",
	}
	if diff := cmp.Diff(want, got); diff != "" {
		t.Errorf("Files() mismatch (-want +got):\n%s", diff)
	}
}

func TestScan_appliesExcludes(t *testing.T) {
	root := writeTree(t, map[string]string{
		"docs/keep.md":           "k",
		"www/skip.md":            "s",
		"marketing/skip.md":      "s",
		".git/HEAD":              "ref",
		"orcha/tmp-foo/x.md":     "s",
		".obsidian/workspace.md": "s",
	})
	w, err := walker.New(walker.Options{
		Root:       root,
		Extensions: []string{".md"},
		Exclude:    []string{"www/**", "marketing/**"},
	})
	if err != nil {
		t.Fatal(err)
	}
	got := w.Files()
	want := []string{"docs/keep.md"}
	if diff := cmp.Diff(want, got); diff != "" {
		t.Errorf("Files() mismatch (-want +got):\n%s", diff)
	}
}

• Step 2: Run, expect failure

go test ./internal/walker/... -v -run TestScan

Expected: walker.New, walker.Options, Files undefined.

• Step 3: Implement walker.go

// internal/walker/walker.go
package walker

import (
	"fmt"
	"io/fs"
	"path/filepath"
	"sort"
	"strings"
	"sync"
)

// Options configures a Walker.
type Options struct {
	Root       string   // absolute path
	Extensions []string // e.g. [".md", ".html"]
	Exclude    []string // user excludes; defaults are always applied
}

// Walker is the source of truth for "what files exist under Root".
type Walker struct {
	opts    Options
	exclude *ExcludeMatcher
	extSet  map[string]struct{}

	mu    sync.RWMutex
	files map[string]struct{} // repo-relative slash paths
}

// New runs the initial scan and returns a Walker. The caller can then
// optionally Start() the watcher (Task 5+).
func New(opts Options) (*Walker, error) {
	if !filepath.IsAbs(opts.Root) {
		return nil, fmt.Errorf("Root must be absolute, got %q", opts.Root)
	}
	w := &Walker{
		opts:    opts,
		exclude: NewExcludeMatcher(opts.Exclude),
		extSet:  make(map[string]struct{}, len(opts.Extensions)),
		files:   make(map[string]struct{}),
	}
	for _, e := range opts.Extensions {
		w.extSet[strings.ToLower(e)] = struct{}{}
	}
	if err := w.scan(); err != nil {
		return nil, fmt.Errorf("initial scan: %w", err)
	}
	return w, nil
}

func (w *Walker) scan() error {
	return filepath.WalkDir(w.opts.Root, func(p string, d fs.DirEntry, err error) error {
		if err != nil {
			return err
		}
		rel, rerr := filepath.Rel(w.opts.Root, p)
		if rerr != nil {
			return rerr
		}
		rel = filepath.ToSlash(rel)
		if rel == "." {
			return nil
		}
		if w.exclude.Match(rel) {
			if d.IsDir() {
				return fs.SkipDir
			}
			return nil
		}
		if d.IsDir() {
			return nil
		}
		if !w.matchesExt(rel) {
			return nil
		}
		w.files[rel] = struct{}{}
		return nil
	})
}

func (w *Walker) matchesExt(path string) bool {
	_, ok := w.extSet[strings.ToLower(filepath.Ext(path))]
	return ok
}

// Files returns the current sorted list of repo-relative paths.
func (w *Walker) Files() []string {
	w.mu.RLock()
	defer w.mu.RUnlock()
	out := make([]string, 0, len(w.files))
	for p := range w.files {
		out = append(out, p)
	}
	sort.Strings(out)
	return out
}

// Has reports whether path is in the canonical file set.
func (w *Walker) Has(path string) bool {
	w.mu.RLock()
	defer w.mu.RUnlock()
	_, ok := w.files[path]
	return ok
}

• Step 4: Run, expect pass

go test ./internal/walker/... -v

Expected: 5 tests PASS (3 exclude + 2 scan).

• Step 5: Commit

git add internal/walker/walker.go internal/walker/walker_test.go
git commit -m "wiki-browser: walker — initial directory scan with excludes"

Task 5: Walker — fsnotify watcher

Add live updates: per-directory fsnotify subscriptions, recursive subscribe on dir-CREATE, ENOSPC handling, swap-file filtering.

Files:

• Create: internal/walker/watch.go

• Test: internal/walker/watch_test.go

• Step 1: Write the failing tests

// internal/walker/watch_test.go
package walker_test

import (
	"errors"
	"os"
	"path/filepath"
	"testing"
	"time"

	"github.com/getorcha/wiki-browser/internal/walker"
)

func waitFor(t *testing.T, ch <-chan walker.Event, want walker.Event, timeout time.Duration) {
	t.Helper()
	deadline := time.After(timeout)
	for {
		select {
		case ev := <-ch:
			if ev == want {
				return
			}
		case <-deadline:
			t.Fatalf("timed out waiting for %+v", want)
		}
	}
}

func TestWatch_emitsCreateEvent(t *testing.T) {
	root := t.TempDir()
	w, err := walker.New(walker.Options{Root: root, Extensions: []string{".md"}})
	if err != nil {
		t.Fatal(err)
	}
	ch := make(chan walker.Event, 16)
	stop, err := w.Start(ch)
	if err != nil {
		t.Fatal(err)
	}
	defer stop()

	if err := os.WriteFile(filepath.Join(root, "new.md"), []byte("# hi"), 0o644); err != nil {
		t.Fatal(err)
	}
	waitFor(t, ch, walker.Event{Path: "new.md", Kind: walker.EventChanged}, 2*time.Second)
}

func TestWatch_emitsRemoveEvent(t *testing.T) {
	root := t.TempDir()
	if err := os.WriteFile(filepath.Join(root, "x.md"), []byte("x"), 0o644); err != nil {
		t.Fatal(err)
	}
	w, err := walker.New(walker.Options{Root: root, Extensions: []string{".md"}})
	if err != nil {
		t.Fatal(err)
	}
	ch := make(chan walker.Event, 16)
	stop, err := w.Start(ch)
	if err != nil {
		t.Fatal(err)
	}
	defer stop()

	if err := os.Remove(filepath.Join(root, "x.md")); err != nil {
		t.Fatal(err)
	}
	waitFor(t, ch, walker.Event{Path: "x.md", Kind: walker.EventRemoved}, 2*time.Second)
}

func TestWatch_subscribesToNewSubdir(t *testing.T) {
	root := t.TempDir()
	w, err := walker.New(walker.Options{Root: root, Extensions: []string{".md"}})
	if err != nil {
		t.Fatal(err)
	}
	ch := make(chan walker.Event, 16)
	stop, err := w.Start(ch)
	if err != nil {
		t.Fatal(err)
	}
	defer stop()

	sub := filepath.Join(root, "fresh")
	if err := os.MkdirAll(sub, 0o755); err != nil {
		t.Fatal(err)
	}
	// Brief settle so the new dir is subscribed.
	time.Sleep(150 * time.Millisecond)
	if err := os.WriteFile(filepath.Join(sub, "deep.md"), []byte("d"), 0o644); err != nil {
		t.Fatal(err)
	}
	waitFor(t, ch, walker.Event{Path: "fresh/deep.md", Kind: walker.EventChanged}, 2*time.Second)
}

func TestWatch_filtersSwapFiles(t *testing.T) {
	root := t.TempDir()
	w, err := walker.New(walker.Options{Root: root, Extensions: []string{".md"}})
	if err != nil {
		t.Fatal(err)
	}
	ch := make(chan walker.Event, 16)
	stop, err := w.Start(ch)
	if err != nil {
		t.Fatal(err)
	}
	defer stop()

	// These should never appear.
	for _, name := range []string{"a.md~", "a.swp", "a.swx", "a.tmp", "4913"} {
		if err := os.WriteFile(filepath.Join(root, name), []byte("x"), 0o644); err != nil {
			t.Fatal(err)
		}
	}
	// And one real file we DO expect.
	if err := os.WriteFile(filepath.Join(root, "real.md"), []byte("r"), 0o644); err != nil {
		t.Fatal(err)
	}
	waitFor(t, ch, walker.Event{Path: "real.md", Kind: walker.EventChanged}, 2*time.Second)

	// Drain briefly and ensure no swap-file events leaked.
	deadline := time.After(300 * time.Millisecond)
	for {
		select {
		case ev := <-ch:
			if ev.Path != "real.md" {
				t.Errorf("unexpected event for swap-like file: %+v", ev)
			}
		case <-deadline:
			return
		}
	}
}

func TestWatch_continuesOnENOSPC(t *testing.T) {
	// We can't induce real ENOSPC portably; instead, ensure Start() does not
	// abort if a subdir cannot be added (simulate by pointing at a removed dir).
	root := t.TempDir()
	subDir := filepath.Join(root, "gone")
	if err := os.MkdirAll(subDir, 0o755); err != nil {
		t.Fatal(err)
	}
	w, err := walker.New(walker.Options{Root: root, Extensions: []string{".md"}})
	if err != nil {
		t.Fatal(err)
	}
	if err := os.RemoveAll(subDir); err != nil {
		t.Fatal(err)
	}
	ch := make(chan walker.Event, 4)
	stop, err := w.Start(ch)
	if !errors.Is(err, nil) {
		// We tolerate but log; we must not abort with hard failure.
		t.Logf("Start() returned %v; expected to continue without panic", err)
	}
	if stop != nil {
		stop()
	}
}

• Step 2: Run, expect failure

go test ./internal/walker/... -v -run TestWatch

Expected: undefined Start, Event, EventChanged, EventRemoved.

• Step 3: Implement watch.go

// internal/walker/watch.go
package walker

import (
	"errors"
	"io/fs"
	"log/slog"
	"os"
	"path/filepath"
	"strings"
	"sync"
	"syscall"

	"github.com/fsnotify/fsnotify"
)

// EventKind discriminates walker events.
type EventKind int

const (
	EventChanged EventKind = iota + 1 // file is new or modified
	EventRemoved                      // file is gone
)

// Event is the walker's notification primitive: repo-relative path + kind.
type Event struct {
	Path string
	Kind EventKind
}

// Start begins watching the tree. Events are sent on out (caller must drain).
// Returns a stop func that closes the watcher and waits for the goroutine to exit.
func (w *Walker) Start(out chan<- Event) (stop func(), err error) {
	watcher, err := fsnotify.NewWatcher()
	if err != nil {
		return nil, err
	}
	// Subscribe to every directory under root that survives excludes.
	if err := w.addDirsRecursive(watcher, w.opts.Root); err != nil {
		// Subscription errors (e.g. ENOSPC) are logged but not fatal.
		slog.Warn("walker: watcher add failed", "err", err)
	}
	done := make(chan struct{})
	go w.loop(watcher, out, done)
	stop = func() {
		_ = watcher.Close()
		<-done
	}
	return stop, nil
}

func (w *Walker) addDirsRecursive(watcher *fsnotify.Watcher, dir string) error {
	return filepath.WalkDir(dir, func(p string, d fs.DirEntry, err error) error {
		if err != nil {
			return nil // best-effort
		}
		if !d.IsDir() {
			return nil
		}
		rel, rerr := filepath.Rel(w.opts.Root, p)
		if rerr != nil {
			return nil
		}
		rel = filepath.ToSlash(rel)
		if rel != "." && w.exclude.Match(rel) {
			return fs.SkipDir
		}
		if err := watcher.Add(p); err != nil {
			if errors.Is(err, syscall.ENOSPC) {
				slog.Warn("walker: inotify watch limit reached; subtree will not receive live updates",
					"path", p,
					"hint", "raise fs.inotify.max_user_watches via sysctl")
				// Don't keep trying deeper; we'd only fail the same way.
				return fs.SkipDir
			}
			slog.Warn("walker: watcher.Add failed", "path", p, "err", err)
		}
		return nil
	})
}

func (w *Walker) loop(watcher *fsnotify.Watcher, out chan<- Event, done chan<- struct{}) {
	defer close(done)
	for {
		select {
		case ev, ok := <-watcher.Events:
			if !ok {
				return
			}
			w.handleFSEvent(watcher, ev, out)
		case err, ok := <-watcher.Errors:
			if !ok {
				return
			}
			slog.Warn("walker: fsnotify error", "err", err)
		}
	}
}

// swapSuffixes are editor temp/swap files we ignore entirely.
var swapSuffixes = []string{"~", ".swp", ".swx", ".swo", ".tmp"}

func isSwapName(name string) bool {
	for _, s := range swapSuffixes {
		if strings.HasSuffix(name, s) {
			return true
		}
	}
	// Vim's atomic-write sentinel.
	if name == "4913" {
		return true
	}
	return false
}

func (w *Walker) handleFSEvent(watcher *fsnotify.Watcher, ev fsnotify.Event, out chan<- Event) {
	rel, err := filepath.Rel(w.opts.Root, ev.Name)
	if err != nil {
		return
	}
	rel = filepath.ToSlash(rel)
	if isSwapName(filepath.Base(rel)) {
		return
	}

	// If it's a new directory, add it to the watcher.
	if ev.Has(fsnotify.Create) {
		info, statErr := os.Stat(ev.Name)
		if statErr == nil && info.IsDir() {
			if !w.exclude.Match(rel) {
				_ = w.addDirsRecursive(watcher, ev.Name)
			}
			return
		}
	}

	if w.exclude.Match(rel) || !w.matchesExt(rel) {
		return
	}

	w.mu.Lock()
	if ev.Has(fsnotify.Remove) || ev.Has(fsnotify.Rename) {
		delete(w.files, rel)
		w.mu.Unlock()
		out <- Event{Path: rel, Kind: EventRemoved}
		return
	}
	if ev.Has(fsnotify.Create) || ev.Has(fsnotify.Write) {
		w.files[rel] = struct{}{}
		w.mu.Unlock()
		out <- Event{Path: rel, Kind: EventChanged}
		return
	}
	w.mu.Unlock()
}

// (compile-time assertion that sync is used elsewhere)
var _ = sync.RWMutex{}

• Step 4: Run, expect pass

go test ./internal/walker/... -v

Expected: all tests PASS. (The fsnotify-based tests can flake on slow CI; if you see flakes locally, raise the timeout in waitFor.)

• Step 5: Commit

git add internal/walker/watch.go internal/walker/watch_test.go
git commit -m "wiki-browser: walker — fsnotify live updates with swap-file filtering"

Task 6: Walker — debounce + Subscribe API

Coalesce bursty events through a 300 ms quiet window per path. The public output is Subscribe(ctx) <-chan Event.

Files:

• Modify: internal/walker/walker.go (add Subscribe)

• Create: internal/walker/debounce.go

• Test: internal/walker/debounce_test.go

• Step 1: Write the failing test

// internal/walker/debounce_test.go
package walker_test

import (
	"context"
	"os"
	"path/filepath"
	"testing"
	"time"

	"github.com/getorcha/wiki-browser/internal/walker"
)

func TestSubscribe_coalescesBurstyEvents(t *testing.T) {
	root := t.TempDir()
	w, err := walker.New(walker.Options{Root: root, Extensions: []string{".md"}})
	if err != nil {
		t.Fatal(err)
	}
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()
	ch := w.Subscribe(ctx)

	// Burst: write a file 10 times rapidly. Expect exactly one Changed event.
	target := filepath.Join(root, "burst.md")
	for i := 0; i < 10; i++ {
		if err := os.WriteFile(target, []byte{byte(i)}, 0o644); err != nil {
			t.Fatal(err)
		}
		time.Sleep(20 * time.Millisecond)
	}
	// Wait for the debounce window to elapse plus a margin.
	deadline := time.After(700 * time.Millisecond)
	got := 0
	for {
		select {
		case ev := <-ch:
			if ev.Path == "burst.md" {
				got++
			}
		case <-deadline:
			if got != 1 {
				t.Errorf("expected 1 coalesced event, got %d", got)
			}
			return
		}
	}
}

• Step 2: Run, expect failure

go test ./internal/walker/... -v -run TestSubscribe

Expected: undefined Subscribe.

• Step 3: Implement debounce.go

// internal/walker/debounce.go
package walker

import (
	"context"
	"sync"
	"time"
)

// DebounceWindow is the quiet period after the last event for a given path
// before emitting downstream. 300 ms balances coalescing a `git pull`'s burst
// against perceived staleness for an interactive edit.
const DebounceWindow = 300 * time.Millisecond

type debouncer struct {
	mu      sync.Mutex
	pending map[string]*time.Timer
	out     chan<- Event
}

func newDebouncer(out chan<- Event) *debouncer {
	return &debouncer{
		pending: make(map[string]*time.Timer),
		out:     out,
	}
}

func (d *debouncer) push(ctx context.Context, ev Event) {
	d.mu.Lock()
	defer d.mu.Unlock()
	if t, ok := d.pending[ev.Path]; ok {
		t.Stop()
	}
	final := ev // capture by value
	d.pending[ev.Path] = time.AfterFunc(DebounceWindow, func() {
		d.mu.Lock()
		delete(d.pending, final.Path)
		d.mu.Unlock()
		select {
		case d.out <- final:
		case <-ctx.Done():
		}
	})
}

• Step 4: Implement Subscribe on Walker

Append to internal/walker/walker.go:

// Subscribe returns a channel of debounced Events. The walker takes care of
// starting the watcher on first call; the channel closes when ctx is cancelled.
func (w *Walker) Subscribe(ctx context.Context) <-chan Event {
	out := make(chan Event, 64)
	raw := make(chan Event, 64)
	stop, err := w.Start(raw)
	if err != nil {
		// Surface a single error event then close; callers should handle.
		go func() { close(out) }()
		return out
	}
	d := newDebouncer(out)
	go func() {
		defer stop()
		defer close(out)
		for {
			select {
			case ev, ok := <-raw:
				if !ok {
					return
				}
				d.push(ctx, ev)
			case <-ctx.Done():
				return
			}
		}
	}()
	return out
}

Add import "context" to walker.go if not already present.

• Step 5: Run, expect pass

go test ./internal/walker/... -v

Expected: all walker tests PASS.

• Step 6: Commit

git add internal/walker
git commit -m "wiki-browser: walker — debounced Subscribe API"

Task 7: Render — Document type and dispatch

Set up the Render entry point and dispatch by file extension.

Files:

• Create: internal/render/render.go

• Test: internal/render/render_test.go

• Step 1: Write the failing tests

// internal/render/render_test.go
package render_test

import (
	"os"
	"path/filepath"
	"strings"
	"testing"

	"github.com/getorcha/wiki-browser/internal/render"
)

func TestRender_dispatchesByExtension(t *testing.T) {
	dir := t.TempDir()
	md := filepath.Join(dir, "a.md")
	if err := os.WriteFile(md, []byte("# Title\n\nbody"), 0o644); err != nil {
		t.Fatal(err)
	}
	doc, err := render.Render(md)
	if err != nil {
		t.Fatal(err)
	}
	if !strings.Contains(doc.HTML, "<h1") {
		t.Errorf("expected rendered MD to contain <h1>, got: %s", doc.HTML)
	}
	if doc.Title != "Title" {
		t.Errorf("Title = %q, want %q", doc.Title, "Title")
	}
}

func TestRender_unknownExtensionFails(t *testing.T) {
	dir := t.TempDir()
	p := filepath.Join(dir, "x.txt")
	if err := os.WriteFile(p, []byte("nope"), 0o644); err != nil {
		t.Fatal(err)
	}
	if _, err := render.Render(p); err == nil {
		t.Error("expected error for unknown extension")
	}
}

• Step 2: Run, expect failure

go test ./internal/render/... -v -run TestRender_dispatch

Expected: undefined render.Render, render.Document.

• Step 3: Implement skeleton render.go

// internal/render/render.go
package render

import (
	"fmt"
	"path/filepath"
	"strings"
)

// Document is a fully-rendered standalone HTML document, plus metadata used by
// the index and the server's iframe-injection logic.
type Document struct {
	HTML        string // complete HTML5 document
	PlainText   string // for FTS body indexing
	Title       string // front-matter title or first H1, fallback: filename
	HasMermaid  bool   // true if source contained at least one mermaid fence
}

// Render turns a file at absPath into a Document. Dispatches by extension.
func Render(absPath string) (*Document, error) {
	switch strings.ToLower(filepath.Ext(absPath)) {
	case ".md":
		return renderMarkdown(absPath)
	case ".html":
		return renderHTML(absPath)
	default:
		return nil, fmt.Errorf("render: unsupported extension for %s", absPath)
	}
}

Stub the implementations so the package compiles:

// internal/render/markdown.go (stub for now)
package render

import "fmt"

func renderMarkdown(absPath string) (*Document, error) {
	return nil, fmt.Errorf("renderMarkdown: not implemented")
}

// internal/render/html.go (stub for now)
package render

import "fmt"

func renderHTML(absPath string) (*Document, error) {
	return nil, fmt.Errorf("renderHTML: not implemented")
}

• Step 4: Run; expect TestRender_unknownExtensionFails to PASS, dispatch test to FAIL with "not implemented"

go test ./internal/render/... -v -run TestRender_dispatch

Expected: dispatch test fails (renderMarkdown stub). Unknown-ext test passes.

• Step 5: Commit (skeleton — tests will pass after Task 8)

git add internal/render
git commit -m "wiki-browser: render — Document type and extension dispatch"

Task 8: Render — Markdown via goldmark + chroma + mermaid extension

Wire goldmark with GFM, footnotes, definition lists, autolinks, front-matter, chroma highlighting, and a custom extension that emits <pre class="mermaid"> for ```mermaid fences.

Files:

• Modify: internal/render/markdown.go

• Create: internal/render/mermaid_extension.go

• Test: internal/render/markdown_test.go

• Create: internal/render/testdata/basic.md, testdata/basic.golden.html

• Create: internal/render/testdata/gfm.md, testdata/gfm.golden.html

• Create: internal/render/testdata/code.md, testdata/code.golden.html

• Create: internal/render/testdata/mermaid.md, testdata/mermaid.golden.html

• Create: internal/render/testdata/frontmatter.md, testdata/frontmatter.golden.html

• Step 1: Write the failing test (golden-file)

// internal/render/markdown_test.go
package render

import (
	"flag"
	"os"
	"path/filepath"
	"strings"
	"testing"
)

var update = flag.Bool("update", false, "update golden files")

func TestRenderMarkdown_goldens(t *testing.T) {
	cases := []struct {
		name    string
		hasMerm bool
		title   string
	}{
		{"basic", false, "Hello"},
		{"gfm", false, "GFM"},
		{"code", false, "Code"},
		{"mermaid", true, "Mermaid"},
		{"frontmatter", false, "From front matter"},
	}
	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			in := filepath.Join("testdata", tc.name+".md")
			doc, err := Render(in)
			if err != nil {
				t.Fatal(err)
			}
			if doc.HasMermaid != tc.hasMerm {
				t.Errorf("HasMermaid = %v, want %v", doc.HasMermaid, tc.hasMerm)
			}
			if doc.Title != tc.title {
				t.Errorf("Title = %q, want %q", doc.Title, tc.title)
			}
			golden := filepath.Join("testdata", tc.name+".golden.html")
			if *update {
				if err := os.WriteFile(golden, []byte(doc.HTML), 0o644); err != nil {
					t.Fatal(err)
				}
				return
			}
			want, err := os.ReadFile(golden)
			if err != nil {
				t.Fatalf("read golden: %v", err)
			}
			if string(want) != doc.HTML {
				// Show a small diff hint.
				ml := func(s string) string {
					if len(s) > 200 {
						return s[:200] + "..."
					}
					return s
				}
				t.Errorf("HTML mismatch.\n--- want ---\n%s\n--- got ---\n%s",
					ml(string(want)), ml(doc.HTML))
			}
			// Positive structural assertions catch the class of bug where the
			// mermaid extension accidentally swallows non-mermaid fences.
			switch tc.name {
			case "code":
				if !strings.Contains(doc.HTML, `class="chroma"`) && !strings.Contains(doc.HTML, `<span class="`) {
					t.Errorf("code output lacks chroma highlight markup; mermaid extension may be intercepting non-mermaid fences")
				}
			case "mermaid":
				if !strings.Contains(doc.HTML, `<pre class="mermaid">`) {
					t.Errorf("mermaid output missing <pre class=\"mermaid\"> wrapper")
				}
			}
		})
	}
}

Test fixtures:

<!-- internal/render/testdata/basic.md -->
# Hello

A paragraph with **bold** and *italic*.

- one
- two

<!-- internal/render/testdata/gfm.md -->
# GFM

| a | b |
|---|---|
| 1 | 2 |

- [x] done
- [ ] todo

~~struck~~

<!-- internal/render/testdata/code.md -->
# Code

```go
package main

func main() {
    println("hi")
}
```

<!-- internal/render/testdata/mermaid.md -->
# Mermaid

```mermaid
graph TD
  A --> B
```

<!-- internal/render/testdata/frontmatter.md -->
---
title: From front matter
---

# Header that should not become Title

text

(Don't pre-create the .golden.html files — Step 5 generates them with -update.)

• Step 2: Implement the mermaid extension

The naive approach — registering a KindFencedCodeBlock renderer at the same priority as goldmark-highlighting and trying to "fall through" with WalkContinue — does NOT work in goldmark. Renderer registration is a single-slot map per kind, and lower-priority registrations overwrite higher-priority ones. The correct approach is a parser-level AST transformer that converts mermaid fences into a custom node BEFORE the highlighter sees them, plus a NodeRenderer for the new kind. Other fences remain KindFencedCodeBlock and chroma handles them normally.

// internal/render/mermaid_extension.go
package render

import (
	"github.com/yuin/goldmark"
	"github.com/yuin/goldmark/ast"
	"github.com/yuin/goldmark/parser"
	"github.com/yuin/goldmark/renderer"
	"github.com/yuin/goldmark/text"
	"github.com/yuin/goldmark/util"
)

// KindMermaidBlock is the AST kind for mermaid code fences after the
// transformer has rewritten them.
var KindMermaidBlock = ast.NewNodeKind("MermaidBlock")

type mermaidBlock struct {
	ast.BaseBlock
	Source []byte
}

func (n *mermaidBlock) Kind() ast.NodeKind            { return KindMermaidBlock }
func (n *mermaidBlock) Dump(src []byte, level int)    { ast.DumpHelper(n, src, level, nil, nil) }

// mermaidTransformer walks the parsed AST and replaces `mermaid`-fenced
// blocks with a *mermaidBlock so the highlighter never sees them.
type mermaidTransformer struct{ saw *bool }

func (t *mermaidTransformer) Transform(doc *ast.Document, reader text.Reader, pc parser.Context) {
	src := reader.Source()
	var toReplace []*ast.FencedCodeBlock
	_ = ast.Walk(doc, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
		if !entering {
			return ast.WalkContinue, nil
		}
		cb, ok := n.(*ast.FencedCodeBlock)
		if !ok {
			return ast.WalkContinue, nil
		}
		if string(cb.Language(src)) != "mermaid" {
			return ast.WalkContinue, nil
		}
		toReplace = append(toReplace, cb)
		return ast.WalkSkipChildren, nil
	})
	for _, cb := range toReplace {
		var body []byte
		lines := cb.Lines()
		for i := 0; i < lines.Len(); i++ {
			body = append(body, lines.At(i).Value(src)...)
		}
		*t.saw = true
		replacement := &mermaidBlock{Source: body}
		parent := cb.Parent()
		parent.ReplaceChild(parent, cb, replacement)
	}
}

// mermaidNodeRenderer emits <pre class="mermaid">…</pre> for *mermaidBlock.
// It only ever fires for our custom kind, so it cannot conflict with chroma.
type mermaidNodeRenderer struct{}

func (r *mermaidNodeRenderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer) {
	reg.Register(KindMermaidBlock, r.render)
}

func (r *mermaidNodeRenderer) render(w util.BufWriter, src []byte, n ast.Node, entering bool) (ast.WalkStatus, error) {
	if !entering {
		return ast.WalkContinue, nil
	}
	mb := n.(*mermaidBlock)
	_, _ = w.WriteString(`<pre class="mermaid">`)
	_, _ = w.Write(util.EscapeHTML(mb.Source))
	_, _ = w.WriteString("</pre>\n")
	return ast.WalkSkipChildren, nil
}

// mermaidExt wires the transformer + renderer.
type mermaidExt struct{ saw *bool }

func (e *mermaidExt) Extend(m goldmark.Markdown) {
	m.Parser().AddOptions(parser.WithASTTransformers(
		util.Prioritized(&mermaidTransformer{saw: e.saw}, 100),
	))
	m.Renderer().AddOptions(renderer.WithNodeRenderers(
		util.Prioritized(&mermaidNodeRenderer{}, 100),
	))
}