domma-cms 1.6.60 → 1.7.1

package/docs/superpowers/specs/2026-06-08-sidebar-tools-plugins-folders-design.md

@@ -0,0 +1,59 @@
+# Sidebar: Tools & Plugins folders
+
+**Date:** 2026-06-08
+**Status:** Implemented (dev checkout; pending commit + deploy)
+
+## Goal
+
+Group plugin admin nav into two auto-built, system-managed top-level sidebar
+folders:
+
+- **Tools** - core plugins (always-on; `CORE_PLUGINS` on the server, currently `analytics`)
+- **Plugins** - optional plugins, led by a **Manage Plugins** link (the old enable/disable page)
+
+Layout (top level): Overview · Content · Data · **Tools** · **Plugins** · System · Documentation.
+
+## Decisions
+
+- **System-managed, not menu-editable.** Folders are synthesised at render time
+  from each plugin's core/optional status - no per-site menu data, no migration,
+  correct on every existing site the instant the code deploys. (Consistent with
+  how plugin nav items are already render-time injected, not persisted.)
+- **Manage Plugins moves into the Plugins folder**; the standalone System →
+  Plugins item is removed from the seed and stripped from already-seeded menus at
+  render time so it never shows twice.
+- **Manage Plugins is unconditional** (not derived from the plugin list) so the
+  management link survives a `registered-items` fetch failure.
+
+## Components
+
+- `admin/js/lib/sidebar-grouping.js` - pure, dependency-free helpers:
+  `groupPluginItems`, `stripItemByUrl`, `insertFoldersBeforeSystem`,
+  `pruneEmptySynthesisedFolders`. Unit-tested under `node --test`.
+- `admin/js/lib/sidebar-renderer.js` - wires the helpers into `renderAdminSidebar`:
+  strip `#/plugins` → group plugin items → insert folders before System →
+  permission filter → prune empty synthesised folders.
+- `server/services/plugins.js` - stamps `core: CORE_PLUGINS.has(name)` on each
+  bridged `plugin.json → admin.sidebar` item. Flows through
+  `GET /api/sidebar/registered-items` unchanged.
+- `config/menus/admin-sidebar.json` - seed no longer carries System → Plugins.
+
+Icons (all in Domma's set): Tools `tool`, Plugins `package`, Manage Plugins `sliders`.
+
+## Data flow
+
+`plugin.json (core?)` → server stamps `core` on item → `registered-items` API →
+`groupPluginItems` → Tools/Plugins folders → `filterByPermission` →
+`pruneEmptySynthesisedFolders` → render.
+
+## Edge cases
+
+- No core plugins → no Tools folder.
+- No optional plugins → Plugins folder still shows (just Manage Plugins).
+- User lacks `plugins` permission and no optional plugins → Plugins folder pruned.
+- Plugin item with an explicit `parent` → keeps nesting there (unchanged).
+
+## Testing
+
+- `admin/js/lib/sidebar-grouping.test.js` - 8 cases, all passing.
+- Not browser-verified: the final rendered sidebar needs a real admin login to confirm.

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

@@ -0,0 +1,192 @@
+# Domma Docs - default documentation project
+
+**Date:** 2026-06-25
+**Status:** Design - awaiting review
+
+## Goal
+
+Ship a built-in **Domma Docs** project on every site. It is **disabled by
+default**. When a site admin enables it, the full CMS documentation becomes
+**live, browsable pages on the public site** under `/domma-docs/...`. When they
+disable it, those pages disappear from the public site entirely.
+
+The documentation is **moved** out of the admin panel and into this project -
+the admin doc screens are retired, and the docs' single home becomes the
+project's public pages.
+
+## Why this works with almost no new mechanism
+
+The public-surface kill-switch already exists (commit `d7c255b`):
+
+- `server/routes/public.js:112-118` resolves each page's project via
+  `getProjectForPage(...)` and returns **404** if that project is disabled -
+  regardless of page visibility.
+- `getProjectForPage(urlPath, frontmatterProject)` resolves a page to a project
+  by an explicit `project:` in frontmatter, or by longest `rootUrl` prefix.
+- `isProjectEnabled(slug)` returns `false` for a disabled project.
+
+So a project with `rootUrl: /domma-docs`, seeded disabled, whose pages are
+tagged `project: domma-docs`, is **automatically** hidden from the public site
+until an admin switches it on. No new routing or guard code is required.
+
+## Non-goals
+
+- No public navbar entry for the docs (browsable by URL / landing page; a menu
+  item can be added later if wanted).
+- No live/interactive admin tooling carried onto public pages (see Caveats).
+- The repo's own developer docs under `docs/*.md` are untouched - this concerns
+  the **admin doc screens** only.
+
+## 1. The project seed
+
+New `seedDocsProject()` in `server/services/projects.js`, called in
+`server/server.js` immediately after `seedCoreProject()`. Create-if-absent by
+slug (an existing record is left untouched, so admin edits and the
+enabled/disabled state survive reboots).
+
+Seed record:
+
+| Field         | Value                                                                                   |
+|---------------|-----------------------------------------------------------------------------------------|
+| `slug`        | `domma-docs` (immutable)                                                                 |
+| `name`        | `Domma Docs`                                                                             |
+| `description` | "The Domma CMS handbook - guides, tutorials, component & API reference. Switch on to publish it on your own site." |
+| `icon`        | `document`                                                                               |
+| `rootUrl`     | `/domma-docs`                                                                            |
+| `sortOrder`   | `0` (Core is `-1`, so this sorts immediately after Core)                                 |
+| `enabled`     | `false`                                                                                  |
+| `protected`   | `true` (see Undeletable below)                                                           |
+
+## 2. Undeletable (permanent but toggleable)
+
+The special-casing that makes Core *always-enabled* and *rootUrl-locked* is keyed
+on the **core slug**, not on the `protected` flag. So `protected: true` can be
+reused purely as "undeletable" for Domma Docs without inheriting Core's other
+locks - Domma Docs stays fully toggleable and its `rootUrl` stays editable.
+
+Changes:
+
+- `deleteProject(slug)` - refuse when the target's `protected === true` (today it
+  refuses only the core slug). Generalises "protected = undeletable" and keeps
+  Core safe by the same rule.
+- The untag-all path - refuse for `protected` projects too. Untagging Domma Docs
+  would re-home its pages to Core (always-on) and defeat the kill-switch.
+- `server/routes/api/projects.js` - mirror both refusals at the route level
+  (consistent with how Core is guarded today).
+- Admin UI - the delete control for a protected project is disabled with a hint
+  ("Disable instead of deleting"), matching the Core treatment.
+
+## 3. Documentation as pages
+
+Pages live under `content/pages/domma-docs/**.md`, mirroring today's screens but
+unified beneath `/domma-docs`. Every page's frontmatter carries
+`visibility: public` and **`project: domma-docs`** (explicit tag → robust
+resolution *and* files the page under the project in admin).
+
+Page tree (one page per current admin screen + landing/group index pages):
+
+```
+/domma-docs                         index (landing - card grid to the 4 groups)
+/domma-docs/usage                   group index
+/domma-docs/usage/pages             ← usage-pages.html
+/domma-docs/usage/media             ← usage-media.html
+/domma-docs/usage/navigation        ← usage-navigation.html
+/domma-docs/usage/dconfig           ← usage-dconfig.html
+/domma-docs/usage/shortcodes        ← usage-shortcodes.html
+/domma-docs/usage/site-settings     ← usage-site-settings.html
+/domma-docs/usage/plugins           ← usage-plugins.html
+/domma-docs/usage/users-roles       ← usage-users-roles.html
+/domma-docs/usage/views             ← usage-views.html
+/domma-docs/usage/actions           ← usage-actions.html
+/domma-docs/usage/cta-shortcode     ← usage-cta-shortcode.html
+/domma-docs/tutorials               group index
+/domma-docs/tutorials/crud          ← tutorial-crud.html (scaffolder → static)
+/domma-docs/tutorials/plugin        ← tutorial-plugin.html
+/domma-docs/tutorials/forms         ← tutorial-forms.html
+/domma-docs/components              group index ← components-reference.html
+/domma-docs/components/howto        ← components-howto.html
+/domma-docs/components/walkthrough  ← components-walkthrough.html
+/domma-docs/components/rules        ← components-rules.html
+/domma-docs/api                     group index
+/domma-docs/api/authentication      ← api-authentication.html
+/domma-docs/api/pages               ← api-pages.html
+/domma-docs/api/settings            ← api-settings.html
+/domma-docs/api/layouts             ← api-layouts.html
+/domma-docs/api/navigation          ← api-navigation.html
+/domma-docs/api/media               ← api-media.html
+/domma-docs/api/users               ← api-users.html
+/domma-docs/api/plugins             ← api-plugins.html
+/domma-docs/api/collections         ← api-collections.html
+/domma-docs/api/views               ← api-views.html
+/domma-docs/api/actions             ← api-actions.html
+```
+
+**Sourcing:** each page body is **ported from the matching admin template's
+inner content** (the `.docs-body` HTML), not re-authored from scratch. Markdown
+pages pass raw HTML through `marked`, so the existing markup, tables, code
+blocks and `data-icon` spans carry over. The admin-only `.view-header`
+back-link strip is dropped from each. This is fast and high-fidelity.
+
+## 4. Public rendering
+
+- **CSS** - add the `.docs-body` styling (typography, tables, code) to
+  `public/css/site.css` so ported pages read well on the public theme.
+- **Syntax highlighting** - ensure the public page pipeline runs the code-block
+  highlighter the admin docs rely on (`Domma.syntax.scan()` equivalent) on
+  `/domma-docs/*` pages. Confirm in `public/js/site.js`; wire if absent.
+- **Icons** - already handled (public `site.js` runs `I.scan()`).
+
+## 5. Admin retirement (the "move")
+
+The docs leave the admin panel:
+
+- Remove the hardcoded **Documentation** section from
+  `config/menus/admin-sidebar.json` (and add a one-time migration/strip for
+  already-seeded sites, consistent with existing sidebar-migration patterns).
+- Remove the doc/tutorial routes from `admin/js/app.js`.
+- Remove the doc views (`documentation.js`, `doc-pages.js`, `tutorials.js`) and
+  their registrations in `views/index.js`. *(`pro-docs.js` is separate - leave
+  it.)*
+- Remove `admin/js/templates/docs/*` after their content is ported.
+
+Admins reach the docs through the **Projects** sidebar subtree: once Domma Docs
+is enabled it appears like any project (with a "Pages (N)" child); while
+disabled it is hidden, exactly as projects already behave.
+
+**Consequence (accepted):** a fresh site, with the project off by default, has
+**no in-admin documentation** until an admin enables Domma Docs - at which point
+the docs are browsed on the public site. This matches "disabled by default".
+
+## Phasing
+
+1. **Engine + pilot** - seed the project (disabled, undeletable, `/domma-docs`);
+   add the `/domma-docs` landing page + 2-3 representative pages (a small usage
+   page, the large `usage/shortcodes`, one `api/*`). Prove end-to-end on the
+   live site: enabled → pages render with correct styling/highlighting/icons;
+   disabled → 404.
+2. **Full migration** - port the remaining screens; add the group index pages.
+3. **Admin retirement** - remove the admin Documentation section, routes, views
+   and templates.
+
+## Caveats
+
+- **Interactive tutorials degrade to static.** `tutorial-crud.html` embeds a
+  live recipe scaffolder (`#tutorial-scaffolder-mount`); on a public page it
+  becomes static reference text. Acceptable for docs; noted so fidelity
+  expectations are correct.
+- **`rootUrl` namespace ownership.** With `rootUrl: /domma-docs`, any page under
+  `/domma-docs/*` resolves to this project and is gated by its toggle. The
+  namespace is owned by the project - intended.
+- **sortOrder tie.** Seeded at `0`; user projects also default to `0` and
+  tie-break alphabetically. Core (`-1`) is always first; Domma Docs sits among
+  the first projects after it.
+
+## Verification
+
+- Unit: `seedDocsProject()` is idempotent (no duplicate on re-boot; existing
+  record untouched). `deleteProject('domma-docs')` rejects. Untag-all rejects.
+- Live (browser, not curl): with the project **disabled**, `/domma-docs` and a
+  child page return 404. **Enable** it → both render with docs styling, working
+  code highlighting and icons. **Disable** again → 404 returns.
+- Admin: Documentation section gone from the sidebar; Domma Docs appears under
+  Projects when enabled with the correct page count; delete control disabled.

