diff --git a/.agency/code-police.md b/.agency/code-police.md
index 8a6ead248..4b9ec237f 100644
--- a/.agency/code-police.md
+++ b/.agency/code-police.md
@@ -8,7 +8,7 @@ The patterns here came out of [#672](https://github.com/srid/emanote/pull/672) (
 
 A docs-page `slug:` must be a **single path segment**, not a multi-segment slash-path. Two reasons:
 
-- The page's directory location already encodes hierarchy. A slug that re-encodes that hierarchy is duplicated state that drifts the moment one of the two moves (a page at `docs/guide/lua-filters/diagrams.md` with `slug: lua-filters/diagrams` carries the same path in two places — a rename of the parent or the page silently breaks the mirror).
+- The page's directory location already encodes hierarchy. A slug that re-encodes that hierarchy is duplicated state that drifts the moment one of the two moves (a page at `docs/extend/lua-filters/diagrams.md` with `slug: lua-filters/diagrams` carries the same path in two places — a rename of the parent or the page silently breaks the mirror).
 - Public URLs stay short and rename-stable. `[[diagrams]]` survives a future reshuffle of where the page sits in the docs tree; `[[lua-filters/diagrams]]` does not.
 
 Acceptable: `slug: diagrams`, `slug: yaml-config`, `slug: html-template`, `slug: i18n.fr` (single segment; dot-namespaced for locale or close variants).
@@ -17,7 +17,7 @@ Unacceptable: `slug: lua-filters/diagrams`, `slug: guide/whatever` — anything
 
 Wikilinks that reference the page use the single-segment form too: `[[diagrams]]`, not `[[lua-filters/diagrams]]`.
 
-> _New rule from this PR_: an early draft of [[diagrams]] used `slug: lua-filters/diagrams` to mirror its directory placement under `docs/guide/lua-filters/`. The slug was reduced to `diagrams` so a future move of the file doesn't invalidate every inbound wikilink.
+> _New rule from this PR_: an early draft of [[diagrams]] used `slug: lua-filters/diagrams` to mirror its directory placement under `docs/extend/lua-filters/`. The slug was reduced to `diagrams` so a future move of the file doesn't invalidate every inbound wikilink.
 
 ## docs-internal-wikilinks
 
@@ -26,7 +26,7 @@ When reviewing documentation changes under `docs/`, check internal documentation
 - Use wikilinks for references to existing docs pages, such as `[[yaml-config]]`, `[[html-template]]`, `[[wikilinks]]`, `[[layer]]`, `[[markdown]]`, `[[query]]`, `[[search]]`, and related guide pages.
 - Prefer wikilinks over raw relative Markdown links for internal docs references.
 - Replace bare mentions of concepts covered by existing docs pages with wikilinks, unless doing so would make the sentence noisy or misleading.
-- New or newly promoted guide pages should be linked from the nearest relevant index page, usually `docs/guide.md`.
+- New or newly promoted pages should be linked from the relevant section folder-note (`docs/authoring/authoring.md`, `docs/config/config.md`, `docs/theme/theme.md`, `docs/extend/extend.md`, `docs/reference/reference.md`, or `docs/start/start.md`).
 
 This rule is meant to catch isolated docs pages that repeat or mention existing Emanote concepts without connecting to the surrounding guide.
 
diff --git a/.agency/do.md b/.agency/do.md
index e03ffc9d7..6157d048c 100644
--- a/.agency/do.md
+++ b/.agency/do.md
@@ -21,7 +21,7 @@ Keep `README.md`, `docs/` (user documentation), and `CHANGELOG.md` (under the `U
 
 **CHANGELOG style: one concise line per PR.** Each user-facing change gets a single bullet — issue/PR number, the headline, and a one-line link to where the detail lives (a docs page, a deep-dive `[[wikilink]]`, the issue, …). The detail belongs on the docs page or in the PR description, not in the CHANGELOG. Multi-paragraph entries that re-explain the design are clutter; if a reviewer needs more than the link, the docs page wasn't pulling its weight.
 
-New or fixed **Markdown-syntax features** should be demonstrated in [`docs/guide/markdown.md`](../docs/guide/markdown.md) so the live example serves as both reference and regression check. A working `<details>` block, a new callout type, a new wiki-link form — each goes there as a real rendered sample, not just a CHANGELOG note.
+New or fixed **Markdown-syntax features** should be demonstrated in [`docs/authoring/markdown.md`](../docs/authoring/markdown.md) so the live example serves as both reference and regression check. A working `<details>` block, a new callout type, a new wiki-link form — each goes there as a real rendered sample, not just a CHANGELOG note.
 
 ## HACK comments
 
diff --git a/.apm/instructions/emanote-docs.instructions.md b/.apm/instructions/emanote-docs.instructions.md
index 9ac9244f3..f9c6c3352 100644
--- a/.apm/instructions/emanote-docs.instructions.md
+++ b/.apm/instructions/emanote-docs.instructions.md
@@ -9,7 +9,7 @@ When adding a new documentation page under `docs/`, give it an explicit simple `
 
 ## Wikilink internal references
 
-Connect docs pages to surrounding documentation with **wikilinks**, both when creating a new page and when editing existing ones. Link to the nearest relevant guide page — `[[yaml-config]]`, `[[html-template]]`, `[[wikilinks]]`, `[[layer]]`, etc. — instead of repeating concepts inline or leaving the page as an isolated note. Prefer wikilinks over raw relative Markdown links for any internal docs reference.
+Connect docs pages to surrounding documentation with **wikilinks**, both when creating a new page and when editing existing ones. Link to the nearest relevant docs page — `[[yaml-config]]`, `[[html-template]]`, `[[wikilinks]]`, `[[layer]]`, etc. — instead of repeating concepts inline or leaving the page as an isolated note. Prefer wikilinks over raw relative Markdown links for any internal docs reference.
 
 When you add prose that mentions another concept covered by an existing page, replace the bare phrase with a wikilink — e.g. write `… see [[html-template]] for the override mechanism …` rather than restating it. If no page covers the concept yet, this is a signal to consider promoting it to a dedicated page (see below) rather than burying the explanation inside an unrelated guide.
 
@@ -21,4 +21,18 @@ A section under one guide page should be **promoted to its own page** once any o
 - It carries reference material — splice tables, override protocols, configuration surfaces — that other pages need to wikilink to.
 - It documents a feature with its own slug-worthy concept name (`wikilinks`, `callout`, `folgezettel`, etc.).
 
-Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[<slug>]]` wikilink, and add the new page to `docs/guide.md`'s top-level list. Inbound links from other docs pages should point at the dedicated page.
+Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[<slug>]]` wikilink, and add the new page to the relevant section folder-note (`docs/start.md`, `docs/authoring.md`, `docs/config.md`, `docs/theme.md`, `docs/extend.md`, `docs/external-tools.md`, or `docs/reference.md`). Inbound links from other docs pages should point at the dedicated page.
+
+## Section layout
+
+`docs/` is organised into seven top-level sections, each driven by a reader concern:
+
+- `start/` — install + emanote-template.
+- `authoring/` — input formats, link syntax, graph structures (folder notes, folgezettel), render features the author types (math, mermaid, syntax-highlighting, images), frontmatter-declared outputs (feed, export).
+- `config/` — configuration surface: `yaml-config`, `layer`, `emanoteignore`, `i18n`.
+- `theme/` — HTML/Heist template customisation (`html-template` and its sub-pages only).
+- `extend/` — code-level extension: Pandoc Lua filters, MCP server.
+- `external-tools/` — third-party tools that integrate with Emanote: editors (vim, vscode, obsidian, nota), Syncthing sync, zk.
+- `reference/` — migration (`neuron`), examples, edge cases (`known-issues`).
+
+Place new pages in the section whose reader concern they match; cross-link via wikilinks rather than reorganising. The folder structure drives the sidebar tree; the page slug determines the public URL (see the slug rule above).
diff --git a/.claude/rules/emanote-docs.md b/.claude/rules/emanote-docs.md
index 69234def1..019b7d8d5 100644
--- a/.claude/rules/emanote-docs.md
+++ b/.claude/rules/emanote-docs.md
@@ -9,7 +9,7 @@ When adding a new documentation page under `docs/`, give it an explicit simple `
 
 ## Wikilink internal references
 
-Connect docs pages to surrounding documentation with **wikilinks**, both when creating a new page and when editing existing ones. Link to the nearest relevant guide page — `[[yaml-config]]`, `[[html-template]]`, `[[wikilinks]]`, `[[layer]]`, etc. — instead of repeating concepts inline or leaving the page as an isolated note. Prefer wikilinks over raw relative Markdown links for any internal docs reference.
+Connect docs pages to surrounding documentation with **wikilinks**, both when creating a new page and when editing existing ones. Link to the nearest relevant docs page — `[[yaml-config]]`, `[[html-template]]`, `[[wikilinks]]`, `[[layer]]`, etc. — instead of repeating concepts inline or leaving the page as an isolated note. Prefer wikilinks over raw relative Markdown links for any internal docs reference.
 
 When you add prose that mentions another concept covered by an existing page, replace the bare phrase with a wikilink — e.g. write `… see [[html-template]] for the override mechanism …` rather than restating it. If no page covers the concept yet, this is a signal to consider promoting it to a dedicated page (see below) rather than burying the explanation inside an unrelated guide.
 
@@ -21,4 +21,18 @@ A section under one guide page should be **promoted to its own page** once any o
 - It carries reference material — splice tables, override protocols, configuration surfaces — that other pages need to wikilink to.
 - It documents a feature with its own slug-worthy concept name (`wikilinks`, `callout`, `folgezettel`, etc.).
 
-Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[<slug>]]` wikilink, and add the new page to `docs/guide.md`'s top-level list. Inbound links from other docs pages should point at the dedicated page.
+Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[<slug>]]` wikilink, and add the new page to the relevant section folder-note (`docs/start.md`, `docs/authoring.md`, `docs/config.md`, `docs/theme.md`, `docs/extend.md`, `docs/external-tools.md`, or `docs/reference.md`). Inbound links from other docs pages should point at the dedicated page.
+
+## Section layout
+
+`docs/` is organised into seven top-level sections, each driven by a reader concern:
+
+- `start/` — install + emanote-template.
+- `authoring/` — input formats, link syntax, graph structures (folder notes, folgezettel), render features the author types (math, mermaid, syntax-highlighting, images), frontmatter-declared outputs (feed, export).
+- `config/` — configuration surface: `yaml-config`, `layer`, `emanoteignore`, `i18n`.
+- `theme/` — HTML/Heist template customisation (`html-template` and its sub-pages only).
+- `extend/` — code-level extension: Pandoc Lua filters, MCP server.
+- `external-tools/` — third-party tools that integrate with Emanote: editors (vim, vscode, obsidian, nota), Syncthing sync, zk.
+- `reference/` — migration (`neuron`), examples, edge cases (`known-issues`).
+
+Place new pages in the section whose reader concern they match; cross-link via wikilinks rather than reorganising. The folder structure drives the sidebar tree; the page slug determines the public URL (see the slug rule above).
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 6ae0d3c49..d34b4aec4 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -1,6 +1,6 @@
 # AGENTS.md
 <!-- Generated by APM CLI from distributed .apm/ primitives -->
-<!-- Build ID: 5057858137bc -->
+<!-- Build ID: 80b77a445a12 -->
 <!-- APM Version: 0.14.2 -->
 <!-- Source: local -->
 
@@ -13,7 +13,7 @@ When adding a new documentation page under `docs/`, give it an explicit simple `
 
 ## Wikilink internal references
 
