Reorganise docs around reader concern

[srid]

The docs site is reshuffled into six top-level sections — start, authoring, config, theme, extend, reference — each driven by a single reader concern instead of mixed under one overloaded guide/ umbrella with overlapping tips/ and four-deep start/resources/editors/… nesting. URLs are unchanged: every docs page already declared a flat slug: in frontmatter, so the folder reshuffle changes only the sidebar tree. Legacy paths (/guide/*, /tips/*, /start/resources/*) continue to redirect via docs/_redirects.

The reorganisation came out of a /talk design pass where Hickey flagged the old guide/ as a kitchen-sink concept and Lowy flagged tips/ as functional-decomposition leakage; the resulting cut tracks axes of change and reader persona rather than feature taxonomy.

Section mapping

Section	Reader concern	Contents
start/	"Get my site running"	install (nix, wsl, flake-module), editors (vim/vscode/obsidian/nota), emanote-template, sync
authoring/	"What do I type?"	markdown (+ callout, custom-style, embed, file-links), wikilinks, query, orgmode, daily-notes, math, mermaid, syntax-highlighting, adding-images, feed, export
config/	"How does the notebook compose?"	yaml-config, layer, emanoteignore, folder-note, folgezettel, i18n (+ fr, zh)
theme/	"How does it look?"	html-template + 13 sub-pages (sidebar, toc, ogp, search, …)
extend/	"How do I hook in code?"	lua-filters (+ diagrams, writing-filters), mcp
reference/	"What's the back-matter?"	known-issues, neuron (migration), zk, examples

docs/guide.md, docs/tips.md, docs/start/resources.md are gone; their child pages all moved into one of the six new homes above. The pre-existing flat slugs do all the URL-preservation work — no page needed a slug rewrite.

Why URLs survive without rewrites

Slug semantics: an explicit slug: in a note's frontmatter bypasses Emanote's file-path→URL pipeline entirely (Emanote.Model.Note.noteHtmlRoute). Every docs page already had one, so moving docs/guide/markdown.md → docs/authoring/markdown.md keeps the URL at /markdown. Wikilinks match by basename plus any path prefix (Commonmark.Extensions.WikiLink.allowedWikiLinks), so [[markdown]] resolves identically before and after — only two path-scoped wikilinks ([[guide/i18n]] in the FR/ZH demo pages) needed updating.

Reviewer follow-ups already landed

Hickey + Lowy were run in parallel on the primary commit; every finding ships as its own commit in this PR so the history reads as a refinement sequence:

• Hickey Start using HTML templating #1 — drop redundant query: path:./* blocks from the five new section folder-notes; the curated bullet lists carry editorial annotations the query cannot, and the sidebar already lists children.
• Hickey Handle wikilinks #2 — differentiate the folgezettel description across the authoring/ and config/ hubs so the dual placement actually carries distinct facets.
• Lowy Start using HTML templating #1 — regenerate .claude/rules/emanote-docs.md from .apm/ so the in-repo agent rules no longer point at the deleted docs/guide.md.
• Lowy Handle wikilinks #2 — backfill _redirects for /guide/html-template/{backlinks, dark-mode, focus-mode, right-panel} (legacy nested URLs that were missed in the prior redirects pass; slug-based canonical URLs were already fine).
• Lowy Switch to Heist #3 — update the docs-path comment in emanote/default/lua-filters/hello.lua (the matching Haddock comment in Filter.hs was updated in the primary commit).
• Lowy Heist splice for Pandoc #4 — rejected; would have added a path:./* query to start.md for symmetry with the new folder-notes, which directly contradicts Hickey Start using HTML templating #1. The bullets-only pattern wins because the bullets carry per-child editorial copy.

Try it locally

nix run github:srid/emanote/doc-org -- -L docs run

Generated by /do on Claude Code (model claude-opus-4-7).

[srid]

Hickey/Lowy Analysis

#	Lens	Finding	Disposition
1	Hickey	Redundant path:./* query + bullet list in five new section folder-notes	Fixed in this PR
2	Hickey	Folgezettel described in near-identical prose from both authoring and config	Fixed in this PR
3	Lowy	.claude/rules/emanote-docs.md not regenerated after .apm/ edit	Fixed in this PR
4	Lowy	Four _redirects entries missing for /guide/html-template/{backlinks,dark-mode,focus-mode,right-panel}	Fixed in this PR
5	Lowy	Stale docs/guide/lua-filters/… path in hello.lua docstring	Fixed in this PR
6	Lowy	Asymmetric: only start.md lacks a path:./* query (cross-validation flip)	No-op (rejected)

Cross-validation: findings 1 and 6 directly conflicted — Hickey wanted the path:./* query removed from the five new folder-notes, Lowy wanted it added to start.md for symmetry. Resolution: bullets-only is the right convention here because the curated bullet form carries one-line editorial copy per child page that a path:./* query cannot, and the sidebar tree already surfaces the full child set. Symmetry is achieved by following start.md's long-standing bullets-only pattern, not by mirroring the kitchen-sink pre-reorg guide.md / tips.md template that the new folder-notes initially inherited.

Hickey rationale

The six-section split landed and the earlier "concept multiplication" critique no longer applies. On the concrete diff, the two narrow findings were (a) two representations of one fact — the child set — duplicated in every new folder-note, and (b) the dual-hub placement of folgezettel lost its meaning because both hub entries described it identically. Both fixed.

Lowy rationale

The six-section split is genuine volatility-based decomposition — axes change independently (new input syntax → authoring; new YAML key → config; new template override → theme; new Lua API → extend). Cross-cutting placements checked out (folgezettel rightly in config with an authoring-side cross-reference; wikilinks in authoring; i18n and layer in config). _redirects is the correct receptacle for URL-evolution volatility. The defects surfaced were mechanical, not architectural: a missed apm install, an asymmetric _redirects block, and a stale path string in a shipped Lua filter — all fixed.

[srid]

Evidence

Sidebar tree, before vs. after. Same docs site, identical URLs, different organisation.

Before (master)	After (this PR)

The previous three-root layout (Getting Started, Guide, Tips, plus Examples) is replaced by six concern-oriented section roots — Getting Started, Authoring, Configuration, Theme, Extend, Reference — surfacing the docs structure directly in the top-level nav instead of burying it under "Guide" and "Tips".

[srid]

/do results

Step	Status	Duration	Verification
sync	✓	1s	git fetch ok; forge=github
research	✓	1m 36s	Mapped move impact; identified 2 scoped wikilinks + source/agent path refs to update
branch	✓	5s	On feature branch doc-org
implement	✓	5m 43s	60+ moves into 6 sections; 5 new folder-notes; wikilink/_redirects/CHANGELOG updates
check	✓	3m 22s	cabal build all green; static gen builds 219 routes; 3 remaining broken links are pre-existing
docs	✓	15s	CHANGELOG entry added
fmt	✓	13s	cabal-fmt + fourmolu + hlint + nixpkgs-fmt all passed
commit	✓	28s	Primary commit pushed
hickey+lowy	✓	23m 48s	Hickey 2/2 fixes applied; Lowy 3/4 applied, 1 rejected via cross-validation
police	—	25s	Skipped — docs-only diff (3 source-file edits are single-line comment fixes)
test	✓	1m 13s	cabal test all: 137/137
create-pr	✓	1m 5s	Draft PR #747 + Hickey/Lowy analysis comment
ci	✓	1m 5s	vira ci signed off on HEAD; e2e-static 60/60 (19 live/morph-only skipped)
evidence	✓	2m 53s	Sidebar before/after screenshots posted
Total		42m 28s

Slowest step: hickey+lowy (23m 48s)

Optimization suggestions

• hickey+lowy was 56% of total time. Two reviewer rounds + cross-validation reasoning ran in parallel sub-agents; the long tail was the second-round application + per-finding commits (6 separate commits with prehook lint per push). For follow-ups, consider batching finding-fix commits when they touch the same file family — the strict one-commit-per-finding rule paid off in PR history readability here, but on a more spread-out diff it amortises worse.
• implement was 5m 43s, mostly file moves. A reorg-shaped diff is a good candidate for scripting the moves first and reviewing the script before execution — the one mistake I had to fix (code-samples/ got nested by a pre-created destination dir) would have been caught by a dry-run.
• vira ci initially failed because the worktree was dirty (an untracked talk-docs-reorg.html artifact left over from the /talk pass). Suggest /talk --html artifacts emit to /tmp/ instead of $PWD so a follow-up /do run isn't blocked by an untracked file in the working tree.

Workflow completed at 2026-05-26T21:46:00Z.