package/docs/superpowers/specs/2026-06-26-domma-charts-upstream-proposal.md

@@ -0,0 +1,44 @@
+# Domma Charts - Upstream Proposal (stub)
+
+**Date:** 2026-06-26
+**Status:** Captured requirement - **not yet brainstormed**. Deferred from the Surveys plugin work.
+**Target repo:** `domma-js` (framework package, served from `node_modules/domma-js/public/dist/`)
+**Seeded by:** [Surveys Pro plugin](./2026-06-26-surveys-pro-plugin-design.md) - its Results view is the first real consumer.
+
+## Why this is a stub, not part of Surveys
+
+Charting is **framework furniture**, not a CMS view or a plugin concern. The dashboard, analytics, blog stats, and Surveys all want it. Building it inside one CMS view (or one plugin) would be the wrong home and would force an extraction later. It therefore belongs upstairs in `domma-js`.
+
+It is **deliberately not blocking Surveys**: once it lives in `domma-js`, it is a separate repo on a separate release cycle. Surveys ships now with a self-contained CSS-bar fallback behind an isolated seam (see below), and upgrades to the real component with a one-function change whenever Domma Charts lands and `domma-js` is re-published.
+
+## The seam already in place
+
+Surveys renders all visualisation through a single function:
+
+```js
+renderDistribution(items /* [{ label, value, pct }] */) -> HTML string
+```
+
+It currently draws lightweight Domma-CSS bars (no external dependency). **The input shape is the contract.** A future `Domma.charts` must accept the same normalised shape so the swap is mechanical:
+
+```js
+// target API (to be designed)
+Domma.charts(el, { type: 'bar', series: [{ label, value, pct }], ... })
+// or alias-consistent with the rest of the framework, e.g. C.create(...)
+```
+
+## Requirements seeded by the survey Results view
+
+The first consumer needs only a modest subset - capture it as the MVP, but design the component for general use:
+
+- **Horizontal distribution bars** - label + value + percentage (choice-field results).
+- **Rating distribution** - bars plus a summary average.
+- **Completions over time** - a simple line/area or stepped bar over a date axis.
+- Theme-aware across all ~28 Domma themes (charts must read CSS variables, not hardcode colours).
+- No hard dependency on a third-party charting library if avoidable (keep the framework dependency-free, consistent with the rest of Domma).
+
+Explicitly **out of the survey use-case** (so do not let it drive the design narrowly): multi-series legends, tooltips on hover, zoom/pan, real-time streaming. Design for them if cheap; do not over-fit to surveys.
+
+## Next step
+
+When picked up: run this through the normal brainstorming → spec → plan flow **in the `domma-js` repo**, using this stub and the survey Results view as the concrete requirements source. On completion, swap `renderDistribution`'s body for the real call and remove the CSS-bar fallback.