-Connect docs pages to surrounding documentation with **wikilinks**, both when creating a new page and when editing existing ones. Link to the nearest relevant guide page — `[[yaml-config]]`, `[[html-template]]`, `[[wikilinks]]`, `[[layer]]`, etc. — instead of repeating concepts inline or leaving the page as an isolated note. Prefer wikilinks over raw relative Markdown links for any internal docs reference.
+Connect docs pages to surrounding documentation with **wikilinks**, both when creating a new page and when editing existing ones. Link to the nearest relevant docs page — `[[yaml-config]]`, `[[html-template]]`, `[[wikilinks]]`, `[[layer]]`, etc. — instead of repeating concepts inline or leaving the page as an isolated note. Prefer wikilinks over raw relative Markdown links for any internal docs reference.
 
 When you add prose that mentions another concept covered by an existing page, replace the bare phrase with a wikilink — e.g. write `… see [[html-template]] for the override mechanism …` rather than restating it. If no page covers the concept yet, this is a signal to consider promoting it to a dedicated page (see below) rather than burying the explanation inside an unrelated guide.
 
@@ -25,7 +25,21 @@ A section under one guide page should be **promoted to its own page** once any o
 - It carries reference material — splice tables, override protocols, configuration surfaces — that other pages need to wikilink to.
 - It documents a feature with its own slug-worthy concept name (`wikilinks`, `callout`, `folgezettel`, etc.).
 
-Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[<slug>]]` wikilink, and add the new page to `docs/guide.md`'s top-level list. Inbound links from other docs pages should point at the dedicated page.
+Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[<slug>]]` wikilink, and add the new page to the relevant section folder-note (`docs/start.md`, `docs/authoring.md`, `docs/config.md`, `docs/theme.md`, `docs/extend.md`, `docs/external-tools.md`, or `docs/reference.md`). Inbound links from other docs pages should point at the dedicated page.
+
+## Section layout
+
+`docs/` is organised into seven top-level sections, each driven by a reader concern:
+
+- `start/` — install + emanote-template.
+- `authoring/` — input formats, link syntax, graph structures (folder notes, folgezettel), render features the author types (math, mermaid, syntax-highlighting, images), frontmatter-declared outputs (feed, export).
+- `config/` — configuration surface: `yaml-config`, `layer`, `emanoteignore`, `i18n`.
+- `theme/` — HTML/Heist template customisation (`html-template` and its sub-pages only).
+- `extend/` — code-level extension: Pandoc Lua filters, MCP server.
+- `external-tools/` — third-party tools that integrate with Emanote: editors (vim, vscode, obsidian, nota), Syncthing sync, zk.
+- `reference/` — migration (`neuron`), examples, edge cases (`known-issues`).
+
+Place new pages in the section whose reader concern they match; cross-link via wikilinks rather than reorganising. The folder structure drives the sidebar tree; the page slug determines the public URL (see the slug rule above).
 
 ---
 *This file was generated by APM CLI. Do not edit manually.*
diff --git a/docs/_redirects b/docs/_redirects
index 90acfdee2..a8bfea965 100644
--- a/docs/_redirects
+++ b/docs/_redirects
@@ -24,6 +24,10 @@
 /guide/html-template/breadcrumbs /breadcrumbs 301
 /guide/html-template/toc /toc 301
 /guide/html-template/ogp /ogp 301
+/guide/html-template/backlinks /backlinks 301
+/guide/html-template/dark-mode /dark-mode 301
+/guide/html-template/focus-mode /focus-mode 301
+/guide/html-template/right-panel /right-panel 301
 
 # Markdown features
 /guide/markdown/custom-style /custom-style 301
@@ -37,9 +41,10 @@
 /start/install/wsl /wsl 301
 /start/neuron /neuron 301
 /start/known-issues /known-issues 301
-/start/resources /resources 301
 
-# Resources
+# Resources (folder retired; pages flattened into /start and /reference)
+/resources /start 301
+/start/resources /start 301
 /start/resources/editors /editors 301
 /start/resources/emanote-template /emanote-template 301
 /start/resources/zk /zk 301
@@ -48,10 +53,22 @@
 /start/resources/editors/vim /vim 301
 /start/resources/editors/vscode /vscode 301
 
-# Tips
+# Tips (folder retired; pages absorbed into /authoring and /start)
+/tips /authoring 301
 /tips/adding-images /adding-images 301
 /tips/js /js 301
-/tips/js/math /tips/math 301
-/tips/js/mermaid /tips/mermaid 301
+/tips/js/math /math 301
+/tips/js/mermaid /mermaid 301
 /tips/js/syntax-highlighting /syntax-highlighting 301
+/tips/math /math 301
+/tips/mermaid /mermaid 301
+/tips/syntax-highlighting /syntax-highlighting 301
 /tips/sync /sync 301
