domma-cms 1.6.60 → 1.7.0

package/docs/superpowers/plans/2026-05-25-admin-sidebar-via-menus.md

@@ -0,0 +1,1112 @@
+# Admin Sidebar via 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 the hand-rolled `admin/js/config/sidebar-config.js` flat-array sidebar with a menu rendered from the Menus system at a new built-in slot `admin-sidebar`. Plugins extend via the menu-locations registry. The Menus admin can edit the sidebar visually. Native `<details>`/`<summary>` provides expand/collapse for nested folders.
+
+**Architecture:** A new core slot `admin-sidebar` is registered in the Menus service. A one-shot migration writes the current sidebar structure to `config/menus/admin-sidebar.json` on first boot and maps the slot. A new `admin/js/lib/sidebar-renderer.js` fetches the menu, merges plugin-registered items, synthesises per-project sub-trees, filters by user permission, and renders nested `<details>` elements. The old `Domma.elements.sidebar(...)` call site in `app.js` is replaced; `sidebar-config.js` becomes a deprecated stub.
+
+**Tech Stack:** Fastify 5 (ESM), Domma SPA admin (`$`/`E`/`F`/`T`/`I`/`H`/`S`), `node:test`, native `<details>`/`<summary>` for expand/collapse, no upstream `domma-js` dependency.
+
+**Spec:** `docs/superpowers/specs/2026-05-25-admin-sidebar-via-menus-design.md`
+
+**Critical project rules** (from `CLAUDE.md` + memory):
+
+- Server always running on port **4096** - never start/stop.
+- Domma admin uses `$`, `H.get/post/put/delete`, `E.toast/confirm`, `S.set/get`, `Domma.icons.scan`.
+- `.get(0)` to unwrap collections.
+- T.create render fns are `(value, row)` two-arg - NOT single-arg.
+- Admin 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`).
+- Do NOT commit during implementation - user commits separately (memory: `feedback_no_commits.md`).
+- No `Co-Authored-By` footers.
+
+---
+
+## File Map
+
+| Path | Purpose | Action |
+|---|---|---|
+| `server/services/menus.js` | Register `admin-sidebar` core slot; allow `permission` field on items | Modify |
+| `server/services/sidebar-migration.js` | One-shot seed of `admin-sidebar.json` + locations patch | Create |
+| `server/services/hooks.js` | Add `registerSidebarItem()` export | Modify |
+| `server/services/plugins.js` | Expose `registerSidebarItem` to plugins (hooks object) | Modify |
+| `server/server.js` | Wire `sidebar-migration` into boot; register `/api/sidebar/registered-items` route | Modify |
+| `server/routes/api/sidebar.js` | New route module for `/api/sidebar/registered-items` | Create |
+| `admin/js/lib/sidebar-renderer.js` | The new sidebar renderer | Create |
+| `admin/js/app.js` | Replace `Domma.elements.sidebar(...)` call with new renderer | Modify |
+| `admin/js/config/sidebar-config.js` | Stub: returns `[]` + deprecation comment | Modify (gut) |
+| `admin/js/views/menu-editor.js` | Add `permission` field to item-row template + save handler | Modify |
+| `admin/css/admin.css` | Styles for `<details>`-based sidebar | Modify |
+| `tests/services/menus.test.js` | Add tests for `admin-sidebar` slot registration + `permission` field acceptance | Modify |
+| `tests/services/sidebar-migration.test.js` | New - migration tests against temp config dirs | Create |
+| `tests/routes/sidebar.test.js` | New - smoke tests for `/api/sidebar/registered-items` | Create |
+| `docs/configuration.md` | Document `admin-sidebar` slot + `permission` field | Modify |
+| `docs/plugin-development.md` | Document `hooks.registerSidebarItem()` | Modify |
+| `docs/api-reference.md` | Document `/api/sidebar/registered-items` | Modify |
+| `CLAUDE.md` | Note menu-data-driven admin sidebar | Modify |
+
+---
+
+## Task 1: Register `admin-sidebar` core slot + accept `permission` on items
+
+**Files:**
+
+- Modify: `server/services/menus.js`
+- Modify: `tests/services/menus.test.js`
+
+### Step 1.1: Write the test
+
+Append to `tests/services/menus.test.js`:
+
+```js
+test('registry - admin-sidebar core slot is registered at module load', () => {
+    const slots = getLocationRegistry().map(s => s.slot);
+    assert.ok(slots.includes('admin-sidebar'), 'admin-sidebar slot should be registered by core');
+});
+
+test('validateMenu - accepts `permission` field on items without complaint', () => {
+    const errors = validateMenu({
+        slug: 'admin-sidebar-test',
+        name: 'X',
+        items: [
+            {text: 'Pages', url: '#/pages', permission: 'pages'},
+            {text: 'No permission item', url: '#/foo'}
+        ]
+    });
+    assert.deepEqual(errors, []);
+});
+```
+
+### Step 1.2: Run to confirm failure
+
+Run: `node --test tests/services/menus.test.js 2>&1 | tail -10`
+
+Expected: the `admin-sidebar` slot test fails (slot not yet registered). The `permission` test may already pass because `validateMenu` doesn't currently reject unknown item keys.
+
+### Step 1.3: Register the core slot
+
+In `server/services/menus.js`, find the existing core-slot registration block (`registerLocation('navbar', …)` etc., around the bottom of the module). Add:
+
+```js
+registerLocation('admin-sidebar', {
+    label:       'Admin sidebar',
+    description: 'The left-side navigation in the admin panel',
+    source:      'core',
+    maxDepth:    null
+});
+```
+
+### Step 1.4: Confirm `permission` is preserved through createMenu/updateMenu
+
+In `server/services/menus.js`, locate `createMenu`. The function builds the persisted menu shape from `input`. Items are written via `items: Array.isArray(input.items) ? input.items : []` - the whole item object passes through, so `permission` is preserved without code change. Verify by reading the code.
+
+If the validateMenu test from Step 1.1 already passes (because validateMenu doesn't whitelist item keys), no further change is needed.
+
+### Step 1.5: Run tests
+
+Run: `node --test tests/services/menus.test.js 2>&1 | tail -5`
+
+Expected: all tests pass (including the two new ones).
+
+---
+
+## Task 2: Sidebar migration service
+
+**Files:**
+
+- Create: `server/services/sidebar-migration.js`
+- Create: `tests/services/sidebar-migration.test.js`
+
+### Step 2.1: Write the migration tests
+
+Create `tests/services/sidebar-migration.test.js`:
+
+```js
+/**
+ * Sidebar migration - exercises the one-shot seed flow on a temporary
+ * config dir so the real project config is untouched.
+ */
+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/sidebar-migration.js';
+
+async function scratch() {
+    return fs.mkdtemp(path.join(os.tmpdir(), 'sidebar-migration-'));
+}
+
+test('no-op when admin-sidebar.json already exists', async () => {
+    const dir = await scratch();
+    await fs.mkdir(path.join(dir, 'menus'), {recursive: true});
+    await fs.writeFile(path.join(dir, 'menus', 'admin-sidebar.json'), '{}', 'utf8');
+    const result = await runMigration({configDir: dir});
+    assert.equal(result.migrated, false);
+    assert.equal(result.reason, 'admin-sidebar.json already present');
+});
+
+test('seeds admin-sidebar.json with the standard tree', async () => {
+    const dir = await scratch();
+    const result = await runMigration({configDir: dir});
+    assert.equal(result.migrated, true);
+
+    const menu = JSON.parse(await fs.readFile(path.join(dir, 'menus', 'admin-sidebar.json'), 'utf8'));
+    assert.equal(menu.slug, 'admin-sidebar');
+    assert.ok(Array.isArray(menu.items));
+    assert.ok(menu.items.length >= 5, 'should seed at least 5 top-level sections');
+    const flat = [];
+    const walk = (xs) => xs.forEach(x => { flat.push(x); if (x.items) walk(x.items); });
+    walk(menu.items);
+    const pages = flat.find(x => x.text === 'Pages');
+    assert.ok(pages, 'Pages item should exist in seeded tree');
+    assert.equal(pages.permission, 'pages');
+});
+
+test('patches menu-locations.json to add admin-sidebar mapping', async () => {
+    const dir = await scratch();
+    await fs.writeFile(path.join(dir, 'menu-locations.json'), '{"navbar":"main"}', 'utf8');
+    await runMigration({configDir: dir});
+    const map = JSON.parse(await fs.readFile(path.join(dir, 'menu-locations.json'), 'utf8'));
+    assert.equal(map.navbar, 'main');
+    assert.equal(map['admin-sidebar'], 'admin-sidebar');
+});
+
+test('creates menu-locations.json when absent', async () => {
+    const dir = await scratch();
+    await runMigration({configDir: dir});
+    const map = JSON.parse(await fs.readFile(path.join(dir, 'menu-locations.json'), 'utf8'));
+    assert.equal(map['admin-sidebar'], 'admin-sidebar');
+});
+```
+
+### Step 2.2: Run to confirm failure
+
+Run: `node --test tests/services/sidebar-migration.test.js`
+
+Expected: `ERR_MODULE_NOT_FOUND` for `sidebar-migration.js`.
+
+### Step 2.3: Implement the migration
+
+Create `server/services/sidebar-migration.js`:
+
+```js
+/**
+ * Admin sidebar auto-migration.
+ *
+ * Runs once on server boot. Idempotent - guarded by the existence of
+ * config/menus/admin-sidebar.json. Seeds the admin sidebar menu with the
+ * standard tree (Overview, Projects, Content, Data, System, Documentation)
+ * and patches config/menu-locations.json to map the `admin-sidebar` slot.
+ */
+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');
+
+const SEED_ITEMS = [
+    {
+        text: 'Overview', icon: 'home',
+        items: [
+            {text: 'Dashboard', url: '#/', icon: 'home'}
+        ]
+    },
+    {
+        text: 'Projects', icon: 'folder', permission: 'projects',
+        items: [
+            {text: 'Manage projects', url: '#/projects', icon: 'folder', permission: 'projects'}
+        ]
+    },
+    {
+        text: 'Content', icon: 'edit',
+        items: [
+            {text: 'Pages', url: '#/pages', icon: 'file-text', permission: 'pages'},
+            {text: 'Media', url: '#/media', icon: 'image',     permission: 'media'},
+            {text: 'Menus', url: '#/menus', icon: 'menu',      permission: 'menus'}
+        ]
+    },
+    {
+        text: 'Data', icon: 'database',
+        items: [
+            {text: 'Collections', url: '#/collections', icon: 'database',  permission: 'collections'},
+            {text: 'Forms',       url: '#/forms',       icon: 'layout',    permission: 'collections'},
+            {text: 'Views',       url: '#/views',       icon: 'eye',       permission: 'views'},
+            {text: 'Actions',     url: '#/actions',     icon: 'zap',       permission: 'actions'},
+            {text: 'Blocks',      url: '#/blocks',      icon: 'box',       permission: 'pages'},
+            {text: 'Components',  url: '#/components',  icon: 'component', permission: 'components'}
+        ]
+    },
+    {
+        text: 'System', icon: 'settings',
+        items: [
+            {text: 'Notifications', url: '#/system/notifications', icon: 'bell',     permission: 'notifications'},
+            {text: 'Roles',         url: '#/roles',                icon: 'shield',   permission: 'plugins'},
+            {text: 'Users',         url: '#/users',                icon: 'users',    permission: 'users'},
+            {text: 'Site Settings', url: '#/settings',             icon: 'settings', permission: 'settings'},
+            {text: 'Effects',       url: '#/effects',              icon: 'sparkles', permission: 'settings'},
+            {text: 'Layouts',       url: '#/layouts',              icon: 'layout',   permission: 'layouts'},
+            {text: 'Plugins',       url: '#/plugins',              icon: 'package',  permission: 'plugins'},
+            {text: 'My Profile',    url: '#/my-profile',           icon: 'user'}
+        ]
+    },
+    {
+        text: 'Documentation', icon: 'book',
+        items: [
+            {text: 'Usage',         url: '#/documentation',  icon: 'book'},
+            {text: 'Tutorials',     url: '#/tutorials',      icon: 'document'},
+            {text: 'API Reference', url: '#/api-reference',  icon: 'code'}
+        ]
+    }
+];
+
+async function exists(p) {
+    try { await fs.access(p); return true; } catch { return false; }
+}
+
+async function readJson(p) {
+    return JSON.parse(await fs.readFile(p, 'utf8'));
+}
+
+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;
+    const menusDir  = path.join(configDir, 'menus');
+    const menuPath  = path.join(menusDir, 'admin-sidebar.json');
+    const locPath   = path.join(configDir, 'menu-locations.json');
+
+    if (await exists(menuPath)) {
+        return {migrated: false, reason: 'admin-sidebar.json already present'};
+    }
+
+    await fs.mkdir(menusDir, {recursive: true});
+    const now = new Date().toISOString();
+    await writeJson(menuPath, {
+        slug:        'admin-sidebar',
+        name:        'Admin sidebar',
+        description: 'Auto-seeded by sidebar migration on first boot',
+        items:       SEED_ITEMS,
+        meta:        {createdAt: now, updatedAt: now, bundled: false, presetOwner: null}
+    });
+
+    let locations = {};
+    if (await exists(locPath)) {
+        try { locations = await readJson(locPath); } catch { /* malformed - start fresh */ }
+    }
+    locations['admin-sidebar'] = 'admin-sidebar';
+    await writeJson(locPath, locations);
+
+    console.log('[admin-sidebar] Seeded admin-sidebar menu + mapped admin-sidebar slot');
+    return {migrated: true};
+}
+```
+
+### Step 2.4: Run tests
+
+Run: `node --test tests/services/sidebar-migration.test.js`
+
+Expected: 4/4 pass.
+
+---
+
+## Task 3: Wire migration into server boot
+
+**Files:**
+
+- Modify: `server/server.js`
+
+### Step 3.1: Find the existing menus migration call
+
+Run: `grep -n "runMenusMigration\|menus-migration" server/server.js`
+
+### Step 3.2: Add the sidebar migration call
+
+Immediately AFTER the existing menus migration block in `server/server.js`, add:
+
+```js
+try {
+    const {runMigration: runSidebarMigration} = await import('./services/sidebar-migration.js');
+    await runSidebarMigration();
+} catch (err) {
+    app.log.warn(`[admin-sidebar] Migration skipped: ${err.message}`);
+}
+```
+
+### Step 3.3: Verify syntax
+
+```bash
+node --check server/server.js
+node -e "import('./server/services/sidebar-migration.js').then(m => console.log('migration ok:', typeof m.runMigration))"
+```
+
+Expected: silent + `migration ok: function`.
+
+DO NOT restart the server. The migration will fire on the next user-initiated restart.
+
+---
+
+## Task 4: `registerSidebarItem` plugin hook
+
+**Files:**
+
+- Modify: `server/services/hooks.js`
+- Modify: `server/services/plugins.js`
+
+### Step 4.1: Add the hook export
+
+In `server/services/hooks.js`, after the existing `registerMenuLocation` block, add:
+
+```js
+// ---------------------------------------------------------------------------
+// Admin sidebar items - plugin-registered runtime injection
+// ---------------------------------------------------------------------------
+
+const _registeredSidebarItems = [];
+
+/**
+ * Register a sidebar item from a plugin. Items are merged into the rendered
+ * admin sidebar at render time - they are NOT persisted into menu JSON.
+ * Plugins re-register on each server boot via their setupPlugin hook.
+ *
+ * @param {{parent?: string, item: {text: string, url: string, icon?: string, permission?: string, items?: object[]}}} opts
+ */
+export function registerSidebarItem(opts) {
+    if (!opts || !opts.item || typeof opts.item.text !== 'string') {
+        throw new Error('registerSidebarItem: opts.item.text is required');
+    }
+    _registeredSidebarItems.push({
+        parent: opts.parent || null,
+        item:   opts.item
+    });
+}
+
+/**
+ * @returns {Array<{parent: string|null, item: object}>}
+ */
+export function getRegisteredSidebarItems() {
+    return _registeredSidebarItems.slice();
+}
+```
+
+### Step 4.2: Expose to plugins via the loader
+
+In `server/services/plugins.js`, find the line that builds the `hooks` object passed to each plugin's Fastify registration (currently includes `registerMenuLocation`). Update the import + the hooks object:
+
+```js
+import {hooks, registerSanitizeRules, registerShortcode, registerTransform, registerMenuLocation, registerSidebarItem} from './hooks.js';
+```
+
+Then update the `hooks:` block in the plugin register call:
+
+```js
+hooks: {registerShortcode, registerSanitizeRules, registerTransform, registerMenuLocation, registerSidebarItem, on: hooks.on.bind(hooks)},
+```
+
+### Step 4.3: Smoke test
+
+Run:
+```bash
+node -e "import('./server/services/hooks.js').then(h => { h.registerSidebarItem({parent: 'system', item: {text: 'X', url: '#/x'}}); console.log(h.getRegisteredSidebarItems()); })"
+```
+
+Expected: prints `[ { parent: 'system', item: { text: 'X', url: '#/x' } } ]`.
+
+---
+
+## Task 5: `/api/sidebar/registered-items` route
+
+**Files:**
+
+- Create: `server/routes/api/sidebar.js`
+- Create: `tests/routes/sidebar.test.js`
+
+### Step 5.1: Write the route test
+
+Create `tests/routes/sidebar.test.js`:
+
+```js
+/**
+ * Smoke test for /api/sidebar/registered-items.
+ */
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import Fastify from 'fastify';
+import fastifyJwt from '@fastify/jwt';
+import {sidebarRoutes} from '../../server/routes/api/sidebar.js';
+import {registerSidebarItem} from '../../server/services/hooks.js';
+
+async function buildApp() {
+    const app = Fastify();
+    app.register(fastifyJwt, {secret: 'test-secret-only-for-tests-32chars'});
+    const authenticate      = async (req) => { req.user = {id: 'sa', role: 'super-admin'}; };
+    const requirePermission = () => async () => {};
+    await app.register(async (inst) => sidebarRoutes(inst, {authenticate, requirePermission}), {prefix: '/api'});
+    return app;
+}
+
+test('GET /api/sidebar/registered-items returns an array', async () => {
+    const app = await buildApp();
+    const res = await app.inject({method: 'GET', url: '/api/sidebar/registered-items'});
+    assert.equal(res.statusCode, 200);
+    assert.ok(Array.isArray(res.json()));
+    await app.close();
+});
+
+test('GET /api/sidebar/registered-items reflects registerSidebarItem calls', async () => {
+    registerSidebarItem({parent: 'system', item: {text: 'PluginX', url: '#/plugin-x'}});
+    const app = await buildApp();
+    const res = await app.inject({method: 'GET', url: '/api/sidebar/registered-items'});
+    const body = res.json();
+    assert.ok(body.some(entry => entry.item.text === 'PluginX'));
+    await app.close();
+});
+```
+
+### Step 5.2: Run to confirm failure
+
+Run: `node --test tests/routes/sidebar.test.js`
+
+Expected: import error.
+
+### Step 5.3: Implement the route
+
+Create `server/routes/api/sidebar.js`:
+
+```js
+/**
+ * Admin sidebar API
+ *
+ * GET /api/sidebar/registered-items - plugin-registered sidebar items
+ *
+ * Auth middlewares are accepted as DI options so tests can supply no-ops.
+ */
+import {
+    authenticate as defaultAuthenticate,
+    requirePermission as defaultRequirePermission
+} from '../../middleware/auth.js';
+import {getRegisteredSidebarItems} from '../../services/hooks.js';
+
+export async function sidebarRoutes(fastify, opts = {}) {
+    const authenticate      = opts.authenticate      || defaultAuthenticate;
+    const requirePermission = opts.requirePermission || defaultRequirePermission;
+
+    const canRead = {preHandler: [authenticate, requirePermission('menus', 'read')]};
+
+    fastify.get('/sidebar/registered-items', canRead, async () => {
+        return getRegisteredSidebarItems();
+    });
+}
+```
+
+### Step 5.4: Run tests
+
+Run: `node --test tests/routes/sidebar.test.js`
+
+Expected: 2/2 pass.
+
+---
+
+## Task 6: Wire `/api/sidebar/*` route into server.js
+
+**Files:**
+
+- Modify: `server/server.js`
+
+### Step 6.1: Add import + register
+
+In `server/server.js`, alongside the existing menus route registration:
+
+```js
+const {sidebarRoutes} = await import('./routes/api/sidebar.js');
+```
+
+Then register:
+
+```js
+await app.register(sidebarRoutes, {prefix: '/api'});
+```
+
+### Step 6.2: Verify
+
+```bash
+node --check server/server.js
+```
+
+Expected: silent.
+
+DO NOT restart the server.
+
+---
+
+## Task 7: Sidebar renderer module
+
+**Files:**
+
+- Create: `admin/js/lib/sidebar-renderer.js`
+
+This is the heart of the new UX. Async render, fetches menu + projects + plugin items, merges, filters, emits nested `<details>` markup, and inserts via `replaceChildren` + `createContextualFragment` (modern safe DOM API - no `el.innerHTML =` assignments).
+
+### Step 7.1: Create the renderer
+
+Create `admin/js/lib/sidebar-renderer.js`:
+
+```js
+/**
+ * Admin sidebar renderer.
+ *
+ * Replaces Domma.elements.sidebar(...) for the admin panel. Reads sidebar
+ * structure from the Menus system (slot `admin-sidebar`), merges plugin-
+ * registered items, synthesises per-project sub-trees, filters by user
+ * permission, and renders nested <details>/<summary> for expand/collapse.
+ *
+ * All user-supplied strings are escaped via esc() before being interpolated
+ * into the rendered markup. Markup is inserted using
+ * Range#createContextualFragment + Element#replaceChildren (modern safe DOM
+ * API) rather than innerHTML assignment.
+ *
+ * Fallback when no admin-sidebar menu is mapped or available: render a
+ * minimal Dashboard + Menus tree so the admin can always escape a broken
+ * state.
+ */
+import {api} from '../api.js';
+
+function esc(s) {
+    return String(s == null ? '' : s)
+        .replace(/&/g, '&amp;').replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+const FALLBACK_TREE = [
+    {text: 'Dashboard', url: '#/',      icon: 'home'},
+    {text: 'Menus',     url: '#/menus', icon: 'menu'}
+];
+
+function canAny(permissions, resource) {
+    if (!resource) return true;
+    if (!permissions || !permissions.length) return false;
+    if (permissions.includes(resource)) return true;
+    return ['read', 'create', 'update', 'delete'].some(a => permissions.includes(`${resource}.${a}`));
+}
+
+function filterByPermission(items, permissions) {
+    const out = [];
+    for (const item of items) {
+        if (item.hidden) continue;
+        if (item.permission && !canAny(permissions, item.permission)) continue;
+        const children = Array.isArray(item.items) && item.items.length
+            ? filterByPermission(item.items, permissions)
+            : [];
+        out.push({...item, items: children});
+    }
+    return out;
+}
+
+function mergePluginItems(tree, registered) {
+    if (!registered || !registered.length) return tree;
+    const findParent = (xs, parentText) => {
+        for (const node of xs) {
+            if ((node.text || '').toLowerCase() === parentText.toLowerCase()) return node;
+            if (Array.isArray(node.items)) {
+                const found = findParent(node.items, parentText);
+                if (found) return found;
+            }
+        }
+        return null;
+    };
+    for (const reg of registered) {
+        if (reg.parent) {
+            const parent = findParent(tree, reg.parent);
+            if (parent) {
+                parent.items = Array.isArray(parent.items) ? parent.items : [];
+                parent.items.push(reg.item);
+            } else {
+                tree.push(reg.item);
+            }
+        } else {
+            tree.push(reg.item);
+        }
+    }
+    return tree;
+}
+
+async function buildProjectsSubtree(permissions) {
+    if (!canAny(permissions, 'projects')) return [];
+    let projects = [];
+    try { projects = await api.projects.list(); } catch { return []; }
+    const countsByProject = {};
+    await Promise.all(projects.map(async p => {
+        try {
+            const grouped = await api.projects.artefacts(p.slug);
+            countsByProject[p.slug] = grouped;
+        } catch { countsByProject[p.slug] = {}; }
+    }));
+
+    const TYPE_DEFS = [
+        {key: 'pages',       text: 'Pages',       icon: 'file-text', path: '/pages'},
+        {key: 'collections', text: 'Collections', icon: 'database',  path: '/collections'},
+        {key: 'forms',       text: 'Forms',       icon: 'layout',    path: '/forms'},
+        {key: 'actions',     text: 'Actions',     icon: 'zap',       path: '/actions'},
+        {key: 'menus',       text: 'Menus',       icon: 'menu',      path: '/menus'},
+        {key: 'blocks',      text: 'Blocks',      icon: 'box',       path: '/blocks'},
+        {key: 'views',       text: 'Views',       icon: 'eye',       path: '/views'},
+        {key: 'roles',       text: 'Roles',       icon: 'shield',    path: '/roles'},
+        {key: 'users',       text: 'Users',       icon: 'users',     path: '/users'}
+    ];
+
+    return projects.map(p => {
+        const slugEnc = encodeURIComponent(p.slug);
+        const base    = '#/projects/' + slugEnc;
+        const counts  = countsByProject[p.slug] || {};
+        const children = [
+            {text: 'Overview', url: base, icon: p.icon || 'folder'}
+        ];
+        for (const def of TYPE_DEFS) {
+            const arr = counts[def.key];
+            const n = Array.isArray(arr) ? arr.length : 0;
+            if (n <= 0) continue;
+            children.push({text: `${def.text} (${n})`, url: base + def.path, icon: def.icon});
+        }
+        children.push({text: 'Settings', url: base + '/settings', icon: 'settings'});
+        return {
+            text:  p.name || p.slug,
+            icon:  p.icon || 'folder',
+            items: children
+        };
+    });
+}
+
+function injectProjectsSubtree(tree, projectChildren) {
+    for (const node of tree) {
+        if ((node.text || '').toLowerCase() === 'projects') {
+            node.items = Array.isArray(node.items) ? node.items.slice() : [];
+            node.items.push(...projectChildren);
+            return;
+        }
+    }
+}
+
+function renderItem(item) {
+    const icon = item.icon ? `<span data-icon="${esc(item.icon)}"></span>` : '';
+    const text = esc(item.text || '');
+    const url  = item.url ? esc(item.url) : '';
+    const hasChildren = Array.isArray(item.items) && item.items.length > 0;
+
+    if (hasChildren) {
+        const stateKey = `sidebar.expanded.${(item.text || '').toLowerCase().replace(/\s+/g, '-')}`;
+        const isOpen = S.get(stateKey) !== false;
+        const childHtml = item.items.map(c => renderItem(c)).join('');
+        return `<details data-state-key="${esc(stateKey)}"${isOpen ? ' open' : ''}>
+            <summary>${icon} <span class="sidebar-text">${text}</span></summary>
+            <div>${childHtml}</div>
+        </details>`;
+    }
+    return `<a href="${url}" class="sidebar-link" data-url="${url}">${icon} <span class="sidebar-text">${text}</span></a>`;
+}
+
+/**
+ * Render the admin sidebar into the given mount selector.
+ *
+ * @param {{mount: string, permissions: string[]}} opts
+ */
+export async function renderAdminSidebar({mount, permissions}) {
+    const mountEl = $(mount).get(0);
+    if (!mountEl) return;
+
+    let tree;
+    try {
+        const menu = await api.menus.get('admin-sidebar');
+        tree = Array.isArray(menu?.items) ? menu.items : null;
+    } catch { tree = null; }
+
+    if (!tree || !tree.length) {
+        console.warn('[admin-sidebar] No admin-sidebar menu found; using fallback tree');
+        tree = FALLBACK_TREE.slice();
+    }
+
+    let registered = [];
+    try {
+        registered = await H.get('/api/sidebar/registered-items') || [];
+    } catch { /* ignore - render without plugin items */ }
+    tree = mergePluginItems(tree, registered);
+
+    const projectsBranch = await buildProjectsSubtree(permissions);
+    if (projectsBranch.length) injectProjectsSubtree(tree, projectsBranch);
+
+    tree = filterByPermission(tree, permissions);
+
+    // Build the markup string from escaped components, then insert via
+    // safe DOM API (replaceChildren + createContextualFragment) - no
+    // direct innerHTML assignment.
+    const markup = `<nav class="dm-admin-sidebar">${tree.map(renderItem).join('')}</nav>`;
+    const range = document.createRange();
+    range.selectNodeContents(mountEl);
+    const fragment = range.createContextualFragment(markup);
+    mountEl.replaceChildren(fragment);
+
+    Domma.icons.scan(mountEl);
+
+    // Persist expand/collapse state
+    $(mountEl).off('toggle', 'details').on('toggle', 'details', function() {
+        const key = $(this).attr('data-state-key');
+        if (key) S.set(key, this.open);
+    });
+
+    // Active item indicator
+    function setActive() {
+        const current = location.hash || '#/';
+        $(mountEl).find('.sidebar-link').removeClass('active');
+        $(mountEl).find(`.sidebar-link[data-url="${current}"]`).addClass('active');
+    }
+    setActive();
+    M.subscribe('router:afterChange', setActive);
+}
+```
+
+### Step 7.2: Verify syntax
+
+Run: `node --check admin/js/lib/sidebar-renderer.js`
+
+Expected: silent.
+
+---
+
+## Task 8: Replace the sidebar call in `app.js`
+
+**Files:**
+
+- Modify: `admin/js/app.js`
+
+### Step 8.1: Find the existing call
+
+Run: `grep -n "Domma.elements.sidebar\|getSidebarConfig" admin/js/app.js | head -5`
+
+### Step 8.2: Replace the sidebar build
+
+In `admin/js/app.js`, find `buildSidebar(permissions)`. Replace its body with the new renderer call:
+
+```js
+async function buildSidebar(permissions) {
+    const {renderAdminSidebar} = await import('./lib/sidebar-renderer.js');
+    await renderAdminSidebar({
+        mount: '#admin-sidebar',
+        permissions
+    });
+}
+```
+
+Remove the now-unused: `getSidebarConfig` import (it'll be a stub from Task 9), and any count/project fetches that exclusively fed the old sidebar build (the renderer fetches its own data).
+
+Keep:
+- The auth guard
+- The router setup
+- All `router:afterChange` subscribers used by other admin features
+
+If `fetchSidebarCounts` is used elsewhere (badge rendering on non-sidebar UI), leave it.
+
+### Step 8.3: Verify syntax
+
+Run: `node --check admin/js/app.js`
+
+Expected: silent.
+
+### Step 8.4: Browser smoke test required
+
+State explicitly: cannot drive the browser. A real browser load is required to confirm:
+- Sidebar renders with the seeded tree (after migration runs on next server restart)
+- Top-level sections (Overview, Projects, Content, Data, System, Documentation) appear
+- Each section is collapsible via the chevron / click on summary
+- Permission-gated items hide for users lacking the permission
+
+---
+
+## Task 9: Deprecate `sidebar-config.js`
+
+**Files:**
+
+- Modify: `admin/js/config/sidebar-config.js`
+
+### Step 9.1: Gut the file
+
+Replace the entire contents of `admin/js/config/sidebar-config.js` with:
+
+```js
+/**
+ * DEPRECATED - kept as a stub for one release.
+ *
+ * The admin sidebar is now rendered from the Menus system at the
+ * `admin-sidebar` slot. Edit `config/menus/admin-sidebar.json` (or use the
+ * Menus admin) to change the sidebar.
+ *
+ * If you're calling this function for sidebar content, switch to:
+ *   import {renderAdminSidebar} from '../lib/sidebar-renderer.js';
+ *
+ * This stub returns an empty array so any straggling callers still work.
+ */
+export function getSidebarConfig() {
+    console.warn('[sidebar-config] getSidebarConfig() is deprecated. Use renderAdminSidebar() from lib/sidebar-renderer.js.');
+    return [];
+}
+```
+
+### Step 9.2: Verify syntax
+
+Run: `node --check admin/js/config/sidebar-config.js`
+
+Expected: silent.
+
+---
+
+## Task 10: Add `permission` field to menu-editor item rows
+
+**Files:**
+
+- Modify: `admin/js/views/menu-editor.js`
+
+### Step 10.1: Find the item-row template
+
+Run: `grep -n "menu-tree-row\|me-text\|me-url\|me-icon\|me-vis" admin/js/views/menu-editor.js | head -10`
+
+The current item row has: text, url, icon, visibility, indent/outdent, move-up/down, hide, remove.
+
+### Step 10.2: Add permission select column
+
+The existing item row template uses these classes for its inputs (added in the Menus plan T20): `.me-text`, `.me-url`, `.me-icon`, `.me-vis` (visibility text input). The new `.me-perm` select sits right after `.me-vis`.
+
+Three edits to `menu-editor.js`:
+
+**(a) At the top of `onMount`, fetch the permissions registry once:**
+
+```js
+const permRegistry = await H.get('/api/auth/permissions-registry').catch(() => ({resources: []}));
+const permOptions  = ['<option value="">- no permission gate -</option>']
+    .concat((permRegistry.resources || []).map(r => `<option value="${r.key}">${r.label || r.key}</option>`));
+```
+
+**(b) In the row template (the function or template literal that builds each `.menu-tree-row`), insert AFTER the `<input class="me-vis" …>` line and BEFORE the indent/outdent buttons:**
+
+```js
+<select class="form-select me-perm" data-id="${row.id}">
+    ${permOptions.map(opt => opt.replace(`value="${row.permission || ''}"`, `value="${row.permission || ''}" selected`)).join('')}
+</select>
+```
+
+(If pre-selection via string replacement feels brittle, build the options inline with a `${row.permission === r.key ? ' selected' : ''}` conditional - same effect.)
+
+**(c) In `flatten(items)`** (the function that turns the nested-array form into a flat list of rows), include `permission` on each row object:
+
+```js
+out.push({
+    id, parentId,
+    text:       it.text       || '',
+    url:        it.url        || '',
+    icon:       it.icon       || '',
+    visibility: it.visibility || '',
+    permission: it.permission || '',
+    hidden:     !!it.hidden,
+    bundled:    !!it.bundled
+});
+```
+
+**(d) In `nest(flat)`** (the function that builds the persisted nested shape on save), include `permission` when truthy:
+
+```js
+return {
+    text: r.text.trim(),
+    url:  r.url.trim(),
+    ...(r.icon       && {icon:       r.icon.trim()}),
+    ...(r.visibility && {visibility: r.visibility}),
+    ...(r.permission && {permission: r.permission}),
+    ...(r.hidden     && {hidden:  true}),
+    ...(r.bundled    && {bundled: true}),
+    ...(children.length && {items: children})
+};
+```
+
+**(e) In `syncRowsFromDom` (or equivalent - the function that reads input values back into the flat array on Save), read the new select:**
+
+```js
+row.permission = $(this).find('.me-perm').val();
+```
+
+### Step 10.3: Verify syntax
+
+Run: `node --check admin/js/views/menu-editor.js`
+
+Expected: silent.
+
+### Step 10.4: Browser smoke test required
+
+State explicitly - cannot drive. A real browser test required to confirm:
+- Editing the `admin-sidebar` menu shows a permission select on each item
+- Selecting a permission and saving persists `permission: '<key>'` in the JSON
+- Clearing the select removes the field
+
+---
+
+## Task 11: CSS for nested `<details>` sidebar
+
+**Files:**
+
+- Modify: `admin/css/admin.css`
+
+### Step 11.1: Append the styles
+
+Append to `admin/css/admin.css`:
+
+```css
+/* Admin sidebar - nested details-based tree */
+.dm-admin-sidebar {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    padding: 8px 0;
+}
+.dm-admin-sidebar details {
+    margin: 0;
+}
+.dm-admin-sidebar details > summary {
+    list-style:    none;
+    cursor:        pointer;
+    display:       flex;
+    align-items:   center;
+    gap:           0.5rem;
+    padding:       0.4rem 0.75rem;
+    border-radius: 4px;
+    user-select:   none;
+}
+.dm-admin-sidebar details > summary::-webkit-details-marker { display: none; }
+.dm-admin-sidebar details > summary::after {
+    content:     '\25B8';
+    margin-left: auto;
+    transition:  transform 0.15s ease;
+    color:       var(--dm-text-muted, #999);
+    font-size:   0.85em;
+}
+.dm-admin-sidebar details[open] > summary::after { transform: rotate(90deg); }
+.dm-admin-sidebar details > div {
+    padding-left: 1rem;
+    border-left:  1px solid var(--dm-border-subtle, rgba(0, 0, 0, 0.08));
+    margin-left:  0.95rem;
+}
+.dm-admin-sidebar .sidebar-link {
+    display:       flex;
+    align-items:   center;
+    gap:           0.5rem;
+    padding:       0.35rem 0.75rem;
+    text-decoration: none;
+    color:         var(--dm-text, inherit);
+    border-radius: 4px;
+}
+.dm-admin-sidebar .sidebar-link:hover,
+.dm-admin-sidebar details > summary:hover {
+    background: var(--dm-bg-subtle, rgba(0, 0, 0, 0.05));
+}
+.dm-admin-sidebar .sidebar-link.active {
+    background: var(--dm-accent-bg, rgba(0, 0, 0, 0.08));
+    font-weight: 600;
+}
+.dm-admin-sidebar .sidebar-text {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+.dm-admin-sidebar [data-icon] {
+    flex-shrink: 0;
+}
+```
+
+### Step 11.2: Verify
+
+Open `admin/css/admin.css` - confirm the appended block has matched braces. (No node check for CSS.)
+
+---
+
+## Task 12: Documentation updates
+
+**Files:**
+
+- Modify: `docs/configuration.md`
+- Modify: `docs/plugin-development.md`
+- Modify: `docs/api-reference.md`
+- Modify: `CLAUDE.md`
+
+### Step 12.1: `docs/configuration.md`
+
+In the existing Menus section, document:
+- The new core slot `admin-sidebar`
+- The `permission` field on menu items (resource key from permissionRegistry)
+- Where the auto-seeded `admin-sidebar.json` lives + the auto-migration
+
+### Step 12.2: `docs/plugin-development.md`
+
+In the hooks reference, add `hooks.registerSidebarItem({parent, item})`. Include the option shape (parent string + item shape) and the runtime behaviour (items are not persisted; plugins re-register on each boot via setupPlugin).
+
+### Step 12.3: `docs/api-reference.md`
+
+Add `GET /api/sidebar/registered-items` - returns the array of `{parent, item}` entries currently registered. Requires `menus.read` permission.
+
+### Step 12.4: `CLAUDE.md`
+
+Add a short note that the admin sidebar is now menu-data-driven (the menu lives at `config/menus/admin-sidebar.json` and renders via `admin/js/lib/sidebar-renderer.js`).
+
+---
+
+## Task 13: Final verification + handoff
+
+**Files:** none (verification only)
+
+### Step 13.1: Run the full feature test suite
+
+```bash
+node --test \
+    tests/services/menus.test.js \
+    tests/services/sidebar-migration.test.js \
+    tests/routes/sidebar.test.js \
+    tests/services/projects.test.js \
+    tests/routes/projects.test.js \
+    tests/services/scaffolder.test.js 2>&1 | tail -10
+```
+
+Expected: all pass.
+
+### Step 13.2: Curl smoke
+
+```bash
+curl -s -o /dev/null -w "GET /api/sidebar/registered-items: %{http_code}\n" http://localhost:4096/api/sidebar/registered-items
+```
+
+Expected (after the user restarts the server): `401`. If still `404`, the user hasn't restarted yet - that's fine, the route will activate on next restart.
+
+### Step 13.3: Browser walkthrough (required - user-driven)
+
+The user MUST hard-refresh the admin and walk through:
+
+1. Sidebar renders with Overview / Projects / Content / Data / System / Documentation as collapsible top-level sections (the chevron rotates on toggle).
+2. Permission-gated items hide for users without the permission (test by creating a user with limited role).
+3. Projects parent expands to show per-project sub-trees (Overview + populated type rows + Settings).
+4. Editing the `admin-sidebar` menu from `#/menus/edit/admin-sidebar` works - the permission select appears on each item.
+5. Re-ordering items in the menu editor reorders the sidebar.
+6. Plugin-registered items (if any are installed) appear under their declared parent.
+
+State explicitly: this is the real test. Server-side tests can't verify the renderer or the visual shape.
+
+### Step 13.4: Hand off
+
+Do NOT commit. Summarise changes for the user to commit. Suggested commit message:
+
+> Admin sidebar now rendered from the Menus system at the `admin-sidebar` slot -
+> auto-migrates the current sidebar tree on first boot, supports per-item
+> permission gating, native <details> expand/collapse, and a registerSidebarItem
+> hook for plugin extensions. The Menus admin can edit the sidebar visually.