package/docs/superpowers/specs/2026-06-26-manager-scheduler-upstream-proposal.md

@@ -0,0 +1,46 @@
+# Manager Scheduler - Upstream Proposal (stub)
+
+**Date:** 2026-06-26
+**Status:** Captured requirement - **not yet brainstormed**. Deferred from the Surveys plugin work.
+**Target repo:** `domma-cms-manager`
+**Seeded by:** [Surveys Pro plugin](./2026-06-26-surveys-pro-plugin-design.md) - its due-work contract is the first real consumer.
+
+## Why this is a stub, not part of Surveys
+
+Scheduling - reminders, targeted-email batches, housekeeping - is **cross-cutting platform infrastructure**, not a survey feature. Blog digests, invoice chasers, contact re-engagement, and Surveys all eventually want it. pm2-driven scheduling is the manager's domain. Building a scheduler inside the Surveys plugin would be the same category error as building charts inside one CMS view.
+
+It is **deliberately not blocking Surveys**: the plugin already ships a working synchronous path (admin "Send invitations" / "Send reminders" buttons). The scheduler does not *add a capability* to Surveys - it merely *automates calling an endpoint that already exists*. The manager is a separate system on its own cycle.
+
+## Design principle: keep the scheduler generic
+
+The scheduler must **not** learn about surveys. The seam is a **generic due-work protocol** any plugin can implement, so the manager stays a dumb poll-and-execute ticker:
+
+- **Policy lives in the plugin.** Reminder cadence (`reminderAfterDays`) is set per-campaign in the survey editor, where that UX belongs.
+- **The manager is a generic loop.** It periodically asks each registered plugin endpoint "what work is due?" and "do this due work" - nothing survey-specific.
+
+## The contract already in place (Surveys side)
+
+Token-authenticated endpoints the plugin exposes (`dcms_` service token; exact auth header to be confirmed against how the manager already talks to the CMS):
+
+```
+GET  /api/plugins/surveys/due-work
+     -> outstanding sends past reminderAfterDays for open campaigns
+
+POST /api/plugins/surveys/run
+     { campaignSlug, audience: 'all' | 'non-responders', reminder: bool }
+     -> execute a batch (flips ledger pending->sent / ->bounced)
+```
+
+Generalise this to a registry the scheduler reads: `{ plugin, dueWorkUrl, runUrl }` so adding a future plugin to the scheduler is config, not code.
+
+## Requirements seeded by Surveys
+
+- pm2-managed poll loop (interval configurable per registered job).
+- Service-token auth to the CMS; never a user JWT.
+- Idempotent execution: a `run` that overlaps a manual admin send must not double-email (the ledger's `completed`/`sent` state is the guard - the plugin already enforces it, but the scheduler should tolerate empty/no-op `due-work` responses gracefully).
+- Housekeeping jobs (the broader manager goal) share the same poll-and-execute machinery - design the loop generically, not just for "send reminders".
+- Observability: log each poll/run result; surface failures (so a stuck SMTP server is visible, not silent).
+
+## Next step
+
+When picked up: run this through the normal brainstorming → spec → plan flow **in the `domma-cms-manager` repo**, using this stub and the survey due-work contract as the first consumer. Surveys needs no change when the scheduler lands - it already exposes the contract.

package/docs/superpowers/specs/2026-06-26-surveys-pro-plugin-design.md

@@ -0,0 +1,206 @@
+# Surveys (Pro Plugin) - Design Spec
+
+**Date:** 2026-06-26
+**Status:** Approved design - ready for implementation planning
+**Repo:** `domma-cms` (this repo)
+**Related upstream work:** [Domma Charts](./2026-06-26-domma-charts-upstream-proposal.md) (`domma-js`), [Manager Scheduler](./2026-06-26-manager-scheduler-upstream-proposal.md) (`domma-cms-manager`)
+
+## 1. Summary
+
+A **Pro plugin** that turns the existing Forms system into a targeted survey tool. A *survey* is **not a new form engine** - it is a *campaign wrapper* around an existing Form, plus an *audience* (shared contacts + groups), plus an *invite/token ledger*, plus a *results/stats* layer.
+
+The Forms system already:
+
+- stores submissions in a Collection whose slug matches the form,
+- runs an actions pipeline (collection / email / webhook) on submit, and
+- accepts an **optional JWT** on the public submit endpoint.
+
+So the genuinely new surface area is narrow: an **invitation/token layer** (the hash), a **campaign** concept (this survey → that audience → sent on this date), and **statistics**.
+
+Everything new lives under `plugins/surveys/`. **Nothing in `server/` is modified** (it is upstream-replaced on update). Where Surveys needs core behaviour (storing a submission, running submit actions, sending mail) it *calls* the existing services rather than reimplementing them.
+
+## 2. Key decisions (resolved during brainstorming)
+
+| Decision | Resolution |
+|---|---|
+| Audience model | Surveys owns shared `survey-contacts` + `survey-groups`; one-way **"Import from Contacts"** bridge from the per-user Contacts plugin. |
+| Storage | Schemas declare `"storage": {"adapter": "mongodb"}` (Pro → Mongo, `cms_`-prefixed); degrade gracefully to `FileAdapter` if no connection. Schema management stays file-based. |
+| Attribution | **Per-survey toggle**: each campaign is created `identified` or `anonymous`. |
+| Survey surface | Plugin-hosted page at `/survey/<slug>` **plus** a `[survey slug]` shortcode for embedding. |
+| Sending | Editor-triggered batch (synchronous, via `email.js`) **plus** a token-authenticated due-work contract for the external scheduler. **No in-process scheduler.** |
+| Statistics | Layered (campaign health + per-question aggregation) **plus** CSV/JSON export. |
+| Charts | Lightweight Domma-CSS bars now, behind an isolated `renderDistribution()` seam; real charting deferred to **Domma Charts** upstream. |
+| Out of v1 (YAGNI) | Per-survey project scoping via `meta.project`; open-tracking pixel (no `opened` status - ledger goes `sent → completed`). |
+
+## 3. Data model
+
+Four plugin collections (`schema.json` files under `plugins/surveys/collections/`, mirroring the Contacts plugin layout), all declaring the mongodb adapter with graceful file fallback:
+
+### `survey-contacts`
+Shared, editor-owned recipients. Fields: `email` (required), `name`, plus optional custom fields. **"Import from Contacts"** copies (one-way) from the per-user Contacts plugin's `user-contacts`.
+
+### `survey-groups`
+Named audience groups. Fields: `name`, `description`, `contactIds[]` (membership by contact id).
+
+### `surveys` (the campaign)
+Fields:
+
+- `slug` (immutable), `title`, `description`
+- `formSlug` - the underlying Form that supplies the questions and the submission collection
+- `groupIds[]` - targeted audience group(s)
+- `mode` - `identified | anonymous`
+- `status` - `draft | open | closed`
+- `opensAt`, `closesAt` (optional)
+- `reminderAfterDays` - per-campaign reminder cadence (consumed by the due-work contract; see §6)
+- `inviteEmail` - `{ subject, body }` template with `{{link}}`, `{{name}}` tokens
+
+### `survey-invites` (the ledger)
+**One row per (survey × contact).** This is the heart of the new mechanic. Fields:
+
+- `surveyId`, `contactId`
+- `tokenHash` - **SHA-256 of the token** (plaintext never stored - identical pattern to `api-tokens`)
+- `status` - `pending | sent | completed | bounced`
+- `sentAt`, `completedAt`
+- `responseId` - the submission row id (identified mode), else null
+
+### Responses
+**Answers reuse the underlying Form's existing submission collection** (slug = `formSlug`). Surveys does **not** create a separate response store.
+
+- **Identified mode:** the submission row carries `surveyInviteId` (and therefore resolves to a contact).
+- **Anonymous mode:** the submission row carries **no** contact/invite link - but the ledger still flips that invite to `completed`.
+
+One mechanism, two privacy postures: the invite ledger drives response-rate stats and reminder-suppression identically in both modes; only the *persisted link on the response row* differs.
+
+## 4. Taking a survey & the token
+
+### Token
+- A **readable code** per invite (e.g. `XR4K-9QP2`, unambiguous alphabet - no `0/O`, `1/I/L`).
+- Only its **SHA-256 hash** is stored in `survey-invites.tokenHash`.
+- The personalised email link embeds the plaintext: `/survey/<slug>?t=XR4K-9QP2`.
+- The manual-entry box on the hosted page accepts the **same code**. One secret, two entry paths.
+
+### Surface
+- **Hosted page** at `/survey/<slug>` (plugin-served, public). Responsibilities:
+  - auto-bind `?t=` from the link,
+  - show a "enter your code" box when no/invalid token is present,
+  - own the **thank-you / already-completed / closed** states,
+  - render the underlying Form (so the form's Domma components initialise via the normal public SSR + `site.js` path).
+- **`[survey slug]` shortcode** for embedding the same experience inside a branded CMS page (registered via `hooks.registerShortcode`).
+
+### Submit flow
+A **plugin** submit endpoint (`POST /api/plugins/surveys/submit/:slug`):
+
+1. Looks up the invite by `tokenHash` (hash the submitted code, match).
+2. Rejects if: token unknown, invite already `completed`, or survey `closed`/outside `opensAt..closesAt`.
+3. **Delegates answer storage + the actions pipeline to the core Forms submit path** (calls the existing public form submit handler / forms service - does not reimplement validation or actions).
+4. Records the invite as `completed` with `completedAt` and `responseId`.
+
+**Notifications reuse existing machinery:**
+- "Notify completion" = an **email action already configured on the underlying Form** - reused, not rebuilt.
+- "Notify it's there" = the **campaign invite email** (§6).
+
+## 5. Statistics (layered + export)
+
+Per-survey **Results** view:
+
+- **Campaign health:** invited / completed / response-rate %; completions over time; **outstanding list** (named in identified mode, count-only in anonymous).
+- **Per-question** (computed live from the form's submission collection):
+  - choice fields → distribution bars,
+  - rating fields → average + distribution,
+  - free-form text → listed responses (not charted).
+- **Export:** raw responses as **CSV / JSON**. Anonymous-mode export is guaranteed contact-free.
+
+### Charts seam (`renderDistribution`)
+All visualisation goes through a single isolated function:
+
+```js
+// returns an HTML string of Domma-CSS bars from a normalised shape
+renderDistribution(items /* [{ label, value, pct }] */) { ... }
+```
+
+It draws lightweight Domma-CSS bars today (e.g. `.dm-progression`-style / grid widths - **no Chart.js, no external dependency**). The input shape is *exactly* what a future `Domma.charts(el, {series})` will accept, so swapping to the real component later is a one-function change. See the [Domma Charts upstream proposal](./2026-06-26-domma-charts-upstream-proposal.md).
+
+## 6. Sending & the due-work contract
+
+The plugin owns the *what*; the external scheduler owns the *when*. **No in-process timers.**
+
+### Admin (synchronous)
+- **"Send invitations"** → emails the targeted group via `email.js`; per-recipient result flips ledger `pending → sent` or `→ bounced`.
+- **"Send reminder to non-responders"** → same, auto-excluding anyone `completed`/`bounced`.
+
+### Generic due-work contract (for the scheduler)
+Token-authenticated plugin endpoints - kept **generic**, not survey-specific, so any future plugin can implement the same protocol and the [Manager Scheduler](./2026-06-26-manager-scheduler-upstream-proposal.md) stays a dumb ticker:
+
+- `GET /api/plugins/surveys/due-work` → outstanding sends past `reminderAfterDays` for open campaigns.
+- `POST /api/plugins/surveys/run` `{ campaignSlug, audience: 'all' | 'non-responders', reminder: bool }` → execute a batch.
+
+Reminder **policy** (cadence) lives **per-campaign in the survey editor**; the scheduler merely polls "what's due?" and "do it". Authentication aligns with the scheme domma-cms-manager already uses against the CMS (a `dcms_` service token - exact header to be confirmed against the manager).
+
+## 7. Permissions & projects
+
+- New permission family **`surveys.{read, create, update, delete}`**. Custom roles are **not** back-filled - admin grants via the role editor (same gotcha as Projects/Menus).
+- v1 surveys are **core-project**. Per-survey `meta.project` scoping is deferred (YAGNI).
+
+## 8. Admin UI (Domma-first throughout)
+
+Plugin sidebar section **Surveys**. The whole plugin obeys the CLAUDE.md Domma conventions - the Contacts plugin (`plugins/contacts/admin/`) is the reference pattern.
+
+- **Views** export `{ templateUrl, async onMount($container) }` with companion `.html` templates; use `$container.find('#id')` + `.get(0)` for native elements.
+- **Tables** (surveys list, contacts, outstanding list) via `T.create` - render functions return **HTML strings** and use **`onclick`**, never `addEventListener` (double-bind gotcha).
+- **Forms** (survey editor, contact editor, audience picker) via `F.create(selector, {blueprint})` - no hand-written `<form>` markup.
+- **UI chrome:** `E.toast` for results; `E.confirm` before destructive sends/deletes; `E.modal` with light-DOM slot projection for any buttons/inputs.
+- **Icons:** `<span data-icon>` + `I.scan()`. Check the registry first; register new SVGs (likely `clipboard-list`, `bar-chart`, `send`) via `I.register` only if missing.
+- **HTTP:** `H.post`/`H.get` for JSON; `fetch().then(r => r.text())` only for HTML templates (the `H.get`-auto-parses-JSON gotcha).
+- **Admin module loading:** rely on the existing `Cache-Control: no-store` header - **no `?v=N`** query strings on admin imports.
+
+Views:
+1. **Surveys list** - `T.create`: title, status, response-rate, actions.
+2. **Survey editor** - pick/create underlying Form, choose groups, `mode` toggle, open/close dates, `reminderAfterDays`, invite-email template.
+3. **Audience** - contacts + groups CRUD, **Import from Contacts** button.
+4. **Results** - health widgets + `renderDistribution` charts + CSV/JSON export.
+
+## 9. Error handling
+
+- Invalid / used token on submit → friendly "this link is no longer valid / already completed".
+- Closed or out-of-window survey → "this survey has closed".
+- Duplicate submit (invite already `completed`) → blocked by default.
+- Batch send → **never fails wholesale**; per-recipient bounce tracking; SMTP rejection → `bounced`.
+- Mongo absent → schemas fall back to `FileAdapter` (no crash).
+- Anonymous mode → assert **no `contactId`/`surveyInviteId`** ever reaches the response row or the export.
+
+## 10. Testing
+
+- **Unit:** token generation / hash / verify; ledger state transitions; stats aggregation (choice / rating / text); anonymous-mode de-linking (assert no contact link on response); `renderDistribution` output shape.
+- **Integration:** send batch → `pending → sent`; valid-token submit → `completed` + `responseId`; used-token submit → rejected; closed-survey submit → rejected; reminder/due-work query excludes `completed`.
+- **Browser-verified** (never claimed from curl alone - see project memory): hosted page link flow + manual code entry + thank-you/closed states; stats dashboard renders bars; survey editor `F.create` round-trip.
+
+## 11. Plugin structure
+
+```
+plugins/surveys/
+  plugin.json              manifest (name, displayName, version, description, author, date, icon, admin{sidebar,routes,views})
+  plugin.js                Fastify plugin: hosted page, submit endpoint, due-work contract, [survey] shortcode
+  config.js                config defaults
+  CLAUDE.md                routes, storage, gotchas
+  collections/
+    survey-contacts/schema.json
+    survey-groups/schema.json
+    surveys/schema.json
+    survey-invites/schema.json
+  admin/
+    templates/*.html
+    views/*.js             surveys list, survey editor, audience, results
+  lib/
+    tokens.js              generate / hash / verify readable codes
+    ledger.js              invite state transitions
+    stats.js               aggregation + renderDistribution seam
+```
+
+## 12. Seams to upstream work
+
+| Seam (lives here) | Consumed by | Upstream stub |
+|---|---|---|
+| `renderDistribution({label,value,pct}[])` | `Domma.charts` (one-function swap) | [Domma Charts](./2026-06-26-domma-charts-upstream-proposal.md) |
+| `GET /due-work` + `POST /run` generic contract | Manager pm2 poll-and-execute loop | [Manager Scheduler](./2026-06-26-manager-scheduler-upstream-proposal.md) |
+
+Both seams ship in v1 so the plugin is self-sufficient; the upstream components upgrade it later without throwing anything away.

package/docs/superpowers/specs/2026-07-02-shortcode-context-menu-design.md

@@ -0,0 +1,96 @@
+# Right-click shortcode context menu - design
+
+**Date:** 2026-07-02
+**Status:** Implemented (pure logic test-covered; menu UI pending browser verification)
+
+## Goal
+
+In the page editor, right-clicking inside the Markdown textarea opens a context
+menu that is aware of the shortcode the cursor sits in. The menu is **hybrid**:
+
+- **Inside a tag** - the tag's own attributes at the top (edit them live), then
+  `Insert…` and `Wrap in…` submenus.
+- **In plain text** - just `Insert…` (plus `Wrap selection in…` when text is
+  selected).
+
+## Decisions (from brainstorming)
+
+- **Scope:** hybrid menu (tag options + Insert + Wrap).
+- **Coverage:** all ~28 shortcodes get full attribute schemas.
+- **Architecture:** one central client-side registry is the source of truth.
+- **Edit model:** inline, live in the menu - checkboxes toggle instantly, value
+  fields edit in place, selects open a submenu; the shortcode text rewrites as
+  you go.
+
+## Components
+
+### `admin/js/lib/shortcode-tags.js` (shared utilities)
+Generalised from the private helpers in `effects-builder.js`:
+- `parseAttrs(attrStr)` - quoted values → strings, bare flags → `true`.
+- `findEnclosingShortcode(textarea, specs)` - innermost tag wrapping the cursor,
+  handling both block (`[card]…[/card]`) and self-closing (`[spacer … /]`), plus
+  the cursor being literally inside a tag's `[…]` brackets. Returns a span
+  `{name, openTagStart, openTagEnd, attrStr, attrs, selfClosing}` or `null`.
+- `serialiseTag(name, attrs, selfClosing)` - rebuild a tag; flags/empties handled;
+  `"` escaped.
+- `setAttr(textarea, span, key, value)` - set/remove one attribute, rewrite in
+  place, dispatch `input`, return the fresh span.
+
+**Robustness:** `selfClosing` is derived from the **actual tag text** (does it end
+in `/]`?), never from the registry hint - so a mis-flagged registry entry can
+never rewrite a paired `[name]…[/name]` opening tag as `[name … /]`.
+
+### `admin/js/lib/shortcode-registry.js` (source of truth)
+`SHORTCODES` - 32 entries (28 top-level shortcodes + child tags `tab`, `item`,
+`col`, `slide`, `event`). Each: `{name, label, category, selfClosing, container,
+wrappable, template, attrs[]}`. Attribute `type` ∈ `text | number | checkbox |
+select | colour | icon | url`; selects carry `options: [[value,label],…]`.
+Attribute names were verified against the `process<X>Blocks` functions in
+`server/services/markdown.js` (code overrides docs). Effects are handled
+separately by `effect-defs.js` and are out of scope here.
+
+### `admin/js/lib/shortcode-context-menu.js` (the menu)
+`attachContextMenu(textarea)` binds a `contextmenu` listener that suppresses the
+browser menu, finds the enclosing shortcode, and renders the menu. Bespoke DOM
+(direct `addEventListener`, no namespaced delegation), a single guarded instance
+reset on **every** close path (outside-click / Esc / scroll) - applying the
+Effects-builder latch lesson. Rows render by attribute type; `Insert…` inserts a
+registry template; `Wrap in…` wraps the selection (grid wraps as
+`[grid][col]…[/col][/grid]`).
+
+### Wiring
+`page-editor.js` imports `attachContextMenu` and calls it on the
+`#markdown-editor` textarea right after the toolbar is created.
+
+## Testing
+
+- **Automated (node `--test`):** `shortcode-tags` (parse / find / serialise /
+  setAttr, incl. nested, self-closing, and the mis-flag-can't-corrupt case);
+  `shortcode-registry` integrity (shape, unique names, coverage, valid attr
+  types, and the self-closing-vs-paired-template invariant).
+- **Browser-only (not yet verified):** the `contextmenu` interception, menu
+  rendering/positioning, inline editing, submenus, and wrap-on-selection.
+
+## Effects extension (2026-07-03)
+
+Effects (`effect-defs.js`, 17) folded into the same menu, full parity:
+
+- **Standalone effect tags** (`[reveal]…[/reveal]`, `[counter /]`) are added to the
+  detection specs and get inline option editing via the existing row engine.
+- **Injected effects on a host** (`[card reveal reveal-animation="…"]`) render an
+  `Effect: <label>` section editing the `<effect>-*` prefixed params, with
+  **✕ Remove effect** (drops the flag + all prefixed keys in one rewrite).
+- **Add effect…** submenu injects into a compatible host (`effect.hosts`) or
+  inserts a standalone effect template.
+
+Shared-util additions: `setAttrs(ta, span, changes)` (multi-attr rewrite) and
+`effectAttrKeys(attrs, name)`. `_attrRow` takes an explicit key so injected
+effects address `<effect>-<attr>`. Integrity guarded by
+`tests/admin/effect-menu-integrity.test.js`.
+
+## Deliberately deferred
+
+- Refactoring `effects-builder.js` onto the shared utilities (works today; avoided
+  to not risk a regression in an untested UI path).
+- Routing `Insert…` for Embed/Effects to their dedicated builders (currently
+  inserts a template; builders remain reachable from the toolbar).