domma-cms 1.6.60 → 1.7.0

package/docs/superpowers/plans/2026-06-25-domma-docs-project.md

@@ -0,0 +1,695 @@
+# Domma Docs Project - 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.
+>
+> **Commits:** This repo's owner commits separately - do NOT run `git commit`. Where a normal plan would commit, this plan has a **Checkpoint** step: stop, report what changed, and let the owner review/commit.
+>
+> **Environment:** Server is already running on port 4096 and must NOT be killed/restarted. Use `curl` for server-side checks. The owner is on SSH - live browser checks are at `http://192.168.1.4:4096`. Never claim a UI change is "verified" without a real browser load (per project convention).
+
+**Goal:** Ship a built-in, disabled-by-default **Domma Docs** project whose pages are the CMS documentation, published on the public site under `/domma-docs/...` and removed from it when the project is toggled off.
+
+**Architecture:** A new seeded project (`domma-docs`, `rootUrl: /domma-docs`, `enabled: false`, `protected: true`) reuses the *existing* public kill-switch (`public.js` 404s pages whose project is disabled). The ~30 admin documentation screens are ported into public Markdown pages (bodies lifted verbatim from the admin HTML templates) via a one-shot script, then the admin doc screens are retired.
+
+**Tech Stack:** Fastify 5 (ESM), Node built-in test runner (`node --test`), file-based content (Markdown + YAML frontmatter), Domma SPA admin, `marked` + shortcode pipeline.
+
+---
+
+## File Structure
+
+**Modify:**
+- `server/services/projects.js` - add `DOCS_PROJECT_SLUG`, `DOCS_PROJECT_SEED`, `seedDocsProject()`; generalise `deleteProject()` and `untagAllForProject()` to refuse any `protected` project.
+- `server/server.js` - call `seedDocsProject()` after `seedCoreProject()`.
+- `server/routes/api/projects.js` - return 403 on delete/untag-all for `protected` projects.
+- `public/css/site.css` - `.docs-body` styling.
+- `public/js/site.js` - run `Domma.syntax.scan()` on rendered page content.
+- `config/menus/admin-sidebar.json` - remove the hardcoded **Documentation** section.
+- `server/services/sidebar-migration.js` - strip the **Documentation** section from already-seeded installs (idempotent).
+- `admin/js/app.js` - remove the doc/tutorial routes (lines 104-136).
+- `admin/js/views/index.js` - remove the doc view imports/registrations.
+
+**Create:**
+- `scripts/migrate-docs.js` - one-shot porter: admin doc templates → public page artefacts.
+- `content/pages/domma-docs/index.md`, `usage/index.md`, `tutorials/index.md`, `api/index.md` - hand-authored landing pages.
+- `content/pages/domma-docs/**` - generated by the migration script.
+
+**Delete (Phase 3, after migration runs):**
+- `admin/js/views/documentation.js`, `admin/js/views/tutorials.js`, `admin/js/views/doc-pages.js`
+- `admin/js/templates/docs/*.html`
+
+**Test:**
+- `tests/services/projects.test.js` - seed + protected-guard tests.
+- `tests/routes/projects.test.js` - route guard tests.
+
+---
+
+## Phase 0 - The engine (seed + undeletable guards)
+
+### Task 1: Seed the Domma Docs project
+
+**Files:**
+- Modify: `server/services/projects.js`
+- Test: `tests/services/projects.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `tests/services/projects.test.js` (import `DOCS_PROJECT_SLUG, seedDocsProject` in the existing import block from `../../server/services/projects.js`):
+
+```js
+test('seedDocsProject - creates a disabled, protected docs project after core', async () => {
+    await seedDocsProject();
+    await seedDocsProject(); // idempotent
+    const docs = await getProject(DOCS_PROJECT_SLUG);
+    assert.ok(docs, 'docs project exists');
+    assert.equal(docs.slug, 'domma-docs');
+    assert.equal(docs.name, 'Domma Docs');
+    assert.equal(docs.icon, 'document');
+    assert.equal(docs.rootUrl, '/domma-docs');
+    assert.equal(docs.enabled, false);
+    assert.equal(docs.protected, true);
+
+    // sortOrder 0 sits immediately after core (-1)
+    const all = await listProjects();
+    const core = all.findIndex(p => p.slug === CORE_PROJECT_SLUG);
+    const di   = all.findIndex(p => p.slug === DOCS_PROJECT_SLUG);
+    assert.ok(core < di, 'core sorts before docs');
+});
+
+test('seedDocsProject - never clobbers an existing record (preserves enabled state)', async () => {
+    await seedDocsProject();
+    await updateProject(DOCS_PROJECT_SLUG, {enabled: true}); // admin turned it on
+    await seedDocsProject();                                  // reboot
+    assert.equal((await getProject(DOCS_PROJECT_SLUG)).enabled, true);
+    await updateProject(DOCS_PROJECT_SLUG, {enabled: false}); // reset for other tests
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npm test -- --test-name-pattern="seedDocsProject"`
+Expected: FAIL - `seedDocsProject is not a function` / `is not exported`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+In `server/services/projects.js`, after the `CORE_PROJECT_SLUG`/`CORE_PROJECT_SEED` block, add:
+
+```js
+/** Slug of the built-in, disabled-by-default documentation project. */
+export const DOCS_PROJECT_SLUG = 'domma-docs';
+
+/** Seed record for the Domma Docs project (created at boot if absent). */
+const DOCS_PROJECT_SEED = {
+    slug:        DOCS_PROJECT_SLUG,
+    name:        'Domma Docs',
+    description: 'The Domma CMS handbook - guides, tutorials, component & API ' +
+                 'reference. Switch on to publish it on your own site.',
+    icon:        'document',
+    rootUrl:     '/domma-docs',
+    sortOrder:   0,
+    enabled:     false,
+    protected:   true
+};
+```
+
+Then add the seed function next to `seedCoreProject`:
+
+```js
+/**
+ * Seed the built-in Domma Docs project at boot. Create-if-absent by slug - an
+ * existing record (including the admin's enabled/disabled choice and any edits)
+ * is returned untouched. Disabled by default: a fresh site ships with the docs
+ * off until an admin enables the project.
+ *
+ * @returns {Promise<object>} The docs project record.
+ */
+export async function seedDocsProject() {
+    const {entries} = await listEntries(PROJECTS_COLLECTION_SLUG, {limit: 0});
+    const existing = entries.find(e => e.data?.slug === DOCS_PROJECT_SLUG);
+    if (existing) return normalise(existing);
+    const now = new Date().toISOString();
+    const data = {...DOCS_PROJECT_SEED, createdAt: now, updatedAt: now};
+    await createEntry(PROJECTS_COLLECTION_SLUG, data);
+    return data;
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npm test -- --test-name-pattern="seedDocsProject"`
+Expected: PASS (both tests).
+
+- [ ] **Step 5: Checkpoint** - report the new export + tests; pause for owner review.
+
+---
+
+### Task 2: Make `protected` projects undeletable (service layer)
+
+**Files:**
+- Modify: `server/services/projects.js` (`deleteProject`, `untagAllForProject`)
+- Test: `tests/services/projects.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+test('deleteProject - refuses to delete a protected project', async () => {
+    await seedDocsProject();
+    await assert.rejects(() => deleteProject(DOCS_PROJECT_SLUG), /protected/i);
+    assert.ok(await getProject(DOCS_PROJECT_SLUG), 'still present');
+});
+
+test('untagAllForProject - refuses a protected project', async () => {
+    await seedDocsProject();
+    await assert.rejects(() => untagAllForProject(DOCS_PROJECT_SLUG), /protected/i);
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npm test -- --test-name-pattern="protected project"`
+Expected: FAIL - `deleteProject` resolves/deletes instead of rejecting.
+
+- [ ] **Step 3: Write minimal implementation**
+
+In `deleteProject`, after the entry is found and before `deleteEntry`:
+
+```js
+    const entry = entries.find(e => e.data?.slug === slug);
+    if (!entry) return false;
+    if (entry.data?.protected === true) {
+        throw new Error(`Cannot delete the protected "${slug}" project`);
+    }
+    await deleteEntry(PROJECTS_COLLECTION_SLUG, entry.id);
+    return true;
+```
+
+In `untagAllForProject`, right after the existing core check:
+
+```js
+    if (projectSlug === CORE_PROJECT_SLUG) {
+        throw new Error('Cannot untag the core project - artefacts would immediately resolve back to it');
+    }
+    const proj = await getProject(projectSlug);
+    if (proj?.protected === true) {
+        throw new Error(`Cannot untag the protected "${projectSlug}" project - its pages would resolve back to core`);
+    }
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npm test -- --test-name-pattern="protected project"`
+Expected: PASS. Also run the full pre-existing core guard test to confirm no regression:
+`npm test -- --test-name-pattern="refuses to delete core"` → PASS.
+
+- [ ] **Step 5: Checkpoint** - pause for review.
+
+---
+
+### Task 3: Route-level guards + boot wiring
+
+**Files:**
+- Modify: `server/routes/api/projects.js`
+- Modify: `server/server.js`
+- Test: `tests/routes/projects.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+Open `tests/routes/projects.test.js`, mirror its existing app-bootstrap pattern (it already builds a Fastify instance and authenticates an admin). Add:
+
+```js
+test('DELETE /api/projects/domma-docs → 403 (protected)', async () => {
+    const res = await app.inject({
+        method: 'DELETE', url: '/api/projects/domma-docs',
+        headers: {authorization: `Bearer ${adminToken}`}
+    });
+    assert.equal(res.statusCode, 403);
+});
+
+test('POST /api/projects/domma-docs/untag-all → 403 (protected)', async () => {
+    const res = await app.inject({
+        method: 'POST', url: '/api/projects/domma-docs/untag-all',
+        headers: {authorization: `Bearer ${adminToken}`}
+    });
+    assert.equal(res.statusCode, 403);
+});
+```
+
+(If the test file's `before` hook does not already seed the docs project, add `await seedDocsProject();` there, importing it from `../../server/services/projects.js`.)
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npm test -- tests/routes/projects.test.js`
+Expected: FAIL - delete returns 200/409 (or untag returns 200) instead of 403.
+
+- [ ] **Step 3: Write minimal implementation**
+
+In `server/routes/api/projects.js`, import `getProject` from the service (add to the existing import block). In the `fastify.delete('/projects/:slug', ...)` handler, after the existing core check:
+
+```js
+        if (request.params.slug === CORE_PROJECT_SLUG) {
+            return reply.status(403).send({error: 'Cannot delete the core project'});
+        }
+        const target = await getProject(request.params.slug);
+        if (target?.protected === true) {
+            return reply.status(403).send({error: 'This project is protected and cannot be deleted'});
+        }
+```
+
+In the `fastify.post('/projects/:slug/untag-all', ...)` handler, after its core check:
+
+```js
+        const target = await getProject(request.params.slug);
+        if (target?.protected === true) {
+            return reply.status(403).send({error: 'This project is protected and cannot be untagged'});
+        }
+```
+
+In `server/server.js`: extend the existing import to
+`import {seedCoreProject, seedDocsProject} from './services/projects.js';`
+and add immediately after the `await seedCoreProject();` line:
+
+```js
+await seedDocsProject();
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npm test -- tests/routes/projects.test.js`
+Expected: PASS.
+
+- [ ] **Step 5: Verify boot seeds it live**
+
+Run: `curl -s localhost:4096/ >/dev/null; ls content/collections/projects/data.json && grep -c '"domma-docs"' content/collections/projects/data.json`
+Expected: `1` (server has restarted via the owner's running process, or seed ran on next boot). If the running server predates the change, note that the seed applies on its next restart - do NOT restart it yourself; report this to the owner.
+
+- [ ] **Step 6: Checkpoint** - pause for review.
+
+---
+
+## Phase 1 - Public rendering polish
+
+### Task 4: `.docs-body` styling + code highlighting on public pages
+
+**Files:**
+- Modify: `public/css/site.css`
+- Modify: `public/js/site.js`
+
+- [ ] **Step 1: Add docs styling**
+
+Append to `public/css/site.css`:
+
+```css
+/* Domma Docs project - ported documentation pages */
+.docs-body { max-width: 60rem; }
+.docs-body h2 { margin-top: 2rem; }
+.docs-body h3 { margin-top: 1.5rem; }
+.docs-body table { width: 100%; border-collapse: collapse; margin: 1rem 0; }
+.docs-body th, .docs-body td { border: 1px solid var(--dm-border, #ddd); padding: .5rem .75rem; text-align: left; }
+.docs-body pre { overflow-x: auto; }
+.docs-body code { font-size: .9em; }
+```
+
+- [ ] **Step 2: Add syntax highlighting to the public render path**
+
+In `public/js/site.js`, find where page content is scanned for icons after the body renders (search for `Domma.icons.scan();` near line ~304 and the post-fragment rescan near ~704). Immediately after each `Domma.icons.scan(...)` that runs over rendered page content, add:
+
+```js
+      if (typeof Domma !== 'undefined' && Domma.syntax?.scan) Domma.syntax.scan();
+```
+
+- [ ] **Step 3: Verify (browser, live)** - deferred until a pilot page exists (Task 6). No standalone check here.
+
+- [ ] **Step 4: Checkpoint** - pause for review.
+
+---
+
+## Phase 2 - Content migration
+
+### Task 5: The migration script
+
+**Files:**
+- Create: `scripts/migrate-docs.js`
+
+- [ ] **Step 1: Write the script**
+
+```js
+/**
+ * One-shot porter: admin documentation screens → public page artefacts under
+ * the Domma Docs project. Reads each admin HTML template, strips the admin-only
+ * view header, wraps the body in page frontmatter tagged `project: domma-docs`,
+ * and writes content/pages/domma-docs/<path>.md. Re-runnable (overwrites).
+ *
+ * Run: node scripts/migrate-docs.js
+ */
+import {mkdirSync, readFileSync, writeFileSync} from 'node:fs';
+import {dirname, join} from 'node:path';
+
+const TPL = 'admin/js/templates/docs';
+const OUT = 'content/pages/domma-docs';
+
+// template basename → {path (URL tail = file path), title}
+const MAP = [
+    ['usage-pages',          'usage/pages',          'Pages'],
+    ['usage-media',          'usage/media',          'Media'],
+    ['usage-navigation',     'usage/navigation',     'Navigation'],
+    ['usage-dconfig',        'usage/dconfig',        'DConfig'],
+    ['usage-shortcodes',     'usage/shortcodes',     'Shortcodes'],
+    ['usage-site-settings',  'usage/site-settings',  'Site Settings'],
+    ['usage-plugins',        'usage/plugins',        'Plugins'],
+    ['usage-users-roles',    'usage/users-roles',    'Users & Roles'],
+    ['usage-views',          'usage/views',          'Views'],
+    ['usage-actions',        'usage/actions',        'Actions'],
+    ['usage-cta-shortcode',  'usage/cta-shortcode',  'CTA Shortcode'],
+    ['tutorial-crud',        'tutorials/crud',       'Building a CRUD App'],
+    ['tutorial-plugin',      'tutorials/plugin',     'Writing a Plugin'],
+    ['tutorial-forms',       'tutorials/forms',      'Form Follow-Up'],
+    ['components-reference', 'components',           'Components Reference'],
+    ['components-howto',     'components/howto',     'Components How-To'],
+    ['components-walkthrough','components/walkthrough','Components Walkthrough'],
+    ['components-rules',     'components/rules',     'Components Rules'],
+    ['api-authentication',   'api/authentication',   'Authentication'],
+    ['api-pages',            'api/pages',            'Pages API'],
+    ['api-settings',         'api/settings',         'Settings API'],
+    ['api-layouts',          'api/layouts',          'Layouts API'],
+    ['api-navigation',       'api/navigation',       'Navigation API'],
+    ['api-media',            'api/media',            'Media API'],
+    ['api-users',            'api/users',            'Users API'],
+    ['api-plugins',          'api/plugins',          'Plugins API'],
+    ['api-collections',      'api/collections',      'Collections API'],
+    ['api-views',            'api/views',            'Views API'],
+    ['api-actions',          'api/actions',          'Actions API']
+];
+
+// Drop the admin-only header block (<div class="view-header"> ... </div>).
+// The header contains no nested <div>, so a non-greedy match to the first
+// </div> is correct.
+function stripHeader(html) {
+    return html.replace(/<div class="view-header">[\s\S]*?<\/div>\s*/, '');
+}
+
+function frontmatter(title) {
+    return `---\ntitle: ${title}\nlayout: default\nvisibility: public\nproject: domma-docs\n---\n\n`;
+}
+
+let n = 0;
+for (const [tpl, path, title] of MAP) {
+    const src  = readFileSync(join(TPL, `${tpl}.html`), 'utf8');
+    const body = stripHeader(src).trim();
+    const dest = join(OUT, `${path}.md`);
+    mkdirSync(dirname(dest), {recursive: true});
+    writeFileSync(dest, frontmatter(title) + body + '\n');
+    n++;
+}
+console.log(`[migrate-docs] wrote ${n} pages to ${OUT}`);
+```
+
+- [ ] **Step 2: Run the script**
+
+Run: `node scripts/migrate-docs.js`
+Expected: `[migrate-docs] wrote 29 pages to content/pages/domma-docs`
+
+- [ ] **Step 3: Spot-check output**
+
+Run: `head -8 content/pages/domma-docs/usage/pages.md`
+Expected: frontmatter with `project: domma-docs`, then the page HTML with the `view-header` gone.
+
+- [ ] **Step 4: Checkpoint** - pause for review.
+
+---
+
+### Task 6: Hand-authored landing pages
+
+**Files:**
+- Create: `content/pages/domma-docs/index.md`, `usage/index.md`, `tutorials/index.md`, `api/index.md`
+
+- [ ] **Step 1: Write the top landing page**
+
+`content/pages/domma-docs/index.md`:
+
+```markdown
+---
+title: Domma Docs
+layout: default
+visibility: public
+project: domma-docs
+---
+
+# Domma CMS Documentation
+
+[grid cols="2" gap="3"]
+[col][card title="Usage"]Day-to-day guides for pages, media, navigation, shortcodes, plugins and more. [link href="/domma-docs/usage"]Browse usage →[/link][/card][/col]
+[col][card title="Tutorials"]Step-by-step walkthroughs. [link href="/domma-docs/tutorials"]Browse tutorials →[/link][/card][/col]
+[col][card title="Components"]The component reference and how-to. [link href="/domma-docs/components"]Browse components →[/link][/card][/col]
+[col][card title="API Reference"]REST endpoints for headless use. [link href="/domma-docs/api"]Browse the API →[/link][/card][/col]
+[/grid]
+```
+
+- [ ] **Step 2: Write the three group landings**
+
+`content/pages/domma-docs/usage/index.md` (links to each usage page):
+
+```markdown
+---
+title: Usage
+layout: default
+visibility: public
+project: domma-docs
+---
+
+# Usage
+
+[listgroup]
+[item][link href="/domma-docs/usage/pages"]Pages[/link][/item]
+[item][link href="/domma-docs/usage/media"]Media[/link][/item]
+[item][link href="/domma-docs/usage/navigation"]Navigation[/link][/item]
+[item][link href="/domma-docs/usage/dconfig"]DConfig[/link][/item]
+[item][link href="/domma-docs/usage/shortcodes"]Shortcodes[/link][/item]
+[item][link href="/domma-docs/usage/site-settings"]Site Settings[/link][/item]
+[item][link href="/domma-docs/usage/plugins"]Plugins[/link][/item]
+[item][link href="/domma-docs/usage/users-roles"]Users & Roles[/link][/item]
+[item][link href="/domma-docs/usage/views"]Views[/link][/item]
+[item][link href="/domma-docs/usage/actions"]Actions[/link][/item]
+[item][link href="/domma-docs/usage/cta-shortcode"]CTA Shortcode[/link][/item]
+[/listgroup]
+```
+
+`content/pages/domma-docs/tutorials/index.md`:
+
+```markdown
+---
+title: Tutorials
+layout: default
+visibility: public
+project: domma-docs
+---
+
+# Tutorials
+
+[listgroup]
+[item][link href="/domma-docs/tutorials/crud"]Building a CRUD App[/link][/item]
+[item][link href="/domma-docs/tutorials/plugin"]Writing a Plugin[/link][/item]
+[item][link href="/domma-docs/tutorials/forms"]Form Follow-Up[/link][/item]
+[/listgroup]
+```
+
+`content/pages/domma-docs/api/index.md`:
+
+```markdown
+---
+title: API Reference
+layout: default
+visibility: public
+project: domma-docs
+---
+
+# API Reference
+
+[listgroup]
+[item][link href="/domma-docs/api/authentication"]Authentication[/link][/item]
+[item][link href="/domma-docs/api/pages"]Pages[/link][/item]
+[item][link href="/domma-docs/api/settings"]Settings[/link][/item]
+[item][link href="/domma-docs/api/layouts"]Layouts[/link][/item]
+[item][link href="/domma-docs/api/navigation"]Navigation[/link][/item]
+[item][link href="/domma-docs/api/media"]Media[/link][/item]
+[item][link href="/domma-docs/api/users"]Users[/link][/item]
+[item][link href="/domma-docs/api/plugins"]Plugins[/link][/item]
+[item][link href="/domma-docs/api/collections"]Collections[/link][/item]
+[item][link href="/domma-docs/api/views"]Views[/link][/item]
+[item][link href="/domma-docs/api/actions"]Actions[/link][/item]
+[/listgroup]
+```
+
+- [ ] **Step 3: Checkpoint** - pause for review.
+
+---
+
+### Task 7: Live end-to-end verification of the toggle + pilot pages
+
+**Files:** none (verification only). Requires the owner's running server to have picked up the Phase 0 boot change. If it has not restarted, ask the owner to confirm a restart before this task - do not restart it yourself.
+
+- [ ] **Step 1: Confirm disabled ⇒ 404 (kill-switch)**
+
+With Domma Docs disabled (default), run:
+```
+curl -s -o /dev/null -w "%{http_code}\n" localhost:4096/domma-docs
+curl -s -o /dev/null -w "%{http_code}\n" localhost:4096/domma-docs/usage/shortcodes
+```
+Expected: `404` for both.
+
+- [ ] **Step 2: Enable the project**
+
+Via the admin Projects UI (or API): set `domma-docs` `enabled: true`. Confirm:
+`curl -s localhost:4096/api/projects | grep -o '"domma-docs"[^}]*"enabled":true' | head -1` → a match.
+
+- [ ] **Step 3: Confirm enabled ⇒ 200 + content**
+
+```
+curl -s -o /dev/null -w "%{http_code}\n" localhost:4096/domma-docs
+curl -s localhost:4096/domma-docs/usage/shortcodes | grep -c "docs-body"
+```
+Expected: `200`, and the shortcodes page contains `docs-body`.
+
+- [ ] **Step 4: Browser fidelity check (pilot pages)** - load in a real browser at `http://192.168.1.4:4096`:
+  - `/domma-docs` - landing card grid renders.
+  - `/domma-docs/usage/shortcodes` - **critical**: confirm the `[card]`/`[grid]` examples render as *literal code*, not expanded components (validates `scrubCodeRegions` over the ported `<pre>` blocks). Confirm code blocks are syntax-highlighted and icons render.
+  - `/domma-docs/api/collections` - tables render with `.docs-body` styling.
+
+  Report findings explicitly. If any shortcode example is wrongly expanded, fix by escaping brackets within `<pre>` in `scripts/migrate-docs.js` (replace `[` → `&#91;` inside `<pre>…</pre>` regions) and re-run the script.
+
+- [ ] **Step 5: Confirm disabling re-hides**
+
+Set `domma-docs` `enabled: false`, then repeat Step 1 → expect `404`. Leave it disabled (the default).
+
+- [ ] **Step 6: Checkpoint** - report the full enabled/disabled matrix; pause for review.
+
+---
+
+## Phase 3 - Retire the admin documentation screens
+
+> Only after Task 7 passes - the migration script reads the admin templates, so they must survive until the pages are generated and verified.
+
+### Task 8: Remove the admin Documentation menu section
+
+**Files:**
+- Modify: `config/menus/admin-sidebar.json`
+- Modify: `server/services/sidebar-migration.js`
+- Test: `tests/services/sidebar-migration.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+In `tests/services/sidebar-migration.test.js`, add a test that the migration removes a top-level item whose `text` is `Documentation`. Mirror the file's existing helper for building a menu fixture and invoking the migration. Example shape:
+
+```js
+test('migration strips the legacy Documentation section', async () => {
+    const menu = {slug: 'admin-sidebar', items: [
+        {text: 'Overview', items: []},
+        {text: 'Documentation', items: [{text: 'Usage', items: []}]}
+    ]};
+    const out = stripDocumentationSection(menu);   // new export
+    assert.equal(out.items.some(i => i.text === 'Documentation'), false);
+    // idempotent
+    assert.deepEqual(stripDocumentationSection(out), out);
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npm test -- tests/services/sidebar-migration.test.js`
+Expected: FAIL - `stripDocumentationSection is not exported`.
+
+- [ ] **Step 3: Implement + wire**
+
+In `server/services/sidebar-migration.js` add and export:
+
+```js
+/**
+ * Remove the legacy top-level "Documentation" section from a persisted
+ * admin-sidebar menu. The docs now live as the Domma Docs project's pages.
+ * Idempotent; returns the (possibly unchanged) menu object.
+ *
+ * @param {{items?: Array<object>}} menu
+ * @returns {object}
+ */
+export function stripDocumentationSection(menu) {
+    if (!menu || !Array.isArray(menu.items)) return menu;
+    const items = menu.items.filter(i => (i?.text || '') !== 'Documentation');
+    return items.length === menu.items.length ? menu : {...menu, items};
+}
+```
+
+Call it in the same place the existing sidebar migrations run at boot (follow the pattern of `ensureSidebarItem`/the migration entry point already in this file): load the `admin-sidebar` menu, apply `stripDocumentationSection`, and persist only if changed.
+
+Then remove the `Documentation` object from `config/menus/admin-sidebar.json` (this install's live menu) so fresh boots never seed it.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npm test -- tests/services/sidebar-migration.test.js`
+Expected: PASS.
+
+- [ ] **Step 5: Browser check** - load the admin at `http://192.168.1.4:4096/admin` in a real browser; confirm the **Documentation** section is gone from the sidebar and the **Projects** section still renders. Report explicitly.
+
+- [ ] **Step 6: Checkpoint** - pause for review.
+
+---
+
+### Task 9: Remove the admin doc routes + views
+
+**Files:**
+- Modify: `admin/js/app.js` (remove lines 104-136 - the `/documentation`, `/tutorials*`, `/docs/*` route entries)
+- Modify: `admin/js/views/index.js` (remove imports at lines 21-23 and registrations `documentation:`, `tutorials:`, `...docViews`)
+- Delete: `admin/js/views/documentation.js`, `admin/js/views/tutorials.js`, `admin/js/views/doc-pages.js`
+- Delete: `admin/js/templates/docs/*.html`
+
+- [ ] **Step 1: Remove the route block** in `admin/js/app.js` - delete every route object from `{path: '/documentation', ...}` through `{path: '/docs/api/actions', ...}` inclusive. Confirm none remain:
+
+Run: `grep -cE "path: '/(docs|tutorials|documentation)" admin/js/app.js`
+Expected: `0`
+
+- [ ] **Step 2: Remove the view registrations** in `admin/js/views/index.js` - delete the three imports (`documentationView`, `tutorialsView`, `docViews`) and the three registry lines (`documentation:`, `tutorials:`, `...docViews`). Confirm:
+
+Run: `grep -cE "documentationView|tutorialsView|docViews" admin/js/views/index.js`
+Expected: `0`
+
+- [ ] **Step 3: Delete the now-orphaned files**
+
+Run:
+```
+rm admin/js/views/documentation.js admin/js/views/tutorials.js admin/js/views/doc-pages.js
+rm -r admin/js/templates/docs
+```
+
+- [ ] **Step 4: Verify no dangling references**
+
+Run: `grep -rnE "doc-pages|templates/docs|tutorialsView|documentationView|docViews|crud-tutorial" admin/js | grep -v "node_modules"`
+Expected: no matches (the `crud-tutorial.js` lib import lived only in `doc-pages.js`; if `crud-tutorial.js` is now unreferenced, delete it too and re-run).
+
+- [ ] **Step 5: Browser smoke test** - load `http://192.168.1.4:4096/admin`, navigate a few sections (Dashboard, Pages, Projects). Confirm no console errors from the removed views and that visiting an old hash like `#/docs/usage/pages` lands on the SPA's not-found/route-miss handling rather than throwing. Report explicitly.
+
+- [ ] **Step 6: Checkpoint** - pause for review.
+
+---
+
+## Final verification
+
+- [ ] **Full test suite**
+
+Run: `npm test`
+Expected: all pass (note any pre-existing unrelated failures separately).
+
+- [ ] **End-to-end matrix (browser, live `http://192.168.1.4:4096`)** - report each explicitly:
+  - Domma Docs **disabled** (default): `/domma-docs/*` → 404; admin sidebar has **no** Documentation section; Projects section present.
+  - Domma Docs **enabled**: `/domma-docs` + a usage/api/tutorial page render with styling, highlighting, icons; shortcode examples on the shortcodes page are literal; admin Projects sidebar shows **Domma Docs** with a `Pages (N)` child; the project's delete control is disabled.
+  - Toggle back to **disabled**: pages 404 again.
+
+- [ ] **Hand off to owner for commit** (this repo's owner commits).
+
+---
+
+## Spec coverage check
+
+- Seed project (slug/name/icon/rootUrl/sortOrder/disabled/protected) → Task 1 ✓
+- Undeletable, toggleable, rootUrl editable (not Core's locks) → Tasks 2-3 ✓
+- Docs as public pages tagged `project: domma-docs`, bodies lifted from templates → Tasks 5-6 ✓
+- Public `.docs-body` CSS + code highlighting → Task 4 ✓
+- Kill-switch (disabled ⇒ 404) reused, not rebuilt → verified Task 7 ✓
+- Retire admin Documentation section/routes/views/templates → Tasks 8-9 ✓
+- Caveat: interactive CRUD scaffolder degrades to static → inherent in Task 5 (no scaffolder mount on public page); confirmed at Task 7 Step 4 ✓
+- Caveat: shortcode examples must stay literal → Task 7 Step 4 explicit check + escape fallback ✓