+
+# Guide (umbrella retired; section split into authoring/config/theme/extend)
+/guide /authoring 301
+/guide/i18n /i18n 301
+/guide/wikilinks /wikilinks 301
+/guide/emanoteignore /emanoteignore 301
+/guide/mcp /mcp 301
+/guide/orgmode /orgmode 301
diff --git a/docs/authoring.md b/docs/authoring.md
new file mode 100644
index 000000000..dc2397674
--- /dev/null
+++ b/docs/authoring.md
@@ -0,0 +1,20 @@
+---
+slug: authoring
+order: 2
+---
+
+# Authoring
+
+What you type into a note — input formats, link syntax, graph structures, render features that an author reaches for from a Markdown buffer.
+
+- **[[markdown]]** — extensions on top of CommonMark: callouts, task lists, emojis, footnotes, footers
+- **[[wikilinks]]** — `[[…]]` syntax, broken / ambiguous link rendering, plus the structural variants that build the sidebar tree
+    - **[[folgezettel]]** — `#[[…]]` wikilinks (and the `folder-folgezettel:` flag) that declare parent/child structure
+    - **[[folder-note]]** — placing `foo.md` next to `foo/` (or `foo/index.md`) so a folder is itself a wikilink target
+- **[[query]]** — Obsidian-style embed queries for dynamic listings
+- **[[daily-notes]]** — date-stamped notes
+- **[[orgmode]]** — Org-mode notes alongside Markdown
+- **[[math]]**, **[[mermaid]]**, **[[syntax-highlighting]]**, **[[adding-images]]** — built-in render features the author types directly
+- **[[feed]]**, **[[export]]** — frontmatter-declared outputs
+
+Cross-cutting: configuration that affects what you can type lives under [[config]] ([[yaml-config]], [[layer]]); output customisation lives under [[theme]]; code-level extension lives under [[extend]].
diff --git a/docs/tips/adding-images.md b/docs/authoring/adding-images.md
similarity index 100%
rename from docs/tips/adding-images.md
rename to docs/authoring/adding-images.md
diff --git a/docs/guide/daily-notes.md b/docs/authoring/daily-notes.md
similarity index 100%
rename from docs/guide/daily-notes.md
rename to docs/authoring/daily-notes.md
diff --git a/docs/guide/daily-notes/2025-03-14.md b/docs/authoring/daily-notes/2025-03-14.md
similarity index 100%
rename from docs/guide/daily-notes/2025-03-14.md
rename to docs/authoring/daily-notes/2025-03-14.md
diff --git a/docs/guide/daily-notes/2025-03-15.md b/docs/authoring/daily-notes/2025-03-15.md
similarity index 100%
rename from docs/guide/daily-notes/2025-03-15.md
rename to docs/authoring/daily-notes/2025-03-15.md
diff --git a/docs/guide/export.md b/docs/authoring/export.md
similarity index 100%
rename from docs/guide/export.md
rename to docs/authoring/export.md
diff --git a/docs/guide/feed.md b/docs/authoring/feed.md
similarity index 100%
rename from docs/guide/feed.md
rename to docs/authoring/feed.md
diff --git a/docs/guide/markdown.md b/docs/authoring/markdown.md
similarity index 100%
rename from docs/guide/markdown.md
rename to docs/authoring/markdown.md
diff --git a/docs/guide/markdown/Sample.txt b/docs/authoring/markdown/Sample.txt
similarity index 100%
rename from docs/guide/markdown/Sample.txt
rename to docs/authoring/markdown/Sample.txt
diff --git a/docs/guide/markdown/callout.md b/docs/authoring/markdown/callout.md
similarity index 100%
rename from docs/guide/markdown/callout.md
rename to docs/authoring/markdown/callout.md
diff --git a/docs/guide/markdown/cat.ogg b/docs/authoring/markdown/cat.ogg
similarity index 100%
rename from docs/guide/markdown/cat.ogg
rename to docs/authoring/markdown/cat.ogg
diff --git a/docs/guide/markdown/code-samples/c-code.c b/docs/authoring/markdown/code-samples/c-code.c
similarity index 100%
rename from docs/guide/markdown/code-samples/c-code.c
rename to docs/authoring/markdown/code-samples/c-code.c
diff --git a/docs/guide/markdown/code-samples/config-demo.toml b/docs/authoring/markdown/code-samples/config-demo.toml
similarity index 100%
rename from docs/guide/markdown/code-samples/config-demo.toml
rename to docs/authoring/markdown/code-samples/config-demo.toml
diff --git a/docs/guide/markdown/code-samples/data-demo.json b/docs/authoring/markdown/code-samples/data-demo.json
similarity index 100%
rename from docs/guide/markdown/code-samples/data-demo.json
rename to docs/authoring/markdown/code-samples/data-demo.json
diff --git a/docs/guide/markdown/code-samples/haskell-code.hs b/docs/authoring/markdown/code-samples/haskell-code.hs
similarity index 100%
rename from docs/guide/markdown/code-samples/haskell-code.hs
rename to docs/authoring/markdown/code-samples/haskell-code.hs
diff --git a/docs/guide/markdown/code-samples/styles-demo.css b/docs/authoring/markdown/code-samples/styles-demo.css
similarity index 100%
rename from docs/guide/markdown/code-samples/styles-demo.css
rename to docs/authoring/markdown/code-samples/styles-demo.css
diff --git a/docs/guide/markdown/custom-style.md b/docs/authoring/markdown/custom-style.md
similarity index 100%
rename from docs/guide/markdown/custom-style.md
rename to docs/authoring/markdown/custom-style.md
diff --git a/docs/guide/markdown/cyclic-embed-demo.md b/docs/authoring/markdown/cyclic-embed-demo.md
similarity index 100%
rename from docs/guide/markdown/cyclic-embed-demo.md
rename to docs/authoring/markdown/cyclic-embed-demo.md
diff --git a/docs/guide/markdown/death-note.mp4 b/docs/authoring/markdown/death-note.mp4
similarity index 100%
rename from docs/guide/markdown/death-note.mp4
rename to docs/authoring/markdown/death-note.mp4
diff --git a/docs/guide/markdown/disaster-girl.jpg b/docs/authoring/markdown/disaster-girl.jpg
similarity index 100%
rename from docs/guide/markdown/disaster-girl.jpg
rename to docs/authoring/markdown/disaster-girl.jpg
diff --git a/docs/guide/markdown/embed.md b/docs/authoring/markdown/embed.md
similarity index 100%
rename from docs/guide/markdown/embed.md
rename to docs/authoring/markdown/embed.md
diff --git a/docs/guide/markdown/external-link-icon.svg b/docs/authoring/markdown/external-link-icon.svg
similarity index 100%
rename from docs/guide/markdown/external-link-icon.svg
rename to docs/authoring/markdown/external-link-icon.svg
diff --git a/docs/guide/markdown/file-links.md b/docs/authoring/markdown/file-links.md
similarity index 100%
rename from docs/guide/markdown/file-links.md
rename to docs/authoring/markdown/file-links.md
diff --git a/docs/guide/markdown/git-cheat-sheet-education.pdf b/docs/authoring/markdown/git-cheat-sheet-education.pdf
similarity index 100%
rename from docs/guide/markdown/git-cheat-sheet-education.pdf
rename to docs/authoring/markdown/git-cheat-sheet-education.pdf
diff --git a/docs/guide/markdown/hello-badge.svg b/docs/authoring/markdown/hello-badge.svg
similarity index 100%
rename from docs/guide/markdown/hello-badge.svg
rename to docs/authoring/markdown/hello-badge.svg
diff --git a/docs/guide/markdown/pIqaD.svg b/docs/authoring/markdown/pIqaD.svg
similarity index 100%
rename from docs/guide/markdown/pIqaD.svg
rename to docs/authoring/markdown/pIqaD.svg
diff --git a/docs/tips/math.md b/docs/authoring/math.md
similarity index 100%
rename from docs/tips/math.md
rename to docs/authoring/math.md
diff --git a/docs/tips/mermaid.md b/docs/authoring/mermaid.md
similarity index 100%
rename from docs/tips/mermaid.md
rename to docs/authoring/mermaid.md
diff --git a/docs/guide/orgmode.org b/docs/authoring/orgmode.org
similarity index 74%
rename from docs/guide/orgmode.org
rename to docs/authoring/orgmode.org
index 4e303e2ea..177de5705 100644
--- a/docs/guide/orgmode.org
+++ b/docs/authoring/orgmode.org
@@ -15,7 +15,7 @@ Here is a handpicked selection of syntatic features of Org Mode as particularly
 
 *** Code blocks 
 
-See [[file:../tips/syntax-highlighting.md][Syntax Highlighting]] for general information.
+See [[file:syntax-highlighting.md][Syntax Highlighting]] for general information.
 
 #+NAME: factorial
 #+BEGIN_SRC haskell :results silent :exports code :var n=0
@@ -25,7 +25,7 @@ See [[file:../tips/syntax-highlighting.md][Syntax Highlighting]] for general inf
 
 *** LaTeX 
 
-See [[file:../tips/math.md][Math]] for general information.
+See [[file:math.md][Math]] for general information.
 
 The radius of the sun is R_sun = 6.96 x 10^8 m.  On the other hand,
 the radius of Alpha Centauri is R_{Alpha Centauri} = 1.28 x R_{sun}.
