Reorganise docs around reader concern

.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.
 

.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
 

.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).

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.*

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

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]].

docs/guide/orgmode.org → 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]].