domma-cms 1.6.59 → 1.7.0

package/docs/superpowers/specs/plans/2026-05-24-menus.md

@@ -0,0 +1,3096 @@
+# Menus 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:** Replace single-navbar `config/navigation.json` + single-footer `site.json.footer.links` with a multi-menu system. Arbitrary named menus, each a tree of items with per-menu styling, mapped to named locations (slots) and renderable inline via a `[menu]` shortcode.
+
+**Architecture:** Per-menu JSON files in `config/menus/<slug>.json`. A slot-to-menu map in `config/menu-locations.json`. A code-level locations registry seeded by core (`navbar`, `footer-primary`, `footer-legal`) and extended at runtime through a new `registerMenuLocation()` hook for plugins. Server-side renderer composes the navbar from a site-wide brand (new `site.json.brand`) + the menu mapped to `navbar`. A new `[menu]` shortcode renders any menu inline. Auto-migration runs once on first boot, converting the two legacy configs and leaving `.bak` files for fallback. The user-visible navbar flyout (depth ≥ 2) and `position: "floating"` are upstream `domma-js` work and are tracked separately - the CMS-side plan assumes they land first.
+
+**Tech Stack:** Fastify 5 (ESM), Domma SPA admin (Domma JS framework `$`/`E`/`F`/`T`/`I`/`H`/`S`), `node:test` runner, gray-matter + marked for markdown.
+
+**Spec:** `docs/superpowers/specs/2026-05-24-menus-design.md`
+
+**Critical project rules** (from `CLAUDE.md` + memory):
+
+- Server runs on port **4096** and is **always running** - never start/stop. Test via `curl` only.
+- Domma admin uses `S.set/get`, `H.get/post/put/delete`, `E.toast/confirm/modal/tabs`, `T.create`, `I.scan`, `F.create`. Never vanilla equivalents.
+- `.get(0)` to unwrap Domma collections, not `[0]`.
+- Tabs class names: `.tabs` / `.tab-list` / `button.tab-item` / `.tab-panel` (NOT `.tabs-nav` etc).
+- Admin JS/MJS/CSS uses `Cache-Control: no-store` - no `?v=N` cache-busting query strings.
+- UI changes must be browser-tested (memory: `feedback_no_verified_without_browser.md`). The server is reachable at `192.168.1.4:4096` from the user's browser; the visual companion (if invoked) needs `--host 0.0.0.0 --url-host 192.168.1.4`.
+- Do NOT commit during implementation - user commits separately (memory: `feedback_no_commits.md`).
+
+---
+
+## File Map
+
+| Path | Purpose | Action |
+|---|---|---|
+| `server/services/menus.js` | New service: CRUD, validation, location registry, `resolveLocation(slot, user)` | Create |
+| `server/services/menus-migration.js` | New service: one-shot migration of `navigation.json` + `site.json.footer.links` | Create |
+| `server/services/hooks.js` | Add `registerMenuLocation()` export | Modify |
+| `server/services/permissionRegistry.js` | Add `menus` family with `read/create/update/delete` actions | Modify |
+| `server/services/renderer.js` | Replace `getConfig('navigation')` flow with menu-location-driven navbar; inject `window.__CMS_FOOTER__` global | Modify |
+| `server/services/markdown.js` | Register `[menu]` shortcode handler | Modify |
+| `server/services/scaffolder.js` | Add `menus` recipe branch (pre-flight + apply between roles and collection) | Modify |
+| `server/routes/api/menus.js` | New: REST API for `/api/menus/*` | Create |
+| `server/routes/api/menu-locations.js` | New: REST API for `/api/menu-locations/*` | Create |
+| `server/server.js` | Call `migrateLegacyNavIfPresent()` at startup; register the two new route modules | Modify |
+| `public/js/site.js` | Read `window.__CMS_FOOTER__` for primary/legal footer columns | Modify |
+| `admin/js/api.js` | Add `api.menus.*` and `api.menuLocations.*` clients | Modify |
+| `admin/js/config/sidebar-config.js` | Rename "Navigation" → "Menus", point at `#/menus`, gate on `menus` permission | Modify |
+| `admin/js/app.js` | Add menu routes (`/menus`, `/menus/edit/:slug`, `/menu-locations`); hash redirect from `/navigation` | Modify |
+| `admin/js/views/index.js` | Export new views | Modify |
+| `admin/js/views/menus.js` | New: list view of menus | Create |
+| `admin/js/views/menu-editor.js` | New: per-menu tree editor (Items / Behaviour / Meta tabs) | Create |
+| `admin/js/views/menu-locations.js` | New: slot → menu mapping editor | Create |
+| `admin/js/templates/menus.html` | New: list template | Create |
+| `admin/js/templates/menu-editor.html` | New: editor template | Create |
+| `admin/js/templates/menu-locations.html` | New: locations template | Create |
+| `admin/css/admin.css` | Tree-row styles for menu editor | Modify |
+| `tests/services/menus.test.js` | New: service tests | Create |
+| `tests/services/menus-migration.test.js` | New: migration tests | Create |
+| `tests/services/menus-shortcode.test.js` | New: `[menu]` shortcode tests | Create |
+| `tests/routes/menus.test.js` | New: API smoke tests via Fastify `.inject` | Create |
+| `docs/configuration.md` | Replace `config/navigation.json` section | Modify |
+| `docs/markdown-shortcodes.md` | Add `[menu]` entry | Modify |
+| `docs/plugin-development.md` | Document `registerMenuLocation` | Modify |
+| `docs/scaffolding.md` | Add `menus` recipe branch | Modify |
+| `CLAUDE.md` | Update navbar/menus section | Modify |
+
+---
+
+## Task 1: Service skeleton - file IO + slug validation
+
+**Files:**
+
+- Create: `server/services/menus.js`
+- Create: `tests/services/menus.test.js`
+
+The service uses the same file-IO pattern as `server/services/forms.js` and `server/services/users.js`. Menus live under `config/menus/<slug>.json`. The skeleton starts with slug validation, paths, and the two basic readers; CRUD comes in later tasks.
+
+- [ ] **Step 1.1: Write the slug + path test**
+
+  Create `tests/services/menus.test.js`:
+
+  ```js
+  /**
+   * Menus service - file IO, validation, location registry, visibility filtering.
+   * Uses unique slugs per test so runs are independent and self-cleaning.
+   */
+  import {test, after, before} from 'node:test';
+  import assert from 'node:assert/strict';
+  import fs from 'fs/promises';
+  import path from 'path';
+  import {
+      MENUS_DIR,
+      validateSlug
+  } from '../../server/services/menus.js';
+
+  test('validateSlug - accepts lowercase alphanumeric + hyphen', () => {
+      assert.equal(validateSlug('main'), true);
+      assert.equal(validateSlug('main-nav'), true);
+      assert.equal(validateSlug('footer-2'), true);
+      assert.equal(validateSlug('1nav'), true);
+  });
+
+  test('validateSlug - rejects empty, capitals, spaces, traversal', () => {
+      assert.equal(validateSlug(''), false);
+      assert.equal(validateSlug('Main'), false);
+      assert.equal(validateSlug('main nav'), false);
+      assert.equal(validateSlug('../etc'), false);
+      assert.equal(validateSlug('main/sub'), false);
+  });
+
+  test('MENUS_DIR - resolves to config/menus inside the project', () => {
+      assert.ok(MENUS_DIR.endsWith('/config/menus'));
+  });
+  ```
+
+- [ ] **Step 1.2: Run the test to confirm it fails**
+
+  Run: `node --test tests/services/menus.test.js`
+
+  Expected: import failure (`Cannot find module '../../server/services/menus.js'`).
+
+- [ ] **Step 1.3: Create the service skeleton**
+
+  Create `server/services/menus.js`:
+
+  ```js
+  /**
+   * Menus service.
+   *
+   * Multi-menu storage backing the public navbar, footer, plugin-registered
+   * slots, and the `[menu]` shortcode. Each menu lives in its own JSON file
+   * under `config/menus/<slug>.json`. A slot → menu-slug map lives in
+   * `config/menu-locations.json`. The list of registered slots (a separate
+   * concept from the map) is held in process memory and seeded by core +
+   * plugin hooks at startup.
+   */
+  import fs from 'fs/promises';
+  import path from 'path';
+  import {fileURLToPath} from 'url';
+
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname  = path.dirname(__filename);
+
+  /** Project root config directory. */
+  const CONFIG_DIR = path.resolve(__dirname, '..', '..', 'config');
+
+  /** Per-menu files live here. */
+  export const MENUS_DIR = path.join(CONFIG_DIR, 'menus');
+
+  /** Slot → menu-slug map. */
+  export const LOCATIONS_FILE = path.join(CONFIG_DIR, 'menu-locations.json');
+
+  const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+  /**
+   * Validate a slug (used for both menu slugs and location slot names).
+   *
+   * @param {unknown} slug
+   * @returns {boolean}
+   */
+  export function validateSlug(slug) {
+      return typeof slug === 'string' && SLUG_RE.test(slug);
+  }
+
+  /**
+   * Ensure MENUS_DIR exists. Safe to call repeatedly.
+   */
+  export async function ensureMenusDir() {
+      await fs.mkdir(MENUS_DIR, {recursive: true});
+  }
+  ```
+
+- [ ] **Step 1.4: Run the test to confirm it passes**
+
+  Run: `node --test tests/services/menus.test.js`
+
+  Expected: all three tests pass.
+
+---
+
+## Task 2: Menu file IO - list, get, create, update, delete, duplicate
+
+**Files:**
+
+- Modify: `server/services/menus.js`
+- Modify: `tests/services/menus.test.js`
+
+- [ ] **Step 2.1: Write the CRUD tests**
+
+  Append to `tests/services/menus.test.js`:
+
+  ```js
+  import {
+      listMenus, getMenu, createMenu, updateMenu, deleteMenu, duplicateMenu
+  } from '../../server/services/menus.js';
+
+  // Unique slug per test run so reruns don't collide.
+  const T = () => 'test-menus-' + Date.now() + '-' + Math.random().toString(36).slice(2, 6);
+
+  test('createMenu → getMenu round-trip preserves all fields', async () => {
+      const slug = T();
+      const menu = {
+          slug, name: 'Test', description: 'd',
+          variant: 'dark', position: 'sticky',
+          style: {fontSize: '14px'},
+          items: [{text: 'Home', url: '/'}]
+      };
+      await createMenu(menu);
+      try {
+          const fetched = await getMenu(slug);
+          assert.equal(fetched.slug, slug);
+          assert.equal(fetched.name, 'Test');
+          assert.equal(fetched.variant, 'dark');
+          assert.equal(fetched.items[0].text, 'Home');
+          assert.ok(fetched.meta.createdAt);
+          assert.ok(fetched.meta.updatedAt);
+      } finally {
+          await deleteMenu(slug);
+      }
+  });
+
+  test('createMenu refuses duplicate slug', async () => {
+      const slug = T();
+      await createMenu({slug, name: 'A', items: []});
+      try {
+          await assert.rejects(
+              () => createMenu({slug, name: 'A', items: []}),
+              /already exists/
+          );
+      } finally {
+          await deleteMenu(slug);
+      }
+  });
+
+  test('updateMenu preserves meta.createdAt, bumps meta.updatedAt', async () => {
+      const slug = T();
+      await createMenu({slug, name: 'A', items: []});
+      try {
+          const original  = await getMenu(slug);
+          await new Promise(r => setTimeout(r, 10));
+          await updateMenu(slug, {slug, name: 'B', items: []});
+          const updated   = await getMenu(slug);
+          assert.equal(updated.meta.createdAt, original.meta.createdAt);
+          assert.notEqual(updated.meta.updatedAt, original.meta.updatedAt);
+          assert.equal(updated.name, 'B');
+      } finally {
+          await deleteMenu(slug);
+      }
+  });
+
+  test('listMenus returns slug+name+description+meta only (no items)', async () => {
+      const slug = T();
+      await createMenu({slug, name: 'A', description: 'd', items: [{text: 'x', url: '/x'}]});
+      try {
+          const all = await listMenus();
+          const found = all.find(m => m.slug === slug);
+          assert.ok(found);
+          assert.equal(found.name, 'A');
+          assert.equal(found.description, 'd');
+          assert.equal(found.items, undefined);
+      } finally {
+          await deleteMenu(slug);
+      }
+  });
+
+  test('getMenu returns null for unknown slug', async () => {
+      assert.equal(await getMenu('nope-' + Date.now()), null);
+  });
+
+  test('getMenu rejects path traversal', async () => {
+      assert.equal(await getMenu('../../etc/passwd'), null);
+  });
+
+  test('duplicateMenu copies content under <slug>-copy (or -copy-N)', async () => {
+      const slug = T();
+      await createMenu({slug, name: 'Orig', items: [{text: 'x', url: '/x'}]});
+      try {
+          const dup1 = await duplicateMenu(slug);
+          assert.equal(dup1.slug, slug + '-copy');
+          assert.equal(dup1.items[0].text, 'x');
+          assert.notEqual(dup1.name, 'Orig'); // name suffixed
+          const dup2 = await duplicateMenu(slug);
+          assert.equal(dup2.slug, slug + '-copy-2');
+          await deleteMenu(dup1.slug);
+          await deleteMenu(dup2.slug);
+      } finally {
+          await deleteMenu(slug);
+      }
+  });
+  ```
+
+- [ ] **Step 2.2: Run to confirm tests fail with "is not a function"**
+
+  Run: `node --test tests/services/menus.test.js`
+
+  Expected: failures referencing `listMenus`, `getMenu`, etc.
+
+- [ ] **Step 2.3: Implement the CRUD functions**
+
+  Append to `server/services/menus.js`:
+
+  ```js
+  function menuPath(slug) {
+      return path.join(MENUS_DIR, `${slug}.json`);
+  }
+
+  async function readMenuFile(slug) {
+      const raw = await fs.readFile(menuPath(slug), 'utf8');
+      return JSON.parse(raw);
+  }
+
+  async function writeMenuFile(menu) {
+      await ensureMenusDir();
+      await fs.writeFile(menuPath(menu.slug), JSON.stringify(menu, null, 2) + '\n', 'utf8');
+  }
+
+  /**
+   * List all menus. Returns metadata only (no items) - use getMenu(slug) for
+   * the full payload. Sorted alphabetically by slug.
+   *
+   * @returns {Promise<Array<{slug:string,name:string,description:string,meta:object}>>}
+   */
+  export async function listMenus() {
+      await ensureMenusDir();
+      const entries = await fs.readdir(MENUS_DIR);
+      const out = [];
+      for (const file of entries) {
+          if (!file.endsWith('.json')) continue;
+          const slug = file.slice(0, -5);
+          if (!validateSlug(slug)) continue;
+          try {
+              const menu = await readMenuFile(slug);
+              out.push({
+                  slug:        menu.slug || slug,
+                  name:        menu.name || '',
+                  description: menu.description || '',
+                  itemsCount:  Array.isArray(menu.items) ? menu.items.length : 0,
+                  meta:        menu.meta || {}
+              });
+          } catch { /* skip malformed file */ }
+      }
+      return out.sort((a, b) => a.slug.localeCompare(b.slug));
+  }
+
+  /**
+   * Read a full menu by slug. Returns null if missing or slug is invalid.
+   *
+   * @param {string} slug
+   * @returns {Promise<object|null>}
+   */
+  export async function getMenu(slug) {
+      if (!validateSlug(slug)) return null;
+      try {
+          return await readMenuFile(slug);
+      } catch (err) {
+          if (err.code === 'ENOENT') return null;
+          throw err;
+      }
+  }
+
+  /**
+   * Create a new menu. Refuses on slug collision.
+   *
+   * @param {object} input - { slug, name, description?, variant?, position?, style?, items, meta? }
+   * @returns {Promise<object>} the persisted menu
+   */
+  export async function createMenu(input) {
+      if (!validateSlug(input?.slug)) {
+          throw new Error(`Invalid menu slug: ${input?.slug}`);
+      }
+      if (await getMenu(input.slug)) {
+          throw new Error(`Menu "${input.slug}" already exists`);
+      }
+      const now = new Date().toISOString();
+      const menu = {
+          slug:        input.slug,
+          name:        input.name || input.slug,
+          description: input.description || '',
+          ...(input.variant  != null && {variant:  input.variant}),
+          ...(input.position != null && {position: input.position}),
+          ...(input.style    != null && {style:    input.style}),
+          items: Array.isArray(input.items) ? input.items : [],
+          meta: {
+              createdAt: now,
+              updatedAt: now,
+              bundled:   Boolean(input.meta?.bundled),
+              presetOwner: input.meta?.presetOwner || null
+          }
+      };
+      await writeMenuFile(menu);
+      return menu;
+  }
+
+  /**
+   * Replace an existing menu. Preserves meta.createdAt; updates meta.updatedAt.
+   * The slug in the path wins over any slug in the body.
+   *
+   * @param {string} slug
+   * @param {object} input
+   * @returns {Promise<object>} the persisted menu
+   */
+  export async function updateMenu(slug, input) {
+      const existing = await getMenu(slug);
+      if (!existing) throw new Error(`Menu "${slug}" not found`);
+      const merged = {
+          ...input,
+          slug,
+          meta: {
+              ...existing.meta,
+              ...(input.meta || {}),
+              createdAt: existing.meta?.createdAt || new Date().toISOString(),
+              updatedAt: new Date().toISOString()
+          }
+      };
+      await writeMenuFile(merged);
+      return merged;
+  }
+
+  /**
+   * Delete a menu file. Returns true if removed, false if it didn't exist.
+   * Callers must check the locations map first - service does not.
+   *
+   * @param {string} slug
+   * @returns {Promise<boolean>}
+   */
+  export async function deleteMenu(slug) {
+      if (!validateSlug(slug)) return false;
+      try {
+          await fs.unlink(menuPath(slug));
+          return true;
+      } catch (err) {
+          if (err.code === 'ENOENT') return false;
+          throw err;
+      }
+  }
+
+  /**
+   * Duplicate a menu as <slug>-copy, falling back to -copy-2, -copy-3, … if
+   * needed. The duplicate's name is suffixed with " (copy)" for clarity.
+   *
+   * @param {string} slug
+   * @returns {Promise<object>} the new menu
+   */
+  export async function duplicateMenu(slug) {
+      const source = await getMenu(slug);
+      if (!source) throw new Error(`Menu "${slug}" not found`);
+      let candidate = slug + '-copy';
+      let n = 2;
+      while (await getMenu(candidate)) {
+          candidate = slug + '-copy-' + n++;
+      }
+      return createMenu({
+          ...source,
+          slug: candidate,
+          name: source.name + ' (copy)',
+          meta: {bundled: false, presetOwner: null}
+      });
+  }
+  ```
+
+- [ ] **Step 2.4: Run all tests in the file**
+
+  Run: `node --test tests/services/menus.test.js`
+
+  Expected: all tests pass.
+
+---
+
+## Task 3: Menu validation - items, urls, position, visibility
+
+**Files:**
+
+- Modify: `server/services/menus.js`
+- Modify: `tests/services/menus.test.js`
+
+- [ ] **Step 3.1: Write the validation tests**
+
+  Append to `tests/services/menus.test.js`:
+
+  ```js
+  import {validateMenu} from '../../server/services/menus.js';
+
+  test('validateMenu - accepts a minimal menu', () => {
+      const errors = validateMenu({slug: 'a', name: 'A', items: []});
+      assert.deepEqual(errors, []);
+  });
+
+  test('validateMenu - rejects bad slug', () => {
+      const errors = validateMenu({slug: 'Bad Slug', name: 'A', items: []});
+      assert.ok(errors.some(e => /slug/i.test(e)));
+  });
+
+  test('validateMenu - rejects bad position', () => {
+      const errors = validateMenu({slug: 'a', name: 'A', position: 'wobble', items: []});
+      assert.ok(errors.some(e => /position/i.test(e)));
+  });
+
+  test('validateMenu - accepts all four position values', () => {
+      for (const p of ['sticky', 'fixed', 'static', 'floating']) {
+          const errors = validateMenu({slug: 'a', name: 'A', position: p, items: []});
+          assert.deepEqual(errors, [], `position "${p}" should be valid`);
+      }
+  });
+
+  test('validateMenu - items must have text + url', () => {
+      const errors = validateMenu({slug: 'a', name: 'A', items: [{text: ''}]});
+      assert.ok(errors.some(e => /text/i.test(e)));
+      const errors2 = validateMenu({slug: 'a', name: 'A', items: [{text: 'X', url: 'no-scheme-or-slash'}]});
+      assert.ok(errors2.some(e => /url/i.test(e)));
+  });
+
+  test('validateMenu - accepts /, #, http, https, mailto urls', () => {
+      const urls = ['/x', '#frag', 'http://e.com', 'https://e.com', 'mailto:a@b.c'];
+      for (const url of urls) {
+          const errors = validateMenu({slug: 'a', name: 'A', items: [{text: 't', url}]});
+          assert.deepEqual(errors, [], `url ${url} should pass`);
+      }
+  });
+
+  test('validateMenu - recursively validates nested children', () => {
+      const errors = validateMenu({
+          slug: 'a', name: 'A',
+          items: [{text: 'top', url: '/', items: [{text: '', url: '/x'}]}]
+      });
+      assert.ok(errors.some(e => /text/i.test(e)));
+  });
+  ```
+
+- [ ] **Step 3.2: Run to confirm validation tests fail**
+
+  Run: `node --test tests/services/menus.test.js`
+
+  Expected: 7 new tests fail with "validateMenu is not a function".
+
+- [ ] **Step 3.3: Implement `validateMenu`**
+
+  Append to `server/services/menus.js`:
+
+  ```js
+  const POSITIONS = new Set(['sticky', 'fixed', 'static', 'floating']);
+  const URL_PREFIX_RE = /^(\/|#|https?:\/\/|mailto:)/;
+
+  /**
+   * Validate a menu object. Returns an array of human-readable error strings
+   * (empty on success). Performs structural + per-item recursive checks; does
+   * NOT validate visibility role names (those are checked at render time).
+   *
+   * @param {object} menu
+   * @returns {string[]}
+   */
+  export function validateMenu(menu) {
+      const errors = [];
+      if (!menu || typeof menu !== 'object') return ['Menu must be an object'];
+      if (!validateSlug(menu.slug)) {
+          errors.push(`Invalid slug "${menu.slug}" - lowercase alphanumeric + hyphen only`);
+      }
+      if (!menu.name || typeof menu.name !== 'string') {
+          errors.push('name is required');
+      }
+      if (menu.position != null && !POSITIONS.has(menu.position)) {
+          errors.push(`Invalid position "${menu.position}" - expected one of: ${[...POSITIONS].join(', ')}`);
+      }
+      if (!Array.isArray(menu.items)) {
+          errors.push('items must be an array');
+      } else {
+          walkItems(menu.items, (item, path) => {
+              if (!item.text || typeof item.text !== 'string') {
+                  errors.push(`Item ${path}: text is required`);
+              }
+              if (!item.url || typeof item.url !== 'string' || !URL_PREFIX_RE.test(item.url)) {
+                  errors.push(`Item ${path}: url must start with /, #, http(s)://, or mailto:`);
+              }
+              if (item.items != null && !Array.isArray(item.items)) {
+                  errors.push(`Item ${path}: items must be an array if present`);
+              }
+          });
+      }
+      return errors;
+  }
+
+  function walkItems(items, fn, parentPath = '') {
+      items.forEach((item, idx) => {
+          const itemPath = parentPath ? `${parentPath}.${idx}` : String(idx);
+          fn(item, itemPath);
+          if (Array.isArray(item?.items)) walkItems(item.items, fn, itemPath);
+      });
+  }
+  ```
+
+- [ ] **Step 3.4: Wire validation into createMenu + updateMenu**
+
+  In `server/services/menus.js`, locate `createMenu`. After the slug-collision check and before the `now` declaration, add:
+
+  ```js
+  const errors = validateMenu({...input, slug: input.slug});
+  if (errors.length) {
+      throw new Error('Validation failed: ' + errors.join('; '));
+  }
+  ```
+
+  In `updateMenu`, after the `existing` check and before constructing `merged`, add:
+
+  ```js
+  const errors = validateMenu({...input, slug});
+  if (errors.length) {
+      throw new Error('Validation failed: ' + errors.join('; '));
+  }
+  ```
+
+- [ ] **Step 3.5: Verify validation also fires through create/update**
+
+  Append to `tests/services/menus.test.js`:
+
+  ```js
+  test('createMenu rejects invalid items via validation', async () => {
+      await assert.rejects(
+          () => createMenu({slug: 'test-bad-' + Date.now(), name: 'A', items: [{text: '', url: '/'}]}),
+          /Validation failed/
+      );
+  });
+  ```
+
+- [ ] **Step 3.6: Run all tests**
+
+  Run: `node --test tests/services/menus.test.js`
+
+  Expected: every test (Tasks 1-3) passes.
+
+---
+
+## Task 4: Locations registry + slot map IO
+
+**Files:**
+
+- Modify: `server/services/menus.js`
+- Modify: `tests/services/menus.test.js`
+
+The registry is a module-level Map of slot → definition, seeded by core at module load and extended at runtime by `registerLocation()`. The slot map is a JSON file (`config/menu-locations.json`).
+
+- [ ] **Step 4.1: Write the registry + map tests**
+
+  Append to `tests/services/menus.test.js`:
+
+  ```js
+  import {
+      registerLocation, getLocationRegistry,
+      getLocations, setLocations
+  } from '../../server/services/menus.js';
+
+  test('registry - built-in slots present after import', () => {
+      const slots = getLocationRegistry().map(s => s.slot);
+      assert.ok(slots.includes('navbar'));
+      assert.ok(slots.includes('footer-primary'));
+      assert.ok(slots.includes('footer-legal'));
+  });
+
+  test('registerLocation - accepts plugin-contributed slot', () => {
+      registerLocation('test-slot-' + Date.now(), {
+          label: 'Test', description: 'd', maxDepth: 2, source: 'test-plugin'
+      });
+      const slots = getLocationRegistry().map(s => s.slot);
+      assert.ok(slots.some(s => s.startsWith('test-slot-')));
+  });
+
+  test('registerLocation - rejects bad slot name', () => {
+      assert.throws(() => registerLocation('Bad Slot', {label: 'x'}), /Invalid slot name/);
+  });
+
+  test('setLocations + getLocations round-trip', async () => {
+      const slug = T();
+      await createMenu({slug, name: 'A', items: []});
+      try {
+          await setLocations({navbar: slug});
+          const map = await getLocations();
+          assert.equal(map.navbar, slug);
+      } finally {
+          // Restore to whatever was there before the test (reset to empty for isolation)
+          await setLocations({});
+          await deleteMenu(slug);
+      }
+  });
+
+  test('setLocations rejects unregistered slot', async () => {
+      const slug = T();
+      await createMenu({slug, name: 'A', items: []});
+      try {
+          await assert.rejects(
+              () => setLocations({'unknown-slot-xyz': slug}),
+              /not registered/
+          );
+      } finally {
+          await deleteMenu(slug);
+      }
+  });
+
+  test('setLocations rejects mapping to nonexistent menu', async () => {
+      await assert.rejects(
+          () => setLocations({navbar: 'nope-' + Date.now()}),
+          /not found/
+      );
+  });
+  ```
+
+- [ ] **Step 4.2: Run to confirm tests fail**
+
+  Run: `node --test tests/services/menus.test.js`
+
+  Expected: 6 new tests fail with "is not a function".
+
+- [ ] **Step 4.3: Implement the registry + slot-map IO**
+
+  Append to `server/services/menus.js`:
+
+  ```js
+  // ---------------------------------------------------------------------------
+  // Locations registry - module-level Map, seeded by core, extended by plugins
+  // ---------------------------------------------------------------------------
+
+  const _locationRegistry = new Map(); // slot -> { label, description, maxDepth, source }
+
+  /**
+   * Register a slot where a menu can be rendered. Re-registering an existing
+   * slot logs a warning and the second registration wins (last-write).
+   *
+   * @param {string} slot
+   * @param {{label:string, description?:string, maxDepth?:number, source?:string}} def
+   */
+  export function registerLocation(slot, def) {
+      if (!validateSlug(slot)) throw new Error(`Invalid slot name: ${slot}`);
+      if (_locationRegistry.has(slot)) {
+          console.warn(`[menus] Slot "${slot}" re-registered - last write wins`);
+      }
+      _locationRegistry.set(slot, {
+          label:       def?.label       || slot,
+          description: def?.description || '',
+          maxDepth:    Number.isFinite(def?.maxDepth) ? def.maxDepth : null,
+          source:      def?.source      || 'core'
+      });
+  }
+
+  /**
+   * @returns {Array<{slot:string, label:string, description:string, maxDepth:number|null, source:string}>}
+   */
+  export function getLocationRegistry() {
+      return [..._locationRegistry.entries()].map(([slot, def]) => ({slot, ...def}));
+  }
+
+  // Core slots - registered at module load. Plugins register theirs from
+  // their plugin.js setup function via the registerMenuLocation hook (Task 7).
+  registerLocation('navbar',         {label: 'Navbar',         description: 'Site navbar', source: 'core'});
+  registerLocation('footer-primary', {label: 'Footer primary', description: 'Primary footer column', source: 'core', maxDepth: 1});
+  registerLocation('footer-legal',   {label: 'Footer legal',   description: 'Legal/secondary footer column', source: 'core', maxDepth: 1});
+
+  // ---------------------------------------------------------------------------
+  // Slot → menu-slug map
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Read the slot → menu-slug map from disk. Returns an empty object when the
+   * file doesn't exist or is malformed (logged as a warning).
+   *
+   * @returns {Promise<Record<string,string>>}
+   */
+  export async function getLocations() {
+      try {
+          const raw = await fs.readFile(LOCATIONS_FILE, 'utf8');
+          return JSON.parse(raw);
+      } catch (err) {
+          if (err.code === 'ENOENT') return {};
+          console.warn(`[menus] menu-locations.json unreadable: ${err.message}`);
+          return {};
+      }
+  }
+
+  /**
+   * Replace the slot map. Validates that every slot is registered and every
+   * menu slug resolves to a real menu file.
+   *
+   * @param {Record<string,string>} map
+   */
+  export async function setLocations(map) {
+      if (!map || typeof map !== 'object' || Array.isArray(map)) {
+          throw new Error('Locations map must be a plain object');
+      }
+      for (const slot of Object.keys(map)) {
+          if (!_locationRegistry.has(slot)) {
+              throw new Error(`Slot "${slot}" is not registered`);
+          }
+          const slug = map[slot];
+          if (slug != null && slug !== '' && !(await getMenu(slug))) {
+              throw new Error(`Menu "${slug}" not found for slot "${slot}"`);
+          }
+      }
+      await fs.writeFile(LOCATIONS_FILE, JSON.stringify(map, null, 2) + '\n', 'utf8');
+  }
+  ```
+
+- [ ] **Step 4.4: Run all tests**
+
+  Run: `node --test tests/services/menus.test.js`
+
+  Expected: every test (Tasks 1-4) passes.
+
+---
+
+## Task 5: `resolveLocation` - visibility-filtered menu lookup
+
+**Files:**
+
+- Modify: `server/services/menus.js`
+- Modify: `tests/services/menus.test.js`
+
+`resolveLocation(slot, user)` is the renderer's entry point. It reads the slot map, fetches the menu, and runs items through `checkVisibility()` from `server/middleware/auth.js` (reused - same helper used by page visibility).
+
+- [ ] **Step 5.1: Verify the existing checkVisibility helper**
+
+  Read `server/middleware/auth.js` and confirm `checkVisibility(userRole, visibility)` is exported. (It's already in use for page visibility per `docs/configuration.md`.)
+
+  If it isn't exported under that exact name, search:
+  Run: `grep -nE "^export (function|const) checkVisibility|^export \\{[^}]*checkVisibility" server/middleware/auth.js`
+
+  Use the actual export name in the next step.
+
+- [ ] **Step 5.2: Write resolveLocation tests**
+
+  Append to `tests/services/menus.test.js`:
+
+  ```js
+  import {resolveLocation} from '../../server/services/menus.js';
+
+  test('resolveLocation - returns null when slot is unmapped', async () => {
+      await setLocations({});
+      const got = await resolveLocation('navbar', null);
+      assert.equal(got, null);
+  });
+
+  test('resolveLocation - returns the menu when mapped', async () => {
+      const slug = T();
+      await createMenu({slug, name: 'A', items: [{text: 'Public', url: '/p'}]});
+      try {
+          await setLocations({navbar: slug});
+          const got = await resolveLocation('navbar', null);
+          assert.equal(got.slug, slug);
+          assert.equal(got.items[0].text, 'Public');
+      } finally {
+          await setLocations({});
+          await deleteMenu(slug);
+      }
+  });
+
+  test('resolveLocation - filters items by visibility for anonymous users', async () => {
+      const slug = T();
+      await createMenu({
+          slug, name: 'A',
+          items: [
+              {text: 'Public',  url: '/p', visibility: 'public'},
+              {text: 'Members', url: '/m', visibility: 'subscriber'}
+          ]
+      });
+      try {
+          await setLocations({navbar: slug});
+          const got = await resolveLocation('navbar', null);
+          assert.equal(got.items.length, 1);
+          assert.equal(got.items[0].text, 'Public');
+      } finally {
+          await setLocations({});
+          await deleteMenu(slug);
+      }
+  });
+
+  test('resolveLocation - drops empty parents whose children are all gated', async () => {
+      const slug = T();
+      await createMenu({
+          slug, name: 'A',
+          items: [
+              {text: 'Top', url: '/t', items: [
+                  {text: 'Members only', url: '/mo', visibility: 'subscriber'}
+              ]}
+          ]
+      });
+      try {
+          await setLocations({navbar: slug});
+          const got = await resolveLocation('navbar', null);
+          // Top stays (it has its own visible link); its items array is empty.
+          assert.equal(got.items.length, 1);
+          assert.equal(got.items[0].text, 'Top');
+          assert.deepEqual(got.items[0].items, []);
+      } finally {
+          await setLocations({});
+          await deleteMenu(slug);
+      }
+  });
+
+  test('resolveLocation - respects hidden flag (always drops)', async () => {
+      const slug = T();
+      await createMenu({
+          slug, name: 'A',
+          items: [
+              {text: 'Visible', url: '/v'},
+              {text: 'Hidden',  url: '/h', hidden: true}
+          ]
+      });
+      try {
+          await setLocations({navbar: slug});
+          const got = await resolveLocation('navbar', null);
+          assert.equal(got.items.length, 1);
+          assert.equal(got.items[0].text, 'Visible');
+      } finally {
+          await setLocations({});
+          await deleteMenu(slug);
+      }
+  });
+  ```
+
+- [ ] **Step 5.3: Run to confirm tests fail**
+
+  Run: `node --test tests/services/menus.test.js`
+
+  Expected: 5 new tests fail with "resolveLocation is not a function".
+
+- [ ] **Step 5.4: Implement resolveLocation**
+
+  Append to `server/services/menus.js`:
+
+  ```js
+  import {checkVisibility} from '../middleware/auth.js';
+
+  /**
+   * Resolve the menu mapped to `slot` for `user`, with items filtered by
+   * `hidden` (always dropped) and `visibility` (per-user role gating).
+   * Returns null if the slot is unmapped or the mapped menu is missing.
+   *
+   * Note: `user` may be null (anonymous). `user.role` and
+   * `user.additionalRoles` are honoured via `checkVisibility`.
+   *
+   * @param {string} slot
+   * @param {object|null} user
+   * @returns {Promise<object|null>}
+   */
+  export async function resolveLocation(slot, user) {
+      const map = await getLocations();
+      const slug = map[slot];
+      if (!slug) return null;
+      const menu = await getMenu(slug);
+      if (!menu) {
+          console.warn(`[menus] Slot "${slot}" maps to "${slug}" which doesn't exist`);
+          return null;
+      }
+      return {
+          ...menu,
+          items: filterItemsForUser(menu.items || [], user)
+      };
+  }
+
+  function filterItemsForUser(items, user) {
+      const out = [];
+      for (const item of items) {
+          if (item.hidden) continue;
+          if (item.visibility != null) {
+              const role = user?.role || null;
+              if (!checkVisibility(role, item.visibility)) continue;
+          }
+          const children = Array.isArray(item.items)
+              ? filterItemsForUser(item.items, user)
+              : [];
+          out.push({...item, items: children});
+      }
+      return out;
+  }
+  ```
+
+  Move the `import {checkVisibility}` to the top of the file with the other imports.
+
+- [ ] **Step 5.5: Run all tests**
+
+  Run: `node --test tests/services/menus.test.js`
+
+  Expected: all tests pass.
+
+---
+
+## Task 6: Permission family - `menus.*`
+
+**Files:**
+
+- Modify: `server/services/permissionRegistry.js`
+
+- [ ] **Step 6.1: Find the navigation entry to anchor the insertion**
+
+  Run: `grep -n "key: 'navigation'" server/services/permissionRegistry.js`
+
+  Expected: one line number - note it.
+
+- [ ] **Step 6.2: Insert the menus family after the navigation entry**
+
+  Read the lines around the `navigation` entry. After its closing `},`, insert the menus block:
+
+  ```js
+      {
+          key: 'menus',
+          label: 'Menus',
+          description: 'Manage menus and the slots they render into.',
+          icon: 'menu',
+          group: 'Structure',
+          actions: [
+              {key: 'read',   label: 'View',   description: 'View menus and locations'},
+              {key: 'create', label: 'Create', description: 'Create new menus'},
+              {key: 'update', label: 'Edit',   description: 'Edit menus and the slot map'},
+              {key: 'delete', label: 'Delete', description: 'Delete menus'}
+          ]
+      },
+  ```
+
+- [ ] **Step 6.3: Smoke-test the import surface**
+
+  Run: `node -e "import('./server/services/permissionRegistry.js').then(m => console.log(m.REGISTRY.find(r => r.key === 'menus')))"`
+
+  Expected: the menus object is printed, including all four actions.
+
+---
+
+## Task 7: `registerMenuLocation` plugin hook
+
+**Files:**
+
+- Modify: `server/services/hooks.js`
+
+- [ ] **Step 7.1: Add the hook export**
+
+  In `server/services/hooks.js`, after the shortcode-registry block (the `getShortcodeProcessors` export, before the sanitize-rules block), add:
+
+  ```js
+  // ---------------------------------------------------------------------------
+  // Menu-location registry - delegated to server/services/menus.js
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Register a menu-location slot. Plugins call this from their setupPlugin to
+   * declare slots where a curated menu can be rendered (e.g. a sidebar widget).
+   * The slot then appears in the admin Locations editor and can be filled with
+   * any menu the admin chooses.
+   *
+   * @param {string} slot - lower-snake-case slot name (e.g. 'sidebar')
+   * @param {{label?:string, description?:string, maxDepth?:number}} def
+   */
+  export async function registerMenuLocation(slot, def) {
+      const {registerLocation} = await import('./menus.js');
+      registerLocation(slot, {...def, source: def?.source || 'plugin'});
+  }
+  ```
+
+- [ ] **Step 7.2: Expose it to plugins via the plugin loader**
+
+  Open `server/services/plugins.js`. Find the `hooks:` block passed to plugins (around line 207):
+
+  ```js
+  hooks: {registerShortcode, registerSanitizeRules, registerTransform, on: hooks.on.bind(hooks)},
+  ```
+
+  Replace with:
+
+  ```js
+  hooks: {registerShortcode, registerSanitizeRules, registerTransform, registerMenuLocation, on: hooks.on.bind(hooks)},
+  ```
+
+  Update the `import {hooks, ...}` line at the top to include `registerMenuLocation`.
+
+- [ ] **Step 7.3: Smoke-test from a Node one-liner**
+
+  Run:
+  ```bash
+  node -e "import('./server/services/hooks.js').then(async h => { await h.registerMenuLocation('plugin-test-sidebar', {label: 'Sidebar', description: 'd', source: 'test'}); const m = await import('./server/services/menus.js'); console.log(m.getLocationRegistry().find(s => s.slot === 'plugin-test-sidebar')); })"
+  ```
+
+  Expected: the registered slot is printed with `source: 'test'`.
+
+---
+
+## Task 8: API routes - `/api/menus/*`
+
+**Files:**
+
+- Create: `server/routes/api/menus.js`
+- Create: `tests/routes/menus.test.js`
+
+- [ ] **Step 8.1: Write the route tests using Fastify .inject**
+
+  Look at how an existing route test calls Fastify (e.g. `tests/routes/dashboard-summary.test.js`) to copy the bootstrapping pattern. The tests should hit the routes through a real Fastify instance with auth disabled or mocked - match whatever the existing route tests do.
+
+  Create `tests/routes/menus.test.js`:
+
+  ```js
+  /**
+   * Smoke tests for /api/menus/* - verifies route shape, auth gates, and
+   * successful round-trip CRUD. Heavy validation is tested in the service
+   * tests; this file checks the wiring.
+   */
+  import {test, after, before} from 'node:test';
+  import assert from 'node:assert/strict';
+  import Fastify from 'fastify';
+  import fastifyJwt from '@fastify/jwt';
+  import {menusRoutes} from '../../server/routes/api/menus.js';
+  import {deleteMenu} from '../../server/services/menus.js';
+
+  // Token-less mode for tests: we replace authenticate + requirePermission with
+  // pass-throughs by exposing the route module's preHandler hooks via fake
+  // implementations. The simplest approach is to register a small auth shim
+  // BEFORE menusRoutes that decorates request.user.
+  async function build() {
+      const app = Fastify();
+      app.register(fastifyJwt, {secret: 'test-secret-only-for-tests-32chars'});
+      app.addHook('preHandler', async (req) => {
+          // Pretend every request is an admin
+          req.user = {id: 'test-admin', role: 'admin'};
+      });
+      await app.register(async (inst) => menusRoutes(inst), {prefix: '/api'});
+      return app;
+  }
+
+  const T = () => 'rt-menus-' + Date.now() + '-' + Math.random().toString(36).slice(2, 6);
+
+  test('POST /api/menus → 201 + body', async () => {
+      const app = await build();
+      const slug = T();
+      try {
+          const res = await app.inject({
+              method: 'POST',
+              url:    '/api/menus',
+              payload: {slug, name: 'Routed', items: []}
+          });
+          assert.equal(res.statusCode, 201);
+          const body = res.json();
+          assert.equal(body.slug, slug);
+      } finally {
+          await deleteMenu(slug);
+          await app.close();
+      }
+  });
+
+  test('GET /api/menus → array including the created menu', async () => {
+      const app = await build();
+      const slug = T();
+      try {
+          await app.inject({method: 'POST', url: '/api/menus', payload: {slug, name: 'A', items: []}});
+          const res = await app.inject({method: 'GET', url: '/api/menus'});
+          assert.equal(res.statusCode, 200);
+          assert.ok(res.json().some(m => m.slug === slug));
+      } finally {
+          await deleteMenu(slug);
+          await app.close();
+      }
+  });
+
+  test('GET /api/menus/:slug → full menu', async () => {
+      const app = await build();
+      const slug = T();
+      try {
+          await app.inject({method: 'POST', url: '/api/menus', payload: {slug, name: 'A', items: [{text: 'H', url: '/'}]}});
+          const res = await app.inject({method: 'GET', url: `/api/menus/${slug}`});
+          assert.equal(res.statusCode, 200);
+          assert.equal(res.json().items[0].text, 'H');
+      } finally {
+          await deleteMenu(slug);
+          await app.close();
+      }
+  });
+
+  test('GET /api/menus/:slug → 404 for unknown', async () => {
+      const app = await build();
+      const res = await app.inject({method: 'GET', url: '/api/menus/does-not-exist-xyz'});
+      assert.equal(res.statusCode, 404);
+      await app.close();
+  });
+
+  test('DELETE /api/menus/:slug → 200 when not mapped', async () => {
+      const app = await build();
+      const slug = T();
+      await app.inject({method: 'POST', url: '/api/menus', payload: {slug, name: 'A', items: []}});
+      const res = await app.inject({method: 'DELETE', url: `/api/menus/${slug}`});
+      assert.equal(res.statusCode, 200);
+      await app.close();
+  });
+
+  test('POST /api/menus/:slug/duplicate → 201 with -copy suffix', async () => {
+      const app = await build();
+      const slug = T();
+      try {
+          await app.inject({method: 'POST', url: '/api/menus', payload: {slug, name: 'A', items: []}});
+          const res = await app.inject({method: 'POST', url: `/api/menus/${slug}/duplicate`});
+          assert.equal(res.statusCode, 201);
+          const body = res.json();
+          assert.equal(body.slug, slug + '-copy');
+          await deleteMenu(body.slug);
+      } finally {
+          await deleteMenu(slug);
+          await app.close();
+      }
+  });
+  ```
+
+- [ ] **Step 8.2: Run to confirm tests fail**
+
+  Run: `node --test tests/routes/menus.test.js`
+
+  Expected: import failures referencing the missing routes module.
+
+- [ ] **Step 8.3: Implement the routes**
+
+  Create `server/routes/api/menus.js`:
+
+  ```js
+  /**
+   * Menus API
+   *
+   * GET    /api/menus                  - list (metadata only)
+   * GET    /api/menus/:slug            - full menu
+   * POST   /api/menus                  - create
+   * PUT    /api/menus/:slug            - replace
+   * DELETE /api/menus/:slug            - delete (409 if mapped to a slot)
+   * POST   /api/menus/:slug/duplicate  - copy as <slug>-copy
+   */
+  import {authenticate, requirePermission} from '../../middleware/auth.js';
+  import {
+      listMenus, getMenu, createMenu, updateMenu, deleteMenu,
+      duplicateMenu, getLocations
+  } from '../../services/menus.js';
+  import * as cache from '../../services/cache/index.js';
+
+  export async function menusRoutes(fastify) {
+      const canRead   = {preHandler: [authenticate, requirePermission('menus', 'read')]};
+      const canCreate = {preHandler: [authenticate, requirePermission('menus', 'create')]};
+      const canUpdate = {preHandler: [authenticate, requirePermission('menus', 'update')]};
+      const canDelete = {preHandler: [authenticate, requirePermission('menus', 'delete')]};
+
+      fastify.get('/menus', canRead, async () => listMenus());
+
+      fastify.get('/menus/:slug', canRead, async (request, reply) => {
+          const menu = await getMenu(request.params.slug);
+          if (!menu) return reply.status(404).send({error: 'Menu not found'});
+          return menu;
+      });
+
+      fastify.post('/menus', canCreate, async (request, reply) => {
+          try {
+              const menu = await createMenu(request.body || {});
+              await cache.invalidateTags([`menu:${menu.slug}`, 'nav']);
+              return reply.status(201).send(menu);
+          } catch (err) {
+              const status = /already exists/.test(err.message) ? 409 : 400;
+              return reply.status(status).send({error: err.message});
+          }
+      });
+
+      fastify.put('/menus/:slug', canUpdate, async (request, reply) => {
+          try {
+              const menu = await updateMenu(request.params.slug, request.body || {});
+              await cache.invalidateTags([`menu:${menu.slug}`, 'nav']);
+              return menu;
+          } catch (err) {
+              const status = /not found/.test(err.message) ? 404 : 400;
+              return reply.status(status).send({error: err.message});
+          }
+      });
+
+      fastify.delete('/menus/:slug', canDelete, async (request, reply) => {
+          const map  = await getLocations();
+          const slot = Object.entries(map).find(([, slug]) => slug === request.params.slug)?.[0];
+          if (slot) {
+              return reply.status(409).send({
+                  error: `Cannot delete - menu is mapped to slot "${slot}". Unmap it first.`
+              });
+          }
+          const ok = await deleteMenu(request.params.slug);
+          if (!ok) return reply.status(404).send({error: 'Menu not found'});
+          await cache.invalidateTags([`menu:${request.params.slug}`, 'nav']);
+          return {success: true};
+      });
+
+      fastify.post('/menus/:slug/duplicate', canCreate, async (request, reply) => {
+          try {
+              const copy = await duplicateMenu(request.params.slug);
+              await cache.invalidateTags([`menu:${copy.slug}`]);
+              return reply.status(201).send(copy);
+          } catch (err) {
+              const status = /not found/.test(err.message) ? 404 : 400;
+              return reply.status(status).send({error: err.message});
+          }
+      });
+  }
+  ```
+
+- [ ] **Step 8.4: Run the route tests**
+
+  Run: `node --test tests/routes/menus.test.js`
+
+  Expected: all pass.
+
+---
+
+## Task 9: API routes - `/api/menu-locations/*`
+
+**Files:**
+
+- Create: `server/routes/api/menu-locations.js`
+- Modify: `tests/routes/menus.test.js`
+
+- [ ] **Step 9.1: Append location-route tests**
+
+  Append to `tests/routes/menus.test.js`:
+
+  ```js
+  import {menuLocationsRoutes} from '../../server/routes/api/menu-locations.js';
+
+  async function buildWithLocations() {
+      const app = Fastify();
+      app.register(fastifyJwt, {secret: 'test-secret-only-for-tests-32chars'});
+      app.addHook('preHandler', async (req) => {
+          req.user = {id: 'test-admin', role: 'admin'};
+      });
+      await app.register(async (inst) => {
+          await menusRoutes(inst);
+          await menuLocationsRoutes(inst);
+      }, {prefix: '/api'});
+      return app;
+  }
+
+  test('GET /api/menu-locations/registry - includes core slots', async () => {
+      const app = await buildWithLocations();
+      const res = await app.inject({method: 'GET', url: '/api/menu-locations/registry'});
+      assert.equal(res.statusCode, 200);
+      const slots = res.json().map(s => s.slot);
+      assert.ok(slots.includes('navbar'));
+      assert.ok(slots.includes('footer-primary'));
+      await app.close();
+  });
+
+  test('PUT /api/menu-locations - saves valid slot map', async () => {
+      const app = await buildWithLocations();
+      const slug = T();
+      try {
+          await app.inject({method: 'POST', url: '/api/menus', payload: {slug, name: 'A', items: []}});
+          const res = await app.inject({
+              method: 'PUT', url: '/api/menu-locations',
+              payload: {navbar: slug}
+          });
+          assert.equal(res.statusCode, 200);
+          const get = await app.inject({method: 'GET', url: '/api/menu-locations'});
+          assert.equal(get.json().navbar, slug);
+      } finally {
+          await app.inject({method: 'PUT', url: '/api/menu-locations', payload: {}});
+          await deleteMenu(slug);
+          await app.close();
+      }
+  });
+
+  test('PUT /api/menu-locations - rejects unknown slot', async () => {
+      const app = await buildWithLocations();
+      const slug = T();
+      try {
+          await app.inject({method: 'POST', url: '/api/menus', payload: {slug, name: 'A', items: []}});
+          const res = await app.inject({
+              method: 'PUT', url: '/api/menu-locations',
+              payload: {'nonexistent-slot': slug}
+          });
+          assert.equal(res.statusCode, 400);
+      } finally {
+          await deleteMenu(slug);
+          await app.close();
+      }
+  });
+  ```
+
+- [ ] **Step 9.2: Run to confirm tests fail**
+
+  Run: `node --test tests/routes/menus.test.js`
+
+  Expected: import failures for `menu-locations.js`.
+
+- [ ] **Step 9.3: Implement the locations route**
+
+  Create `server/routes/api/menu-locations.js`:
+
+  ```js
+  /**
+   * Menu locations API
+   *
+   * GET /api/menu-locations           - current slot → menu-slug map
+   * PUT /api/menu-locations           - replace the map (validates against registry + menus)
+   * GET /api/menu-locations/registry  - list registered slots (core + plugin-contributed)
+   */
+  import {authenticate, requirePermission} from '../../middleware/auth.js';
+  import {getLocations, setLocations, getLocationRegistry} from '../../services/menus.js';
+  import * as cache from '../../services/cache/index.js';
+
+  export async function menuLocationsRoutes(fastify) {
+      const canRead   = {preHandler: [authenticate, requirePermission('menus', 'read')]};
+      const canUpdate = {preHandler: [authenticate, requirePermission('menus', 'update')]};
+
+      fastify.get('/menu-locations',          canRead, async () => getLocations());
+      fastify.get('/menu-locations/registry', canRead, async () => getLocationRegistry());
+
+      fastify.put('/menu-locations', canUpdate, async (request, reply) => {
+          try {
+              await setLocations(request.body || {});
+              await cache.invalidateTags(['menu-locations', 'nav']);
+              return {success: true};
+          } catch (err) {
+              return reply.status(400).send({error: err.message});
+          }
+      });
+  }
+  ```
+
+- [ ] **Step 9.4: Run all route tests**
+
+  Run: `node --test tests/routes/menus.test.js`
+
+  Expected: all pass.
+
+---
+
+## Task 10: Wire routes into `server/server.js`
+
+**Files:**
+
+- Modify: `server/server.js`
+
+- [ ] **Step 10.1: Find where navigation routes are registered**
+
+  Run: `grep -n "navigationRoutes\|navigation" server/server.js`
+
+  Expected: a `register(navigationRoutes, ...)` line and an import.
+
+- [ ] **Step 10.2: Import + register the new routes**
+
+  In `server/server.js`, add the imports next to the existing route imports:
+
+  ```js
+  import {menusRoutes}         from './routes/api/menus.js';
+  import {menuLocationsRoutes} from './routes/api/menu-locations.js';
+  ```
+
+  Find the navigation route registration block. Immediately after it, add:
+
+  ```js
+  await fastify.register(menusRoutes,         {prefix: '/api'});
+  await fastify.register(menuLocationsRoutes, {prefix: '/api'});
+  ```
+
+- [ ] **Step 10.3: Verify with curl that the routes are live**
+
+  The server is always running on port 4096. Use a real token from `S.get('auth_token')` (the user can grab one from the browser) or hit the routes with no auth to see a 401 (proves they're routed, not 404).
+
+  Run:
+  ```bash
+  curl -s -o /dev/null -w "%{http_code}\n" http://localhost:4096/api/menu-locations/registry
+  ```
+
+  Expected: `401` (auth required) - confirms the route is registered. If you get `404` the registration didn't take.
+
+  Notify the user that route registration is complete and request they refresh / re-test in the browser if they want a live check.
+
+---
+
+## Task 11: Migration service - convert legacy nav + footer
+
+**Files:**
+
+- Create: `server/services/menus-migration.js`
+- Create: `tests/services/menus-migration.test.js`
+
+The migration is one-shot. Idempotency guard: if `config/menu-locations.json` already exists, it's skipped.
+
+- [ ] **Step 11.1: Write the migration tests with a temp config directory**
+
+  Create `tests/services/menus-migration.test.js`:
+
+  ```js
+  /**
+   * Menus migration - exercises the convert-once flow on a temporary config dir
+   * so the real project config is untouched. Each test points the migration at
+   * its own scratch directory.
+   */
+  import {test} from 'node:test';
+  import assert from 'node:assert/strict';
+  import fs from 'fs/promises';
+  import path from 'path';
+  import os from 'os';
+  import {runMigration} from '../../server/services/menus-migration.js';
+
+  async function scratch() {
+      const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'menus-migration-'));
+      return dir;
+  }
+
+  test('no-op when menu-locations.json already exists', async () => {
+      const dir = await scratch();
+      await fs.writeFile(path.join(dir, 'menu-locations.json'), '{"navbar":"main"}', 'utf8');
+      const result = await runMigration({configDir: dir});
+      assert.equal(result.migrated, false);
+      assert.equal(result.reason, 'menu-locations.json already present');
+  });
+
+  test('migrates navigation.json + footer.links + writes locations + brand', async () => {
+      const dir = await scratch();
+      await fs.writeFile(path.join(dir, 'navigation.json'), JSON.stringify({
+          brand:   {text: 'My Site', url: '/', icon: 'home'},
+          items:   [{text: 'Home', url: '/'}, {text: 'About', url: '/about'}],
+          variant: 'transparent', position: 'sticky'
+      }), 'utf8');
+      await fs.writeFile(path.join(dir, 'site.json'), JSON.stringify({
+          title: 'My Site',
+          footer: {
+              copyright: '© 2026',
+              links: [{text: 'Privacy', url: '/privacy'}]
+          }
+      }), 'utf8');
+
+      const result = await runMigration({configDir: dir});
+      assert.equal(result.migrated, true);
+
+      // menus/main.json
+      const main = JSON.parse(await fs.readFile(path.join(dir, 'menus', 'main.json'), 'utf8'));
+      assert.equal(main.slug, 'main');
+      assert.equal(main.items[0].text, 'Home');
+      assert.equal(main.variant, 'transparent');
+
+      // menus/footer.json
+      const footer = JSON.parse(await fs.readFile(path.join(dir, 'menus', 'footer.json'), 'utf8'));
+      assert.equal(footer.slug, 'footer');
+      assert.equal(footer.items[0].text, 'Privacy');
+
+      // brand moved into site.json
+      const site = JSON.parse(await fs.readFile(path.join(dir, 'site.json'), 'utf8'));
+      assert.equal(site.brand.text, 'My Site');
+      assert.deepEqual(site.footer.links, []);
+      assert.equal(site.footer.copyright, '© 2026');
+
+      // menu-locations
+      const loc = JSON.parse(await fs.readFile(path.join(dir, 'menu-locations.json'), 'utf8'));
+      assert.equal(loc.navbar, 'main');
+      assert.equal(loc['footer-primary'], 'footer');
+
+      // .bak preserved
+      const bakExists = await fs.access(path.join(dir, 'navigation.json.bak')).then(() => true).catch(() => false);
+      assert.equal(bakExists, true);
+  });
+
+  test('handles missing footer.links gracefully', async () => {
+      const dir = await scratch();
+      await fs.writeFile(path.join(dir, 'navigation.json'), JSON.stringify({
+          brand: {text: 'X'}, items: [{text: 'Home', url: '/'}]
+      }), 'utf8');
+      await fs.writeFile(path.join(dir, 'site.json'), JSON.stringify({title: 'X'}), 'utf8');
+
+      const result = await runMigration({configDir: dir});
+      assert.equal(result.migrated, true);
+
+      const loc = JSON.parse(await fs.readFile(path.join(dir, 'menu-locations.json'), 'utf8'));
+      assert.equal(loc.navbar, 'main');
+      assert.equal(loc['footer-primary'], undefined);
+  });
+
+  test('handles missing navigation.json gracefully', async () => {
+      const dir = await scratch();
+      await fs.writeFile(path.join(dir, 'site.json'), JSON.stringify({
+          title: 'X',
+          footer: {links: [{text: 'Privacy', url: '/p'}]}
+      }), 'utf8');
+
+      const result = await runMigration({configDir: dir});
+      assert.equal(result.migrated, true);
+
+      const loc = JSON.parse(await fs.readFile(path.join(dir, 'menu-locations.json'), 'utf8'));
+      assert.equal(loc.navbar, undefined);
+      assert.equal(loc['footer-primary'], 'footer');
+  });
+  ```
+
+- [ ] **Step 11.2: Run to confirm tests fail**
+
+  Run: `node --test tests/services/menus-migration.test.js`
+
+  Expected: import error on `menus-migration.js`.
+
+- [ ] **Step 11.3: Implement the migration**
+
+  Create `server/services/menus-migration.js`:
+
+  ```js
+  /**
+   * Menus auto-migration.
+   *
+   * Runs once on server boot. Idempotent - guarded by the existence of
+   * config/menu-locations.json. Converts:
+   *   - config/navigation.json → config/menus/main.json + locations.navbar
+   *     (brand moves into site.json.brand)
+   *   - site.json.footer.links → config/menus/footer.json + locations.footer-primary
+   *     (footer.copyright preserved)
+   * The originals are renamed to .bak for one release of read-fallback safety.
+   */
+  import fs from 'fs/promises';
+  import path from 'path';
+  import {fileURLToPath} from 'url';
+
+  const __filename = fileURLToPath(import.meta.url);
+  const DEFAULT_CONFIG_DIR = path.resolve(path.dirname(__filename), '..', '..', 'config');
+
+  async function exists(p) {
+      try { await fs.access(p); return true; } catch { return false; }
+  }
+
+  async function readJson(p) {
+      const raw = await fs.readFile(p, 'utf8');
+      return JSON.parse(raw);
+  }
+
+  async function writeJson(p, data) {
+      await fs.writeFile(p, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  }
+
+  /**
+   * Run the migration. Returns `{migrated: boolean, reason?: string}`.
+   *
+   * @param {{configDir?: string}} [opts]
+   */
+  export async function runMigration(opts = {}) {
+      const configDir = opts.configDir || DEFAULT_CONFIG_DIR;
+
+      // 1. Guard
+      if (await exists(path.join(configDir, 'menu-locations.json'))) {
+          return {migrated: false, reason: 'menu-locations.json already present'};
+      }
+
+      const menusDir = path.join(configDir, 'menus');
+      await fs.mkdir(menusDir, {recursive: true});
+      const locations = {};
+      const now = new Date().toISOString();
+
+      // 2. navigation.json
+      const navPath = path.join(configDir, 'navigation.json');
+      if (await exists(navPath)) {
+          const nav = await readJson(navPath);
+          const mainMenu = {
+              slug:        'main',
+              name:        'Main navigation',
+              description: 'Migrated from config/navigation.json',
+              ...(nav.variant  != null && {variant:  nav.variant}),
+              ...(nav.position != null && {position: nav.position}),
+              ...(nav.style    != null && {style:    nav.style}),
+              items: Array.isArray(nav.items) ? nav.items : [],
+              meta:  {createdAt: now, updatedAt: now, bundled: false, presetOwner: null}
+          };
+          await writeJson(path.join(menusDir, 'main.json'), mainMenu);
+          locations.navbar = 'main';
+
+          if (nav.brand) {
+              const sitePath = path.join(configDir, 'site.json');
+              const site = (await exists(sitePath)) ? await readJson(sitePath) : {};
+              site.brand = nav.brand;
+              await writeJson(sitePath, site);
+          }
+
+          await fs.rename(navPath, navPath + '.bak');
+          console.log(`[menus] Migrated navigation.json → menus/main.json + locations.navbar`);
+      }
+
+      // 3. site.json footer.links
+      const sitePath = path.join(configDir, 'site.json');
+      if (await exists(sitePath)) {
+          const site = await readJson(sitePath);
+          const links = site.footer?.links;
+          if (Array.isArray(links) && links.length) {
+              const footerMenu = {
+                  slug:        'footer',
+                  name:        'Footer',
+                  description: 'Migrated from site.json footer.links',
+                  items: links.map(l => ({
+                      text: l.text || '',
+                      url:  l.url  || '/',
+                      ...(l.hidden && {hidden: true})
+                  })),
+                  meta: {createdAt: now, updatedAt: now, bundled: false, presetOwner: null}
+              };
+              await writeJson(path.join(menusDir, 'footer.json'), footerMenu);
+              locations['footer-primary'] = 'footer';
+              site.footer = {...site.footer, links: []};
+              await writeJson(sitePath, site);
+              console.log(`[menus] Migrated footer.links → menus/footer.json + locations.footer-primary`);
+          }
+      }
+
+      // 4. Write the locations map (even if empty - its existence is the migration guard)
+      await writeJson(path.join(configDir, 'menu-locations.json'), locations);
+
+      return {migrated: true};
+  }
+  ```
+
+- [ ] **Step 11.4: Run the migration tests**
+
+  Run: `node --test tests/services/menus-migration.test.js`
+
+  Expected: all four tests pass.
+
+---
+
+## Task 12: Wire migration into server startup
+
+**Files:**
+
+- Modify: `server/server.js`
+
+- [ ] **Step 12.1: Find a stable insertion point**
+
+  Run: `grep -n "loadConfig\|fastify.register\|getConfig\|await loadRoles" server/server.js | head -20`
+
+  The migration must run after config-load and before route registration. Common placement is right after the first `loadConfig()` call or alongside `await loadRoles()` (whichever runs at startup).
+
+- [ ] **Step 12.2: Add the import and call**
+
+  At the top of `server/server.js`, add:
+
+  ```js
+  import {runMigration as runMenusMigration} from './services/menus-migration.js';
+  ```
+
+  After the existing config / role load calls (and before the menus + menu-locations route registrations from Task 10), add:
+
+  ```js
+  try {
+      await runMenusMigration();
+  } catch (err) {
+      fastify.log.warn(`[menus] Migration skipped: ${err.message}`);
+  }
+  ```
+
+  If `fastify` isn't in scope at that point, swap to `console.warn`.
+
+- [ ] **Step 12.3: Verify on a scratch project**
+
+  Don't run the migration against the live config. Instead, on a copy:
+
+  ```bash
+  cp -r config /tmp/menus-mig-test
+  node -e "import('./server/services/menus-migration.js').then(m => m.runMigration({configDir: '/tmp/menus-mig-test'}).then(console.log))"
+  ls /tmp/menus-mig-test/menus /tmp/menus-mig-test/menu-locations.json
+  ```
+
+  Expected: `menus/main.json`, `menus/footer.json`, `menu-locations.json`, plus `navigation.json.bak`.
+
+  Notify the user - the live config will migrate on next server restart. The server is currently running; restart timing is the user's call.
+
+---
+
+## Task 13: Renderer integration - navbar + footer globals
+
+**Files:**
+
+- Modify: `server/services/renderer.js`
+
+- [ ] **Step 13.1: Locate the existing navigation injection**
+
+  Run: `grep -n "getConfig('navigation')\|__CMS_NAV__\|navJson" server/services/renderer.js`
+
+  Expected: a line that reads navigation from config and a line that builds `navJson` from it. Note the line numbers.
+
+- [ ] **Step 13.2: Replace the navigation-config read with location resolution**
+
+  In `server/services/renderer.js`:
+
+  - Add imports at the top:
+
+    ```js
+    import {resolveLocation, getLocations} from './menus.js';
+    ```
+
+  - Find the existing line that fetches `navigation` from `getConfig('navigation')` and the `navJson` line. Replace the navigation fetch with:
+
+    ```js
+    // Resolve the menu mapped to the navbar slot; fall back to navigation.json.bak
+    // for one release if no menu is mapped (see migration spec).
+    const navMenu = await resolveLocation('navbar', user);
+    const site    = getConfig('site') || {};
+    const brand   = site.brand || {};
+    const navigation = navMenu
+        ? {
+            brand,
+            items:    filterHiddenNavItems({items: navMenu.items}).items,
+            variant:  navMenu.variant  || 'default',
+            position: navMenu.position || 'sticky',
+            ...(navMenu.style && {style: navMenu.style})
+        }
+        : await readLegacyNavBackup() || {brand, items: []};
+    ```
+
+  - At the bottom of the file (before the final `}` if any), add:
+
+    ```js
+    /**
+     * Read config/navigation.json.bak as a one-release fallback when no menu is
+     * mapped to the navbar slot. Returns null when the .bak is missing.
+     */
+    async function readLegacyNavBackup() {
+        try {
+            const fs   = await import('fs/promises');
+            const path = await import('path');
+            const {fileURLToPath} = await import('url');
+            const here = fileURLToPath(import.meta.url);
+            const bak  = path.resolve(path.dirname(here), '..', '..', 'config', 'navigation.json.bak');
+            const raw  = await fs.readFile(bak, 'utf8');
+            console.warn('[menus] navbar location unmapped - falling back to navigation.json.bak (deprecated)');
+            return JSON.parse(raw);
+        } catch {
+            return null;
+        }
+    }
+    ```
+
+- [ ] **Step 13.3: Add the footer global injection**
+
+  In `server/services/renderer.js`, find where the existing site config is serialised into the page (look for `__CMS_SITE__` or `siteJson`). Just before that block, build the footer payload:
+
+  ```js
+  // Compose window.__CMS_FOOTER__ from the menus mapped to footer-primary / footer-legal.
+  const footerPrimary = await resolveLocation('footer-primary', user);
+  const footerLegal   = await resolveLocation('footer-legal',   user);
+  const footer = {
+      primary:   footerPrimary ? footerPrimary.items : [],
+      legal:     footerLegal   ? footerLegal.items   : [],
+      copyright: site.footer?.copyright || ''
+  };
+  const footerJson = JSON.stringify(footer).replace(/<\/script>/gi, '<\\/script>');
+  ```
+
+  Inject the global by adding to the existing template placeholder substitution (find where `__CMS_NAV__` is injected - typically `templates/page.html` has a `{{footerScript}}` slot or similar). If the renderer currently uses string substitution, add:
+
+  ```js
+  html = html.replace('{{footerScript}}', `<script>window.__CMS_FOOTER__ = ${footerJson};</script>`);
+  ```
+
+  If `{{footerScript}}` does not yet exist in the page template, jump to Step 13.4 first.
+
+- [ ] **Step 13.4: Add the placeholder to the page shell template**
+
+  Open `server/templates/page.html`. Find the line that has `{{navScript}}` or `window.__CMS_NAV__`. Immediately after it, add:
+
+  ```html
+  {{footerScript}}
+  ```
+
+- [ ] **Step 13.5: Smoke-test in the browser**
+
+  The server is always running. Open the public homepage in the user's browser (`http://192.168.1.4:4096/`) and:
+
+  - **Hard-refresh** so the new page shell is fetched.
+  - Open DevTools console → type `window.__CMS_FOOTER__`. Should print `{primary: [...], legal: [...], copyright: "…"}`.
+  - Type `window.__CMS_NAV__`. Should print the composed navbar with the migrated `main` menu items (assuming migration has run) and `brand` from site.json.
+
+  Notify the user with explicit limits - note that this is a real browser load. If you cannot reach the browser yourself, state that clearly and ask the user to do the check.
+
+---
+
+## Task 14: `[menu]` shortcode
+
+**Files:**
+
+- Modify: `server/services/markdown.js`
+- Create: `tests/services/menus-shortcode.test.js`
+
+The shortcode is wired through the same `registerShortcode` registry as `[view]`, `[block]`, `[collection]`. It's self-closing (`[menu slug="…" /]`) and resolves visibility from the request's user (passed in via `context`).
+
+- [ ] **Step 14.1: Find the existing shortcode registration pattern**
+
+  Run: `grep -n "registerShortcode\|getShortcodeProcessors\|context\.user\|context\.parseShortcodeAttrs" server/services/markdown.js | head -20`
+
+  Look at how `[view]` or `[block]` is registered - copy that shape exactly. If they're inlined in `markdown.js` (not through `registerShortcode`), follow the inline pattern.
+
+- [ ] **Step 14.2: Write the shortcode tests**
+
+  Create `tests/services/menus-shortcode.test.js`:
+
+  ```js
+  /**
+   * [menu] shortcode - renders by slug or location, respects visibility,
+   * outputs nested <ul> markup.
+   */
+  import {test} from 'node:test';
+  import assert from 'node:assert/strict';
+  import {parseMarkdown} from '../../server/services/markdown.js';
+  import {
+      createMenu, deleteMenu, setLocations, getLocations
+  } from '../../server/services/menus.js';
+
+  const T = () => 'mdsc-' + Date.now() + '-' + Math.random().toString(36).slice(2, 6);
+
+  test('[menu slug=...] renders the menu items as <ul>', async () => {
+      const slug = T();
+      await createMenu({
+          slug, name: 'A',
+          items: [
+              {text: 'Home', url: '/'},
+              {text: 'About', url: '/about'}
+          ]
+      });
+      try {
+          const md = `Hello\n\n[menu slug="${slug}" /]`;
+          const html = await parseMarkdown(md, {});
+          assert.match(html, /class="dm-menu/);
+          assert.match(html, /href="\/about"/);
+          assert.match(html, /<ul/);
+      } finally {
+          await deleteMenu(slug);
+      }
+  });
+
+  test('[menu location=...] renders the menu mapped to that slot', async () => {
+      const slug = T();
+      await createMenu({slug, name: 'A', items: [{text: 'Top', url: '/t'}]});
+      try {
+          await setLocations({navbar: slug});
+          const html = await parseMarkdown(`[menu location="navbar" /]`, {});
+          assert.match(html, /href="\/t"/);
+      } finally {
+          await setLocations({});
+          await deleteMenu(slug);
+      }
+  });
+
+  test('[menu] omits hidden items', async () => {
+      const slug = T();
+      await createMenu({
+          slug, name: 'A',
+          items: [{text: 'Visible', url: '/v'}, {text: 'Hidden', url: '/h', hidden: true}]
+      });
+      try {
+          const html = await parseMarkdown(`[menu slug="${slug}" /]`, {});
+          assert.match(html, /Visible/);
+          assert.doesNotMatch(html, /Hidden/);
+      } finally {
+          await deleteMenu(slug);
+      }
+  });
+
+  test('[menu] depth attr caps render depth', async () => {
+      const slug = T();
+      await createMenu({
+          slug, name: 'A',
+          items: [{text: 'Top', url: '/t', items: [{text: 'Mid', url: '/m', items: [{text: 'Deep', url: '/d'}]}]}]
+      });
+      try {
+          const html = await parseMarkdown(`[menu slug="${slug}" depth="2" /]`, {});
+          assert.match(html, /Top/);
+          assert.match(html, /Mid/);
+          assert.doesNotMatch(html, /Deep/);
+      } finally {
+          await deleteMenu(slug);
+      }
+  });
+
+  test('[menu] missing slug + location → empty render with no error', async () => {
+      const html = await parseMarkdown(`[menu /]`, {});
+      assert.doesNotMatch(html, /<ul/);
+  });
+  ```
+
+  If `parseMarkdown` isn't the actual export name, run `grep -n "export.*parse\|export.*render" server/services/markdown.js` to find the right one - adjust the import.
+
+- [ ] **Step 14.3: Run to confirm tests fail**
+
+  Run: `node --test tests/services/menus-shortcode.test.js`
+
+  Expected: failures - the `[menu]` shortcode renders the literal text or empty, not the `<ul>`.
+
+- [ ] **Step 14.4: Implement the shortcode**
+
+  In `server/services/markdown.js`, find the section where other self-closing shortcodes like `[view]` or `[block]` are processed. Add a sibling processor for `[menu]`:
+
+  ```js
+  /**
+   * Replace [menu slug="..." /] / [menu location="..." /] with rendered HTML.
+   * Self-closing only. Visibility filtering uses the request user from `context.user`.
+   */
+  async function processMenuShortcode(markdown, context) {
+      const re = /\[menu(\s+[^\]]*?)\s*\/\]/gi;
+      const matches = [...markdown.matchAll(re)];
+      if (!matches.length) return markdown;
+
+      const {resolveLocation, getMenu} = await import('./menus.js');
+      let out = markdown;
+      for (const m of matches) {
+          const attrs = context.parseShortcodeAttrs(m[1] || '');
+          let menu = null;
+          if (attrs.slug)         menu = await getMenu(attrs.slug);
+          else if (attrs.location) menu = await resolveLocation(attrs.location, context.user || null);
+          if (!menu) { out = out.replace(m[0], ''); continue; }
+
+          // For [menu slug=...] we still need to filter by user - resolveLocation
+          // does that for us, but the slug path does its own filtering here.
+          const items = attrs.slug
+              ? filterMenuForUser(menu.items || [], context.user || null)
+              : menu.items;
+
+          const depth = Number.parseInt(attrs.depth, 10);
+          const capped = Number.isFinite(depth) && depth > 0 ? capDepth(items, depth) : items;
+          const klass  = attrs.class ? ` ${context.escapeAttr(attrs.class)}` : '';
+          const variantClass = attrs.variant ? ` dm-menu--variant-${context.escapeAttr(attrs.variant)}` : '';
+          const html = `<nav class="dm-menu dm-menu--${context.escapeAttr(menu.slug)}${variantClass}${klass}" data-menu="${context.escapeAttr(menu.slug)}">${renderItemsAsUl(capped, context)}</nav>`;
+          out = out.replace(m[0], html);
+      }
+      return out;
+  }
+
+  function renderItemsAsUl(items, context) {
+      if (!items.length) return '';
+      const lis = items.map(it => {
+          const href  = context.escapeAttr(it.url || '#');
+          const text  = context.escapeAttr(it.text || '');
+          const child = Array.isArray(it.items) && it.items.length ? renderItemsAsUl(it.items, context) : '';
+          return `<li><a href="${href}">${text}</a>${child}</li>`;
+      }).join('');
+      return `<ul>${lis}</ul>`;
+  }
+
+  function capDepth(items, max, depth = 1) {
+      return items.map(it => ({
+          ...it,
+          items: depth < max && Array.isArray(it.items) ? capDepth(it.items, max, depth + 1) : []
+      }));
+  }
+
+  function filterMenuForUser(items, user) {
+      // Local mirror of resolveLocation's filter - used when looking up by slug
+      // directly (where we already have the menu but still need to gate).
+      const out = [];
+      for (const item of items) {
+          if (item.hidden) continue;
+          if (item.visibility != null) {
+              const role = user?.role || null;
+              if (!_checkVisibility(role, item.visibility)) continue;
+          }
+          out.push({...item, items: Array.isArray(item.items) ? filterMenuForUser(item.items, user) : []});
+      }
+      return out;
+  }
+  ```
+
+  At the top of `server/services/markdown.js`, add the visibility import:
+
+  ```js
+  import {checkVisibility as _checkVisibility} from '../middleware/auth.js';
+  ```
+
+- [ ] **Step 14.5: Wire processMenuShortcode into the main pipeline**
+
+  Find the main `parseMarkdown` (or equivalent) function that orchestrates the shortcode processors. Add a call to `processMenuShortcode` alongside the other self-closing shortcode calls (after `[block]` / `[view]` / `[collection]` per the docs' "Shortcode Nesting Rules"):
+
+  ```js
+  markdown = await processMenuShortcode(markdown, context);
+  ```
+
+  Make sure `context` includes `parseShortcodeAttrs`, `escapeAttr`, and the request `user` - the existing shortcode pipeline already populates these (see how `[view]` accesses them).
+
+- [ ] **Step 14.6: Run the shortcode tests**
+
+  Run: `node --test tests/services/menus-shortcode.test.js`
+
+  Expected: all five tests pass.
+
+---
+
+## Task 15: Public site footer rendering
+
+**Files:**
+
+- Modify: `public/js/site.js`
+
+- [ ] **Step 15.1: Locate the current footer init**
+
+  Run: `grep -n "footer\|__CMS_FOOTER__\|__CMS_SITE__" public/js/site.js | head -20`
+
+  Note where the site reads existing footer links from `__CMS_SITE__.footer.links`.
+
+- [ ] **Step 15.2: Read the new footer global and render two columns**
+
+  Replace the current footer init logic with:
+
+  ```js
+  // Footer: read window.__CMS_FOOTER__ for primary + legal columns and
+  // window.__CMS_SITE__.footer.copyright for the copyright line.
+  (function initFooter() {
+      const footerEl = $('#site-footer').get(0);
+      if (!footerEl) return;
+
+      const data = window.__CMS_FOOTER__ || {primary: [], legal: [], copyright: ''};
+
+      function itemHtml(it) {
+          const children = (it.items || []).map(c =>
+              `<li><a href="${c.url || '#'}">${c.text || ''}</a></li>`).join('');
+          return `<li><a href="${it.url || '#'}">${it.text || ''}</a>${children ? `<ul>${children}</ul>` : ''}</li>`;
+      }
+
+      const primaryHtml = data.primary.length
+          ? `<nav class="footer-nav footer-nav--primary"><ul>${data.primary.map(itemHtml).join('')}</ul></nav>`
+          : '';
+      const legalHtml = data.legal.length
+          ? `<nav class="footer-nav footer-nav--legal"><ul>${data.legal.map(itemHtml).join('')}</ul></nav>`
+          : '';
+      const copyrightHtml = data.copyright
+          ? `<div class="footer-copyright">${data.copyright}</div>`
+          : '';
+
+      $(footerEl).html(`${primaryHtml}${legalHtml}${copyrightHtml}`);
+      Domma.icons.scan(footerEl);
+  })();
+  ```
+
+  If the existing markup wraps the footer in different containers, preserve that structure - just point the nav HTML at `data.primary` and `data.legal`.
+
+- [ ] **Step 15.3: Browser smoke-test**
+
+  Hard-refresh the homepage in the browser. Confirm:
+
+  - The footer renders the migrated `footer` menu's items in the primary column.
+  - If no `footer-legal` mapping, the legal column is absent.
+  - Copyright line still renders from `site.json.footer.copyright`.
+
+  This is the second UI checkpoint - call out browser limitations explicitly if you can't reach it yourself.
+
+---
+
+## Task 16: Scaffolder integration - `menus` recipe branch
+
+**Files:**
+
+- Modify: `server/services/scaffolder.js`
+- Modify: `tests/services/scaffolder.test.js`
+
+- [ ] **Step 16.1: Write the menus-recipe test**
+
+  Append to `tests/services/scaffolder.test.js`:
+
+  ```js
+  test('applyRecipe - menus branch creates menus and updates locations', async () => {
+      const menuSlug = 'test-recipe-menu-' + Date.now();
+      // Stash a minimal one-off recipe by writing to RECIPES_DIR temporarily.
+      const tempRecipe = {
+          slug:        'test-menu-recipe',
+          name:        'Test menu recipe',
+          description: 'Scaffolder menu integration test',
+          icon:        'menu',
+          options:     [{name: 'menuSlug', label: 'Menu slug', default: menuSlug}],
+          menus: [
+              {
+                  slug:  '{{menuSlug}}',
+                  name:  'Recipe-created',
+                  items: [{text: 'Home', url: '/'}]
+              }
+          ]
+      };
+      const tempPath = path.join(RECIPES_DIR, 'test-menu-recipe.json');
+      await fs.writeFile(tempPath, JSON.stringify(tempRecipe), 'utf8');
+      try {
+          const result = await applyRecipe('test-menu-recipe', {options: {menuSlug}});
+          assert.ok(result.created.menus.includes(menuSlug));
+          const {getMenu, deleteMenu} = await import('../../server/services/menus.js');
+          const menu = await getMenu(menuSlug);
+          assert.ok(menu);
+          assert.equal(menu.name, 'Recipe-created');
+          await deleteMenu(menuSlug);
+      } finally {
+          await fs.unlink(tempPath).catch(() => {});
+      }
+  });
+  ```
+
+- [ ] **Step 16.2: Run to confirm the test fails**
+
+  Run: `node --test tests/services/scaffolder.test.js`
+
+  Expected: failure - `result.created.menus` is undefined.
+
+- [ ] **Step 16.3: Implement the menus branch**
+
+  In `server/services/scaffolder.js`:
+
+  - Add the import near the existing imports:
+
+    ```js
+    import {createMenu as createMenuFile, getMenu as getMenuFile, getLocations as getMenuLocations, setLocations as setMenuLocations} from './menus.js';
+    ```
+
+  - In `preflight()`, after the actions loop and before the final `return conflicts;`, add:
+
+    ```js
+    for (const menu of (resolvedRecipe.menus || [])) {
+        if (!menu.slug) continue;
+        if (await getMenuFile(menu.slug)) {
+            conflicts.push(`Menu "${menu.slug}" already exists`);
+        }
+    }
+    ```
+
+  - In `applyRecipe()`, initialise `created.menus = []` next to the existing `roles: []` / `users: []` array fields.
+
+  - Add the menus apply step between the **Roles** step (block `// 0. Roles`) and the **Collection** step (block `// 1. Collection`):
+
+    ```js
+    // 0b. Menus - write each declared menu and, if requested, map it to a slot.
+    for (const menu of (resolved.menus || [])) {
+        if (!menu.slug) continue;
+        try {
+            await createMenuFile({
+                slug:        menu.slug,
+                name:        menu.name || menu.slug,
+                description: menu.description || '',
+                ...(menu.variant  != null && {variant:  menu.variant}),
+                ...(menu.position != null && {position: menu.position}),
+                ...(menu.style    != null && {style:    menu.style}),
+                items: Array.isArray(menu.items) ? menu.items : [],
+                meta:  {bundled: true, presetOwner: recipeSlug}
+            });
+            created.menus.push(menu.slug);
+
+            if (Array.isArray(menu.locations) && menu.locations.length) {
+                const map = await getMenuLocations();
+                let touched = false;
+                for (const slot of menu.locations) {
+                    if (map[slot] && map[slot] !== menu.slug && !menu.force) {
+                        warnings.push(`Slot "${slot}" already mapped to "${map[slot]}" - left unchanged (set force:true to overwrite)`);
+                        continue;
+                    }
+                    map[slot] = menu.slug;
+                    touched = true;
+                }
+                if (touched) {
+                    try { await setMenuLocations(map); } catch (err) {
+                        warnings.push(`Locations update failed: ${err.message}`);
+                    }
+                }
+            }
+        } catch (err) {
+            warnings.push(`Menu "${menu.slug}" failed: ${err.message}`);
+        }
+    }
+    ```
+
+- [ ] **Step 16.4: Run the scaffolder tests**
+
+  Run: `node --test tests/services/scaffolder.test.js`
+
+  Expected: every test (including the new menus one) passes.
+
+---
+
+## Task 17: Admin api.js client
+
+**Files:**
+
+- Modify: `admin/js/api.js`
+
+- [ ] **Step 17.1: Find the existing client pattern**
+
+  Run: `grep -n "navigation:\|settings:\|api\\.navigation\|export const api" admin/js/api.js | head -10`
+
+  Note the export pattern - the existing `api.navigation = {get, save}` shape is what we mirror.
+
+- [ ] **Step 17.2: Add menus + menuLocations clients**
+
+  In `admin/js/api.js`, alongside the existing resource clients, add:
+
+  ```js
+  // Menus + menu locations (replaces the older single `navigation` client; the
+  // navigation client is kept temporarily so any cached admin code still works
+  // during a release cycle).
+  api.menus = {
+      list:      ()             => H.get('/api/menus'),
+      get:       (slug)         => H.get('/api/menus/' + encodeURIComponent(slug)),
+      create:    (menu)         => H.post('/api/menus', menu),
+      update:    (slug, menu)   => H.put('/api/menus/' + encodeURIComponent(slug), menu),
+      remove:    (slug)         => H.delete('/api/menus/' + encodeURIComponent(slug)),
+      duplicate: (slug)         => H.post('/api/menus/' + encodeURIComponent(slug) + '/duplicate')
+  };
+
+  api.menuLocations = {
+      get:      ()    => H.get('/api/menu-locations'),
+      save:     (map) => H.put('/api/menu-locations', map),
+      registry: ()    => H.get('/api/menu-locations/registry')
+  };
+  ```
+
+  If the file uses a single `export const api = {...}` literal rather than mutation, insert the two blocks as sibling properties.
+
+- [ ] **Step 17.3: Smoke-test the client**
+
+  Add a temporary test page in the browser dev console:
+
+  ```js
+  await api.menuLocations.registry()
+  ```
+
+  Expected: an array including `navbar`, `footer-primary`, `footer-legal`.
+
+  Notify the user that this requires browser interaction; ask them to run it if you cannot.
+
+---
+
+## Task 18: Sidebar + router updates
+
+**Files:**
+
+- Modify: `admin/js/config/sidebar-config.js`
+- Modify: `admin/js/app.js`
+
+- [ ] **Step 18.1: Rename the Structure entry from Navigation → Menus**
+
+  Open `admin/js/config/sidebar-config.js`. Find the line containing `id: 'navigation', text: 'Navigation'` (around line 49). Replace the entire conditional block:
+
+  ```js
+  if (canAny('navigation') || canAny('layouts')) {
+      items.push(
+          {heading: 'Structure'},
+          ...(canAny('navigation') ? [{id: 'navigation', text: 'Navigation', icon: 'menu',   url: '#/navigation', section: '#/navigation', badge: badge(counts.navigation)}] : []),
+          ...(canAny('layouts')    ? [{id: 'layouts',    text: 'Layouts',    icon: 'layout', url: '#/layouts',    section: '#/layouts',    badge: badge(counts.layouts)}]    : []),
+          {divider: true}
+      );
+  }
+  ```
+
+  With:
+
+  ```js
+  if (canAny('menus') || canAny('navigation') || canAny('layouts')) {
+      items.push(
+          {heading: 'Structure'},
+          ...(canAny('menus') ? [{id: 'menus', text: 'Menus', icon: 'menu', url: '#/menus', section: '#/menus', badge: badge(counts.menus)}] : []),
+          ...(canAny('layouts') ? [{id: 'layouts', text: 'Layouts', icon: 'layout', url: '#/layouts', section: '#/layouts', badge: badge(counts.layouts)}] : []),
+          {divider: true}
+      );
+  }
+  ```
+
+- [ ] **Step 18.2: Add menu routes + a redirect from /navigation**
+
+  Open `admin/js/app.js`. Find the route table (around line 243 - the `coreRoutes` array). Replace the line:
+
+  ```js
+  { path: '/navigation',     view: 'navigation',   title: 'Navigation - Domma CMS' },
+  ```
+
+  with:
+
+  ```js
+  { path: '/menus',                view: 'menus',          title: 'Menus - Domma CMS' },
+  { path: '/menus/new',            view: 'menuEditor',     title: 'New Menu - Domma CMS' },
+  { path: '/menus/edit/:slug',     view: 'menuEditor',     title: 'Edit Menu - Domma CMS' },
+  { path: '/menu-locations',       view: 'menuLocations',  title: 'Menu Locations - Domma CMS' },
+  // Backwards-compat redirect for bookmarks; the old navigation view is removed.
+  { path: '/navigation',           view: 'menusRedirect',  title: 'Menus - Domma CMS' },
+  ```
+
+- [ ] **Step 18.3: Add the redirect view**
+
+  Open `admin/js/views/index.js`. Add (alongside the other view exports):
+
+  ```js
+  export const menusRedirect = {
+      templateUrl: '',
+      async onMount(/* $container */) {
+          location.hash = '#/menus';
+      }
+  };
+  ```
+
+  If `index.js` uses a `views` object rather than named exports, add `menusRedirect` as a property.
+
+- [ ] **Step 18.4: Browser smoke-test**
+
+  Hard-refresh the admin SPA. Click "Menus" in the sidebar - should land on `#/menus`. Manually navigate to `#/navigation` - should redirect to `#/menus`.
+
+---
+
+## Task 19: Menus list view
+
+**Files:**
+
+- Create: `admin/js/views/menus.js`
+- Create: `admin/js/templates/menus.html`
+- Modify: `admin/js/views/index.js`
+
+- [ ] **Step 19.1: Create the list template**
+
+  Create `admin/js/templates/menus.html`:
+
+  ```html
+  <div class="page-header">
+      <h2><span data-icon="menu"></span> Menus</h2>
+      <div class="header-actions">
+          <a class="btn btn-secondary" href="#/menu-locations"><span data-icon="map"></span> Manage locations</a>
+          <a class="btn btn-primary" href="#/menus/new"><span data-icon="plus"></span> New menu</a>
+      </div>
+  </div>
+  <div id="menus-table"></div>
+  ```
+
+- [ ] **Step 19.2: Create the view**
+
+  Create `admin/js/views/menus.js`:
+
+  ```js
+  import {api} from '../api.js';
+
+  export const menusView = {
+      templateUrl: '/admin/js/templates/menus.html',
+      async onMount($container) {
+          let [menus, locations] = await Promise.all([
+              api.menus.list().catch(() => []),
+              api.menuLocations.get().catch(() => ({}))
+          ]);
+
+          // Build slug → [slot, slot] map for the "Mapped" column
+          const mappedBy = {};
+          for (const [slot, slug] of Object.entries(locations)) {
+              if (!mappedBy[slug]) mappedBy[slug] = [];
+              mappedBy[slug].push(slot);
+          }
+
+          T.create('#menus-table', {
+              data: menus,
+              empty: 'No menus yet. Click "New menu" to create one.',
+              columns: [
+                  {key: 'slug',  label: 'Slug',  sortable: true},
+                  {key: 'name',  label: 'Name',  sortable: true},
+                  {key: 'itemsCount', label: 'Items', render: row => String(row.itemsCount ?? 0)},
+                  {key: 'mapped', label: 'Mapped', render: row => {
+                      const slots = mappedBy[row.slug] || [];
+                      return slots.length
+                          ? slots.map(s => `<span class="badge badge-info">${s}</span>`).join(' ')
+                          : '<span class="text-muted">-</span>';
+                  }},
+                  {key: 'bundled', label: 'Bundled', render: row =>
+                      row.meta?.bundled ? `<span class="badge badge-secondary">bundled</span>` : ''
+                  },
+                  {key: '_actions', label: 'Actions', render: row => {
+                      const mapped = (mappedBy[row.slug] || []).length > 0;
+                      const delTip = mapped ? 'data-tooltip="Unmap this menu before deleting"' : '';
+                      const delDisabled = mapped ? 'disabled' : '';
+                      return `
+                          <a class="btn btn-sm btn-ghost" href="#/menus/edit/${encodeURIComponent(row.slug)}"><span data-icon="edit"></span></a>
+                          <button class="btn btn-sm btn-ghost btn-duplicate" data-slug="${row.slug}" data-tooltip="Duplicate"><span data-icon="copy"></span></button>
+                          <button class="btn btn-sm btn-danger btn-delete" data-slug="${row.slug}" ${delDisabled} ${delTip}><span data-icon="trash"></span></button>
+                      `;
+                  }}
+              ]
+          });
+
+          // Fill in item counts for the rendered rows (list endpoint omits items)
+          // Done after the initial render to keep the table snappy.
+          Domma.icons.scan('#menus-table');
+
+          $container.off('click', '.btn-duplicate').on('click', '.btn-duplicate', async function() {
+              const slug = $(this).data('slug');
+              try {
+                  const copy = await api.menus.duplicate(slug);
+                  E.toast(`Duplicated as "${copy.slug}".`, {type: 'success'});
+                  location.reload();
+              } catch (err) {
+                  E.toast(`Duplicate failed: ${err.message || err}`, {type: 'error'});
+              }
+          });
+
+          $container.off('click', '.btn-delete').on('click', '.btn-delete', async function() {
+              const slug = $(this).data('slug');
+              if (!await E.confirm(`Delete menu "${slug}"? This cannot be undone.`)) return;
+              try {
+                  await api.menus.remove(slug);
+                  E.toast('Menu deleted.', {type: 'success'});
+                  location.reload();
+              } catch (err) {
+                  E.toast(`Delete failed: ${err.message || err}`, {type: 'error'});
+              }
+          });
+      }
+  };
+  ```
+
+- [ ] **Step 19.3: Export the view**
+
+  In `admin/js/views/index.js`, add:
+
+  ```js
+  export {menusView as menus} from './menus.js';
+  ```
+
+  (Or add to the central `views` object if that's the pattern in the file.)
+
+- [ ] **Step 19.4: Browser smoke-test**
+
+  Hard-refresh the admin, navigate to `#/menus`. Confirm:
+
+  - The migrated `main` and `footer` menus are listed.
+  - "Mapped" column shows `navbar` next to `main`, `footer-primary` next to `footer`.
+  - Delete is disabled (with tooltip) for mapped menus.
+  - Duplicate works - creates `main-copy`.
+
+  Browser-test or surface as a blocker per `feedback_no_verified_without_browser.md`.
+
+---
+
+## Task 20: Menu editor - Items tab tree editor
+
+**Files:**
+
+- Create: `admin/js/views/menu-editor.js`
+- Create: `admin/js/templates/menu-editor.html`
+- Modify: `admin/js/views/index.js`
+- Modify: `admin/css/admin.css`
+
+This is the heaviest UI piece - a recursive tree editor with indent/outdent buttons.
+
+- [ ] **Step 20.1: Create the editor template**
+
+  Create `admin/js/templates/menu-editor.html`:
+
+  ```html
+  <div class="page-header">
+      <h2><span data-icon="menu"></span> <span id="me-title">Edit menu</span></h2>
+      <div class="header-actions">
+          <a class="btn btn-secondary" href="#/menus"><span data-icon="arrow-left"></span> Back</a>
+          <button class="btn btn-primary" id="me-save"><span data-icon="check"></span> Save</button>
+      </div>
+  </div>
+
+  <div class="tabs" id="me-tabs">
+      <div class="tab-list">
+          <button class="tab-item active" data-tab="me-items">Items</button>
+          <button class="tab-item"        data-tab="me-behaviour">Behaviour</button>
+          <button class="tab-item"        data-tab="me-meta">Meta</button>
+      </div>
+      <div class="tab-content">
+          <div class="tab-panel active" id="me-items" data-panel="me-items">
+              <div class="toolbar">
+                  <button class="btn btn-sm btn-secondary" id="me-add-item"><span data-icon="plus"></span> Add item</button>
+              </div>
+              <div id="me-items-list" class="menu-tree"></div>
+          </div>
+
+          <div class="tab-panel" id="me-behaviour" data-panel="me-behaviour">
+              <div id="me-behaviour-form"></div>
+          </div>
+
+          <div class="tab-panel" id="me-meta" data-panel="me-meta">
+              <div id="me-meta-form"></div>
+          </div>
+      </div>
+  </div>
+  ```
+
+- [ ] **Step 20.2: Create the editor view**
+
+  Create `admin/js/views/menu-editor.js`:
+
+  ```js
+  import {api} from '../api.js';
+
+  let _nextId = 1;
+  const uid = () => 'i_' + (_nextId++);
+
+  // Convert the persisted nested-array form into a flat array with parentId
+  // pointers, indexed so the tree renderer is simple recursive iteration.
+  function flatten(items, parentId = null, out = []) {
+      for (const it of (items || [])) {
+          const id = uid();
+          out.push({
+              id, parentId,
+              text: it.text || '', url: it.url || '', icon: it.icon || '',
+              visibility: it.visibility || '',
+              hidden: !!it.hidden, bundled: !!it.bundled
+          });
+          if (Array.isArray(it.items) && it.items.length) {
+              flatten(it.items, id, out);
+          }
+      }
+      return out;
+  }
+
+  // Re-nest the flat list back into the persisted shape.
+  function nest(flat) {
+      const byParent = new Map();
+      for (const r of flat) {
+          if (!byParent.has(r.parentId)) byParent.set(r.parentId, []);
+          byParent.get(r.parentId).push(r);
+      }
+      function build(parentId) {
+          return (byParent.get(parentId) || []).map(r => {
+              const children = build(r.id);
+              return {
+                  text: r.text.trim(),
+                  url:  r.url.trim(),
+                  ...(r.icon && {icon: r.icon.trim()}),
+                  ...(r.visibility && {visibility: r.visibility}),
+                  ...(r.hidden  && {hidden: true}),
+                  ...(r.bundled && {bundled: true}),
+                  ...(children.length && {items: children})
+              };
+          });
+      }
+      return build(null);
+  }
+
+  function escapeAttr(s) {
+      return String(s || '').replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+  }
+
+  function depthOf(id, flat) {
+      let d = 0;
+      let cur = flat.find(r => r.id === id);
+      while (cur && cur.parentId) {
+          d++;
+          cur = flat.find(r => r.id === cur.parentId);
+      }
+      return d;
+  }
+
+  function renderTree($host, flat) {
+      $host.html('');
+      // Render in tree order: parents before children.
+      function walk(parentId) {
+          for (const row of flat.filter(r => r.parentId === parentId)) {
+              const d = depthOf(row.id, flat);
+              $host.append(`
+                  <div class="menu-tree-row${row.hidden ? ' menu-tree-row--hidden' : ''}" data-id="${row.id}" style="margin-left:${d * 28}px">
+                      <span class="menu-tree-grip" data-icon="grip-vertical"></span>
+                      <input type="text" class="form-input me-text" value="${escapeAttr(row.text)}" placeholder="Label">
+                      <input type="text" class="form-input me-url"  value="${escapeAttr(row.url)}"  placeholder="/url">
+                      <input type="text" class="form-input me-icon" value="${escapeAttr(row.icon)}" placeholder="icon">
+                      <input type="text" class="form-input me-vis"  value="${escapeAttr(row.visibility)}" placeholder="visibility">
+                      <button class="btn btn-sm btn-ghost me-outdent" data-tooltip="Outdent"><span data-icon="chevron-left"></span></button>
+                      <button class="btn btn-sm btn-ghost me-indent"  data-tooltip="Indent"><span data-icon="chevron-right"></span></button>
+                      <button class="btn btn-sm btn-ghost me-up"      data-tooltip="Move up"><span data-icon="arrow-up"></span></button>
+                      <button class="btn btn-sm btn-ghost me-down"    data-tooltip="Move down"><span data-icon="arrow-down"></span></button>
+                      <button class="btn btn-sm btn-ghost me-hidden ${row.hidden ? 'active' : ''}" data-tooltip="${row.hidden ? 'Show' : 'Hide'}"><span data-icon="eye-off"></span></button>
+                      <button class="btn btn-sm btn-danger me-remove" data-tooltip="Remove"><span data-icon="trash"></span></button>
+                  </div>
+              `);
+              walk(row.id);
+          }
+      }
+      walk(null);
+      Domma.icons.scan($host.get(0));
+  }
+
+  function syncRowsFromDom($host, flat) {
+      $host.find('.menu-tree-row').each(function() {
+          const id  = $(this).data('id');
+          const row = flat.find(r => r.id === id);
+          if (!row) return;
+          row.text       = $(this).find('.me-text').val();
+          row.url        = $(this).find('.me-url').val();
+          row.icon       = $(this).find('.me-icon').val();
+          row.visibility = $(this).find('.me-vis').val();
+      });
+  }
+
+  export const menuEditorView = {
+      templateUrl: '/admin/js/templates/menu-editor.html',
+      async onMount($container) {
+          // Route params: empty slug = "new menu" mode
+          const hashMatch = location.hash.match(/^#\/menus\/edit\/(.+)$/);
+          const slug = hashMatch ? decodeURIComponent(hashMatch[1]) : null;
+          const isNew = !slug;
+
+          let menu;
+          if (isNew) {
+              menu = {slug: '', name: '', description: '', items: []};
+          } else {
+              try {
+                  menu = await api.menus.get(slug);
+              } catch (err) {
+                  E.toast(`Failed to load menu: ${err.message || err}`, {type: 'error'});
+                  location.hash = '#/menus';
+                  return;
+              }
+          }
+
+          $container.find('#me-title').text(isNew ? 'New menu' : `Edit "${menu.slug}"`);
+
+          let flat = flatten(menu.items);
+
+          // Items tab
+          const $list = $container.find('#me-items-list');
+          renderTree($list, flat);
+
+          $container.find('#me-add-item').on('click', () => {
+              syncRowsFromDom($list, flat);
+              flat.push({id: uid(), parentId: null, text: '', url: '/', icon: '', visibility: '', hidden: false, bundled: false});
+              renderTree($list, flat);
+          });
+
+          $container.off('click', '.me-remove').on('click', '.me-remove', function() {
+              const id = $(this).closest('.menu-tree-row').data('id');
+              flat = flat.filter(r => r.id !== id && r.parentId !== id);
+              renderTree($list, flat);
+          });
+
+          $container.off('click', '.me-indent').on('click', '.me-indent', function() {
+              syncRowsFromDom($list, flat);
+              const id = $(this).closest('.menu-tree-row').data('id');
+              const row = flat.find(r => r.id === id);
+              if (!row) return;
+              // Indent: parent becomes the previous sibling at the same depth (within the same parent).
+              const siblings = flat.filter(r => r.parentId === row.parentId);
+              const idx = siblings.findIndex(r => r.id === id);
+              if (idx <= 0) return; // can't indent first sibling
+              row.parentId = siblings[idx - 1].id;
+              renderTree($list, flat);
+          });
+
+          $container.off('click', '.me-outdent').on('click', '.me-outdent', function() {
+              syncRowsFromDom($list, flat);
+              const id = $(this).closest('.menu-tree-row').data('id');
+              const row = flat.find(r => r.id === id);
+              if (!row || row.parentId == null) return;
+              const parent = flat.find(r => r.id === row.parentId);
+              row.parentId = parent ? parent.parentId : null;
+              renderTree($list, flat);
+          });
+
+          $container.off('click', '.me-up').on('click', '.me-up', function() {
+              syncRowsFromDom($list, flat);
+              const id = $(this).closest('.menu-tree-row').data('id');
+              const siblings = flat.filter(r => r.parentId === flat.find(x => x.id === id)?.parentId);
+              const idx = siblings.findIndex(r => r.id === id);
+              if (idx <= 0) return;
+              // Swap positions inside the master flat array
+              const a = flat.indexOf(siblings[idx]);
+              const b = flat.indexOf(siblings[idx - 1]);
+              [flat[a], flat[b]] = [flat[b], flat[a]];
+              renderTree($list, flat);
+          });
+
+          $container.off('click', '.me-down').on('click', '.me-down', function() {
+              syncRowsFromDom($list, flat);
+              const id = $(this).closest('.menu-tree-row').data('id');
+              const siblings = flat.filter(r => r.parentId === flat.find(x => x.id === id)?.parentId);
+              const idx = siblings.findIndex(r => r.id === id);
+              if (idx === -1 || idx >= siblings.length - 1) return;
+              const a = flat.indexOf(siblings[idx]);
+              const b = flat.indexOf(siblings[idx + 1]);
+              [flat[a], flat[b]] = [flat[b], flat[a]];
+              renderTree($list, flat);
+          });
+
+          $container.off('click', '.me-hidden').on('click', '.me-hidden', function() {
+              syncRowsFromDom($list, flat);
+              const id = $(this).closest('.menu-tree-row').data('id');
+              const row = flat.find(r => r.id === id);
+              if (row) row.hidden = !row.hidden;
+              renderTree($list, flat);
+          });
+
+          // Tabs
+          E.tabs($container.find('#me-tabs').get(0));
+
+          // Behaviour tab - Domma F.create signature is (blueprint, values, options).renderTo(el)
+          const behBlueprint = {
+              variant:  {label: 'Variant',  type: 'select', options: [
+                  {value: '',            label: '- default -'},
+                  {value: 'transparent', label: 'Transparent'},
+                  {value: 'dark',        label: 'Dark'},
+                  {value: 'light',       label: 'Light'},
+                  {value: 'default',     label: 'Default'}
+              ]},
+              position: {label: 'Position', type: 'select', options: [
+                  {value: '',         label: '- default -'},
+                  {value: 'sticky',   label: 'Sticky'},
+                  {value: 'fixed',    label: 'Fixed'},
+                  {value: 'static',   label: 'Static'},
+                  {value: 'floating', label: 'Floating'}
+              ]},
+              fontFamily:    {label: 'Font family',    type: 'text'},
+              fontSize:      {label: 'Font size',      type: 'text'},
+              fontWeight:    {label: 'Font weight',    type: 'text'},
+              letterSpacing: {label: 'Letter spacing', type: 'text'},
+              iconSize:      {label: 'Icon size',      type: 'text'}
+          };
+          const behValues = {
+              variant:       menu.variant  || '',
+              position:      menu.position || '',
+              fontFamily:    menu.style?.fontFamily    || '',
+              fontSize:      menu.style?.fontSize      || '',
+              fontWeight:    menu.style?.fontWeight    || '',
+              letterSpacing: menu.style?.letterSpacing || '',
+              iconSize:      menu.style?.iconSize      || ''
+          };
+          const behEl = $container.find('#me-behaviour-form').get(0);
+          F.create(behBlueprint, behValues, {showSubmitButton: false}).renderTo(behEl);
+
+          // Meta tab
+          const metaBlueprint = {
+              slug:        {label: 'Slug',        type: 'text', required: true, hint: 'Lowercase, hyphens - affects file name'},
+              name:        {label: 'Name',        type: 'text', required: true},
+              description: {label: 'Description', type: 'text'}
+          };
+          const metaValues = {
+              slug:        menu.slug,
+              name:        menu.name,
+              description: menu.description
+          };
+          const metaEl = $container.find('#me-meta-form').get(0);
+          F.create(metaBlueprint, metaValues, {showSubmitButton: false}).renderTo(metaEl);
+
+          // Helper to read form values back via the rendered DOM
+          // (Domma F.create doesn't expose a read API - read inputs by [name=…]).
+          function readForm(el, keys) {
+              const out = {};
+              for (const k of keys) {
+                  const input = el.querySelector(`[name="${k}"]`);
+                  if (!input) continue;
+                  out[k] = input.type === 'checkbox' ? input.checked : input.value;
+              }
+              return out;
+          }
+
+          // Save handler
+          $container.find('#me-save').on('click', async () => {
+              syncRowsFromDom($list, flat);
+
+              const behForm  = readForm(behEl,  ['variant', 'position', 'fontFamily', 'fontSize', 'fontWeight', 'letterSpacing', 'iconSize']);
+              const metaForm = readForm(metaEl, ['slug', 'name', 'description']);
+
+              const next = {
+                  slug:        metaForm.slug,
+                  name:        metaForm.name,
+                  description: metaForm.description,
+                  ...(behForm.variant  && {variant:  behForm.variant}),
+                  ...(behForm.position && {position: behForm.position}),
+                  style: Object.fromEntries(
+                      Object.entries(behForm).filter(([k, v]) => ['fontFamily','fontSize','fontWeight','letterSpacing','iconSize'].includes(k) && v)
+                  ),
+                  items: nest(flat)
+              };
+              if (Object.keys(next.style).length === 0) delete next.style;
+
+              try {
+                  if (isNew) {
+                      await api.menus.create(next);
+                  } else if (next.slug !== menu.slug) {
+                      // Rename: POST new → PUT locations rewrite → DELETE old
+                      await api.menus.create(next);
+                      const map = await api.menuLocations.get();
+                      let touched = false;
+                      for (const [slot, val] of Object.entries(map)) {
+                          if (val === menu.slug) { map[slot] = next.slug; touched = true; }
+                      }
+                      if (touched) await api.menuLocations.save(map);
+                      await api.menus.remove(menu.slug);
+                  } else {
+                      await api.menus.update(menu.slug, next);
+                  }
+                  E.toast('Saved.', {type: 'success'});
+                  location.hash = '#/menus/edit/' + encodeURIComponent(next.slug);
+              } catch (err) {
+                  E.toast(`Save failed: ${err.message || err}`, {type: 'error'});
+              }
+          });
+      }
+  };
+  ```
+
+- [ ] **Step 20.3: Export the view**
+
+  In `admin/js/views/index.js`, add:
+
+  ```js
+  export {menuEditorView as menuEditor} from './menu-editor.js';
+  ```
+
+- [ ] **Step 20.4: Add tree-row styles**
+
+  Append to `admin/css/admin.css`:
+
+  ```css
+  .menu-tree-row {
+      display:        grid;
+      grid-template-columns: 16px 1.5fr 1.5fr 0.8fr 0.8fr repeat(6, auto);
+      gap:            6px;
+      align-items:    center;
+      padding:        4px 0;
+      transition:     opacity 0.15s ease;
+  }
+  .menu-tree-row--hidden { opacity: 0.5; }
+  .menu-tree-grip { cursor: grab; color: var(--dm-text-muted); }
+  .menu-tree { padding: 8px 0; }
+  ```
+
+- [ ] **Step 20.5: Browser smoke-test**
+
+  Hard-refresh admin, open `#/menus/edit/main`. Confirm:
+
+  - Items load and render as a tree, indented by depth.
+  - Indent/outdent buttons reparent items.
+  - Behaviour tab fields are populated from the migrated menu.
+  - Save returns to the same edit URL and the toast confirms success.
+  - Slug rename creates a new menu and updates the navbar location (verify via `/api/menu-locations`).
+
+  Limit-explicit: this is a UI-critical task. Surface a real browser limitation if you can't run it yourself.
+
+---
+
+## Task 21: Menu locations editor
+
+**Files:**
+
+- Create: `admin/js/views/menu-locations.js`
+- Create: `admin/js/templates/menu-locations.html`
+- Modify: `admin/js/views/index.js`
+
+- [ ] **Step 21.1: Create the template**
+
+  Create `admin/js/templates/menu-locations.html`:
+
+  ```html
+  <div class="page-header">
+      <h2><span data-icon="map"></span> Menu Locations</h2>
+      <div class="header-actions">
+          <a class="btn btn-secondary" href="#/menus"><span data-icon="arrow-left"></span> Back to Menus</a>
+          <button class="btn btn-primary" id="ml-save"><span data-icon="check"></span> Save</button>
+      </div>
+  </div>
+  <p class="text-muted">Map each registered slot to a menu. Plugins can register additional slots.</p>
+  <div id="ml-table"></div>
+  ```
+
+- [ ] **Step 21.2: Create the view**
+
+  Create `admin/js/views/menu-locations.js`:
+
+  ```js
+  import {api} from '../api.js';
+
+  function depthOfItems(items, current = 0) {
+      let max = current;
+      for (const it of (items || [])) {
+          if (Array.isArray(it.items) && it.items.length) {
+              max = Math.max(max, depthOfItems(it.items, current + 1));
+          }
+      }
+      return max + (items.length ? 1 : 0);
+  }
+
+  export const menuLocationsView = {
+      templateUrl: '/admin/js/templates/menu-locations.html',
+      async onMount($container) {
+          const [registry, map, menus] = await Promise.all([
+              api.menuLocations.registry(),
+              api.menuLocations.get(),
+              api.menus.list()
+          ]);
+
+          // Build a slug → max depth lookup so the warning column can render.
+          // For depth we need the full menu - fetch in parallel.
+          const fullMenus = await Promise.all(menus.map(m => api.menus.get(m.slug)));
+          const depthBySlug = Object.fromEntries(fullMenus.map(m => [m.slug, depthOfItems(m.items || [])]));
+
+          const rows = registry.map(slot => ({
+              slot:        slot.slot,
+              label:       slot.label,
+              source:      slot.source,
+              description: slot.description,
+              maxDepth:    slot.maxDepth,
+              menu:        map[slot.slot] || ''
+          }));
+
+          T.create('#ml-table', {
+              data: rows,
+              columns: [
+                  {key: 'slot',        label: 'Slot'},
+                  {key: 'label',       label: 'Label'},
+                  {key: 'source',      label: 'Source', render: r => `<span class="badge badge-secondary">${r.source}</span>`},
+                  {key: 'description', label: 'Description'},
+                  {key: 'menu', label: 'Menu', render: r => {
+                      const opts = ['<option value="">- none -</option>']
+                          .concat(menus.map(m =>
+                              `<option value="${m.slug}"${m.slug === r.menu ? ' selected' : ''}>${m.name || m.slug}</option>`
+                          ));
+                      return `<select class="form-select ml-select" data-slot="${r.slot}">${opts.join('')}</select>`;
+                  }},
+                  {key: 'warning', label: '', render: r => {
+                      if (!r.menu || r.maxDepth == null) return '';
+                      const d = depthBySlug[r.menu] || 0;
+                      return d > r.maxDepth
+                          ? `<span class="badge badge-warning" data-tooltip="This slot supports max depth ${r.maxDepth}; menu is depth ${d}">⚠ depth</span>`
+                          : '';
+                  }}
+              ]
+          });
+
+          Domma.icons.scan('#ml-table');
+
+          $container.find('#ml-save').on('click', async () => {
+              const next = {};
+              $container.find('.ml-select').each(function() {
+                  const slot = $(this).data('slot');
+                  const val  = $(this).val();
+                  if (val) next[slot] = val;
+              });
+              try {
+                  await api.menuLocations.save(next);
+                  E.toast('Locations saved.', {type: 'success'});
+              } catch (err) {
+                  E.toast(`Save failed: ${err.message || err}`, {type: 'error'});
+              }
+          });
+      }
+  };
+  ```
+
+- [ ] **Step 21.3: Export the view**
+
+  In `admin/js/views/index.js`:
+
+  ```js
+  export {menuLocationsView as menuLocations} from './menu-locations.js';
+  ```
+
+- [ ] **Step 21.4: Browser smoke-test**
+
+  Hard-refresh, navigate to `#/menu-locations`. Confirm:
+
+  - All three core slots appear (`navbar`, `footer-primary`, `footer-legal`).
+  - The mapped menu shows the migrated `main` / `footer` selections.
+  - Changing the select + Save updates `/api/menu-locations`.
+
+---
+
+## Task 22: Documentation updates
+
+**Files:**
+
+- Modify: `docs/configuration.md`
+- Modify: `docs/markdown-shortcodes.md`
+- Modify: `docs/plugin-development.md`
+- Modify: `docs/scaffolding.md`
+- Modify: `CLAUDE.md`
+
+- [ ] **Step 22.1: Update `docs/configuration.md`**
+
+  Replace the entire `## config/navigation.json` section with `## config/menus/<slug>.json` + `## config/menu-locations.json`. Copy the field tables from the spec - they're authoritative. Add a one-line backwards-compat note that mentions auto-migration on first boot and the `.bak` fallback.
+
+- [ ] **Step 22.2: Update `docs/markdown-shortcodes.md`**
+
+  Add a `[menu]` entry alongside `[block]` / `[view]` / `[collection]`. Use the four attribute examples from the spec verbatim. Note the depth attribute and that `slug` or `location` is required.
+
+- [ ] **Step 22.3: Update `docs/plugin-development.md`**
+
+  In the hooks section, add `registerMenuLocation()` with the same shape as other hook docs (signature, example, idempotency note).
+
+- [ ] **Step 22.4: Update `docs/scaffolding.md`**
+
+  Add the `menus` recipe branch to the recipe format reference. Show the `{slug, name, items, variant?, position?, locations?, force?}` shape and call out that bundled-from-recipe menus get `meta.bundled: true` and `meta.presetOwner: <recipeSlug>`.
+
+- [ ] **Step 22.5: Update `CLAUDE.md`**
+
+  In the project `CLAUDE.md`, replace any specific guidance about `config/navigation.json` (e.g. the "Navigation Dropdown Pattern" / "Navbar Dropdown Toggle" sections) with a pointer to the multi-menu architecture. Add a one-paragraph summary:
+
+  > **Multi-menu system.** Menus live in `config/menus/<slug>.json`. The slot → menu map lives in `config/menu-locations.json`. Built-in slots are `navbar`, `footer-primary`, `footer-legal`; plugins register additional slots via `hooks.registerMenuLocation()`. The public navbar's brand is on `site.json.brand` (parallel to `adminBrand`); items + variant + position come from the menu mapped to `navbar`. The `[menu]` shortcode renders any menu inline.
+
+  Keep the existing Domma navbar gotchas - they still apply.
+
+---
+
+## Task 23: Final verification pass
+
+**Files:** none (verification only)
+
+- [ ] **Step 23.1: Run the full test suite**
+
+  Run: `node --test tests/services/menus.test.js tests/services/menus-migration.test.js tests/services/menus-shortcode.test.js tests/services/scaffolder.test.js tests/routes/menus.test.js`
+
+  Expected: all pass.
+
+- [ ] **Step 23.2: Live browser walkthrough**
+
+  Hard-refresh the admin SPA. Walk through the full happy path:
+
+  1. Sidebar shows "Menus" (not "Navigation"). Click it → land on `#/menus` list.
+  2. `main` and `footer` menus listed, "Mapped" chips visible.
+  3. Edit `main` → all migrated items visible in tree form.
+  4. Add a new item, save → toast confirms, item appears in the public navbar after hard-refresh of `/`.
+  5. Manage locations → all three slots, correct sources, save works.
+  6. New menu via "New menu" button → save → new menu file written.
+  7. `[menu slug="footer" /]` in a page → renders nested `<ul>` on the public side.
+  8. `#/navigation` → redirects to `#/menus`.
+
+  Surface a real browser limit explicitly per `feedback_no_verified_without_browser.md`. The user should drive this if you can't.
+
+- [ ] **Step 23.3: Hand off to the user for commit**
+
+  Per `feedback_no_commits.md`, do not commit. Summarise the changes and let the user commit when ready. Suggest a commit message like:
+
+  > Multi-menu system with locations registry + auto-migration of navigation.json + footer.links; new [menu] shortcode; scaffolder recipe support; permissions family