@@ -38,4 +38,4 @@ If $a^2=b$ and \( b=2 \), then the solution must be
 either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \]
 
 ** Limitations
-- While =#+TITLE= is recognized, most other metadata are not recognized yet. [[file:lua-filters.md][Pandoc Lua filters]] are the exception: use one =#+PANDOC_FILTERS_PARSE: path/to/filter.lua= keyword per parse-time filter, or =#+PANDOC_FILTERS_RENDER_HTML: path/to/filter.lua= per render-time HTML filter. Store other file-associated metadata in a separate [[file:yaml-config.md][YAML file]].
+- While =#+TITLE= is recognized, most other metadata are not recognized yet. [[file:../extend/lua-filters.md][Pandoc Lua filters]] are the exception: use one =#+PANDOC_FILTERS_PARSE: path/to/filter.lua= keyword per parse-time filter, or =#+PANDOC_FILTERS_RENDER_HTML: path/to/filter.lua= per render-time HTML filter. Store other file-associated metadata in a separate [[file:../config/yaml-config.md][YAML file]].
diff --git a/docs/guide/orgmode.yaml b/docs/authoring/orgmode.yaml
similarity index 100%
rename from docs/guide/orgmode.yaml
rename to docs/authoring/orgmode.yaml
diff --git a/docs/guide/query.md b/docs/authoring/query.md
similarity index 100%
rename from docs/guide/query.md
rename to docs/authoring/query.md
diff --git a/docs/tips/syntax-highlighting.md b/docs/authoring/syntax-highlighting.md
similarity index 100%
rename from docs/tips/syntax-highlighting.md
rename to docs/authoring/syntax-highlighting.md
diff --git a/docs/guide/wikilinks.md b/docs/authoring/wikilinks.md
similarity index 85%
rename from docs/guide/wikilinks.md
rename to docs/authoring/wikilinks.md
index f0381d38f..b12200b53 100644
--- a/docs/guide/wikilinks.md
+++ b/docs/authoring/wikilinks.md
@@ -10,13 +10,17 @@ You can link to a note by placing the filename (without extension) inside double
 
 See [[folgezettel]] for the special wiki-link form used to declare the [[sidebar]] (and [[uptree]]) hierarchy.
 
