domma-cms 1.6.60 → 1.7.0

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

@@ -0,0 +1,380 @@
+# Projects Design
+
+**Date:** 2026-05-25
+**Status:** Approved
+**Scope:** Introduce Projects - a lightweight grouping of related artefacts (Pages, Collections, Forms, Actions, Menus, Blocks, Views, Roles, Users) with sidebar-level navigation, per-user permission scoping, and tight integration with the scaffolder so a recipe-applied "members area" becomes a navigable Project the moment it's installed.
+
+## Problem
+
+The CMS produces a growing set of artefact types. A scaffolder recipe like Onboarding installs a Collection, a Form, three Actions, optionally a Menu, and (after this feature) Roles and Users. Today those artefacts land in eight different admin sidebar locations (Collections, Forms, Actions, Menus, Roles, Users…), grouped by *type*, not by *purpose*. An editor who wants to "work on the members site" has to traverse every resource type, mentally filtering for the items whose slug starts with `members-`.
+
+There's also no notion of "this user works on the members project, not the intranet". Every editor sees every artefact subject only to their role. Multi-tenant-style scoping is impossible.
+
+The scaffolder's existing `namespace` option is the kernel of a solution: every recipe-produced artefact already shares a slug prefix. We can turn that prefix into a first-class *Project* - both a navigation grouping (every artefact for project X in one sidebar section) and a permission boundary (a user can be scoped to a list of projects).
+
+## Goals
+
+- Group recipe-produced artefacts under a named Project; sidebar shows each Project as an expandable section with its scoped sub-items.
+- Allow manual creation/editing of Projects (not only via recipes).
+- Scope users to one or more Projects so they only see/edit their assigned Projects' artefacts plus untagged site-wide artefacts.
+- Auto-create a Project on recipe apply when the recipe declares a `project` block.
+- Auto-inherit a Project on pages whose URL falls under the Project's `rootUrl` prefix.
+- Preserve the existing flat resource-typed sidebar groups for cross-project browsing - Projects is *additive*, not a replacement.
+- Zero auto-migration of existing artefacts - they stay untagged and continue to appear in the existing sections.
+
+## Non-Goals (YAGNI)
+
+- Project rename (slug change). Requires updating every tagged artefact and is rare. Workaround: delete + recreate with new slug + bulk re-tag.
+- Nested Projects (sub-projects).
+- Project-scoped permissions on individual artefacts (e.g. "this collection is private to a subset of Members users"). Scope is at the Project membership level; per-artefact access uses the existing role-permission system.
+- Cross-site Project distribution. Recipes are the distribution unit (and export-as-recipe is a tracked follow-up).
+- Project-scoped media library. Media stays site-wide.
+- Filesystem isolation (each Project in its own subdirectory). Tag-based membership is sufficient and keeps existing paths stable.
+
+## Data Model
+
+### Project record
+
+Projects live in a **preset collection** at `content/collections/projects/` - same pattern as `user-types` and `roles`. This gives CRUD UI, validation, and permission integration for free.
+
+```json
+{
+  "slug":        "members",
+  "name":        "Members Area",
+  "description": "Curated members-only zone with profile, billing, and content.",
+  "icon":        "users",
+  "rootUrl":     "/members",
+  "sortOrder":   10,
+  "createdAt":   "2026-05-25T10:00:00Z",
+  "updatedAt":   "2026-05-25T10:00:00Z"
+}
+```
+
+| Field | Required | Type | Description |
+|---|---|---|---|
+| `slug` | yes | string | URL-safe identifier; matches `^[a-z0-9][a-z0-9-]*$`; used as the value of `meta.project` on tagged artefacts; immutable after create |
+| `name` | yes | string | Human-readable; sidebar label |
+| `description` | no | string | Free text |
+| `icon` | no | string | Sidebar icon (Domma icon name); defaults to `folder` |
+| `rootUrl` | no | string | URL prefix (must start with `/`); enables page auto-inheritance |
+| `sortOrder` | no | number | Sidebar order; default = creation order |
+
+### Artefact-side `meta.project` field
+
+Nine artefact types gain an optional `meta.project: '<slug>'` field. The field is informational - it declares "this artefact lives in this Project" for the purposes of sidebar grouping and permission scoping. Existing files without the field stay site-wide (visible in the standard Content/Data/Structure sections, not in any Project section).
+
+| Type | Where `meta.project` lives | Notes |
+|---|---|---|
+| **Pages** | YAML frontmatter `project:` | Auto-inherited from URL prefix when project has `rootUrl` set (see "URL inheritance" below) |
+| **Collections** | `schema.json` top-level `meta.project` | All entries inherit the schema's project |
+| **Forms** | Form JSON top-level `meta.project` | |
+| **Actions** | Mongo doc `meta.project` | |
+| **Menus** | `meta.project` (alongside existing `meta.bundled`, `meta.presetOwner`) | The Menus `meta` block from spec 2026-05-24 already accepts unknown keys; we extend it |
+| **Blocks** | Block JSON top-level `meta.project` | |
+| **Views** | View JSON top-level `meta.project` | |
+| **Roles** | Role entry `data.meta.project` (collection entry meta) | |
+| **Users** | User JSON `meta.project` + access-scope `projects: []` (see "Permission scoping" below) | Two fields, different jobs |
+
+### Page URL inheritance
+
+When a page is loaded the project is determined in this order:
+
+1. If frontmatter has `project: null` → explicit opt-out; page is untagged regardless of URL.
+2. If frontmatter has `project: '<slug>'` → use it (explicit override).
+3. Else (`project:` field missing entirely), look up the project whose `rootUrl` is the longest prefix match of the page's URL → use that.
+4. Else, page is untagged (site-wide).
+
+Example: project `members` has `rootUrl: '/members'`. Page at `/members/profile.md` without a `project:` frontmatter is implicitly in `members`. Page at `/about.md` is untagged. Page at `/members/admin.md` with explicit `project: 'staff'` overrides the auto-match.
+
+Multiple projects with overlapping prefixes: longest match wins. If two prefixes tie, alphabetical-by-slug wins (deterministic).
+
+The resolver `getProjectForPage(urlPath, frontmatterProject)` is the single source of truth and is called from every page-load path (renderer, sidebar, API list endpoints).
+
+### Permission scoping
+
+Users gain a new optional field `projects: ['<slug>', ...]` - the *access scope*. Distinct from `meta.project` on the user record (the *administrative ownership* - where the user appears in the sidebar). Most of the time both hold the same single value, but they can diverge (a recruiter user owned by the `members` project might be granted access to `members` + `intranet`).
+
+**Access rule** (enforced in API route guards, sidebar render, and list/get endpoints):
+
+```js
+function canSeeArtefact(user, artefact) {
+    if (isSuperAdmin(user)) return true;                          // bypass
+    const project = artefact.meta?.project;
+    if (!project) return true;                                    // untagged = site-wide
+    if (!user.projects || user.projects.length === 0) return true; // no scope = no restriction
+    return user.projects.includes(project);
+}
+```
+
+Applied to:
+- List endpoints (filter results)
+- Get endpoints (return 403 instead of the artefact)
+- Write endpoints (refuse with 403)
+- Sidebar render (filter the Projects section to projects the user can see, and filter the standard resource sections to artefacts the user can see)
+
+Notes:
+- **Empty `projects: []` = no restriction.** A user with no scope set sees everything (subject to role).
+- **Super-admins bypass entirely.** Even if their `projects` field is set, they see all projects.
+- **Untagged artefacts are always visible** to anyone with the relevant role permission. This matches the mental model of "site-wide things are always visible; project things are filtered".
+- **`meta.project` on the user record is administrative metadata.** It tells the sidebar where to file this user under the Project view. The `projects: []` array is the access enforcement field. They can hold different values.
+
+## Server-side Services
+
+### `server/services/projects.js` (new)
+
+| Export | Description |
+|---|---|
+| `listProjects()` | All projects (no filtering) - for admin lookups |
+| `listProjectsForUser(user)` | Projects the user can see (super-admin sees all; scoped users see their scope) |
+| `getProject(slug)` | Returns the project record or `null` |
+| `createProject(input)` | Validates + writes; refuses on slug collision |
+| `updateProject(slug, input)` | Slug immutable; other fields editable |
+| `deleteProject(slug)` | Refuses if any tagged artefacts exist (409 with breakdown); otherwise deletes the project entry |
+| `getProjectForPage(urlPath, frontmatterProject)` | Resolves a page's project per the URL-inheritance rules |
+| `untagAllForProject(slug)` | Escape hatch - sets `meta.project: null` on every artefact currently tagged with the slug |
+| `getArtefactsForProject(slug)` | Returns all artefacts grouped by type - used by sidebar + project detail page |
+| `canSeeArtefact(user, artefact)` | Permission check used by API routes + sidebar |
+
+The collection is seeded with no entries on first run (a fresh CMS has no projects).
+
+### Validation
+
+- `slug` matches `^[a-z0-9][a-z0-9-]*$` (mirrors collection slug + menu slug rules)
+- `name` non-empty string
+- `rootUrl`, when set, must start with `/` and not be just `/` (the root URL `/` would auto-claim every page - clearly wrong; refuse it)
+- `icon` (when set) is a non-empty string
+
+## Server-side Integration Points
+
+Each artefact's service is touched to:
+1. **Read** the `meta.project` field (no validation - it's an opt-in informational tag).
+2. **Filter** lists by `canSeeArtefact(user, artefact)`.
+3. **Pass** `meta.project` through create/update calls without losing it.
+
+Concretely:
+
+| Service | Change |
+|---|---|
+| `server/services/pages.js` (via `content.js`) | `parseMarkdown` already passes frontmatter through; loader resolves project from URL or frontmatter; list endpoints filter |
+| `server/services/collections.js` | `createCollection` accepts `meta.project`; `listCollections` filters by user scope |
+| `server/services/forms.js` | `writeForm`/`readForm` preserve `meta`; `listForms` filters |
+| `server/services/actions.js` | `createAction` accepts `meta.project`; `listActions` filters |
+| `server/services/menus.js` | `meta.project` flows through `createMenu`/`updateMenu` (already accepts arbitrary `meta` keys); `listMenus` filters |
+| `server/services/blocks.js` | `meta.project` on the block JSON; list filter |
+| `server/services/views.js` | `meta.project` on the view JSON; list filter |
+| `server/services/roles.js` | Role collection entries gain `data.meta.project`; list filter on the Roles admin |
+| `server/services/users.js` | User JSON gains `meta.project` + access-scope `projects: []`; list filter on Users admin |
+
+In every list path, the filter is a single call:
+
+```js
+const visible = list.filter(item => canSeeArtefact(user, item));
+```
+
+## API Surface
+
+`server/routes/api/projects.js` (new), registered from `server/server.js`.
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| `GET` | `/api/projects` | `projects.read` | List projects the user can see |
+| `GET` | `/api/projects/:slug` | `projects.read` | Project details |
+| `POST` | `/api/projects` | `projects.create` | Create a project |
+| `PUT` | `/api/projects/:slug` | `projects.update` | Edit (slug immutable) |
+| `DELETE` | `/api/projects/:slug` | `projects.delete` | Delete (409 if any artefacts tagged; body lists the count by type) |
+| `GET` | `/api/projects/:slug/artefacts` | `projects.read` | All artefacts grouped by type - used by sidebar + project detail |
+| `POST` | `/api/projects/:slug/untag-all` | `projects.delete` | Set `meta.project: null` on every tagged artefact (escape hatch before delete) |
+
+### Permissions
+
+New family `projects.{read, create, update, delete}` added to `server/services/permissionRegistry.js`. Defaults (admin-edited via the Users → Roles editor after seeding):
+
+| Role | read | create | update | delete |
+|---|:---:|:---:|:---:|:---:|
+| user | ❌ | ❌ | ❌ | ❌ |
+| admin | ✅ | ✅ | ✅ | ❌ |
+| super-admin | ✅ | ✅ | ✅ | ✅ |
+
+(Existing roles are not back-filled automatically - same gotcha as the menus permission. The admin grants `projects` to existing roles via the role editor.)
+
+## Scaffolder Integration
+
+`server/services/scaffolder.js` gains a project-aware apply step BEFORE any artefact creation:
+
+1. Resolve `tokens.namespace` from the recipe options. (This already exists - the namespace cascades into every artefact's slug.)
+2. If the recipe has a `project` block AND no project with that slug exists → create the project record using `namespace` as the slug and the recipe's name/description/icon/rootUrl.
+3. If a project with that slug exists already → leave it alone (idempotent - re-applying a recipe does not clobber edits to the project record).
+4. Pass the project slug through to every artefact-creation call so each created file gets `meta.project: <namespace>` stamped on it.
+
+Recipe shape (additive; backwards compatible):
+
+```json
+{
+  "slug":    "members-area",
+  "name":    "Members Area",
+  "options": [{"name": "namespace", "default": "members"}],
+  "project": {
+    "name":        "Members Area",
+    "description": "Members-only zone",
+    "icon":        "users",
+    "rootUrl":     "/{{namespace}}"
+  },
+  "collection": { ... },
+  "form":       { ... },
+  "actions":    [ ... ],
+  "menus":      [ ... ]
+}
+```
+
+Recipes that don't define a `project` block still work - they produce untagged artefacts (existing behaviour). Recipes that DO define one but where the project record creation fails (validation error, write error) abort the whole apply with a clear error message before any artefact is written.
+
+The scaffolder's existing seeded artefacts - collections, forms, actions, menus, roles, users - all get `meta.project` stamped when a project is in play. Seeded **users** additionally get `projects: ['<namespace>']` set on their access-scope field, so a recipe-seeded HR user can immediately log in and see only the project they were created for.
+
+## Admin UI
+
+### Sidebar - new Projects section
+
+A new top-level **Projects** group is inserted immediately below the Overview group (Dashboard stays first in the sidebar). It renders only when at least one project exists AND the current user can see at least one project (`listProjectsForUser(user).length > 0`).
+
+Each project appears as a collapsible expander:
+
+```
+▾ Members              ← project (icon + name)
+    Pages (3)          ← sub-item per artefact type
+    Collections (2)
+    Forms (1)
+    Actions (3)
+    Menus (1)
+    Blocks (0)         ← suppressed when empty
+    Views (0)
+    Roles (1)
+    Users (2)
+▸ Intranet             ← collapsed
+```
+
+Behaviour:
+- Sub-items only render when the project has at least one of that type. The empty rows (`Blocks (0)`) above are illustrative - they're filtered out at render time.
+- Each sub-item is a link to the standard list view for that type, filtered by project: e.g. `#/projects/members/collections`, which reuses the Collections list view with a `project=members` filter.
+- Expansion state persists per project in `S.set('sidebar.project.<slug>.expanded', bool)`.
+- Counts are loaded **lazily** when the project is first expanded - not on initial sidebar mount. The counts come from `/api/projects/:slug/artefacts`.
+- Project order follows `sortOrder` ascending, then `name` alphabetical for ties.
+
+The standard Content/Data/Structure sections stay below the Projects section. They render artefacts the user can see (super-admin: everything; scoped user: their projects' artefacts + untagged).
+
+### `#/projects` - list view
+
+`T.create` table:
+
+| Column | Content |
+|---|---|
+| Slug | Project slug |
+| Name | Human-readable |
+| Icon | Rendered icon |
+| Root URL | The URL prefix (linked) |
+| Artefacts | Total count badge |
+| Actions | Edit · Delete (disabled with tooltip if non-empty) |
+
+Top-right toolbar: "New project" button.
+
+### `#/projects/new` and `#/projects/edit/:slug`
+
+Single form built with `F.create(blueprint, values, options).renderTo(el)`:
+
+| Field | Type | Notes |
+|---|---|---|
+| `slug` | text | Required; disabled on edit |
+| `name` | text | Required |
+| `description` | textarea | Optional |
+| `icon` | text | Optional; defaults to `folder` |
+| `rootUrl` | text | Optional; must start with `/` if set |
+| `sortOrder` | number | Optional; defaults to `0` |
+
+Save → `POST /api/projects` (new) or `PUT /api/projects/:slug` (edit). Redirect to `#/projects` on success with a toast.
+
+### `#/projects/:slug` - project detail
+
+Tabbed view (`E.tabs` with the verified `.tabs / .tab-list / button.tab-item / .tab-panel` classes):
+
+| Tab | Content |
+|---|---|
+| Overview | Project name + description + artefact counts + a "Recent activity" list (latest 10 artefacts changed by anyone) |
+| Pages | Standard pages list, filtered to this project |
+| Collections | Standard collections list, filtered |
+| Forms | Standard forms list, filtered |
+| Actions | Standard actions list, filtered |
+| Menus | Standard menus list, filtered |
+| Blocks | Standard blocks list, filtered |
+| Views | Standard views list, filtered |
+| Roles | Roles whose `meta.project` matches |
+| Users | Users whose `meta.project` matches |
+| Settings | Same fields as the editor + "Untag all artefacts" and "Delete project" buttons |
+
+The standard list views are reused - no duplicate UI. They accept an optional `project` filter parameter (passed via route params).
+
+### Project field in existing artefact editors
+
+Every in-scope artefact editor (Page editor, Collection editor, Form editor, etc.) gains a "Project" select in its Meta tab. Options: `(none)` + every project the current user can see. Defaults to `(none)` for new artefacts unless the editor was opened from a project-scoped sidebar entry (in which case the project is pre-selected from the URL).
+
+For Pages, the select has two states:
+
+- **`(none)`** - page is untagged. Writes `project: null` to frontmatter.
+- **`<slug>`** - explicit project. Writes `project: <slug>` to frontmatter.
+
+The selector defaults to whatever the URL-inheritance rule resolves to on first load - so an admin editing a page at `/members/profile.md` for the first time sees `Members` pre-selected. Once they Save, the explicit value is written. The dropdown has no hidden magic - what you see is what's persisted.
+
+URL inheritance still applies to pages with no `project:` field in frontmatter (pre-existing pages, hand-edited pages). The dropdown writes explicit values forward; the resolver passively fills in missing values for backwards compatibility.
+
+### User editor - project access field
+
+The User editor gains a multi-select "Project access" field listing every project. Empty = no restriction. Recipe-seeded users have it pre-populated. Stored in the user JSON as `projects: ['<slug>', ...]`.
+
+The User editor also gains the administrative `meta.project` field as a separate single-select (`(none)` + projects). This is the field used by the sidebar to file the user under a project. Most users have both fields set to the same single project; the UI shows them in distinct sections (Access vs Ownership) with a one-line explanation.
+
+## Caching
+
+New cache tags:
+
+| Tag | Invalidated when |
+|---|---|
+| `project:<slug>` | Project record changed, OR any artefact's `meta.project` is set/changed to this slug |
+| `projects` | Project list changed (create/delete) |
+
+Existing artefact tags (`page:`, `nav`, `menu:<slug>`, etc.) gain a sibling tag `project:<artefact's project>` when the artefact is tagged, so a project rename or settings change can flush dependent pages without enumerating them.
+
+**User-scope changes invalidate per-user cache entries.** When a user's `projects: []` array is edited, an explicit `cache.invalidateTags(['user:<id>'])` fires from the user-update path. The renderer's existing per-role cache key isn't sufficient on its own (JWTs are long-lived; the user's session continues with the same token after a scope change), so we add a per-user tag to caches that contain user-scoped filtering. List/get endpoints that filter by `canSeeArtefact` write entries tagged with both the artefact's `project:` tag and the requesting user's `user:<id>` tag; either invalidation tag flushes the entry.
+
+**Operational note - cache cardinality.** Per-user tagging multiplies cache entry count by the number of distinct scoped users hitting an endpoint. For a 10-user team this is negligible; for a multi-hundred-user install where scoped users have varying `projects: []` arrays, the memory driver may evict entries faster than they're useful. If cache hit ratio degrades, the v2 mitigation is a short-circuit: scoped users skip the cache entirely (`if (user.projects?.length) skipCache = true`), trading a small per-request render cost for a hard guarantee against scope leak. v1 ships with the tagging approach because small-to-medium installs are the common case.
+
+Public page rendering is unaffected - visitor users have no `projects` scope (they're either anonymous or have a public role) and the per-role cache key already covers them.
+
+## Retrofit / Migration Policy
+
+- **No auto-migration.** Existing artefacts stay untagged. They render in the standard Content/Data/Structure sections, invisible to the Projects section. Site keeps working unchanged.
+- **Manual retrofit available.** Admins open any artefact and set the Project field one at a time. (Bulk "Move N items to project" is a tracked follow-up - see Open Follow-Ups.)
+- **Scaffolder-created artefacts from this release forward** carry the project tag automatically.
+- **The Menus created in the 2026-05-24 release** (`main`, `footer`) stay untagged - they're cross-project site-wide menus and shouldn't be claimed by any project.
+
+## Documentation Updates
+
+- `docs/configuration.md` - add a "Projects" section documenting the `content/collections/projects/` shape, the `meta.project` field on each in-scope artefact, the `rootUrl` inheritance rules, and the user `projects: []` access scope.
+- `docs/scaffolding.md` - document the recipe `project: {...}` block and how `meta.project` is stamped onto recipe-produced artefacts. Cross-link from the existing namespace explanation.
+- `docs/api-reference.md` - add the `/api/projects/*` endpoints with request/response shapes.
+- `CLAUDE.md` (project) - add a "Projects" section summarising the data model, the URL-inheritance rule, and the per-user `projects: []` access-scope semantics. Note the cross-cutting nature (touches 9 services).
+
+## Out of Scope (Recorded for Later)
+
+- **Project rename** (slug change). Workaround: delete + recreate + bulk re-tag.
+- **Nested Projects.**
+- **Per-artefact project scoping** beyond the project membership level.
+- **Cross-site Project distribution.** Recipes are the distribution unit.
+- **Project-scoped media library.**
+- **Filesystem isolation.** Tag-based.
+- **Project-level analytics dashboards.** Future feature once the data model lands.
+
+## Open Follow-Ups (Tracked)
+
+- **Export Project as recipe.** Given a project, emit a recipe JSON that recreates it artefact-for-artefact. Pairs with the scaffolder. The killer feature for multi-site distribution and templates marketplaces.
+- **Bulk move/re-tag UI.** Some artefact lists already support multi-select; wiring "Move N items to Project X" is a small follow-up.
+- **Project archive.** Soft-delete that hides a project from the sidebar without deleting its artefacts.
+- **Auto-grant `projects` permission to existing roles on first install.** Currently the admin has to grant it via the Users → Roles editor (same gotcha as Menus). Worth a one-line migration that grants `projects.read` to anyone with `pages.read`.
+- **Recipe `project` block can specify `extraRoles: []` to grant project access** to specific role names at apply time. Useful for "this recipe is for admins only" patterns.

package/docs/superpowers/specs/2026-06-08-navbar-mobile-drawer-and-menu-enrichment-design.md

@@ -0,0 +1,292 @@
+# Navbar Mobile Drawer & Menu Entry Enrichment - Design
+
+**Date:** 2026-06-08
+**Status:** Approved (brainstorm complete, pending implementation plan)
+
+## Overview
+
+Two related improvements to Domma CMS menus:
+
+1. **Mobile drawer navbar** - make the public navbar mobile-first. On small
+   screens the hamburger moves to the far left and the menu opens as a slide-in
+   drawer over a dimmed backdrop, fixing the current bug where the open menu is
+   clipped / hidden behind the sticky bar and floating theme controls.
+2. **Menu entry enrichment** - let menu entries carry **badges**, render as
+   **pills**, and take **colour** overrides, configured in the menu editor and
+   painted by the renderers.
+
+Both are implemented **without modifying `domma-js`** (the framework is an
+upstream npm dependency) and **without modifying the `server/` request
+pipeline beyond the menu/render services** that are already ours to extend.
+
+## Constraints & ground rules
+
+- `domma-js` is a dependency in `node_modules` - never edited. We layer on top
+  of what `Domma.elements.navbar()` already produces.
+- Decoration rendering and live-count resolution happen **server-side** wherever
+  possible, so collection row-access / visibility is honoured and no public
+  counts endpoint is exposed.
+- British English throughout (e.g. "colour").
+- No work is claimed "working"/"verified" from server-side checks (curl,
+  esbuild, file diffs) alone - every visual surface is verified in a real
+  browser before being called done.
+
+---
+
+## Feature 1 - Mobile drawer navbar
+
+### Behaviour
+
+- Below the navbar collapse breakpoint, the hamburger toggle sits at the **far
+  left**; the brand sits immediately to its right.
+- Tapping the hamburger slides a panel in **from the left** over a **dimmed
+  backdrop**. The page content stays in place underneath (not pushed down).
+- The drawer closes on: backdrop tap, an explicit close (X), tapping any menu
+  link, or pressing `Esc`.
+- On desktop (≥ breakpoint) the navbar renders exactly as today - no change.
+
+### Mechanism (no domma-js edits)
+
+`Domma.elements.navbar()` already:
+- renders `.navbar-toggle` (hamburger) and `.navbar-collapse` (the menu body);
+- toggles a `.show` class on `.navbar-collapse` when the hamburger is tapped;
+- auto-collapses when a link is clicked while `window.innerWidth <
+  collapseAt`.
+
+We add, in **our** files:
+
+- **`public/css/site.css`**
+  - Reorder the toggle to the far left on mobile via flex `order` on
+    `.navbar-toggle` / `.navbar-brand` (the navbar is `display:flex;
+    flex-wrap:wrap` mobile-first).
+  - Restyle `.navbar-collapse.show` from an in-flow drop-down into a
+    `position:fixed`, left-anchored, full-height drawer with a slide
+    transition (`transform: translateX(-100%)` → `none`). Because it is
+    `fixed`, it can no longer be clipped by the sticky navbar or overlapped by
+    the floating theme/variant controls - this is the fix for the "can't see
+    the contents" bug.
+  - Give the drawer a sensible width (~80vw, capped ~320px) and an internal
+    scroll for long menus.
+
+- **`public/js/site.js`** (after navbar init)
+  - On hamburger toggle, mount a backdrop element (and a body scroll-lock
+    class); remove it on close.
+  - Backdrop click and `Esc` close the drawer by **re-triggering Domma's own
+    collapse** (programmatic click on `.navbar-toggle` or calling the navbar
+    instance's collapse) so we reuse the framework's state handling rather than
+    duplicating it.
+  - A close (X) affordance inside the drawer does the same.
+
+### Out of scope
+
+- No change to desktop navbar layout or to the dropdown behaviour.
+- No change to `domma-js`.
+
+---
+
+## Feature 2 - Menu entry enrichment
+
+### Data model
+
+Optional fields on each item in `config/menus/<slug>.json` (alongside the
+existing `text`, `url`, `icon`, `visibility`, `permission`, `hidden`,
+`bundled`, `items`):
+
+```jsonc
+{
+  "text": "Pricing",
+  "url": "/pricing",
+  "badge": {
+    "text": "New",              // static label (optional)
+    "countFrom": "orders",      // collection slug → live count (optional)
+    "variant": "success"        // colour value (optional)
+  },
+  "pill": {
+    "style": "filled",          // "filled" | "outline"
+    "variant": "primary"        // colour value
+  },
+  "colour": "#f59e0b"           // overrides the entry's text colour
+}
+```
+
+- All three keys are optional and omitted when unset (same serialisation
+  pattern as existing optional fields in `nest()`).
+- A `badge` may have `text` **or** `countFrom` (if both are present, the
+  resolved count wins - see resolver). `variant` is independent.
+- `pill` only renders on the navbar (a filled chip is meaningless stacked in a
+  footer); other surfaces ignore it.
+
+### Colour convention (presets + custom override)
+
+A **colour value** is a single string, either:
+
+- a **preset key**: `primary | success | danger | warning | info | neutral`
+  → mapped to the active theme's CSS custom property (e.g. `var(--dm-primary)`),
+  so it adapts to the theme and dark/light; or
+- a **custom hex**: `#rrggbb` → used literally.
+
+This one convention is reused by `badge.variant`, `pill.variant`, and `colour`.
+A shared helper resolves a colour value → concrete CSS on both server and
+client so every surface renders identically.
+
+### Rendering - where decorations paint
+
+Scope: **everywhere sensible** (confirmed).
+
+| Surface | Badge | Pill | Colour |
+|---|---|---|---|
+| Navbar (public) | ✅ | ✅ | ✅ |
+| Footer (public) | ✅ | - | ✅ |
+| `[menu]` shortcode | ✅ | - | ✅ |
+| Admin sidebar | ✅ (on top of existing counts) | - | ✅ |
+
+**Shared server-side resolver - the cross-cutting core.**
+A new helper `resolveMenuDecorations(items, ctx)` in
+`server/services/menus.js` walks a menu tree (recursively, including `items`
+children) and, for any item with `badge.countFrom`, computes the entry count
+through the collections service **server-side**, honouring `rowAccess` /
+visibility for the request context. It stamps the resolved number onto the item
+(`badge.text` ← `String(count)`), leaving static badges untouched. Returns the
+decorated tree. Called by every server render path:
+
+- **Navbar** - `server/services/renderer.js` runs the navbar menu items through
+  the resolver before injecting `window.__CMS_NAV__`.
+- **Footer** - `renderer.js` resolves footer menu items into
+  `window.__CMS_FOOTER__`.
+- **`[menu]` shortcode** - `server/services/markdown.js` `processMenuBlocks()`
+  runs the resolver (it already has `user` in scope) before
+  `renderMenuItemsAsUl()`.
+
+**Client / template painters.**
+
+- **Navbar** - in `public/js/site.js`, *after* `Domma.elements.navbar()`
+  renders, walk `.navbar-link[data-index]` (top-level) and dropdown children
+  `[data-index][data-subindex]`. The indexes align with the
+  **separator-stripped** items array already passed to the navbar, so we index
+  into that same array to find each item's decorations. For each item: append a
+  badge `<span>`, add pill classes (`dm-nav-pill dm-nav-pill--filled` etc.),
+  and set the text colour. `domma-js` is untouched.
+- **Footer** - extend `renderItem()` in `site.js` to emit a badge span and
+  colour style (no pills).
+- **`[menu]` shortcode** - extend `renderMenuItemsAsUl()` in `markdown.js` to
+  emit badge + colour inline (server-rendered, already sanitised downstream).
+- **Admin sidebar** - extend `renderItem()` in
+  `admin/js/lib/sidebar-renderer.js` to add badge + colour on top of its
+  existing count display.
+
+**Shared colour/badge helper.** A small module `public/js/menu-decor.js`
+(also importable by the admin) exports: `resolveColour(value)` (preset→var /
+hex→literal) and `buildBadge(badge)` (returns a badge DOM node / HTML), so the
+navbar, footer and sidebar painters render identically. Server-side renderers
+share the same preset→var mapping (kept in one place to avoid drift).
+
+### Validation
+
+`validateMenu()` in `server/services/menus.js` gains optional-shape checks:
+- `badge`, if present, is an object; `badge.text`/`badge.countFrom` are strings;
+  `badge.variant` is a valid colour value.
+- `pill`, if present, is an object; `pill.style` ∈ {`filled`,`outline`};
+  `pill.variant` is a valid colour value.
+- `colour`, if present, is a valid colour value (preset key or `#rrggbb`).
+- A colour value is valid iff it is one of the preset keys **or** matches
+  `/^#[0-9a-fA-F]{6}$/`.
+
+Malformed values are rejected with a clear per-item error path (same style as
+existing `Item ${path}: …` messages). Separator items continue to short-circuit
+before these checks.
+
+---
+
+## Feature 2 (cont.) - Editor: slim rows + slideover
+
+### Tree rows become an overview
+
+Each `.menu-tree-row` is slimmed to: drag grip · **label with a live
+badge/colour preview** · muted URL · structure buttons (outdent / indent / up /
+down) · hide · **✎ Edit** · remove. The content inputs (text, url, icon,
+visibility, permission) leave the row and move into the slideover. Separator
+rows are unchanged.
+
+### The ✎ Edit slideover
+
+Clicking ✎ opens `E.slideover()` containing the full per-item form:
+
+- Label, URL, Icon (existing `openIconPicker`), Visibility, Permission (the
+  existing permission select), then a **Decoration** section:
+  - **Badge text** (string)
+  - **Badge count-from** (select of collection slugs; "- none -" default)
+  - **Badge colour** (preset dropdown + "Custom…" → hex field)
+  - **Render as** (Link / Pill); when Pill: **Pill style** (filled/outline) +
+    **Pill colour** (preset/custom)
+  - **Text colour** (preset dropdown + "Custom…" → hex field)
+
+**Gotcha respected (CLAUDE.md):** Domma's `.html()` / `setContent()` strip
+`<button>` / `<input>`. The form is built as DOM (or via `F.create`) and
+**appended** into the slideover element via light-DOM slot projection
+(`slideover.element.appendChild(formEl)`), never injected as an HTML string.
+
+On slideover save, values are written back into the flat row object held by the
+editor; `nest()` serialises the new fields, omitting empties (same pattern as
+existing optional fields). The tree row's live preview re-renders.
+
+### Editor files
+
+- `admin/js/views/menu-editor.js` - slim row markup, remove inline content
+  inputs, add ✎ handler + slideover form build/read, extend `flatten()` /
+  `nest()` / `syncRowsFromDom()` for the new fields, render the row preview.
+- `admin/js/templates/menu-editor.html` - adjust toolbar/row scaffold if needed.
+- `admin/css/admin.css` - slim-row layout + slideover form styles.
+
+---
+
+## Files touched (summary)
+
+**Public site**
+- `public/css/site.css` - drawer styles + decoration (badge/pill/colour) styles.
+- `public/js/site.js` - drawer wiring (backdrop, Esc, far-left order), navbar +
+  footer decoration painters.
+- `public/js/menu-decor.js` *(new)* - shared colour/badge helpers.
+
+**Server (menu/render services only)**
+- `server/services/menus.js` - `resolveMenuDecorations()` + `validateMenu()`
+  shape checks.
+- `server/services/renderer.js` - resolve navbar + footer menus before
+  injecting globals.
+- `server/services/markdown.js` - `[menu]` shortcode badge/colour rendering +
+  resolver call in `processMenuBlocks()`.
+
+**Admin**
+- `admin/js/views/menu-editor.js` - slim rows + edit slideover.
+- `admin/js/templates/menu-editor.html` - row/toolbar scaffold tweaks.
+- `admin/js/lib/sidebar-renderer.js` - sidebar badge + colour.
+- `admin/css/admin.css` - slim row + slideover form styles.
+
+---
+
+## Testing
+
+- **Unit (server):** `resolveMenuDecorations()` - static badges untouched,
+  `countFrom` resolves to a count, row-access/visibility honoured, recursion
+  into `items`, separators skipped. `validateMenu()` - accepts well-formed
+  badge/pill/colour, rejects bad `style`, bad colour values, wrong types, with
+  correct error paths.
+- **Browser (mandatory before "done"):**
+  - Mobile: hamburger far-left; drawer slides in from left; backdrop tap / X /
+    link / `Esc` all close; menu fully visible (clipping bug gone); desktop
+    unchanged.
+  - Decorations: badge (static + live count), pill (filled + outline), colour
+    (preset + custom hex) on navbar, footer, `[menu]` shortcode, admin sidebar.
+  - Editor: slim rows show live preview; ✎ slideover opens, edits, saves;
+    fields round-trip through save/reload; separators still work.
+
+## Open questions / risks
+
+- **Live-count performance:** resolving counts on every page render adds
+  collection reads. If a menu references many `countFrom` collections, consider
+  caching via the existing response cache (`server/services/cache`) keyed by
+  collection + visitor role. Flagged for the implementation plan, not solved
+  here.
+- **Index alignment (navbar painter):** the client painter relies on
+  `data-index` matching the separator-stripped items array. The implementation
+  must index into the *same* stripped array passed to `Domma.elements.navbar()`.
+```