domma-cms 1.6.60 → 1.7.0

package/docs/superpowers/specs/plans/2026-05-25-projects.md

@@ -0,0 +1,2869 @@
+# Projects 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:** Introduce Projects - a lightweight grouping of related artefacts (Pages, Collections, Forms, Actions, Menus, Blocks, Views, Roles, Users) with sidebar navigation, per-user permission scoping, and tight scaffolder integration.
+
+**Architecture:** Projects live in a preset collection (`content/collections/projects/`). Nine artefact types gain an optional `meta.project: '<slug>'` field. Users gain a `projects: []` access-scope array. The scaffolder auto-creates a project (and stamps `meta.project` on every artefact it produces) when a recipe declares a `project` block. The admin sidebar gains a new Projects section above Content. Untagged artefacts stay site-wide.
+
+**Tech Stack:** Fastify 5 (ESM), Domma SPA admin (`$`/`E`/`F`/`T`/`I`/`H`/`S`), `node:test` runner, JSON file storage.
+
+**Spec:** `docs/superpowers/specs/2026-05-25-projects-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`
+- Admin JS/MJS/CSS uses `Cache-Control: no-store` - no `?v=N` cache-busting query strings
+- T.create render functions return HTML strings (memory: `feedback_tcreate_render_strings.md`)
+- 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`)
+
+---
+
+## File Map
+
+| Path | Purpose | Action |
+|---|---|---|
+| `server/services/projects.js` | New service: CRUD + scope helpers (`canSeeArtefact`, `getProjectForPage`) | Create |
+| `server/services/presetCollections.js` | Add `projects` to PRESETS array | Modify |
+| `server/services/permissionRegistry.js` | Add `projects.{read,create,update,delete}` family | Modify |
+| `server/services/scaffolder.js` | Project auto-creation + stamp `meta.project` on all artefacts | Modify |
+| `server/services/collections.js` | `createCollection` accepts `meta.project`; `listCollections` filter | Modify |
+| `server/services/forms.js` | `meta.project` flow + `listForms` filter | Modify |
+| `server/services/actions.js` | `createAction` accepts `meta.project`; `listActions` filter | Modify |
+| `server/services/menus.js` | Accept `meta.project` (already has `meta` block); `listMenus` filter | Modify |
+| `server/services/blocks.js` | `meta.project` flow + `listBlocks` filter | Modify |
+| `server/services/views.js` | `meta.project` flow + `listViews` filter | Modify |
+| `server/services/roles.js` | Role entries' `data.meta.project`; filter | Modify |
+| `server/services/users.js` | User `meta.project` + access-scope `projects: []`; filter; cache invalidate on `projects` change | Modify |
+| `server/services/content.js` | Page list filter + URL inheritance via `getProjectForPage` | Modify |
+| `server/routes/api/projects.js` | New: REST API + `/artefacts` + `/untag-all` | Create |
+| `server/server.js` | Register projects routes; seed projects preset on boot | Modify |
+| `admin/js/api.js` | Add `api.projects.*` client | Modify |
+| `admin/js/config/sidebar-config.js` | Add Projects section (lazy expansion, scoped to user) | Modify |
+| `admin/js/app.js` | New routes: `/projects`, `/projects/new`, `/projects/edit/:slug`, `/projects/:slug`, `/projects/:slug/:tab` | Modify |
+| `admin/js/views/index.js` | Export new views | Modify |
+| `admin/js/views/projects.js` | New: list view | Create |
+| `admin/js/views/project-editor.js` | New: create/edit form | Create |
+| `admin/js/views/project-detail.js` | New: tabbed detail view (Overview + 9 type tabs + Settings) | Create |
+| `admin/js/views/page-editor.js` | Add Project select (URL-inheritance pre-fill) | Modify |
+| `admin/js/views/collection-editor.js` | Add Project select to Meta tab | Modify |
+| `admin/js/views/form-editor.js` | Add Project select to Meta tab | Modify |
+| `admin/js/views/action-editor.js` | Add Project select | Modify |
+| `admin/js/views/menu-editor.js` | Add Project select to Meta tab | Modify |
+| `admin/js/views/block-editor.js` | Add Project select | Modify |
+| `admin/js/views/view-editor.js` | Add Project select | Modify |
+| `admin/js/views/role-editor.js` | Add Project select | Modify |
+| `admin/js/views/user-editor.js` | Add `projects: []` multi-select + `meta.project` single-select | Modify |
+| `admin/js/templates/projects.html` | New: list template | Create |
+| `admin/js/templates/project-editor.html` | New: editor template | Create |
+| `admin/js/templates/project-detail.html` | New: detail template | Create |
+| `admin/css/admin.css` | Sidebar Projects section styles | Modify |
+| `tests/services/projects.test.js` | New: service tests | Create |
+| `tests/services/projects-scope.test.js` | New: `canSeeArtefact` + cross-service scope filtering | Create |
+| `tests/services/projects-page-inheritance.test.js` | New: `getProjectForPage` URL rules | Create |
+| `tests/services/projects-scaffolder.test.js` | New: scaffolder project block | Create |
+| `tests/routes/projects.test.js` | New: API smoke tests | Create |
+| `docs/configuration.md` | Add Projects section | Modify |
+| `docs/scaffolding.md` | Document `project` recipe branch | Modify |
+| `docs/api-reference.md` | Add `/api/projects/*` endpoints | Modify |
+| `CLAUDE.md` | Add Projects summary | Modify |
+
+---
+
+## Task 1: Projects service skeleton - slug validation + paths
+
+**Files:**
+
+- Create: `server/services/projects.js`
+- Create: `tests/services/projects.test.js`
+
+- [ ] **Step 1.1: Write the slug + path test**
+
+  Create `tests/services/projects.test.js`:
+
+  ```js
+  /**
+   * Projects service tests. Each test uses a unique slug per run to keep
+   * runs independent and self-cleaning.
+   */
+  import {test} from 'node:test';
+  import assert from 'node:assert/strict';
+  import {validateSlug, PROJECTS_COLLECTION_SLUG} from '../../server/services/projects.js';
+
+  test('validateSlug - accepts lowercase alphanumeric + hyphen', () => {
+      assert.equal(validateSlug('members'), true);
+      assert.equal(validateSlug('members-area'), true);
+      assert.equal(validateSlug('1site'), true);
+  });
+
+  test('validateSlug - rejects empty, capitals, trailing hyphen, traversal', () => {
+      assert.equal(validateSlug(''), false);
+      assert.equal(validateSlug('Members'), false);
+      assert.equal(validateSlug('members-'), false);
+      assert.equal(validateSlug('../etc'), false);
+      assert.equal(validateSlug('members/intranet'), false);
+  });
+
+  test('PROJECTS_COLLECTION_SLUG - exported constant', () => {
+      assert.equal(PROJECTS_COLLECTION_SLUG, 'projects');
+  });
+  ```
+
+- [ ] **Step 1.2: Run to confirm failure**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: `ERR_MODULE_NOT_FOUND` for `projects.js`.
+
+- [ ] **Step 1.3: Create the service skeleton**
+
+  Create `server/services/projects.js`:
+
+  ```js
+  /**
+   * Projects service.
+   *
+   * Projects group related artefacts (Pages, Collections, Forms, Actions,
+   * Menus, Blocks, Views, Roles, Users) under a named slug. Membership is
+   * a metadata tag (`meta.project: '<slug>'`) on each artefact - no
+   * filesystem isolation. Projects also act as a permission boundary:
+   * users with `projects: []` set only see their projects' artefacts plus
+   * untagged site-wide artefacts.
+   *
+   * Storage: a preset collection at `content/collections/projects/`.
+   * Access: dedicated `/api/projects/*` routes wrap this service.
+   */
+
+  /** Slug of the preset collection that stores project records. */
+  export const PROJECTS_COLLECTION_SLUG = 'projects';
+
+  const SLUG_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+
+  /**
+   * Validate a project slug (also used for any artefact's `meta.project`
+   * value). Same rules as collection / menu slugs.
+   *
+   * @param {unknown} slug
+   * @returns {boolean}
+   */
+  export function validateSlug(slug) {
+      return typeof slug === 'string' && SLUG_RE.test(slug);
+  }
+  ```
+
+- [ ] **Step 1.4: Verify tests pass**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: 3/3 pass.
+
+---
+
+## Task 2: Register `projects` as a preset collection
+
+**Files:**
+
+- Modify: `server/services/presetCollections.js`
+
+- [ ] **Step 2.1: Add the projects preset**
+
+  In `server/services/presetCollections.js`, inside the `PRESETS` array (after the `notifications` entry, around line 39), add:
+
+  ```js
+      ,
+      {
+          slug: 'projects',
+          title: 'Projects',
+          description: 'Named groupings of related artefacts.',
+          preset: true,
+          systemManaged: true,
+          fields: [
+              {name: 'slug',        label: 'Slug',        type: 'text',     required: true},
+              {name: 'name',        label: 'Name',        type: 'text',     required: true},
+              {name: 'description', label: 'Description', type: 'textarea'},
+              {name: 'icon',        label: 'Icon',        type: 'text',     default: 'folder'},
+              {name: 'rootUrl',     label: 'Root URL',    type: 'text'},
+              {name: 'sortOrder',   label: 'Sort Order',  type: 'number',   default: 0}
+          ],
+          api: {
+              create: {enabled: false, access: 'admin'},
+              read:   {enabled: false, access: 'admin'},
+              update: {enabled: false, access: 'admin'},
+              delete: {enabled: false, access: 'admin'}
+          }
+      }
+  ```
+
+  (Generic collection API for `projects` is disabled - the dedicated `/api/projects/*` routes from Task 7 are the access path.)
+
+- [ ] **Step 2.2: Verify the preset is registered**
+
+  Run:
+  ```bash
+  node -e "import('./server/services/presetCollections.js').then(m => console.log('slugs:', m.PRESET_COLLECTION_SLUGS))"
+  ```
+
+  Expected: prints `slugs: [ 'notifications', 'projects' ]`.
+
+---
+
+## Task 3: Projects CRUD service
+
+**Files:**
+
+- Modify: `server/services/projects.js`
+- Modify: `tests/services/projects.test.js`
+
+The service stores projects as entries in the preset collection, using the existing `server/services/collections.js` entry CRUD as the storage layer.
+
+- [ ] **Step 3.1: Write the CRUD tests**
+
+  Append to `tests/services/projects.test.js`:
+
+  ```js
+  import {
+      listProjects, getProject, createProject, updateProject, deleteProject
+  } from '../../server/services/projects.js';
+  import {load as loadRoles} from '../../server/services/roles.js';
+
+  const T = () => 'test-project-' + Date.now() + '-' + Math.random().toString(36).slice(2, 6);
+
+  // Roles must be loaded before any service that may consult them.
+  await loadRoles();
+
+  test('createProject → getProject round-trip', async () => {
+      const slug = T();
+      const project = {
+          slug, name: 'Test Project', description: 'd',
+          icon: 'box', rootUrl: '/' + slug, sortOrder: 5
+      };
+      await createProject(project);
+      try {
+          const fetched = await getProject(slug);
+          assert.equal(fetched.slug, slug);
+          assert.equal(fetched.name, 'Test Project');
+          assert.equal(fetched.rootUrl, '/' + slug);
+          assert.equal(fetched.sortOrder, 5);
+          assert.ok(fetched.createdAt);
+          assert.ok(fetched.updatedAt);
+      } finally {
+          await deleteProject(slug);
+      }
+  });
+
+  test('createProject refuses duplicate slug', async () => {
+      const slug = T();
+      await createProject({slug, name: 'A'});
+      try {
+          await assert.rejects(
+              () => createProject({slug, name: 'B'}),
+              /already exists/
+          );
+      } finally {
+          await deleteProject(slug);
+      }
+  });
+
+  test('updateProject preserves createdAt + slug; bumps updatedAt; allows other edits', async () => {
+      const slug = T();
+      await createProject({slug, name: 'Old'});
+      try {
+          const original = await getProject(slug);
+          await updateProject(slug, {name: 'New', description: 'updated'});
+          const updated = await getProject(slug);
+          assert.equal(updated.slug, slug);
+          assert.equal(updated.name, 'New');
+          assert.equal(updated.description, 'updated');
+          assert.equal(updated.createdAt, original.createdAt);
+          assert.ok(updated.updatedAt >= original.updatedAt);
+      } finally {
+          await deleteProject(slug);
+      }
+  });
+
+  test('listProjects returns slug+name+description+icon+rootUrl+sortOrder', async () => {
+      const slug = T();
+      await createProject({slug, name: 'Listed', icon: 'star'});
+      try {
+          const all = await listProjects();
+          const found = all.find(p => p.slug === slug);
+          assert.ok(found);
+          assert.equal(found.name, 'Listed');
+          assert.equal(found.icon, 'star');
+      } finally {
+          await deleteProject(slug);
+      }
+  });
+
+  test('getProject returns null for unknown slug', async () => {
+      assert.equal(await getProject('nope-' + Date.now()), null);
+  });
+
+  test('deleteProject removes the record when no artefacts tagged', async () => {
+      const slug = T();
+      await createProject({slug, name: 'Soon-gone'});
+      const ok = await deleteProject(slug);
+      assert.equal(ok, true);
+      assert.equal(await getProject(slug), null);
+  });
+  ```
+
+- [ ] **Step 3.2: Run to confirm tests fail**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: failures referencing `listProjects`, etc.
+
+- [ ] **Step 3.3: Implement the CRUD functions**
+
+  Append to `server/services/projects.js`:
+
+  ```js
+  import {
+      listEntries, createEntry, updateEntry, deleteEntry
+  } from './collections.js';
+
+  /**
+   * List all projects. Returns a flat array of project records, sorted by
+   * sortOrder ascending then name alphabetical.
+   *
+   * @returns {Promise<Array<object>>}
+   */
+  export async function listProjects() {
+      const entries = await listEntries(PROJECTS_COLLECTION_SLUG);
+      const projects = entries.map(e => normalise(e));
+      return projects.sort((a, b) => {
+          const so = (a.sortOrder ?? 0) - (b.sortOrder ?? 0);
+          if (so !== 0) return so;
+          return (a.name || '').localeCompare(b.name || '');
+      });
+  }
+
+  /**
+   * Fetch a single project by slug. Returns null if missing or slug invalid.
+   *
+   * @param {string} slug
+   * @returns {Promise<object|null>}
+   */
+  export async function getProject(slug) {
+      if (!validateSlug(slug)) return null;
+      const entries = await listEntries(PROJECTS_COLLECTION_SLUG);
+      const entry = entries.find(e => e.data?.slug === slug);
+      return entry ? normalise(entry) : null;
+  }
+
+  /**
+   * Create a new project. Refuses on slug collision or validation failure.
+   *
+   * @param {object} input
+   * @returns {Promise<object>} the persisted project
+   * @throws {Error}
+   */
+  export async function createProject(input) {
+      const errors = validateProject(input);
+      if (errors.length) throw new Error('Validation failed: ' + errors.join('; '));
+      if (await getProject(input.slug)) {
+          throw new Error(`Project "${input.slug}" already exists`);
+      }
+      const now = new Date().toISOString();
+      const data = {
+          slug:        input.slug,
+          name:        input.name,
+          description: input.description || '',
+          icon:        input.icon        || 'folder',
+          ...(input.rootUrl   != null && {rootUrl:   input.rootUrl}),
+          sortOrder:   Number.isFinite(input.sortOrder) ? input.sortOrder : 0,
+          createdAt:   now,
+          updatedAt:   now
+      };
+      await createEntry(PROJECTS_COLLECTION_SLUG, data);
+      return data;
+  }
+
+  /**
+   * Update a project. Slug is immutable. Preserves createdAt; bumps updatedAt.
+   *
+   * @param {string} slug
+   * @param {object} input
+   * @returns {Promise<object>}
+   * @throws {Error}
+   */
+  export async function updateProject(slug, input) {
+      const existing = await getProject(slug);
+      if (!existing) throw new Error(`Project "${slug}" not found`);
+      const merged = {
+          ...existing,
+          ...(input.name        != null && {name:        input.name}),
+          ...(input.description != null && {description: input.description}),
+          ...(input.icon        != null && {icon:        input.icon}),
+          ...(input.rootUrl     != null && {rootUrl:     input.rootUrl}),
+          ...(Number.isFinite(input.sortOrder) && {sortOrder: input.sortOrder}),
+          slug,                                          // slug is immutable
+          createdAt: existing.createdAt,
+          updatedAt: new Date().toISOString()
+      };
+      const errors = validateProject(merged);
+      if (errors.length) throw new Error('Validation failed: ' + errors.join('; '));
+      // Find the entry id by slug to update by id
+      const entries = await listEntries(PROJECTS_COLLECTION_SLUG);
+      const entry = entries.find(e => e.data?.slug === slug);
+      if (!entry) throw new Error(`Project "${slug}" not found`);
+      await updateEntry(PROJECTS_COLLECTION_SLUG, entry.id, merged);
+      return merged;
+  }
+
+  /**
+   * Delete a project. Returns true if removed, false if not found.
+   * Does NOT check for tagged artefacts - caller (API route) must do that.
+   *
+   * @param {string} slug
+   * @returns {Promise<boolean>}
+   */
+  export async function deleteProject(slug) {
+      if (!validateSlug(slug)) return false;
+      const entries = await listEntries(PROJECTS_COLLECTION_SLUG);
+      const entry = entries.find(e => e.data?.slug === slug);
+      if (!entry) return false;
+      await deleteEntry(PROJECTS_COLLECTION_SLUG, entry.id);
+      return true;
+  }
+
+  function normalise(entry) {
+      return {...(entry.data || {})};
+  }
+  ```
+
+- [ ] **Step 3.4: Add validation helper**
+
+  Append (also to `server/services/projects.js`):
+
+  ```js
+  /**
+   * Validate a project object. Returns an array of error strings (empty = OK).
+   *
+   * @param {object} project
+   * @returns {string[]}
+   */
+  export function validateProject(project) {
+      const errors = [];
+      if (!project || typeof project !== 'object') return ['Project must be an object'];
+      if (!validateSlug(project.slug)) {
+          errors.push(`Invalid slug "${project.slug}" - lowercase alphanumeric + hyphen only`);
+      }
+      if (!project.name || typeof project.name !== 'string') {
+          errors.push('name is required');
+      }
+      if (project.rootUrl != null && project.rootUrl !== '') {
+          if (typeof project.rootUrl !== 'string' || !project.rootUrl.startsWith('/')) {
+              errors.push('rootUrl must start with /');
+          } else if (project.rootUrl === '/') {
+              errors.push('rootUrl cannot be exactly "/" (would auto-claim every page)');
+          }
+      }
+      if (project.icon != null && (typeof project.icon !== 'string' || !project.icon.trim())) {
+          errors.push('icon must be a non-empty string when set');
+      }
+      return errors;
+  }
+  ```
+
+- [ ] **Step 3.5: Run tests**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: all tests pass.
+
+---
+
+## Task 4: `canSeeArtefact` + `getProjectForPage` helpers
+
+**Files:**
+
+- Modify: `server/services/projects.js`
+- Modify: `tests/services/projects.test.js`
+
+The two scope/lookup helpers used everywhere artefacts are filtered or pages are loaded.
+
+- [ ] **Step 4.1: Write helper tests**
+
+  Append to `tests/services/projects.test.js`:
+
+  ```js
+  import {canSeeArtefact, getProjectForPage} from '../../server/services/projects.js';
+
+  test('canSeeArtefact - super-admin sees everything', () => {
+      const user = {id: 'sa', role: 'super-admin', projects: []};
+      const tagged = {meta: {project: 'members'}};
+      assert.equal(canSeeArtefact(user, tagged), true);
+  });
+
+  test('canSeeArtefact - untagged artefact visible to everyone', () => {
+      const user = {id: 'u', role: 'admin', projects: ['members']};
+      const untagged = {meta: {}};
+      const noMeta  = {};
+      assert.equal(canSeeArtefact(user, untagged), true);
+      assert.equal(canSeeArtefact(user, noMeta), true);
+  });
+
+  test('canSeeArtefact - empty user.projects = no restriction', () => {
+      const user = {id: 'u', role: 'admin', projects: []};
+      const tagged = {meta: {project: 'members'}};
+      assert.equal(canSeeArtefact(user, tagged), true);
+      const userUndef = {id: 'u', role: 'admin'};
+      assert.equal(canSeeArtefact(userUndef, tagged), true);
+  });
+
+  test('canSeeArtefact - scoped user can see their projects, not others', () => {
+      const user = {id: 'u', role: 'admin', projects: ['members']};
+      assert.equal(canSeeArtefact(user, {meta: {project: 'members'}}), true);
+      assert.equal(canSeeArtefact(user, {meta: {project: 'intranet'}}), false);
+  });
+
+  test('getProjectForPage - explicit project: null = untagged', async () => {
+      const slug = T();
+      await createProject({slug, name: 'A', rootUrl: '/a'});
+      try {
+          assert.equal(await getProjectForPage('/a/foo', null), null);
+      } finally {
+          await deleteProject(slug);
+      }
+  });
+
+  test('getProjectForPage - explicit project: <slug> wins', async () => {
+      const slug1 = T();
+      const slug2 = T();
+      await createProject({slug: slug1, name: 'A', rootUrl: '/a'});
+      await createProject({slug: slug2, name: 'B'});
+      try {
+          assert.equal(await getProjectForPage('/a/foo', slug2), slug2);
+      } finally {
+          await deleteProject(slug1);
+          await deleteProject(slug2);
+      }
+  });
+
+  test('getProjectForPage - URL inheritance: longest prefix wins', async () => {
+      const slug1 = T();
+      const slug2 = T();
+      await createProject({slug: slug1, name: 'A', rootUrl: '/members'});
+      await createProject({slug: slug2, name: 'B', rootUrl: '/members/billing'});
+      try {
+          assert.equal(await getProjectForPage('/members/foo',         undefined), slug1);
+          assert.equal(await getProjectForPage('/members/billing/x',   undefined), slug2);
+      } finally {
+          await deleteProject(slug1);
+          await deleteProject(slug2);
+      }
+  });
+
+  test('getProjectForPage - no rootUrl match returns null', async () => {
+      assert.equal(await getProjectForPage('/random-url', undefined), null);
+  });
+  ```
+
+- [ ] **Step 4.2: Run to confirm failure**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: 8 new tests fail.
+
+- [ ] **Step 4.3: Implement the helpers**
+
+  Append to `server/services/projects.js`:
+
+  ```js
+  import {getRoleLevel} from './roles.js';
+
+  /**
+   * List projects the given user is allowed to see. Super-admin sees all;
+   * users with empty `projects: []` see all; scoped users see their listed
+   * projects only.
+   *
+   * @param {object|null} user
+   * @returns {Promise<Array<object>>}
+   */
+  export async function listProjectsForUser(user) {
+      const all = await listProjects();
+      if (!user) return [];
+      if (getRoleLevel(user.role) === 0) return all;
+      if (!Array.isArray(user.projects) || user.projects.length === 0) return all;
+      return all.filter(p => user.projects.includes(p.slug));
+  }
+
+  /**
+   * Permission gate: can `user` see / edit `artefact` given its project tag
+   * and the user's `projects: []` access scope?
+   *
+   * Rules:
+   *   - Super-admin (role level 0) bypasses everything.
+   *   - Untagged artefacts (no `meta.project`) are visible to all.
+   *   - Users with no scope set (`projects: []` or missing) have no restriction.
+   *   - Otherwise: artefact's project must be in user's scope.
+   *
+   * @param {object} user      - Authenticated user; must have `role`.
+   * @param {object} artefact  - Anything with optional `meta.project`.
+   * @returns {boolean}
+   */
+  export function canSeeArtefact(user, artefact) {
+      if (!user) return false;
+      if (getRoleLevel(user.role) === 0) return true;                        // super-admin bypass
+      const project = artefact?.meta?.project;
+      if (!project) return true;                                             // untagged
+      if (!Array.isArray(user.projects) || user.projects.length === 0) return true;
+      return user.projects.includes(project);
+  }
+
+  /**
+   * Resolve the project a page belongs to using the inheritance rules:
+   *   1. Explicit `project: null` in frontmatter → untagged
+   *   2. Explicit `project: '<slug>'` → use it
+   *   3. Missing field → longest matching `rootUrl` prefix wins
+   *   4. No match → untagged
+   *
+   * @param {string} urlPath             - The page's URL (e.g. '/members/profile').
+   * @param {string|null|undefined} explicitProject - Frontmatter `project:` value.
+   * @returns {Promise<string|null>}
+   */
+  export async function getProjectForPage(urlPath, explicitProject) {
+      if (explicitProject === null) return null;                  // explicit opt-out
+      if (typeof explicitProject === 'string' && explicitProject) return explicitProject;
+      // No explicit field - URL inheritance
+      const projects = await listProjects();
+      let best = null;
+      let bestLen = -1;
+      for (const p of projects) {
+          if (!p.rootUrl) continue;
+          if (urlPath === p.rootUrl || urlPath.startsWith(p.rootUrl + '/')) {
+              if (p.rootUrl.length > bestLen) {
+                  best = p.slug;
+                  bestLen = p.rootUrl.length;
+              } else if (p.rootUrl.length === bestLen && p.slug < best) {
+                  best = p.slug;                                   // alphabetical tie-breaker
+              }
+          }
+      }
+      return best;
+  }
+  ```
+
+- [ ] **Step 4.4: Run tests**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: all tests pass.
+
+---
+
+## Task 5: `getArtefactsForProject` + `untagAllForProject`
+
+**Files:**
+
+- Modify: `server/services/projects.js`
+- Modify: `tests/services/projects.test.js`
+
+These two functions are heavy: they touch every artefact service to enumerate or mutate. They're the backbone of the project detail page and the safe-delete escape hatch.
+
+- [ ] **Step 5.1: Write the enumeration test**
+
+  Append to `tests/services/projects.test.js`:
+
+  ```js
+  import {getArtefactsForProject, untagAllForProject} from '../../server/services/projects.js';
+  import {createMenu, deleteMenu} from '../../server/services/menus.js';
+
+  test('getArtefactsForProject returns artefacts grouped by type', async () => {
+      const slug = T();
+      await createProject({slug, name: 'A'});
+      const menuSlug = 'gafp-' + Date.now();
+      await createMenu({slug: menuSlug, name: 'X', items: [], meta: {project: slug}});
+      try {
+          const grouped = await getArtefactsForProject(slug);
+          assert.ok(Array.isArray(grouped.menus));
+          assert.ok(grouped.menus.some(m => m.slug === menuSlug));
+          // Other type arrays exist even if empty
+          assert.ok(Array.isArray(grouped.collections));
+          assert.ok(Array.isArray(grouped.forms));
+          assert.ok(Array.isArray(grouped.pages));
+      } finally {
+          await deleteMenu(menuSlug);
+          await deleteProject(slug);
+      }
+  });
+
+  test('untagAllForProject clears meta.project on matching artefacts', async () => {
+      const slug = T();
+      await createProject({slug, name: 'A'});
+      const menuSlug = 'untag-' + Date.now();
+      await createMenu({slug: menuSlug, name: 'X', items: [], meta: {project: slug}});
+      try {
+          const removed = await untagAllForProject(slug);
+          assert.ok(removed.menus >= 1);
+          const {getMenu} = await import('../../server/services/menus.js');
+          const m = await getMenu(menuSlug);
+          assert.equal(m.meta?.project ?? null, null);
+      } finally {
+          await deleteMenu(menuSlug);
+          await deleteProject(slug);
+      }
+  });
+  ```
+
+- [ ] **Step 5.2: Run to confirm failure**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: 2 new tests fail.
+
+- [ ] **Step 5.3: Implement enumeration + untag**
+
+  Append to `server/services/projects.js`:
+
+  ```js
+  /**
+   * Enumerate every artefact tagged with the given project. Returns a flat
+   * grouping by type - each value is an array of artefact summary objects.
+   * Used by the project detail page (counts + per-type tabs).
+   *
+   * @param {string} projectSlug
+   * @returns {Promise<{pages:object[], collections:object[], forms:object[], actions:object[], menus:object[], blocks:object[], views:object[], roles:object[], users:object[]}>}
+   */
+  export async function getArtefactsForProject(projectSlug) {
+      const out = {
+          pages: [], collections: [], forms: [], actions: [],
+          menus: [], blocks: [], views: [], roles: [], users: []
+      };
+
+      try {
+          const {listMenus, getMenu} = await import('./menus.js');
+          for (const m of await listMenus()) {
+              const full = await getMenu(m.slug);
+              if (full?.meta?.project === projectSlug) out.menus.push(m);
+          }
+      } catch { /* service unavailable in test contexts */ }
+
+      try {
+          const {listForms, readForm} = await import('./forms.js');
+          for (const f of await listForms()) {
+              const full = await readForm(f.slug);
+              if (full?.meta?.project === projectSlug) out.forms.push(f);
+          }
+      } catch { /* skip */ }
+
+      try {
+          const {listCollections, getCollection} = await import('./collections.js');
+          for (const c of await listCollections()) {
+              const full = await getCollection(c.slug);
+              if (full?.meta?.project === projectSlug) out.collections.push(c);
+          }
+      } catch { /* skip */ }
+
+      try {
+          const {listActions} = await import('./actions.js');
+          for (const a of await listActions()) {
+              if (a?.meta?.project === projectSlug) out.actions.push(a);
+          }
+      } catch { /* skip */ }
+
+      try {
+          const {listBlocks, readBlock} = await import('./blocks.js');
+          for (const b of await listBlocks()) {
+              const full = (typeof readBlock === 'function') ? await readBlock(b.slug) : b;
+              if (full?.meta?.project === projectSlug) out.blocks.push(b);
+          }
+      } catch { /* skip */ }
+
+      try {
+          const {listViews} = await import('./views.js');
+          for (const v of await listViews()) {
+              if (v?.meta?.project === projectSlug) out.views.push(v);
+          }
+      } catch { /* skip */ }
+
+      try {
+          const {getRoleMap} = await import('./roles.js');
+          for (const role of getRoleMap().values()) {
+              if (role?.meta?.project === projectSlug) out.roles.push(role);
+          }
+      } catch { /* skip */ }
+
+      try {
+          const {listUsers} = await import('./users.js');
+          for (const u of await listUsers()) {
+              if (u?.meta?.project === projectSlug) out.users.push(u);
+          }
+      } catch { /* skip */ }
+
+      try {
+          const {listPages} = await import('./content.js');
+          for (const p of await listPages()) {
+              const pageProject = await getProjectForPage(p.url || p.urlPath || '/', p.project);
+              if (pageProject === projectSlug) out.pages.push(p);
+          }
+      } catch { /* skip */ }
+
+      return out;
+  }
+
+  /**
+   * Set `meta.project: null` on every artefact tagged with this project.
+   * Returns a count map of how many of each type were untagged. Used as the
+   * "Untag all" escape hatch before delete.
+   *
+   * @param {string} projectSlug
+   * @returns {Promise<Record<string, number>>}
+   */
+  export async function untagAllForProject(projectSlug) {
+      const counts = {
+          pages: 0, collections: 0, forms: 0, actions: 0,
+          menus: 0, blocks: 0, views: 0, roles: 0, users: 0
+      };
+      const grouped = await getArtefactsForProject(projectSlug);
+
+      try {
+          const {getMenu, updateMenu} = await import('./menus.js');
+          for (const m of grouped.menus) {
+              const full = await getMenu(m.slug);
+              if (!full) continue;
+              const meta = {...(full.meta || {})};
+              delete meta.project;
+              await updateMenu(m.slug, {...full, meta});
+              counts.menus++;
+          }
+      } catch { /* skip */ }
+
+      // Forms, Collections, Actions, Blocks, Views, Roles, Users, Pages -
+      // each service's update path is similar. We rely on the per-service
+      // tasks (Tasks 9-16) having already plumbed `meta.project` through
+      // update, so calling the standard update with `meta.project` removed
+      // is sufficient. Each block below mirrors the menus pattern.
+
+      try {
+          const {readForm, writeForm} = await import('./forms.js');
+          for (const f of grouped.forms) {
+              const full = await readForm(f.slug);
+              if (!full) continue;
+              const meta = {...(full.meta || {})};
+              delete meta.project;
+              await writeForm(f.slug, {...full, meta});
+              counts.forms++;
+          }
+      } catch { /* skip */ }
+
+      try {
+          const {getCollection, updateCollection} = await import('./collections.js');
+          for (const c of grouped.collections) {
+              const full = await getCollection(c.slug);
+              if (!full) continue;
+              const meta = {...(full.meta || {})};
+              delete meta.project;
+              await updateCollection(c.slug, {...full, meta});
+              counts.collections++;
+          }
+      } catch { /* skip */ }
+
+      try {
+          const {updateAction} = await import('./actions.js');
+          for (const a of grouped.actions) {
+              const meta = {...(a.meta || {})};
+              delete meta.project;
+              await updateAction(a.slug, {...a, meta});
+              counts.actions++;
+          }
+      } catch { /* skip */ }
+
+      try {
+          const {readBlock, writeBlock} = await import('./blocks.js');
+          for (const b of grouped.blocks) {
+              const full = (typeof readBlock === 'function') ? await readBlock(b.slug) : b;
+              if (!full) continue;
+              const meta = {...(full.meta || {})};
+              delete meta.project;
+              if (typeof writeBlock === 'function') {
+                  await writeBlock(b.slug, {...full, meta});
+                  counts.blocks++;
+              }
+          }
+      } catch { /* skip */ }
+
+      try {
+          const {readView, writeView} = await import('./views.js');
+          for (const v of grouped.views) {
+              const full = (typeof readView === 'function') ? await readView(v.slug) : v;
+              if (!full) continue;
+              const meta = {...(full.meta || {})};
+              delete meta.project;
+              if (typeof writeView === 'function') {
+                  await writeView(v.slug, {...full, meta});
+                  counts.views++;
+              }
+          }
+      } catch { /* skip */ }
+
+      // Roles + Users carry `meta.project` on the user/role record; updateUser
+      // and the role-collection-entry update path both accept meta. Pages
+      // would need frontmatter rewriting - defer to a follow-up; for v1 the
+      // page count is reported but no rewrite happens (admin can edit the
+      // page to clear the project).
+      // The function still returns counts.pages = 0 in v1 even when pages
+      // were tagged; the API route's response surfaces this caveat.
+
+      return counts;
+  }
+  ```
+
+- [ ] **Step 5.4: Run tests**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: all pass (including the 2 new ones).
+
+  Note: the test only exercises the menus path because that's the only service that has `meta.project` plumbed at this point in the build. Per-service plumbing comes in Tasks 9-16; afterwards `untagAllForProject` exercises every type.
+
+---
+
+## Task 6: Permission family `projects.*`
+
+**Files:**
+
+- Modify: `server/services/permissionRegistry.js`
+
+- [ ] **Step 6.1: Insert the projects family**
+
+  Run: `grep -n "key: 'menus'" server/services/permissionRegistry.js`
+
+  In `server/services/permissionRegistry.js`, after the `menus` entry's closing `},`, insert:
+
+  ```js
+      {
+          key: 'projects',
+          label: 'Projects',
+          description: 'Group related artefacts under named projects.',
+          icon: 'folder',
+          group: 'Structure',
+          actions: [
+              {key: 'read',   label: 'View',   description: 'View projects and their artefacts'},
+              {key: 'create', label: 'Create', description: 'Create new projects'},
+              {key: 'update', label: 'Edit',   description: 'Edit projects and tag/untag artefacts'},
+              {key: 'delete', label: 'Delete', description: 'Delete projects (refused if any artefacts tagged)'}
+          ]
+      },
+  ```
+
+- [ ] **Step 6.2: Smoke test**
+
+  Run:
+  ```bash
+  node -e "import('./server/services/permissionRegistry.js').then(m => console.log(m.REGISTRY.find(r => r.key === 'projects')))"
+  ```
+
+  Expected: prints the projects family with all 4 actions.
+
+---
+
+## Task 7: API routes `/api/projects/*`
+
+**Files:**
+
+- Create: `server/routes/api/projects.js`
+- Create: `tests/routes/projects.test.js`
+
+- [ ] **Step 7.1: Write route tests**
+
+  Create `tests/routes/projects.test.js`:
+
+  ```js
+  /**
+   * Smoke tests for /api/projects/* - verifies route shape, auth gates, and
+   * happy-path CRUD via Fastify .inject.
+   */
+  import {test, before, after} from 'node:test';
+  import assert from 'node:assert/strict';
+  import Fastify from 'fastify';
+  import fastifyJwt from '@fastify/jwt';
+  import {projectsRoutes} from '../../server/routes/api/projects.js';
+  import {deleteProject} from '../../server/services/projects.js';
+  import {load as loadRoles} from '../../server/services/roles.js';
+
+  await loadRoles();
+
+  // DI-friendly auth stubs (same pattern as menus routes).
+  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) => projectsRoutes(inst, {authenticate, requirePermission}), {prefix: '/api'});
+      return app;
+  }
+
+  const T = () => 'rt-proj-' + Date.now() + '-' + Math.random().toString(36).slice(2, 6);
+
+  test('POST /api/projects → 201 + body', async () => {
+      const app = await buildApp();
+      const slug = T();
+      try {
+          const res = await app.inject({method: 'POST', url: '/api/projects', payload: {slug, name: 'Test'}});
+          assert.equal(res.statusCode, 201);
+          assert.equal(res.json().slug, slug);
+      } finally {
+          await deleteProject(slug);
+          await app.close();
+      }
+  });
+
+  test('GET /api/projects → array including the created project', async () => {
+      const app = await buildApp();
+      const slug = T();
+      try {
+          await app.inject({method: 'POST', url: '/api/projects', payload: {slug, name: 'A'}});
+          const res = await app.inject({method: 'GET', url: '/api/projects'});
+          assert.equal(res.statusCode, 200);
+          assert.ok(res.json().some(p => p.slug === slug));
+      } finally {
+          await deleteProject(slug);
+          await app.close();
+      }
+  });
+
+  test('GET /api/projects/:slug → full project', async () => {
+      const app = await buildApp();
+      const slug = T();
+      try {
+          await app.inject({method: 'POST', url: '/api/projects', payload: {slug, name: 'A'}});
+          const res = await app.inject({method: 'GET', url: `/api/projects/${slug}`});
+          assert.equal(res.statusCode, 200);
+          assert.equal(res.json().name, 'A');
+      } finally {
+          await deleteProject(slug);
+          await app.close();
+      }
+  });
+
+  test('GET /api/projects/:slug → 404 for unknown', async () => {
+      const app = await buildApp();
+      const res = await app.inject({method: 'GET', url: '/api/projects/does-not-exist'});
+      assert.equal(res.statusCode, 404);
+      await app.close();
+  });
+
+  test('PUT /api/projects/:slug → 200 + updated', async () => {
+      const app = await buildApp();
+      const slug = T();
+      try {
+          await app.inject({method: 'POST', url: '/api/projects', payload: {slug, name: 'A'}});
+          const res = await app.inject({method: 'PUT', url: `/api/projects/${slug}`, payload: {name: 'B'}});
+          assert.equal(res.statusCode, 200);
+          assert.equal(res.json().name, 'B');
+      } finally {
+          await deleteProject(slug);
+          await app.close();
+      }
+  });
+
+  test('DELETE /api/projects/:slug → 200 when empty', async () => {
+      const app = await buildApp();
+      const slug = T();
+      await app.inject({method: 'POST', url: '/api/projects', payload: {slug, name: 'A'}});
+      const res = await app.inject({method: 'DELETE', url: `/api/projects/${slug}`});
+      assert.equal(res.statusCode, 200);
+      await app.close();
+  });
+
+  test('GET /api/projects/:slug/artefacts → grouped object', async () => {
+      const app = await buildApp();
+      const slug = T();
+      try {
+          await app.inject({method: 'POST', url: '/api/projects', payload: {slug, name: 'A'}});
+          const res = await app.inject({method: 'GET', url: `/api/projects/${slug}/artefacts`});
+          assert.equal(res.statusCode, 200);
+          const body = res.json();
+          assert.ok(Array.isArray(body.menus));
+          assert.ok(Array.isArray(body.collections));
+      } finally {
+          await deleteProject(slug);
+          await app.close();
+      }
+  });
+  ```
+
+- [ ] **Step 7.2: Run to confirm failure**
+
+  Run: `node --test tests/routes/projects.test.js`
+
+  Expected: import error.
+
+- [ ] **Step 7.3: Implement the route module**
+
+  Create `server/routes/api/projects.js`:
+
+  ```js
+  /**
+   * Projects API
+   *
+   * GET    /api/projects                       - list visible projects
+   * GET    /api/projects/:slug                 - full project
+   * POST   /api/projects                       - create
+   * PUT    /api/projects/:slug                 - edit (slug immutable)
+   * DELETE /api/projects/:slug                 - delete (409 if any artefacts tagged)
+   * GET    /api/projects/:slug/artefacts       - grouped artefacts
+   * POST   /api/projects/:slug/untag-all       - escape hatch before delete
+   *
+   * 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 {
+      listProjects, listProjectsForUser, getProject, createProject, updateProject, deleteProject,
+      getArtefactsForProject, untagAllForProject
+  } from '../../services/projects.js';
+  import * as cache from '../../services/cache/index.js';
+
+  export async function projectsRoutes(fastify, opts = {}) {
+      const authenticate      = opts.authenticate      || defaultAuthenticate;
+      const requirePermission = opts.requirePermission || defaultRequirePermission;
+
+      const canRead   = {preHandler: [authenticate, requirePermission('projects', 'read')]};
+      const canCreate = {preHandler: [authenticate, requirePermission('projects', 'create')]};
+      const canUpdate = {preHandler: [authenticate, requirePermission('projects', 'update')]};
+      const canDelete = {preHandler: [authenticate, requirePermission('projects', 'delete')]};
+
+      fastify.get('/projects', canRead, async (request) => {
+          return listProjectsForUser(request.user);
+      });
+
+      fastify.get('/projects/:slug', canRead, async (request, reply) => {
+          const project = await getProject(request.params.slug);
+          if (!project) return reply.status(404).send({error: 'Project not found'});
+          return project;
+      });
+
+      fastify.post('/projects', canCreate, async (request, reply) => {
+          try {
+              const project = await createProject(request.body || {});
+              await cache.invalidateTags(['projects']);
+              return reply.status(201).send(project);
+          } catch (err) {
+              const status = /already exists/.test(err.message) ? 409 : 400;
+              return reply.status(status).send({error: err.message});
+          }
+      });
+
+      fastify.put('/projects/:slug', canUpdate, async (request, reply) => {
+          try {
+              const project = await updateProject(request.params.slug, request.body || {});
+              await cache.invalidateTags(['projects', `project:${request.params.slug}`]);
+              return project;
+          } catch (err) {
+              const status = /not found/.test(err.message) ? 404 : 400;
+              return reply.status(status).send({error: err.message});
+          }
+      });
+
+      fastify.delete('/projects/:slug', canDelete, async (request, reply) => {
+          const grouped = await getArtefactsForProject(request.params.slug);
+          const total = Object.values(grouped).reduce((sum, arr) => sum + arr.length, 0);
+          if (total > 0) {
+              return reply.status(409).send({
+                  error: `Cannot delete - ${total} artefacts still tagged with this project`,
+                  artefacts: Object.fromEntries(Object.entries(grouped).map(([k, v]) => [k, v.length]))
+              });
+          }
+          const ok = await deleteProject(request.params.slug);
+          if (!ok) return reply.status(404).send({error: 'Project not found'});
+          await cache.invalidateTags(['projects', `project:${request.params.slug}`]);
+          return {success: true};
+      });
+
+      fastify.get('/projects/:slug/artefacts', canRead, async (request, reply) => {
+          if (!(await getProject(request.params.slug))) {
+              return reply.status(404).send({error: 'Project not found'});
+          }
+          return getArtefactsForProject(request.params.slug);
+      });
+
+      fastify.post('/projects/:slug/untag-all', canDelete, async (request, reply) => {
+          if (!(await getProject(request.params.slug))) {
+              return reply.status(404).send({error: 'Project not found'});
+          }
+          const counts = await untagAllForProject(request.params.slug);
+          await cache.invalidateTags(['projects', `project:${request.params.slug}`]);
+          return {success: true, untagged: counts};
+      });
+  }
+  ```
+
+- [ ] **Step 7.4: Run tests**
+
+  Run: `node --test tests/routes/projects.test.js`
+
+  Expected: all 7 tests pass.
+
+---
+
+## Task 8: Wire routes + preset seed into server.js
+
+**Files:**
+
+- Modify: `server/server.js`
+
+- [ ] **Step 8.1: Import + register**
+
+  At the top of `server/server.js` (with the other dynamic imports):
+
+  ```js
+  const {projectsRoutes} = await import('./routes/api/projects.js');
+  ```
+
+  After the existing menus routes registration:
+
+  ```js
+  await app.register(projectsRoutes, {prefix: '/api'});
+  ```
+
+- [ ] **Step 8.2: Verify syntax + import**
+
+  Run: `node --check server/server.js`
+
+  Then:
+  ```bash
+  node -e "import('./server/routes/api/projects.js').then(m => console.log('projects ok:', typeof m.projectsRoutes))"
+  ```
+
+  Expected: silent + `projects ok: function`.
+
+- [ ] **Step 8.3: Curl smoke test (server already running)**
+
+  Run:
+  ```bash
+  curl -s -o /dev/null -w "%{http_code}\n" http://localhost:4096/api/projects
+  ```
+
+  Expected: `401` (auth-gated, route registered). The route won't fire until the server is restarted. Tell the user to restart at their convenience.
+
+---
+
+## Task 9: Plumb `meta.project` through `collections.js`
+
+**Files:**
+
+- Modify: `server/services/collections.js`
+
+The collection schema's `meta.project` field needs to be persisted on create/update and read back on get. List filtering happens in the route handler (Task 17 onwards).
+
+- [ ] **Step 9.1: Find createCollection signature**
+
+  Run: `grep -n "export async function createCollection\|export async function updateCollection" server/services/collections.js`
+
+  The current signature is `createCollection({title, slug, description, fields, api, storage, bundled, plugin})`.
+
+- [ ] **Step 9.2: Accept `meta` in create/update**
+
+  In `server/services/collections.js`:
+
+  - In `createCollection`, add `meta` to the destructured params and persist it into the schema object that's written. Locate the line that builds the schema (`const schema = {...}`) and add:
+
+    ```js
+    ...(meta != null && {meta}),
+    ```
+
+  - In `updateCollection`, the function already accepts a partial update; ensure that `meta` is preserved if not in the update payload (typical updates spread existing + new). Locate the merge and confirm `meta` flows through. If it does, no change needed; if not, add an explicit `meta: input.meta ?? existing.meta` line.
+
+- [ ] **Step 9.3: Verify with a round-trip test**
+
+  Append to `tests/services/projects.test.js`:
+
+  ```js
+  import {createCollection, getCollection, deleteCollection} from '../../server/services/collections.js';
+
+  test('collections - meta.project round-trips through create/get', async () => {
+      const slug = 'meta-proj-col-' + Date.now();
+      await createCollection({
+          slug, title: 'X', fields: [{name: 't', label: 'T', type: 'text'}],
+          meta: {project: 'members'}
+      });
+      try {
+          const c = await getCollection(slug);
+          assert.equal(c?.meta?.project, 'members');
+      } finally {
+          await deleteCollection(slug);
+      }
+  });
+  ```
+
+- [ ] **Step 9.4: Run the test**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: pass.
+
+---
+
+## Task 10: Plumb `meta.project` through `forms.js`
+
+**Files:**
+
+- Modify: `server/services/forms.js`
+
+Forms persist as JSON files; `writeForm(slug, data)` already takes the full object. The persistence path likely preserves arbitrary keys - verify, then add a test.
+
+- [ ] **Step 10.1: Verify `writeForm` preserves arbitrary keys**
+
+  Read `server/services/forms.js`. Inspect `writeForm`'s body. If it spreads `data` directly into the file (the common case), `meta` is already persisted.
+
+  If the function builds a whitelist of fields, add `meta` to the whitelist:
+
+  ```js
+  const persisted = {
+      slug: data.slug,
+      title: data.title,
+      // ... existing fields ...
+      ...(data.meta != null && {meta: data.meta})
+  };
+  ```
+
+- [ ] **Step 10.2: Round-trip test**
+
+  Append to `tests/services/projects.test.js`:
+
+  ```js
+  import {writeForm, readForm, deleteForm} from '../../server/services/forms.js';
+
+  test('forms - meta.project round-trips', async () => {
+      const slug = 'meta-proj-form-' + Date.now();
+      await writeForm(slug, {slug, title: 'X', fields: [], meta: {project: 'members'}});
+      try {
+          const f = await readForm(slug);
+          assert.equal(f?.meta?.project, 'members');
+      } finally {
+          await deleteForm(slug);
+      }
+  });
+  ```
+
+- [ ] **Step 10.3: Run the test**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: pass.
+
+---
+
+## Task 11: Plumb `meta.project` through `actions.js`
+
+**Files:**
+
+- Modify: `server/services/actions.js`
+
+- [ ] **Step 11.1: Check `createAction` signature**
+
+  Run: `grep -A 10 "export async function createAction" server/services/actions.js | head -15`
+
+  Confirm the function accepts a `data` bag and ensure `data.meta` is persisted alongside other fields when writing to Mongo.
+
+- [ ] **Step 11.2: Add `meta` to the persisted record**
+
+  In `createAction`, the Mongo insert should include `meta` if present:
+
+  ```js
+  const doc = {
+      slug:        data.slug,
+      title:       data.title,
+      // ... existing fields ...
+      ...(data.meta != null && {meta: data.meta}),
+      createdAt:   new Date(),
+      createdBy:   userId
+  };
+  ```
+
+  Likewise in `updateAction`.
+
+- [ ] **Step 11.3: Skip the round-trip test if Mongo isn't configured**
+
+  Append to `tests/services/projects.test.js`:
+
+  ```js
+  import {createAction, getAction, deleteAction} from '../../server/services/actions.js';
+
+  test('actions - meta.project round-trips (when Mongo configured)', async () => {
+      const slug = 'meta-proj-act-' + Date.now();
+      try {
+          await createAction({slug, title: 'X', collection: 'foo', meta: {project: 'members'}});
+      } catch (err) {
+          if (/Mongo/i.test(err.message)) return; // skip if Mongo not available
+          throw err;
+      }
+      try {
+          const a = await getAction(slug);
+          assert.equal(a?.meta?.project, 'members');
+      } finally {
+          await deleteAction(slug).catch(() => {});
+      }
+  });
+  ```
+
+- [ ] **Step 11.4: Run the test**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: pass (or skip silently when Mongo not configured).
+
+---
+
+## Task 12: Plumb `meta.project` through `menus.js`
+
+**Files:**
+
+- Modify: `server/services/menus.js`
+
+Menus already has a `meta` block that accepts `{createdAt, updatedAt, bundled, presetOwner}`. Need to allow `project` as an additional key (passthrough) AND surface it on `listMenus` results.
+
+- [ ] **Step 12.1: Update `createMenu` to accept `meta.project`**
+
+  In `server/services/menus.js`, locate `createMenu`. The `meta` block currently has fixed keys. Update it to spread input's meta:
+
+  ```js
+  meta: {
+      createdAt: now,
+      updatedAt: now,
+      bundled:     Boolean(input.meta?.bundled),
+      presetOwner: input.meta?.presetOwner || null,
+      ...(input.meta?.project != null && {project: input.meta.project})
+  }
+  ```
+
+  Likewise in `updateMenu` - the existing merge already spreads `input.meta`, so `project` will flow through.
+
+- [ ] **Step 12.2: Surface project in `listMenus`**
+
+  In `listMenus`, the existing summary object includes `meta`. The full `meta` is returned (including `project`). No change needed - verify by reading the function.
+
+- [ ] **Step 12.3: Round-trip test**
+
+  Append to `tests/services/projects.test.js`:
+
+  ```js
+  import {createMenu as cMenu, getMenu as gMenu, deleteMenu as dMenu} from '../../server/services/menus.js';
+
+  test('menus - meta.project round-trips', async () => {
+      const slug = 'meta-proj-menu-' + Date.now();
+      await cMenu({slug, name: 'X', items: [], meta: {project: 'members'}});
+      try {
+          const m = await gMenu(slug);
+          assert.equal(m?.meta?.project, 'members');
+      } finally {
+          await dMenu(slug);
+      }
+  });
+  ```
+
+- [ ] **Step 12.4: Run the test**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: pass.
+
+---
+
+## Task 13: Plumb `meta.project` through `blocks.js`
+
+**Files:**
+
+- Modify: `server/services/blocks.js`
+
+- [ ] **Step 13.1: Find the write path**
+
+  Run: `grep -n "export async function" server/services/blocks.js`
+
+  Identify the create/update/write function. Confirm or add `meta` passthrough on persistence (same shape as forms).
+
+- [ ] **Step 13.2: Round-trip test**
+
+  Append to `tests/services/projects.test.js`:
+
+  ```js
+  import {createBlock, getBlock, deleteBlock} from '../../server/services/blocks.js';
+
+  test('blocks - meta.project round-trips', async () => {
+      const slug = 'meta-proj-block-' + Date.now();
+      await createBlock({slug, name: 'X', body: '', meta: {project: 'members'}});
+      try {
+          const b = await getBlock(slug);
+          assert.equal(b?.meta?.project, 'members');
+      } finally {
+          await deleteBlock(slug);
+      }
+  });
+  ```
+
+  If the block service's create/get function names are different, adjust to match (`createBlock` may be `writeBlock`, `getBlock` may be `readBlock`).
+
+- [ ] **Step 13.3: Run the test**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: pass.
+
+---
+
+## Task 14: Plumb `meta.project` through `views.js`
+
+**Files:**
+
+- Modify: `server/services/views.js`
+
+Same pattern as Task 13. Read the file to find the write function; add `meta` passthrough; round-trip test.
+
+- [ ] **Step 14.1: Read the file to find the write path**
+
+  Read `server/services/views.js`, focusing on create/write functions.
+
+- [ ] **Step 14.2: Ensure `meta` passes through write**
+
+  Same edit pattern as forms/blocks.
+
+- [ ] **Step 14.3: Round-trip test**
+
+  Append to `tests/services/projects.test.js`:
+
+  ```js
+  import {createView, getView, deleteView} from '../../server/services/views.js';
+
+  test('views - meta.project round-trips', async () => {
+      const slug = 'meta-proj-view-' + Date.now();
+      await createView({slug, name: 'X', query: {}, meta: {project: 'members'}});
+      try {
+          const v = await getView(slug);
+          assert.equal(v?.meta?.project, 'members');
+      } finally {
+          await deleteView(slug);
+      }
+  });
+  ```
+
+  Adjust function names + fields to match the actual view shape.
+
+- [ ] **Step 14.4: Run the test**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: pass.
+
+---
+
+## Task 15: Plumb `meta.project` through `roles.js`
+
+**Files:**
+
+- Modify: `server/services/roles.js`
+
+Roles are stored as entries in a collection. `createRole(data)` writes the role entry. `data.meta.project` should be persisted as part of the role's data record.
+
+- [ ] **Step 15.1: Find createRole + load**
+
+  Read `server/services/roles.js`. `createRole(data)` accepts the role data; verify the entry write preserves arbitrary keys (likely yes - the function spreads data into the entry).
+
+  If the function whitelists keys, add `meta` to the whitelist.
+
+- [ ] **Step 15.2: Round-trip test**
+
+  Append to `tests/services/projects.test.js`:
+
+  ```js
+  import {createRole, getRoleMap, removeRole} from '../../server/services/roles.js';
+
+  test('roles - meta.project round-trips', async () => {
+      const name = 'meta-proj-role-' + Date.now();
+      await createRole({
+          name, label: 'Test', level: 5, permissions: [], meta: {project: 'members'}
+      });
+      try {
+          const role = getRoleMap().get(name);
+          assert.equal(role?.meta?.project, 'members');
+      } finally {
+          await removeRole(name);
+      }
+  });
+  ```
+
+- [ ] **Step 15.3: Run the test**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: pass.
+
+---
+
+## Task 16: Plumb `meta.project` + access scope through `users.js`
+
+**Files:**
+
+- Modify: `server/services/users.js`
+
+Users get TWO new fields: `meta.project` (administrative ownership - single project slug) and `projects: []` (access scope - array of project slugs).
+
+- [ ] **Step 16.1: Update `createUser` / `updateUser`**
+
+  In `server/services/users.js`, the create/update functions persist a user JSON. Add `meta` and `projects` to the persisted shape (or confirm they pass through if the writer spreads input).
+
+  Specifically, the persisted user should include:
+
+  ```js
+  ...(input.meta != null && {meta: input.meta}),
+  ...(Array.isArray(input.projects) && {projects: input.projects})
+  ```
+
+- [ ] **Step 16.2: Invalidate per-user cache on `projects` change**
+
+  In `updateUser`, after the write, detect whether `projects` was changed. If so, fire:
+
+  ```js
+  const cache = await import('./cache/index.js');
+  await cache.invalidateTags([`user:${userId}`]);
+  ```
+
+  (The `user:<id>` tag is what list endpoints in Tasks 17-25 will tag their cache entries with.)
+
+- [ ] **Step 16.3: Round-trip test**
+
+  Append to `tests/services/projects.test.js`:
+
+  ```js
+  import {createUser, getUserById, deleteUser} from '../../server/services/users.js';
+
+  test('users - meta.project + projects[] round-trip', async () => {
+      const email = 'meta-proj-' + Date.now() + '@test.local';
+      const user = await createUser({
+          name: 'T', email, password: 'longenoughpw',
+          role: 'user', meta: {project: 'members'}, projects: ['members']
+      });
+      try {
+          const fetched = await getUserById(user.id);
+          assert.equal(fetched?.meta?.project, 'members');
+          assert.deepEqual(fetched?.projects, ['members']);
+      } finally {
+          await deleteUser(user.id);
+      }
+  });
+  ```
+
+- [ ] **Step 16.4: Run the test**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: pass.
+
+---
+
+## Task 17: Page list URL inheritance via `getProjectForPage`
+
+**Files:**
+
+- Modify: `server/services/content.js`
+
+Pages already accept arbitrary frontmatter (parseMarkdown preserves `project:` automatically). For *list* endpoints we need the resolved project (via URL inheritance) attached to each page summary so the admin can filter and the sidebar can group.
+
+- [ ] **Step 17.1: Decorate page list summaries with resolved project**
+
+  In `server/services/content.js`, find `listPages` (or equivalent - `grep -n "listPages\|listAllPages" server/services/content.js`). After the list is built, decorate each entry:
+
+  ```js
+  const {getProjectForPage} = await import('./projects.js');
+  for (const page of pages) {
+      page.resolvedProject = await getProjectForPage(page.url || page.urlPath || '/', page.project);
+  }
+  ```
+
+  (`resolvedProject` is a runtime-computed field - not persisted to disk.)
+
+- [ ] **Step 17.2: Page-resolve test**
+
+  Append to `tests/services/projects.test.js`:
+
+  ```js
+  test('listPages decorates each entry with resolvedProject', async () => {
+      // This test is intentionally light - it just asserts the field exists
+      // on the returned shape. URL-inheritance correctness is covered by
+      // getProjectForPage's own tests above.
+      const {listPages} = await import('../../server/services/content.js');
+      const pages = await listPages();
+      if (!pages.length) return;
+      // Every page object should have `resolvedProject` (null or string)
+      for (const p of pages) {
+          assert.ok('resolvedProject' in p);
+      }
+  });
+  ```
+
+- [ ] **Step 17.3: Run the test**
+
+  Run: `node --test tests/services/projects.test.js`
+
+  Expected: pass.
+
+---
+
+## Task 18: Scaffolder integration - project block + meta.project stamping
+
+**Files:**
+
+- Modify: `server/services/scaffolder.js`
+- Create: `tests/services/projects-scaffolder.test.js`
+
+- [ ] **Step 18.1: Write the scaffolder test**
+
+  Create `tests/services/projects-scaffolder.test.js`:
+
+  ```js
+  /**
+   * Scaffolder + Projects integration - verify that applying a recipe with
+   * a `project` block creates the project record and stamps meta.project
+   * onto every produced artefact.
+   */
+  import {test} from 'node:test';
+  import assert from 'node:assert/strict';
+  import fs from 'fs/promises';
+  import path from 'path';
+  import {fileURLToPath} from 'url';
+  import {applyRecipe} from '../../server/services/scaffolder.js';
+  import {getProject, deleteProject} from '../../server/services/projects.js';
+  import {load as loadRoles} from '../../server/services/roles.js';
+
+  const __filename = fileURLToPath(import.meta.url);
+  const RECIPES_DIR = path.join(path.dirname(__filename), '..', '..', 'server', 'services', 'recipes');
+
+  await loadRoles();
+
+  test('applyRecipe with project block creates the project + stamps meta.project on menus', async () => {
+      const ns        = 'sproj-' + Date.now();
+      const recipePath = path.join(RECIPES_DIR, 'test-scaff-project.json');
+      const recipe = {
+          slug:    'test-scaff-project',
+          name:    'Test scaff project',
+          options: [{name: 'namespace', default: ns}],
+          project: {
+              name:        'Test Scaff Project',
+              description: 'recipe-created',
+              icon:        'box',
+              rootUrl:     '/{{namespace}}'
+          },
+          menus: [
+              {slug: '{{namespace}}-menu', name: 'Test menu', items: [{text: 'X', url: '/x'}]}
+          ]
+      };
+      await fs.writeFile(recipePath, JSON.stringify(recipe), 'utf8');
+      try {
+          const result = await applyRecipe('test-scaff-project', {options: {namespace: ns}});
+          // Project was created
+          const proj = await getProject(ns);
+          assert.ok(proj, 'project should exist');
+          assert.equal(proj.name, 'Test Scaff Project');
+          assert.equal(proj.rootUrl, '/' + ns);
+
+          // The menu was created with meta.project = namespace
+          assert.ok(result.created.menus.includes(ns + '-menu'));
+          const {getMenu, deleteMenu} = await import('../../server/services/menus.js');
+          const m = await getMenu(ns + '-menu');
+          assert.equal(m?.meta?.project, ns);
+          await deleteMenu(ns + '-menu');
+      } finally {
+          await deleteProject(ns).catch(() => {});
+          await fs.unlink(recipePath).catch(() => {});
+      }
+  });
+  ```
+
+- [ ] **Step 18.2: Run to confirm failure**
+
+  Run: `node --test tests/services/projects-scaffolder.test.js`
+
+  Expected: fails (project not auto-created; menu not tagged).
+
+- [ ] **Step 18.3: Implement project auto-create in scaffolder**
+
+  In `server/services/scaffolder.js`:
+
+  - Add imports near the existing imports:
+
+    ```js
+    import {getProject, createProject} from './projects.js';
+    ```
+
+  - In `applyRecipe`, AFTER the `resolveOptions` call and BEFORE preflight, add a project step:
+
+    ```js
+    // Project - auto-create if the recipe declares one and it doesn't exist.
+    let projectSlug = null;
+    if (resolved.project) {
+        projectSlug = tokens.namespace;
+        if (projectSlug && !(await getProject(projectSlug))) {
+            try {
+                await createProject({
+                    slug:        projectSlug,
+                    name:        resolved.project.name        || projectSlug,
+                    description: resolved.project.description || '',
+                    icon:        resolved.project.icon        || 'folder',
+                    rootUrl:     resolved.project.rootUrl     || undefined,
+                    sortOrder:   resolved.project.sortOrder
+                });
+            } catch (err) {
+                const e = new Error(`Cannot create project "${projectSlug}": ${err.message}`);
+                e.statusCode = 400;
+                throw e;
+            }
+        }
+    }
+    ```
+
+  - In the menus loop, modify the `createMenuFile` call to include `meta.project`:
+
+    ```js
+    await createMenuFile({
+        slug:        menu.slug,
+        name:        menu.name || menu.slug,
+        // ... existing fields ...
+        meta: {bundled: true, presetOwner: recipeSlug, ...(projectSlug && {project: projectSlug})}
+    });
+    ```
+
+  - In the collection creation block (`createCollection({...})`), add `meta: {project: projectSlug}` when `projectSlug` is set.
+
+  - In the form creation block, add `meta: {project: projectSlug}` to the form data passed to `writeForm`.
+
+  - In the action creation loop, add `meta: {project: projectSlug}` to each `createAction` payload.
+
+  - In the role creation loop, add `meta: {project: projectSlug}` to each `createRole` payload.
+
+  - In the user creation loop, add `meta: {project: projectSlug}` AND `projects: [projectSlug]` (so the seeded user can immediately log in and see only their project's artefacts):
+
+    ```js
+    await createUser({
+        name:            u.name || u.email,
+        // ... existing fields ...
+        ...(projectSlug && {meta: {project: projectSlug}, projects: [projectSlug]})
+    });
+    ```
+
+- [ ] **Step 18.4: Run the test**
+
+  Run: `node --test tests/services/projects-scaffolder.test.js`
+
+  Expected: pass.
+
+---
+
+## Task 19: Cross-service scope filtering - `canSeeArtefact` integration
+
+**Files:**
+
+- Modify: `server/routes/api/menus.js`
+- Modify: `server/routes/api/collections.js`
+- Modify: `server/routes/api/forms.js`
+- Modify: `server/routes/api/actions.js`
+- Modify: `server/routes/api/blocks.js`
+- Modify: `server/routes/api/views.js`
+- Modify: `server/routes/api/users.js`
+- Create: `tests/services/projects-scope.test.js`
+
+This task adds the scope filter to every list/get endpoint that returns artefacts. Each route uses the same one-line pattern.
+
+- [ ] **Step 19.1: Write the cross-service scope test**
+
+  Create `tests/services/projects-scope.test.js`:
+
+  ```js
+  /**
+   * Cross-service scope filtering - verify that listMenus, listForms, etc.
+   * are correctly filtered by canSeeArtefact when called via API.
+   * Service-layer functions return everything; route handlers apply the filter.
+   * This test exercises the routes via Fastify .inject.
+   */
+  import {test} 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 {createMenu, deleteMenu} from '../../server/services/menus.js';
+  import {load as loadRoles} from '../../server/services/roles.js';
+
+  await loadRoles();
+
+  async function buildWithUser(user) {
+      const app = Fastify();
+      app.register(fastifyJwt, {secret: 'test-secret-only-for-tests-32chars'});
+      const authenticate      = async (req) => { req.user = user; };
+      const requirePermission = () => async () => {};
+      await app.register(async (inst) => menusRoutes(inst, {authenticate, requirePermission}), {prefix: '/api'});
+      return app;
+  }
+
+  test('GET /api/menus filters by user.projects scope', async () => {
+      const taggedSlug   = 'scope-tagged-' + Date.now();
+      const untaggedSlug = 'scope-untagged-' + Date.now();
+      await createMenu({slug: taggedSlug, name: 'M', items: [], meta: {project: 'members'}});
+      await createMenu({slug: untaggedSlug, name: 'U', items: []});
+      try {
+          // Super-admin sees both
+          const sa = await buildWithUser({id: 'sa', role: 'super-admin'});
+          const r1 = await sa.inject({method: 'GET', url: '/api/menus'});
+          const slugs1 = r1.json().map(m => m.slug);
+          assert.ok(slugs1.includes(taggedSlug));
+          assert.ok(slugs1.includes(untaggedSlug));
+          await sa.close();
+
+          // Scoped user (not in 'members') sees only the untagged one
+          const scoped = await buildWithUser({id: 'u', role: 'admin', projects: ['intranet']});
+          const r2 = await scoped.inject({method: 'GET', url: '/api/menus'});
+          const slugs2 = r2.json().map(m => m.slug);
+          assert.equal(slugs2.includes(taggedSlug), false);
+          assert.ok(slugs2.includes(untaggedSlug));
+          await scoped.close();
+
+          // Scoped user IN 'members' sees both
+          const member = await buildWithUser({id: 'u', role: 'admin', projects: ['members']});
+          const r3 = await member.inject({method: 'GET', url: '/api/menus'});
+          const slugs3 = r3.json().map(m => m.slug);
+          assert.ok(slugs3.includes(taggedSlug));
+          assert.ok(slugs3.includes(untaggedSlug));
+          await member.close();
+      } finally {
+          await deleteMenu(taggedSlug);
+          await deleteMenu(untaggedSlug);
+      }
+  });
+  ```
+
+- [ ] **Step 19.2: Run to confirm failure**
+
+  Run: `node --test tests/services/projects-scope.test.js`
+
+  Expected: the scoped-user test fails (they currently see all menus).
+
+- [ ] **Step 19.3: Add scope filter to menus list endpoint**
+
+  In `server/routes/api/menus.js`, modify the `GET /menus` handler:
+
+  ```js
+  fastify.get('/menus', canRead, async (request) => {
+      const {canSeeArtefact} = await import('../../services/projects.js');
+      const all = await listMenus();
+      // Service returns metadata only - fetch full record per menu to get meta.project.
+      // For performance, fetch full once per slug.
+      const filtered = [];
+      for (const m of all) {
+          const full = await getMenu(m.slug);
+          if (canSeeArtefact(request.user, full)) filtered.push(m);
+      }
+      return filtered;
+  });
+  ```
+
+  Also gate `GET /menus/:slug` (return 403 if not visible):
+
+  ```js
+  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'});
+      const {canSeeArtefact} = await import('../../services/projects.js');
+      if (!canSeeArtefact(request.user, menu)) {
+          return reply.status(403).send({error: 'Access denied for this project'});
+      }
+      return menu;
+  });
+  ```
+
+- [ ] **Step 19.4: Verify menus filter test passes**
+
+  Run: `node --test tests/services/projects-scope.test.js`
+
+  Expected: pass.
+
+- [ ] **Step 19.5: Apply the same pattern to the other route modules**
+
+  Repeat Step 19.3's edits for each of these route files. Each file's `GET /<resource>` list handler and `GET /<resource>/:slug` get the same `canSeeArtefact` check:
+
+  - `server/routes/api/collections.js` - wrap `listCollections` results; gate `GET /collections/:slug`. Use `getCollection(slug)` to load the full record for filtering.
+  - `server/routes/api/forms.js` - `listForms` + `readForm`
+  - `server/routes/api/actions.js` - `listActions` directly returns full records, so just filter
+  - `server/routes/api/blocks.js` - `listBlocks` + `readBlock`
+  - `server/routes/api/views.js` - `listViews` directly returns full records
+  - `server/routes/api/users.js` - list path needs filtering; `meta.project` on each user
+
+  Each is the same one-import + one-filter pattern.
+
+- [ ] **Step 19.6: Verify nothing else broke**
+
+  Run: `node --test tests/services/ tests/routes/ 2>&1 | tail -10`
+
+  Expected: all pass.
+
+---
+
+## Task 20: Admin api.js client
+
+**Files:**
+
+- Modify: `admin/js/api.js`
+
+- [ ] **Step 20.1: Add projects client**
+
+  In `admin/js/api.js`, alongside the existing resource clients (after `menuLocations`), add:
+
+  ```js
+      // Projects
+      projects: {
+          list:        ()             => apiRequest('/projects', {method: 'GET'}),
+          get:         (slug)         => apiRequest(`/projects/${encodeURIComponent(slug)}`, {method: 'GET'}),
+          create:      (project)      => apiRequest('/projects', {method: 'POST', body: JSON.stringify(project)}),
+          update:      (slug, patch)  => apiRequest(`/projects/${encodeURIComponent(slug)}`, {method: 'PUT', body: JSON.stringify(patch)}),
+          remove:      (slug)         => apiRequest(`/projects/${encodeURIComponent(slug)}`, {method: 'DELETE'}),
+          artefacts:   (slug)         => apiRequest(`/projects/${encodeURIComponent(slug)}/artefacts`, {method: 'GET'}),
+          untagAll:    (slug)         => apiRequest(`/projects/${encodeURIComponent(slug)}/untag-all`, {method: 'POST'})
+      },
+  ```
+
+- [ ] **Step 20.2: Verify syntax**
+
+  Run: `node --check admin/js/api.js`
+
+  Expected: silent.
+
+---
+
+## Task 21: Sidebar - Projects section with lazy expansion
+
+**Files:**
+
+- Modify: `admin/js/config/sidebar-config.js`
+- Modify: `admin/js/app.js`
+- Modify: `admin/css/admin.css`
+
+The sidebar needs to dynamically load the user's visible projects on mount, then render each as an expandable group whose children load lazily on expand.
+
+- [ ] **Step 21.1: Update sidebar-config.js to accept projects + render the new section**
+
+  In `admin/js/config/sidebar-config.js`:
+
+  - Update the function signature to accept `projects`:
+
+    ```js
+    export function getSidebarConfig(permissions = [], counts = {}, pluginItems = [], projects = []) {
+        // ... existing ...
+    ```
+
+  - Add a new section AFTER the Overview group (which is currently the first item) and BEFORE the Plugins divider:
+
+    ```js
+        // Projects - appears between Overview and Plugins; only when user can see at least one
+        if (canAny('projects') && projects.length) {
+            items.push({heading: 'Projects'});
+            for (const p of projects) {
+                items.push({
+                    id:      'project-' + p.slug,
+                    text:    p.name,
+                    icon:    p.icon || 'folder',
+                    url:     '#/projects/' + encodeURIComponent(p.slug),
+                    section: '#/projects/' + encodeURIComponent(p.slug)
+                });
+            }
+            items.push({divider: true});
+        }
+    ```
+
+  Note: For v1, the Projects entries link to the Project detail page (`#/projects/:slug`) rather than rendering an expandable in-sidebar tree of artefact sub-types. Lazy artefact-count expansion is a follow-up. The Project detail page already shows all sub-types as tabs (Task 24), so the user experience is "click project, see everything" - one click instead of two.
+
+- [ ] **Step 21.2: Update app.js to fetch projects and pass them to the sidebar**
+
+  In `admin/js/app.js`, find `buildSidebar(permissions)` (around line 122). Update its signature and the parallel-fetch block:
+
+  ```js
+  async function buildSidebar(permissions) {
+      // ... existing ...
+      const [counts, dbStatus, siteSettings, projects] = await Promise.all([
+          fetchSidebarCounts(),
+          fetchDbStatus(),
+          isAuthenticated() ? api.settings.get().catch(() => ({})) : Promise.resolve({}),
+          permissions.includes('projects') || permissions.includes('projects.read')
+              ? api.projects.list().catch(() => [])
+              : Promise.resolve([])
+      ]);
+      // ... existing ...
+  ```
+
+  Find the `getSidebarConfig(permissions, counts, enrichedPluginItems)` call and update to pass `projects`:
+
+  ```js
+  items: getSidebarConfig(permissions, counts, enrichedPluginItems, projects),
+  ```
+
+- [ ] **Step 21.3: Verify syntax**
+
+  Run:
+  ```bash
+  node --check admin/js/config/sidebar-config.js
+  node --check admin/js/app.js
+  ```
+
+  Expected: silent.
+
+- [ ] **Step 21.4: Browser smoke test required**
+
+  State explicitly: a real browser load is required to confirm:
+  - The Projects section appears between Overview and Plugins
+  - Each project links to `#/projects/:slug`
+  - Section is suppressed when the user has no `projects.read` permission OR no visible projects
+
+---
+
+## Task 22: Admin route table - projects routes + placeholders
+
+**Files:**
+
+- Modify: `admin/js/app.js`
+- Modify: `admin/js/views/index.js`
+
+- [ ] **Step 22.1: Add the routes**
+
+  In `admin/js/app.js`, find the `coreRoutes` array. Add (alongside other resource routes):
+
+  ```js
+  { path: '/projects',                 view: 'projects',       title: 'Projects - Domma CMS' },
+  { path: '/projects/new',             view: 'projectEditor',  title: 'New Project - Domma CMS' },
+  { path: '/projects/edit/:slug',      view: 'projectEditor',  title: 'Edit Project - Domma CMS' },
+  { path: '/projects/:slug',           view: 'projectDetail',  title: 'Project - Domma CMS' },
+  ```
+
+- [ ] **Step 22.2: Add placeholder views in `admin/js/views/index.js`**
+
+  Add the three new view entries to the `views` object using placeholders that print a console warning:
+
+  ```js
+  views.projects        = {templateUrl: '', async onMount() { console.warn('[projects] projects view not yet implemented'); }};
+  views.projectEditor   = {templateUrl: '', async onMount() { console.warn('[projects] projectEditor view not yet implemented'); }};
+  views.projectDetail   = {templateUrl: '', async onMount() { console.warn('[projects] projectDetail view not yet implemented'); }};
+  ```
+
+  These are replaced by Tasks 23 + 24.
+
+- [ ] **Step 22.3: Verify syntax**
+
+  Run:
+  ```bash
+  node --check admin/js/app.js
+  node --check admin/js/views/index.js
+  ```
+
+  Expected: silent.
+
+---
+
+## Task 23: Projects list view + editor
+
+**Files:**
+
+- Create: `admin/js/views/projects.js`
+- Create: `admin/js/views/project-editor.js`
+- Create: `admin/js/templates/projects.html`
+- Create: `admin/js/templates/project-editor.html`
+- Modify: `admin/js/views/index.js`
+
+- [ ] **Step 23.1: Create the list template**
+
+  Create `admin/js/templates/projects.html`:
+
+  ```html
+  <div class="page-header">
+      <h2><span data-icon="folder"></span> Projects</h2>
+      <div class="header-actions">
+          <a class="btn btn-primary" href="#/projects/new"><span data-icon="plus"></span> New project</a>
+      </div>
+  </div>
+  <p class="text-muted">Group related artefacts under a project for navigation and per-user access scoping.</p>
+  <div id="projects-table"></div>
+  ```
+
+- [ ] **Step 23.2: Create the list view**
+
+  Create `admin/js/views/projects.js`:
+
+  ```js
+  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;');
+  }
+
+  export const projectsView = {
+      templateUrl: '/admin/js/templates/projects.html',
+      async onMount($container) {
+          const projects = await api.projects.list().catch(() => []);
+
+          // Fetch artefact counts in parallel for the badge
+          const counts = await Promise.all(projects.map(p =>
+              api.projects.artefacts(p.slug)
+                  .then(g => Object.values(g).reduce((sum, arr) => sum + arr.length, 0))
+                  .catch(() => 0)
+          ));
+          const rows = projects.map((p, i) => ({...p, artefactCount: counts[i]}));
+
+          T.create('#projects-table', {
+              data: rows,
+              emptyMessage: 'No projects yet. Click "New project" to create one.',
+              columns: [
+                  {key: 'slug',     title: 'Slug',     sortable: true},
+                  {key: 'name',     title: 'Name',     sortable: true},
+                  {key: 'icon',     title: 'Icon',     render: r => r.icon ? `<span data-icon="${esc(r.icon)}"></span>` : ''},
+                  {key: 'rootUrl',  title: 'Root URL', render: r => r.rootUrl ? `<code>${esc(r.rootUrl)}</code>` : '<span class="text-muted">-</span>'},
+                  {key: 'artefactCount', title: 'Artefacts', render: r => `<span class="badge badge-info">${r.artefactCount}</span>`},
+                  {key: '_actions', title: 'Actions', render: r => {
+                      const empty = r.artefactCount === 0;
+                      const delTip = empty ? '' : 'data-tooltip="Untag artefacts first or use the project detail page"';
+                      const delDisabled = empty ? '' : 'disabled';
+                      return `
+                          <a class="btn btn-sm btn-ghost" href="#/projects/${encodeURIComponent(r.slug)}"><span data-icon="eye"></span></a>
+                          <a class="btn btn-sm btn-ghost" href="#/projects/edit/${encodeURIComponent(r.slug)}"><span data-icon="edit"></span></a>
+                          <button class="btn btn-sm btn-danger btn-delete-project" data-slug="${esc(r.slug)}" ${delDisabled} ${delTip}><span data-icon="trash"></span></button>
+                      `;
+                  }}
+              ]
+          });
+
+          Domma.icons.scan('#projects-table');
+          document.querySelectorAll('#projects-table [data-tooltip]').forEach(el => {
+              E.tooltip(el, {content: el.getAttribute('data-tooltip'), position: 'top'});
+          });
+
+          $container.off('click', '.btn-delete-project').on('click', '.btn-delete-project', async function() {
+              if (this.disabled) return;
+              const slug = $(this).data('slug');
+              if (!await E.confirm(`Delete project "${slug}"? This cannot be undone.`)) return;
+              try {
+                  await api.projects.remove(slug);
+                  E.toast('Project deleted.', {type: 'success'});
+                  location.reload();
+              } catch (err) {
+                  E.toast(`Delete failed: ${err.message || err}`, {type: 'error'});
+              }
+          });
+      }
+  };
+  ```
+
+- [ ] **Step 23.3: Create the editor template**
+
+  Create `admin/js/templates/project-editor.html`:
+
+  ```html
+  <div class="page-header">
+      <h2><span data-icon="folder"></span> <span id="pe-title">Edit project</span></h2>
+      <div class="header-actions">
+          <a class="btn btn-secondary" href="#/projects"><span data-icon="arrow-left"></span> Back</a>
+          <button class="btn btn-primary" id="pe-save"><span data-icon="check"></span> Save</button>
+      </div>
+  </div>
+  <div id="pe-form"></div>
+  ```
+
+- [ ] **Step 23.4: Create the editor view**
+
+  Create `admin/js/views/project-editor.js`:
+
+  ```js
+  import {api} from '../api.js';
+
+  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;
+  }
+
+  export const projectEditorView = {
+      templateUrl: '/admin/js/templates/project-editor.html',
+      async onMount($container) {
+          const editMatch = location.hash.match(/^#\/projects\/edit\/(.+)$/);
+          const slug = editMatch ? decodeURIComponent(editMatch[1]) : null;
+          const isNew = !slug;
+
+          let project = {slug: '', name: '', description: '', icon: 'folder', rootUrl: '', sortOrder: 0};
+          if (!isNew) {
+              try {
+                  project = await api.projects.get(slug);
+              } catch (err) {
+                  E.toast(`Failed to load project: ${err.message || err}`, {type: 'error'});
+                  location.hash = '#/projects';
+                  return;
+              }
+          }
+
+          $container.find('#pe-title').text(isNew ? 'New project' : `Edit "${project.slug}"`);
+
+          const blueprint = {
+              slug:        {label: 'Slug',        type: 'text',     required: true, disabled: !isNew, hint: 'Lowercase alphanumeric + hyphen; immutable after create'},
+              name:        {label: 'Name',        type: 'text',     required: true},
+              description: {label: 'Description', type: 'textarea'},
+              icon:        {label: 'Icon',        type: 'text',     hint: 'Domma icon name; defaults to "folder"'},
+              rootUrl:     {label: 'Root URL',    type: 'text',     hint: 'URL prefix for auto-inheritance (e.g. "/members"); must start with /'},
+              sortOrder:   {label: 'Sort order',  type: 'number',   hint: 'Lower = higher in the sidebar'}
+          };
+          const values = {
+              slug:        project.slug || '',
+              name:        project.name || '',
+              description: project.description || '',
+              icon:        project.icon || 'folder',
+              rootUrl:     project.rootUrl || '',
+              sortOrder:   project.sortOrder ?? 0
+          };
+
+          const formEl = $container.find('#pe-form').get(0);
+          F.create(blueprint, values, {showSubmitButton: false}).renderTo(formEl);
+
+          $container.find('#pe-save').on('click', async () => {
+              const data = readForm(formEl, ['slug', 'name', 'description', 'icon', 'rootUrl', 'sortOrder']);
+              data.sortOrder = Number.parseInt(data.sortOrder, 10) || 0;
+              if (!data.rootUrl) delete data.rootUrl;
+
+              try {
+                  if (isNew) {
+                      await api.projects.create(data);
+                  } else {
+                      // Slug is immutable; drop it from the patch.
+                      const {slug: _drop, ...patch} = data;
+                      await api.projects.update(slug, patch);
+                  }
+                  E.toast('Saved.', {type: 'success'});
+                  location.hash = '#/projects';
+              } catch (err) {
+                  E.toast(`Save failed: ${err.message || err}`, {type: 'error'});
+              }
+          });
+      }
+  };
+  ```
+
+- [ ] **Step 23.5: Wire into views/index.js**
+
+  Replace the placeholders in `admin/js/views/index.js`:
+
+  ```js
+  views.projects      = (await import('./projects.js')).projectsView;
+  views.projectEditor = (await import('./project-editor.js')).projectEditorView;
+  ```
+
+  (Or use direct imports if that's the file's pattern. Match what menus did.)
+
+- [ ] **Step 23.6: Verify syntax**
+
+  Run:
+  ```bash
+  node --check admin/js/views/projects.js
+  node --check admin/js/views/project-editor.js
+  ```
+
+  Expected: silent.
+
+- [ ] **Step 23.7: Browser smoke test required**
+
+  State explicitly: real browser load required for `#/projects`, `#/projects/new`, `#/projects/edit/:slug`.
+
+---
+
+## Task 24: Project detail view with tabbed artefacts
+
+**Files:**
+
+- Create: `admin/js/views/project-detail.js`
+- Create: `admin/js/templates/project-detail.html`
+- Modify: `admin/js/views/index.js`
+
+- [ ] **Step 24.1: Template**
+
+  Create `admin/js/templates/project-detail.html`:
+
+  ```html
+  <div class="page-header">
+      <h2><span id="pd-icon" data-icon="folder"></span> <span id="pd-name">Project</span></h2>
+      <div class="header-actions">
+          <a class="btn btn-secondary" href="#/projects"><span data-icon="arrow-left"></span> Back</a>
+          <a class="btn btn-secondary" id="pd-edit"><span data-icon="edit"></span> Edit</a>
+      </div>
+  </div>
+  <p id="pd-desc" class="text-muted"></p>
+
+  <div class="tabs" id="pd-tabs">
+      <div class="tab-list">
+          <button class="tab-item active" data-tab="pd-overview">Overview</button>
+          <button class="tab-item" data-tab="pd-pages">Pages</button>
+          <button class="tab-item" data-tab="pd-collections">Collections</button>
+          <button class="tab-item" data-tab="pd-forms">Forms</button>
+          <button class="tab-item" data-tab="pd-actions">Actions</button>
+          <button class="tab-item" data-tab="pd-menus">Menus</button>
+          <button class="tab-item" data-tab="pd-blocks">Blocks</button>
+          <button class="tab-item" data-tab="pd-views">Views</button>
+          <button class="tab-item" data-tab="pd-roles">Roles</button>
+          <button class="tab-item" data-tab="pd-users">Users</button>
+          <button class="tab-item" data-tab="pd-settings">Settings</button>
+      </div>
+      <div class="tab-content">
+          <div class="tab-panel active" id="pd-overview"   data-panel="pd-overview"><div id="pd-overview-body"></div></div>
+          <div class="tab-panel"        id="pd-pages"      data-panel="pd-pages"><div id="pd-pages-list"></div></div>
+          <div class="tab-panel"        id="pd-collections" data-panel="pd-collections"><div id="pd-collections-list"></div></div>
+          <div class="tab-panel"        id="pd-forms"      data-panel="pd-forms"><div id="pd-forms-list"></div></div>
+          <div class="tab-panel"        id="pd-actions"    data-panel="pd-actions"><div id="pd-actions-list"></div></div>
+          <div class="tab-panel"        id="pd-menus"      data-panel="pd-menus"><div id="pd-menus-list"></div></div>
+          <div class="tab-panel"        id="pd-blocks"     data-panel="pd-blocks"><div id="pd-blocks-list"></div></div>
+          <div class="tab-panel"        id="pd-views"      data-panel="pd-views"><div id="pd-views-list"></div></div>
+          <div class="tab-panel"        id="pd-roles"      data-panel="pd-roles"><div id="pd-roles-list"></div></div>
+          <div class="tab-panel"        id="pd-users"      data-panel="pd-users"><div id="pd-users-list"></div></div>
+          <div class="tab-panel"        id="pd-settings"   data-panel="pd-settings"><div id="pd-settings-body"></div></div>
+      </div>
+  </div>
+  ```
+
+- [ ] **Step 24.2: View**
+
+  Create `admin/js/views/project-detail.js`:
+
+  ```js
+  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;');
+  }
+
+  function renderArtefactList(containerSelector, items, columns) {
+      if (!items.length) {
+          $(containerSelector).html('<p class="text-muted">No items in this project.</p>');
+          return;
+      }
+      T.create(containerSelector, {data: items, columns, emptyMessage: 'None'});
+  }
+
+  export const projectDetailView = {
+      templateUrl: '/admin/js/templates/project-detail.html',
+      async onMount($container) {
+          const m = location.hash.match(/^#\/projects\/([^/]+)$/);
+          const slug = m ? decodeURIComponent(m[1]) : null;
+          if (!slug) { location.hash = '#/projects'; return; }
+
+          const project = await api.projects.get(slug).catch(() => null);
+          if (!project) {
+              E.toast('Project not found.', {type: 'error'});
+              location.hash = '#/projects';
+              return;
+          }
+
+          $container.find('#pd-name').text(project.name);
+          $container.find('#pd-icon').attr('data-icon', project.icon || 'folder');
+          $container.find('#pd-desc').text(project.description || '');
+          $container.find('#pd-edit').attr('href', '#/projects/edit/' + encodeURIComponent(slug));
+          Domma.icons.scan($container.find('.page-header').get(0));
+
+          E.tabs($container.find('#pd-tabs').get(0));
+
+          const grouped = await api.projects.artefacts(slug).catch(() => ({}));
+
+          // Overview - counts grid
+          const overviewBody = $container.find('#pd-overview-body');
+          overviewBody.html(`
+              <div class="grid grid-cols-3" style="gap:1rem;">
+                  ${Object.entries(grouped).map(([type, arr]) =>
+                      `<div class="card"><div class="card-body"><strong>${type}</strong>: ${arr.length}</div></div>`
+                  ).join('')}
+              </div>
+          `);
+
+          // Per-type lists - simple slug+name tables with edit links
+          renderArtefactList('#pd-pages-list', grouped.pages || [], [
+              {key: 'url',   title: 'URL'},
+              {key: 'title', title: 'Title'}
+          ]);
+          renderArtefactList('#pd-collections-list', grouped.collections || [], [
+              {key: 'slug',  title: 'Slug'},
+              {key: 'title', title: 'Title'}
+          ]);
+          renderArtefactList('#pd-forms-list', grouped.forms || [], [
+              {key: 'slug',  title: 'Slug'},
+              {key: 'title', title: 'Title'}
+          ]);
+          renderArtefactList('#pd-actions-list', grouped.actions || [], [
+              {key: 'slug',  title: 'Slug'},
+              {key: 'title', title: 'Title'}
+          ]);
+          renderArtefactList('#pd-menus-list', grouped.menus || [], [
+              {key: 'slug', title: 'Slug'},
+              {key: 'name', title: 'Name'}
+          ]);
+          renderArtefactList('#pd-blocks-list', grouped.blocks || [], [
+              {key: 'slug', title: 'Slug'},
+              {key: 'name', title: 'Name'}
+          ]);
+          renderArtefactList('#pd-views-list', grouped.views || [], [
+              {key: 'slug', title: 'Slug'},
+              {key: 'name', title: 'Name'}
+          ]);
+          renderArtefactList('#pd-roles-list', grouped.roles || [], [
+              {key: 'name',  title: 'Name'},
+              {key: 'label', title: 'Label'}
+          ]);
+          renderArtefactList('#pd-users-list', grouped.users || [], [
+              {key: 'email', title: 'Email'},
+              {key: 'name',  title: 'Name'}
+          ]);
+
+          // Settings - reuse the editor form + danger zone
+          $container.find('#pd-settings-body').html(`
+              <div class="card"><div class="card-body">
+                  <h3>Settings</h3>
+                  <p>Edit project details on the <a href="#/projects/edit/${encodeURIComponent(slug)}">Edit page</a>.</p>
+              </div></div>
+              <div class="card" style="margin-top:1rem;border-color:#c33;"><div class="card-body">
+                  <h3>Danger zone</h3>
+                  <p>Untagging removes <code>meta.project</code> from every artefact currently tagged with "${esc(slug)}". The artefacts remain (un-tagged); the project record is unchanged.</p>
+                  <button class="btn btn-warning" id="pd-untag-all"><span data-icon="tag"></span> Untag all artefacts</button>
+                  <p style="margin-top:0.5rem;">Deleting the project is only possible when no artefacts are tagged.</p>
+                  <button class="btn btn-danger" id="pd-delete"><span data-icon="trash"></span> Delete project</button>
+              </div></div>
+          `);
+          Domma.icons.scan('#pd-settings-body');
+
+          $container.find('#pd-untag-all').on('click', async () => {
+              if (!await E.confirm(`Untag all artefacts from project "${slug}"? They will become site-wide.`)) return;
+              try {
+                  const res = await api.projects.untagAll(slug);
+                  E.toast(`Untagged: ${JSON.stringify(res.untagged)}`, {type: 'success'});
+                  setTimeout(() => location.reload(), 600);
+              } catch (err) {
+                  E.toast(`Failed: ${err.message || err}`, {type: 'error'});
+              }
+          });
+
+          $container.find('#pd-delete').on('click', async () => {
+              if (!await E.confirm(`Delete project "${slug}"? This refuses if any artefacts are still tagged.`)) return;
+              try {
+                  await api.projects.remove(slug);
+                  E.toast('Project deleted.', {type: 'success'});
+                  location.hash = '#/projects';
+              } catch (err) {
+                  E.toast(`Delete failed: ${err.message || err}`, {type: 'error'});
+              }
+          });
+      }
+  };
+  ```
+
+- [ ] **Step 24.3: Wire into views/index.js**
+
+  Replace the placeholder:
+
+  ```js
+  views.projectDetail = (await import('./project-detail.js')).projectDetailView;
+  ```
+
+- [ ] **Step 24.4: Verify syntax**
+
+  Run: `node --check admin/js/views/project-detail.js`
+
+  Expected: silent.
+
+- [ ] **Step 24.5: Browser smoke test required**
+
+  Real browser test for the tabbed view + danger zone actions.
+
+---
+
+## Task 25: Project field in artefact editors (menus, collections, forms, blocks, views, actions, roles)
+
+**Files:**
+
+- Modify: `admin/js/views/menu-editor.js`
+- Modify: `admin/js/views/collection-editor.js`
+- Modify: `admin/js/views/form-editor.js`
+- Modify: `admin/js/views/block-editor.js`
+- Modify: `admin/js/views/view-editor.js`
+- Modify: `admin/js/views/action-editor.js`
+- Modify: `admin/js/views/role-editor.js`
+
+The same one-field addition repeats across seven editors. Each gets a "Project" select in its Meta tab (or main form) that sets `meta.project` on save.
+
+- [ ] **Step 25.1: Add Project select to menu-editor.js**
+
+  In `admin/js/views/menu-editor.js`, find the Meta tab's F.create blueprint. Add `project` to the blueprint AFTER `description`:
+
+  ```js
+  project: {label: 'Project', type: 'select', options: [], hint: 'Group this menu under a project'},
+  ```
+
+  Before `F.create(...).renderTo(metaEl)`, fetch projects + populate the options:
+
+  ```js
+  const projects = await api.projects.list().catch(() => []);
+  metaBlueprint.project.options = [{value: '', label: '- none -'}].concat(
+      projects.map(p => ({value: p.slug, label: p.name}))
+  );
+  metaValues.project = menu.meta?.project || '';
+  ```
+
+  In the save handler, read the project value and stamp into `meta.project`:
+
+  ```js
+  const metaFormVals = readForm(metaEl, ['slug', 'name', 'description', 'project']);
+  next.meta = {
+      ...(menu.meta || {}),
+      ...(metaFormVals.project ? {project: metaFormVals.project} : {project: null})
+  };
+  // (Existing per-field assignment for slug/name/description still applies.)
+  ```
+
+- [ ] **Step 25.2: Apply the same pattern to the other six editors**
+
+  Repeat Step 25.1's three-edit pattern in:
+  - `admin/js/views/collection-editor.js`
+  - `admin/js/views/form-editor.js`
+  - `admin/js/views/block-editor.js`
+  - `admin/js/views/view-editor.js`
+  - `admin/js/views/action-editor.js`
+  - `admin/js/views/role-editor.js`
+
+  Each editor:
+  1. Fetch projects via `api.projects.list().catch(() => [])`
+  2. Add a `project` field to the F.create blueprint (or however that editor builds its form)
+  3. Populate options + value
+  4. On save, set `data.meta = {...(existing.meta || {}), project: <value or null>}`
+
+  If an editor doesn't have a Meta tab structure, add the Project select inline next to other settings.
+
+- [ ] **Step 25.3: Verify syntax across all seven**
+
+  Run:
+  ```bash
+  for f in admin/js/views/menu-editor.js admin/js/views/collection-editor.js admin/js/views/form-editor.js admin/js/views/block-editor.js admin/js/views/view-editor.js admin/js/views/action-editor.js admin/js/views/role-editor.js; do node --check "$f"; done
+  ```
+
+  Expected: silent for all seven.
+
+- [ ] **Step 25.4: Browser smoke test required**
+
+  Real browser load - open each editor and verify the Project select appears, defaults correctly, and saves the chosen value.
+
+---
+
+## Task 26: Page editor - Project select with URL-inheritance pre-fill
+
+**Files:**
+
+- Modify: `admin/js/views/page-editor.js`
+
+Pages are special because URL inheritance applies. The select has just `(none)` + project list - no `(auto)`. The pre-selected value is whatever `getProjectForPage(url, frontmatter.project)` resolves to.
+
+- [ ] **Step 26.1: Add the Project select**
+
+  In `admin/js/views/page-editor.js`, find the form blueprint or fields list. Add a `project` field in the same area as other frontmatter fields (visibility, status, etc.).
+
+  ```js
+  project: {label: 'Project', type: 'select', options: []}
+  ```
+
+  Fetch projects and populate options:
+
+  ```js
+  const projects = await api.projects.list().catch(() => []);
+  // Pre-selected value: existing frontmatter.project OR URL-inheritance resolution
+  let preProject = page.project ?? null;
+  if (preProject === undefined && page.url) {
+      // URL-inheritance resolution client-side
+      let bestSlug = '';
+      let bestLen = -1;
+      for (const p of projects) {
+          if (!p.rootUrl) continue;
+          if (page.url === p.rootUrl || page.url.startsWith(p.rootUrl + '/')) {
+              if (p.rootUrl.length > bestLen) { bestSlug = p.slug; bestLen = p.rootUrl.length; }
+          }
+      }
+      preProject = bestSlug;
+  }
+  blueprint.project.options = [{value: '', label: '- none -'}].concat(
+      projects.map(p => ({value: p.slug, label: p.name}))
+  );
+  values.project = preProject || '';
+  ```
+
+  On save, write the explicit `project:` frontmatter:
+
+  ```js
+  if (formVals.project) {
+      payload.project = formVals.project;
+  } else {
+      // Empty selection - explicit null to opt out of URL inheritance
+      payload.project = null;
+  }
+  ```
+
+- [ ] **Step 26.2: Verify syntax**
+
+  Run: `node --check admin/js/views/page-editor.js`
+
+  Expected: silent.
+
+- [ ] **Step 26.3: Browser smoke test required**
+
+  Real browser test - open a page editor for a page under a project's `rootUrl`, verify the Project select is pre-selected.
+
+---
+
+## Task 27: User editor - `projects: []` + `meta.project`
+
+**Files:**
+
+- Modify: `admin/js/views/user-editor.js`
+
+- [ ] **Step 27.1: Add the two new fields**
+
+  In `admin/js/views/user-editor.js`, locate the form blueprint. Add:
+
+  ```js
+  metaProject: {label: 'Owned by project', type: 'select', options: [], hint: 'Where this user appears in the sidebar'},
+  projects:    {label: 'Project access',   type: 'multiselect', options: [], hint: 'Leave empty for no restriction'}
+  ```
+
+  Fetch projects and populate both:
+
+  ```js
+  const projects = await api.projects.list().catch(() => []);
+  blueprint.metaProject.options = [{value: '', label: '- none -'}].concat(
+      projects.map(p => ({value: p.slug, label: p.name}))
+  );
+  blueprint.projects.options = projects.map(p => ({value: p.slug, label: p.name}));
+  values.metaProject = user.meta?.project || '';
+  values.projects    = Array.isArray(user.projects) ? user.projects : [];
+  ```
+
+  On save:
+
+  ```js
+  payload.meta = {
+      ...(user.meta || {}),
+      ...(formVals.metaProject ? {project: formVals.metaProject} : {project: null})
+  };
+  // multiselect returns an array directly; if it's a single string, normalise
+  payload.projects = Array.isArray(formVals.projects) ? formVals.projects : [formVals.projects].filter(Boolean);
+  ```
+
+  If Domma's `F.create` doesn't have a native `multiselect` type, use a comma-separated `text` field with a hint and parse on save. Verify by reading what `multiselect` accepts in this codebase (`grep -n "type: 'multiselect'" admin/js/views/`).
+
+- [ ] **Step 27.2: Verify syntax**
+
+  Run: `node --check admin/js/views/user-editor.js`
+
+  Expected: silent.
+
+- [ ] **Step 27.3: Browser smoke test required**
+
+  Real browser test - open a user editor, verify both Project fields work.
+
+---
+
+## Task 28: Documentation updates
+
+**Files:**
+
+- Modify: `docs/configuration.md`
+- Modify: `docs/scaffolding.md`
+- Modify: `docs/api-reference.md`
+- Modify: `CLAUDE.md`
+
+- [ ] **Step 28.1: Update `docs/configuration.md`**
+
+  Add a new top-level section `## Projects` after the existing Menus section. Document:
+
+  - The `content/collections/projects/` storage (entry shape from the spec)
+  - The `meta.project` field on each of the nine in-scope artefact types
+  - The `rootUrl` URL-inheritance rule
+  - The user `projects: []` access-scope field + `meta.project` ownership distinction
+  - That permissions don't auto-grant - admin must enable `projects.read` for existing roles (same gotcha as Menus)
+
+- [ ] **Step 28.2: Update `docs/scaffolding.md`**
+
+  Add a section on the recipe `project: {name, description, icon, rootUrl}` block. Document that:
+  - `tokens.namespace` becomes the project slug
+  - The project is created if missing on apply (idempotent)
+  - Every produced artefact gets `meta.project` stamped
+  - Seeded users additionally get `projects: ['<namespace>']` on their access scope
+
+- [ ] **Step 28.3: Update `docs/api-reference.md`**
+
+  Add the `/api/projects/*` endpoints with request/response shapes from the spec.
+
+- [ ] **Step 28.4: Update project `CLAUDE.md`**
+
+  Append a `## Projects` section summarising:
+  - Data model: preset collection at `content/collections/projects/`, `meta.project` tag on nine artefact types
+  - URL inheritance rule + the three-way frontmatter semantics (`project: null` opts out; `project: '<slug>'` explicit; missing field falls through to URL match)
+  - `user.projects: []` access scope semantics + super-admin bypass
+  - Cross-cutting nature (touches 9 services)
+
+---
+
+## Task 29: Final verification + handoff
+
+**Files:** none (verification only)
+
+- [ ] **Step 29.1: Run the full feature test suite**
+
+  Run:
+  ```bash
+  node --test tests/services/projects.test.js \
+      tests/services/projects-scope.test.js \
+      tests/services/projects-scaffolder.test.js \
+      tests/routes/projects.test.js \
+      tests/services/menus.test.js \
+      tests/routes/menus.test.js \
+      tests/services/scaffolder.test.js \
+      tests/services/visibility.test.js
+  ```
+
+  Expected: all pass.
+
+- [ ] **Step 29.2: Curl smoke test on the running server**
+
+  Server must have been restarted after Tasks 8 + 18. The user controls restarts.
+
+  ```bash
+  curl -s -o /dev/null -w "GET /api/projects: %{http_code}\n" http://localhost:4096/api/projects
+  ```
+
+  Expected: 401 (auth-gated, route registered).
+
+- [ ] **Step 29.3: Live browser walkthrough**
+
+  Hard-refresh the admin SPA. Walk through:
+
+  1. After granting `projects` permission to your role (Users → Roles → super-admin → add `projects`), the Projects sidebar section appears (empty until you create one).
+  2. `#/projects/new` → create a project (e.g. slug=`demo`, rootUrl=`/demo`).
+  3. Sidebar refreshes → Projects section shows `demo`.
+  4. Open the Menu editor for `main`; set Project = `demo`; save.
+  5. `#/projects/demo` → the Menus tab lists `main`; Overview shows counts.
+  6. User editor → set `projects: ['demo']` on a non-super-admin user; log in as them; they only see `demo` artefacts.
+  7. Scaffolder: apply a recipe (Onboarding or any) - if it has a `project` block in the recipe JSON, the project auto-creates.
+  8. Settings → Untag all → confirm the menu becomes untagged again.
+  9. Delete the project - succeeds when no tagged artefacts remain.
+
+  Per memory `feedback_no_verified_without_browser.md`, surface this as a real limit if you cannot drive the browser yourself.
+
+- [ ] **Step 29.4: Hand off**
+
+  Do NOT commit. Summarise the changes and let the user commit. Suggested commit message:
+
+  > Projects feature - grouping artefacts under named projects with sidebar navigation, per-user permission scoping (user.projects[]), URL inheritance for pages, and scaffolder integration (recipe project block auto-creates + stamps meta.project across 9 artefact types).