+## Folder notes
+
+A wiki-link can resolve to a [[folder-note|folder note]] — a `foo.md` placed next to a `foo/` directory (or `foo/index.md` inside it) — so `[[guide]]` links to the page that represents the whole folder.
+
 ## Anchors
 
 Wiki-links [do not yet](https://github.com/srid/emanote/discussions/105) support anchor links. Regular Markdown links do — for example, [example link](./markdown.md#lists).
 
 ## Regular Markdown note links
 
-Regular Markdown links to notes can include their `.md` or `.org` extension, but they don't have to. `[Neuron](../start/neuron)` and `[Neuron](../start/neuron.md)` both render as [Neuron](../start/neuron). Folder-note links such as `[Guide](../guide)` resolve the same way before Emanote falls back to looking for a static file at that path.
+Regular Markdown links to notes can include their `.md` or `.org` extension, but they don't have to. `[Neuron](../reference/neuron)` and `[Neuron](../reference/neuron.md)` both render as [Neuron](../reference/neuron). Folder-note links such as `[Reference](../reference)` resolve the same way before Emanote falls back to looking for a static file at that path.
 
 ## Broken links
 
diff --git a/docs/guide/folder-note.md b/docs/authoring/wikilinks/folder-note.md
similarity index 100%
rename from docs/guide/folder-note.md
rename to docs/authoring/wikilinks/folder-note.md
diff --git a/docs/guide/folgezettel.md b/docs/authoring/wikilinks/folgezettel.md
similarity index 100%
rename from docs/guide/folgezettel.md
rename to docs/authoring/wikilinks/folgezettel.md
diff --git a/docs/config.md b/docs/config.md
new file mode 100644
index 000000000..13655580e
--- /dev/null
+++ b/docs/config.md
@@ -0,0 +1,15 @@
+---
+slug: config
+order: 3
+---
+
+# Configuration
+
+The configuration surface — YAML files, layer mounts, ignore patterns, language toggles. Read this section before [[theme|theming]] or writing [[extend|extensions]]; both consume the surfaces defined here.
+
+- **[[yaml-config]]** — site and per-note metadata, cascade rules
+- **[[layer]]** — merging multiple notebook directories
+- **[[emanoteignore]]** — excluding files from the notebook model
+- **[[i18n]]** — internationalisation via `page.lang`
+
+Notebook-model semantics that flow from authoring choices (folder notes, structural wikilinks) live under [[authoring]].
diff --git a/docs/guide/emanoteignore.md b/docs/config/emanoteignore.md
similarity index 100%
rename from docs/guide/emanoteignore.md
rename to docs/config/emanoteignore.md
diff --git a/docs/guide/i18n.md b/docs/config/i18n.md
similarity index 100%
rename from docs/guide/i18n.md
rename to docs/config/i18n.md
diff --git a/docs/guide/i18n/i18n.fr.md b/docs/config/i18n/i18n.fr.md
similarity index 97%
rename from docs/guide/i18n/i18n.fr.md
rename to docs/config/i18n/i18n.fr.md
index 952e2649c..41d9c8cdb 100644
--- a/docs/guide/i18n/i18n.fr.md
+++ b/docs/config/i18n/i18n.fr.md
@@ -16,7 +16,7 @@ Cette page définit explicitement `page.lang: fr` dans sa
 
 Autres langues :
 
-- [[guide/i18n|English]]
+- [[i18n|English]]
 - [[i18n/i18n.zh|中文]]
 
 ## Ce qui change
diff --git a/docs/guide/i18n/i18n.zh.md b/docs/config/i18n/i18n.zh.md
similarity index 97%
rename from docs/guide/i18n/i18n.zh.md
rename to docs/config/i18n/i18n.zh.md
index 1328f1a55..6e5680b94 100644
--- a/docs/guide/i18n/i18n.zh.md
+++ b/docs/config/i18n/i18n.zh.md
@@ -13,7 +13,7 @@ page:
 
 其他语言：
 
-- [[guide/i18n|English]]
+- [[i18n|English]]
 - [[i18n/i18n.fr|Français]]
 
 ## 哪些内容会变化
diff --git a/docs/guide/layer.md b/docs/config/layer.md
similarity index 100%
rename from docs/guide/layer.md
rename to docs/config/layer.md
diff --git a/docs/guide/yaml-config.md b/docs/config/yaml-config.md
similarity index 96%
rename from docs/guide/yaml-config.md
rename to docs/config/yaml-config.md
index f8041cdb8..5dfceb9cb 100644
--- a/docs/guide/yaml-config.md
+++ b/docs/config/yaml-config.md
@@ -13,7 +13,7 @@ tags: [emanote/yaml/demo]
 
 Configure your site metadata, rendering configuration and such using YAML configuration. Create a `foo.yaml` alongside `foo.md` (see [[folder-note]]) or `foo/` folder, and those settings apply only to that route. The YAML structure is the same as your Markdown frontmatter, and vice-versa. Settings in the YAML frontmatter apply onto that Markdown route only; whereas settings in an individual .yaml file apply to that entire sub-route tree. Emanote does a deep-merge of the parent YAML configurations, so you can have children override only what's necessary. This is sometimes known as ["data cascade"](https://www.11ty.dev/docs/data-cascade/). The final merged YAML structure is passed to the HTML templates, of which you have full rendering control over.
 
-Notice how this page's sidebar colorscheme has [changed to green]{.greenery}? View [the source of this page](https://github.com/srid/emanote/blob/master/docs/guide/yaml-config.md) to see the magic involved. That CSS greenery you just saw too comes from YAML.
+Notice how this page's sidebar colorscheme has [changed to green]{.greenery}? View [the source of this page](https://github.com/srid/emanote/blob/master/docs/config/yaml-config.md) to see the magic involved. That CSS greenery you just saw too comes from YAML.
 
 >[!tip] Using in HTML templates
 > You can reference the YAML frontmatter config from [[html-template]]. See [here](https://github.com/srid/emanote/discussions/131#discussioncomment-1382189) for details.
diff --git a/docs/extend.md b/docs/extend.md
new file mode 100644
index 000000000..2f2caaede
--- /dev/null
+++ b/docs/extend.md
@@ -0,0 +1,11 @@
+---
+slug: extend
+order: 5
+---
+
+# Extend
+
+Add code that hooks into Emanote's pipeline or exposes it to external clients.
+
+- **[[lua-filters]]** — Pandoc Lua filters at parse-time and render-time (including bundled [[diagrams]] for d2/cetz)
+- **[[mcp]]** — Model Context Protocol server alongside the live server
diff --git a/docs/guide/lua-filters.md b/docs/extend/lua-filters.md
similarity index 100%
rename from docs/guide/lua-filters.md
rename to docs/extend/lua-filters.md
diff --git a/docs/guide/lua-filters/diagrams.md b/docs/extend/lua-filters/diagrams.md
similarity index 100%
rename from docs/guide/lua-filters/diagrams.md
rename to docs/extend/lua-filters/diagrams.md
diff --git a/docs/guide/lua-filters/writing-filters.md b/docs/extend/lua-filters/writing-filters.md
similarity index 100%
rename from docs/guide/lua-filters/writing-filters.md
rename to docs/extend/lua-filters/writing-filters.md
diff --git a/docs/guide/lua-filters/writing-filters/slides.md b/docs/extend/lua-filters/writing-filters/slides.md
similarity index 100%
rename from docs/guide/lua-filters/writing-filters/slides.md
rename to docs/extend/lua-filters/writing-filters/slides.md
diff --git a/docs/guide/mcp.md b/docs/extend/mcp.md
similarity index 98%
rename from docs/guide/mcp.md
rename to docs/extend/mcp.md
index 04dc1ad0e..d1e7baad4 100644
--- a/docs/guide/mcp.md
+++ b/docs/extend/mcp.md
@@ -69,7 +69,7 @@ Emanote advertises the notebook under the `emanote://` scheme as a single static
 
 | URI | MIME | What it returns |
 |---|---|---|
-| `emanote://export/metadata` | `application/json` | Metadata for every note — titles, source paths, parent routes, resolved links. Same shape as [`emanote export --format=metadata`](export.md). Use this to discover paths. |
+| `emanote://export/metadata` | `application/json` | Metadata for every note — titles, source paths, parent routes, resolved links. Same shape as [`emanote export --format=metadata`](../authoring/export.md). Use this to discover paths. |
 
 `resources/list` returns only the metadata export. Emanote intentionally does **not** enumerate one entry per note: that scales linearly with notebook size and inflates context on every poll. Clients discover note paths from `emanote://export/metadata` (every note's `filePath`) and the query tools below; the underlying files are read through the client's own filesystem tools (e.g. Claude Code's `Read`, Codex's local file access), not through MCP.
 
diff --git a/docs/external-tools.md b/docs/external-tools.md
new file mode 100644
index 000000000..df5466b05
--- /dev/null
+++ b/docs/external-tools.md
@@ -0,0 +1,12 @@
+---
+slug: external-tools
+order: 8
+---
+
+# External tools
+
+Third-party tools that talk to your Emanote notebook — editors that author it, sync engines that replicate it, alternative notebook formats Emanote can read.
+
+- **[[editors]]** — Vim, VS Code, Obsidian, Nota integrations
+- **[[sync]]** — syncing notes across devices with Syncthing
+- **[[zk]]** — running Emanote on a [zk](https://github.com/mickael-menu/zk) notebook
diff --git a/docs/start/resources/editors.md b/docs/external-tools/editors.md
similarity index 94%
rename from docs/start/resources/editors.md
rename to docs/external-tools/editors.md
index 2b0db3e12..6b71fe1f7 100644
--- a/docs/start/resources/editors.md
+++ b/docs/external-tools/editors.md
@@ -1,5 +1,5 @@
 ---
-order: 0
+order: 3
 slug: editors
 ---
 
diff --git a/docs/start/resources/editors/nota.md b/docs/external-tools/editors/nota.md
similarity index 100%
rename from docs/start/resources/editors/nota.md
rename to docs/external-tools/editors/nota.md
diff --git a/docs/start/resources/editors/obsmd.md b/docs/external-tools/editors/obsmd.md
similarity index 100%
rename from docs/start/resources/editors/obsmd.md
rename to docs/external-tools/editors/obsmd.md
diff --git a/docs/start/resources/editors/vim.md b/docs/external-tools/editors/vim.md
similarity index 100%
rename from docs/start/resources/editors/vim.md
rename to docs/external-tools/editors/vim.md
diff --git a/docs/start/resources/editors/vscode.md b/docs/external-tools/editors/vscode.md
similarity index 100%
rename from docs/start/resources/editors/vscode.md
rename to docs/external-tools/editors/vscode.md
diff --git a/docs/tips/sync.md b/docs/external-tools/sync.md
similarity index 98%
rename from docs/tips/sync.md
rename to docs/external-tools/sync.md
index d77a9f8fa..237dc4dbe 100644
--- a/docs/tips/sync.md
+++ b/docs/external-tools/sync.md
@@ -23,5 +23,3 @@ Git also acts as backup if you push your repository to a remote location (GitHub
 [^sup]: "superior" ... because when using Dropbox, Android phones (unlike desktop computers) cannot have automatic full-sync of files on disk.
 
 [^ios]: Obsidian can also synchronize notes between iOS and macOS [via iCloud](https://help.obsidian.md/Getting+started/Sync+your+notes+across+devices).
-
-#[[resources]]
diff --git a/docs/start/resources/zk.md b/docs/external-tools/zk.md
similarity index 100%
rename from docs/start/resources/zk.md
rename to docs/external-tools/zk.md
diff --git a/docs/guide.md b/docs/guide.md
deleted file mode 100644
index a5eb20531..000000000
--- a/docs/guide.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-slug: guide
-order: 2
----
-
-# Guide
-
-This guide covers Emanote's core features:
-
-- **[[markdown]]** — Markdown extensions: callouts, task lists, emojis, footnotes
-- **[[wikilinks]]** — `[[…]]` syntax, structural links, broken / ambiguous link rendering
-- **[[query]]** — Obsidian-style embed queries for dynamic content
-- **[[yaml-config]]** — Site metadata and per-page configuration
-- **[[lua-filters]]** — Pandoc Lua filter phases, bundled filters, and demos (including [[diagrams|inline-SVG diagrams]] from d2 and cetz)
-- **[[i18n|Internationalisation]]** — English and French pages using `page.lang`
-- **[[html-template]]** — Full HTML customization with Heist templates
-- **[[layer]]** — Merging multiple notebook directories
-
-```query
-path:./*
-```
diff --git a/docs/reference.md b/docs/reference.md
new file mode 100644
index 000000000..8f4d02888
--- /dev/null
+++ b/docs/reference.md
@@ -0,0 +1,14 @@
+---
+slug: reference
+order: 9
+---
+
+# Reference
+
+Back-matter: migration paths, the ecosystem around Emanote, and known edge cases.
+
+- **[[examples]]** — Emanote sites in the wild
+- **[[neuron]]** — migrating from neuron
+- **[[known-issues]]** — edge cases and workarounds
+
+For third-party tools that integrate with Emanote (editors, sync, alternative formats), see [[external-tools]].
diff --git a/docs/examples.md b/docs/reference/examples.md
similarity index 100%
rename from docs/examples.md
rename to docs/reference/examples.md
diff --git a/docs/start/known-issues.md b/docs/reference/known-issues.md
similarity index 100%
rename from docs/start/known-issues.md
rename to docs/reference/known-issues.md
diff --git a/docs/start/neuron.md b/docs/reference/neuron.md
similarity index 100%
rename from docs/start/neuron.md
rename to docs/reference/neuron.md
diff --git a/docs/start.md b/docs/start.md
index 87bda3784..53c96fca6 100644
--- a/docs/start.md
+++ b/docs/start.md
@@ -11,8 +11,14 @@ Follow these steps to get started with Emanote.
 1. Use your existing notebook, or create one from [[emanote-template]][^gh].
 1. Run `emanote run --port=8080` (or just `emanote`) in terminal after `cd`'ing to that notebook folder; this will launch the live server.
      - Or, if you only want to generate the HTML files (for deployment), run `mkdir /tmp/output; emanote gen /tmp/output`.
-2. Visit [[guide]] to learn more about Emanote, or [[examples]] to get inspired first.[^h]
+2. From there:[^h]
+    - **[[authoring]]** — what you can type into a note
+    - **[[config]]** — `yaml-config`, layers, `.emanoteignore`, i18n
+    - **[[theme]]** — customise the HTML output, [[neuron-layout|Neuron-like layout]]
+    - **[[extend]]** — Pandoc Lua filters, the MCP server
+    - **[[external-tools]]** — set up your [[editors|editor]], sync with [[sync|Syncthing]]
+    - **[[examples]]** — Emanote sites in the wild, for inspiration
 
 
 [^gh]: [[emanote-template]] also includes the GitHub Pages workflow for static site deployment.
-[^h]: If you are [Haskell](https://srid.ca/haskell) developer, see [[architecture]].
\ No newline at end of file
+[^h]: If you are a [Haskell](https://srid.ca/haskell) developer, see [[architecture]].
\ No newline at end of file
diff --git a/docs/start/resources/emanote-template.md b/docs/start/emanote-template.md
similarity index 98%
rename from docs/start/resources/emanote-template.md
rename to docs/start/emanote-template.md
index d681f5958..46b97f2d1 100644
--- a/docs/start/resources/emanote-template.md
+++ b/docs/start/emanote-template.md
@@ -1,5 +1,6 @@
 ---
 slug: emanote-template
+order: 2
 ---
 
 # emanote-template
diff --git a/docs/start/resources.md b/docs/start/resources.md
deleted file mode 100644
index 55578fa79..000000000
--- a/docs/start/resources.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-order: 15
-slug: resources
----
-
-# Resources
-
-Applications and resources relevant to Emanote.
-
-```query
-children:.
-```
\ No newline at end of file
diff --git a/docs/theme.md b/docs/theme.md
new file mode 100644
index 000000000..870f80888
--- /dev/null
+++ b/docs/theme.md
@@ -0,0 +1,11 @@
+---
+slug: theme
+order: 4
+---
+
+# Theme
+
+Customise the generated HTML via Heist templates. This is presentation only — model behaviour belongs under [[config]], and code-level rendering hooks belong under [[extend]] ([[lua-filters]]).
+
+- **[[html-template]]** — overriding the default Heist templates wholesale or per-fragment
+- **[[neuron-layout]]** — built-in preset that toggles [[sidebar]] / [[uptree]] / [[breadcrumbs]] / [[toc]] to mimic the Neuron look
diff --git a/docs/guide/html-template.md b/docs/theme/html-template.md
similarity index 100%
rename from docs/guide/html-template.md
rename to docs/theme/html-template.md
diff --git a/docs/guide/html-template/backlinks.md b/docs/theme/html-template/backlinks.md
similarity index 100%
rename from docs/guide/html-template/backlinks.md
rename to docs/theme/html-template/backlinks.md
diff --git a/docs/guide/html-template/breadcrumbs.md b/docs/theme/html-template/breadcrumbs.md
similarity index 100%
rename from docs/guide/html-template/breadcrumbs.md
rename to docs/theme/html-template/breadcrumbs.md
diff --git a/docs/guide/html-template/dark-mode.md b/docs/theme/html-template/dark-mode.md
similarity index 100%
rename from docs/guide/html-template/dark-mode.md
rename to docs/theme/html-template/dark-mode.md
diff --git a/docs/guide/html-template/external-links.md b/docs/theme/html-template/external-links.md
similarity index 100%
rename from docs/guide/html-template/external-links.md
rename to docs/theme/html-template/external-links.md
diff --git a/docs/guide/html-template/focus-mode.md b/docs/theme/html-template/focus-mode.md
similarity index 100%
rename from docs/guide/html-template/focus-mode.md
rename to docs/theme/html-template/focus-mode.md
diff --git a/docs/guide/html-template/fonts.md b/docs/theme/html-template/fonts.md
similarity index 100%
rename from docs/guide/html-template/fonts.md
rename to docs/theme/html-template/fonts.md
diff --git a/docs/guide/html-template/neuron-layout.md b/docs/theme/html-template/neuron-layout.md
similarity index 100%
rename from docs/guide/html-template/neuron-layout.md
rename to docs/theme/html-template/neuron-layout.md
diff --git a/docs/guide/html-template/ogp.md b/docs/theme/html-template/ogp.md
similarity index 100%
rename from docs/guide/html-template/ogp.md
rename to docs/theme/html-template/ogp.md
diff --git a/docs/guide/html-template/right-panel.md b/docs/theme/html-template/right-panel.md
similarity index 100%
rename from docs/guide/html-template/right-panel.md
rename to docs/theme/html-template/right-panel.md
diff --git a/docs/guide/html-template/search.md b/docs/theme/html-template/search.md
similarity index 100%
rename from docs/guide/html-template/search.md
rename to docs/theme/html-template/search.md
diff --git a/docs/guide/html-template/sidebar.md b/docs/theme/html-template/sidebar.md
similarity index 100%
rename from docs/guide/html-template/sidebar.md
rename to docs/theme/html-template/sidebar.md
diff --git a/docs/guide/html-template/toc.md b/docs/theme/html-template/toc.md
similarity index 100%
rename from docs/guide/html-template/toc.md
rename to docs/theme/html-template/toc.md
diff --git a/docs/guide/html-template/uptree.md b/docs/theme/html-template/uptree.md
similarity index 100%
rename from docs/guide/html-template/uptree.md
rename to docs/theme/html-template/uptree.md
diff --git a/docs/tips.md b/docs/tips.md
deleted file mode 100644
index 9b9196b4d..000000000
--- a/docs/tips.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-order: 9
-slug: tips
----
-
-# Tips
-
-Practical tips and recipes for common Emanote workflows.
-
-```query
-path:./*
-```
diff --git a/emanote/CHANGELOG.md b/emanote/CHANGELOG.md
index 2234aac53..7ab7233da 100644
--- a/emanote/CHANGELOG.md
+++ b/emanote/CHANGELOG.md
@@ -25,6 +25,7 @@
   - The default template now has a note focus button in the note area when collapsible side chrome is present. It expands the central note column inside the browser window by hiding the sidebar, right-panel, and bottom strip while leaving the uptree visible; the control is hidden on narrow screens and the state survives Ema live hot reloads until the user explicitly restores the layout.
 - Mermaid: add `elk` layout ([#618](https://github.com/srid/emanote/pull/618))
 - Home Manager module: macOS support via launchd ([#623](https://github.com/srid/emanote/pull/623))
+- Docs site reorganised around reader concern: `start`, `authoring`, `config`, `theme`, `extend`, `reference`. URLs are unchanged (every page already has a slug); legacy `/guide/*`, `/tips/*`, and `/start/resources/*` paths continue to redirect.
 
 **Bug fixes**
 
diff --git a/emanote/default/index.yaml b/emanote/default/index.yaml
index c265aa5c3..acf745e6b 100644
--- a/emanote/default/index.yaml
+++ b/emanote/default/index.yaml
@@ -345,5 +345,5 @@ emanote:
   # Render `$...$` / `$$...$$` to MathML at build time via texmath (default: true).
   # Modern browsers render MathML natively (Firefox, Safari, Chrome >=109), so
   # no runtime JS is needed. Set to false to fall back to client-side JS
-  # (MathJax snippet, or a custom KaTeX snippet — see docs/tips/js/math).
+  # (MathJax snippet, or a custom KaTeX snippet — see docs/authoring/math.md).
   staticMath: true
diff --git a/emanote/default/lua-filters/hello.lua b/emanote/default/lua-filters/hello.lua
index ea474bc2e..6d3837b10 100644
--- a/emanote/default/lua-filters/hello.lua
+++ b/emanote/default/lua-filters/hello.lua
@@ -2,7 +2,7 @@
 --
 -- Handles `hello` fenced code blocks and demonstrates Emanote's
 -- in-place error protocol via the injected `emanote.error_block`
--- helper (see `docs/guide/lua-filters/writing-filters.md`).
+-- helper (see `docs/extend/lua-filters/writing-filters.md`).
 --
 -- Happy path -> a greeting; sad path -> a protocol-shaped error block
 -- that (a) shows inline as a red banner on the live server, and
diff --git a/emanote/src/Emanote/Model/Note/Filter.hs b/emanote/src/Emanote/Model/Note/Filter.hs
index 1ba42c07e..ddd98566d 100644
--- a/emanote/src/Emanote/Model/Note/Filter.hs
+++ b/emanote/src/Emanote/Model/Note/Filter.hs
@@ -305,7 +305,7 @@ parse-time sandbox lets it through.
 Emitted on a single physical line so a runtime/syntax error in the user's
 filter still reports the right line number (see the comment on
 'parseTimeNoIOPrelude'). For the protocol the @error_block@ builder
-implements, see @docs/guide/lua-filters/writing-filters.md@.
+implements, see @docs/extend/lua-filters/writing-filters.md@.
 -}
 emanoteLuaHelpers :: Text
 emanoteLuaHelpers =