domma-cms 1.6.60 → 1.7.0

package/docs/superpowers/specs/plans/2026-05-17-cache-system.md

@@ -0,0 +1,1436 @@
+# Cache System 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. **This project's rule:** never run `git commit` - list a suggested commit message in each commit step; the user commits separately.
+
+**Goal:** Add a pluggable caching layer to Domma CMS with tag-based invalidation, switchable between in-memory (default), disabled (dev), and Redis (optional Pro), driven by `config/cache.json` and hooked into existing write paths so stale content never persists across an admin edit.
+
+**Architecture:** Core service at `server/services/cache/` mirroring the existing adapter/connection-manager patterns. Public page renders are wrapped through `cache.wrap(key, producer, {tags})`. The markdown pipeline collects tags from each shortcode it processes (`[collection slug="faq"]` → `collection:faq`) so invalidation needs no central embed-map. Write services emit `cache.invalidateTags([...])` after every mutating operation.
+
+**Tech Stack:** Node 24 ESM, Fastify 5, `node:test` + `node:assert/strict`, no required new runtime deps (`ioredis` added only to `optionalDependencies` for the Pro driver).
+
+---
+
+## File Structure
+
+```
+server/services/cache/
+  index.js              Public API: initCache, get, set, wrap, invalidateTags, clear, isEnabled
+  drivers/
+    MemoryDriver.js     Bounded LRU + tag index, TTL support
+    NoneDriver.js       No-op driver - wrap always calls producer, get always returns undefined
+    RedisDriver.js      Optional, loaded dynamically. ioredis-backed with tag sets.
+  lru.js                Small zero-dep bounded map (Map-backed LRU)
+config/
+  cache.json.example    Template; absence → defaults baked into the facade
+server/server.js        Initialise cache on boot via initCache(config.cache)
+server/routes/public.js Wrap the SSR response through cache.wrap()
+server/services/markdown.js  parseMarkdown returns {html, tags} instead of html-only
+server/services/renderer.js  Forward tags from markdown to caller
+server/services/content.js   invalidateTags(['page:<urlPath>']) on page CRUD
+server/services/collections.js invalidateTags(['collection:<slug>']) on entry CRUD
+server/services/forms.js     invalidateTags(['form:<slug>']) on form CRUD
+server/services/blocks.js    invalidateTags(['block:<name>']) on block CRUD
+server/services/views.js     invalidateTags(['view:<slug>']) on view CRUD
+server/routes/api/navigation.js invalidateTags(['nav']) on nav save (flushes every page)
+server/routes/api/settings.js   invalidateTags(['site']) on site settings save
+server/routes/api/cache.js   POST /api/cache/clear admin endpoint
+tests/services/cache/
+  lru.test.js
+  MemoryDriver.test.js
+  NoneDriver.test.js
+  index.test.js
+  invalidation-integration.test.js
+docs/cache.md           User-facing docs: config, drivers, tag conventions
+```
+
+## API surface (frozen)
+
+```js
+// server/services/cache/index.js
+export async function initCache(config)            // sets driver, idempotent
+export async function get(key)                      // returns value | undefined
+export async function set(key, value, opts = {})    // opts: {ttlSeconds, tags}
+export async function wrap(key, producer, opts)     // get-or-set with in-flight coalescing
+export async function invalidateTags(tags)          // tags: string[]
+export async function clear()                       // flush everything (admin button)
+export function isEnabled()                         // boolean - for branches in callers
+export function _resetForTests()                    // test hook; mirrors health.js pattern
+```
+
+`key` is a string. Callers serialise composite keys (e.g. `` `page:${urlPath}:role${roleLevel}` ``).
+
+## Tag conventions (frozen)
+
+- `page:<urlPath>` - every cached page response carries this; invalidated on page CRUD
+- `collection:<slug>` - added by `[collection slug="..."]` shortcode; invalidated on entry CRUD or schema change
+- `form:<slug>` - added by `[form slug="..."]` shortcode; invalidated on form save
+- `block:<name>` - added by `[block name="..."]` shortcode; invalidated on block save
+- `view:<slug>` - added by `[view slug="..."]` shortcode; invalidated on view save
+- `nav` - added to every cached page; invalidated on navigation change
+- `site` - added to every cached page; invalidated on site settings save
+
+Cache keys are versioned with a `v1:` prefix so future schema changes can auto-invalidate.
+
+---
+
+## Task 1: Zero-dep bounded LRU
+
+**Files:**
+- Create: `server/services/cache/lru.js`
+- Test: `tests/services/cache/lru.test.js`
+
+- [ ] **Step 1: Write the failing tests**
+
+```js
+// tests/services/cache/lru.test.js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {LRU} from '../../../server/services/cache/lru.js';
+
+test('LRU set/get round-trip', () => {
+    const lru = new LRU(10);
+    lru.set('a', 1);
+    assert.equal(lru.get('a'), 1);
+});
+
+test('LRU returns undefined for missing keys', () => {
+    const lru = new LRU(10);
+    assert.equal(lru.get('missing'), undefined);
+});
+
+test('LRU evicts oldest when full', () => {
+    const lru = new LRU(2);
+    lru.set('a', 1);
+    lru.set('b', 2);
+    lru.set('c', 3);
+    assert.equal(lru.get('a'), undefined);
+    assert.equal(lru.get('b'), 2);
+    assert.equal(lru.get('c'), 3);
+});
+
+test('LRU promotes on get so recently-read keys survive eviction', () => {
+    const lru = new LRU(2);
+    lru.set('a', 1);
+    lru.set('b', 2);
+    lru.get('a');             // promote a
+    lru.set('c', 3);          // should evict b, not a
+    assert.equal(lru.get('a'), 1);
+    assert.equal(lru.get('b'), undefined);
+    assert.equal(lru.get('c'), 3);
+});
+
+test('LRU delete removes a key', () => {
+    const lru = new LRU(2);
+    lru.set('a', 1);
+    lru.delete('a');
+    assert.equal(lru.get('a'), undefined);
+});
+
+test('LRU clear empties the store', () => {
+    const lru = new LRU(2);
+    lru.set('a', 1);
+    lru.set('b', 2);
+    lru.clear();
+    assert.equal(lru.get('a'), undefined);
+    assert.equal(lru.size, 0);
+});
+
+test('LRU size reflects current item count', () => {
+    const lru = new LRU(5);
+    lru.set('a', 1);
+    lru.set('b', 2);
+    assert.equal(lru.size, 2);
+});
+```
+
+- [ ] **Step 2: Run the tests, confirm they fail**
+
+```
+node --test tests/services/cache/lru.test.js
+```
+
+Expected: `Cannot find module '.../lru.js'` or similar - all tests fail.
+
+- [ ] **Step 3: Implement LRU**
+
+```js
+// server/services/cache/lru.js
+/**
+ * Bounded LRU built on the insertion-order property of Map.
+ * On hit, delete + re-set the entry so it becomes the most-recent.
+ * On set when at capacity, delete the first (oldest) key.
+ */
+export class LRU {
+    /**
+     * @param {number} maxItems
+     */
+    constructor(maxItems) {
+        if (!Number.isInteger(maxItems) || maxItems < 1) {
+            throw new TypeError('LRU: maxItems must be a positive integer');
+        }
+        this._max = maxItems;
+        this._map = new Map();
+    }
+
+    get size() {
+        return this._map.size;
+    }
+
+    get(key) {
+        if (!this._map.has(key)) return undefined;
+        const value = this._map.get(key);
+        this._map.delete(key);
+        this._map.set(key, value);
+        return value;
+    }
+
+    set(key, value) {
+        if (this._map.has(key)) {
+            this._map.delete(key);
+        } else if (this._map.size >= this._max) {
+            const oldest = this._map.keys().next().value;
+            this._map.delete(oldest);
+        }
+        this._map.set(key, value);
+    }
+
+    delete(key) {
+        return this._map.delete(key);
+    }
+
+    clear() {
+        this._map.clear();
+    }
+
+    keys() {
+        return this._map.keys();
+    }
+}
+```
+
+- [ ] **Step 4: Run tests, confirm pass**
+
+```
+node --test tests/services/cache/lru.test.js
+```
+
+Expected: 7/7 pass.
+
+- [ ] **Step 5: Save (no commit - user will batch)**
+
+Suggested commit message: `feat(cache): add zero-dep bounded LRU primitive`
+
+---
+
+## Task 2: MemoryDriver with TTL + tag index
+
+**Files:**
+- Create: `server/services/cache/drivers/MemoryDriver.js`
+- Test: `tests/services/cache/MemoryDriver.test.js`
+
+`MemoryDriver` wraps the LRU and adds:
+- TTL (per-entry expiry; eviction-on-read for laziness, no timers)
+- Tag index: `Map<tag, Set<key>>` so `invalidateTags(['foo'])` flushes every key tagged `foo`
+
+- [ ] **Step 1: Write the failing tests**
+
+```js
+// tests/services/cache/MemoryDriver.test.js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {MemoryDriver} from '../../../server/services/cache/drivers/MemoryDriver.js';
+
+test('MemoryDriver set/get round-trip', async () => {
+    const d = new MemoryDriver({maxItems: 10});
+    await d.set('k', 'v');
+    assert.equal(await d.get('k'), 'v');
+});
+
+test('MemoryDriver returns undefined for unset key', async () => {
+    const d = new MemoryDriver({maxItems: 10});
+    assert.equal(await d.get('nope'), undefined);
+});
+
+test('MemoryDriver expires entries past TTL', async () => {
+    const d = new MemoryDriver({maxItems: 10}, {now: () => 0});
+    let clock = 0;
+    d._now = () => clock;
+    await d.set('k', 'v', {ttlSeconds: 1});
+    clock = 500;   // 500ms in - still valid
+    assert.equal(await d.get('k'), 'v');
+    clock = 1500;  // past 1s TTL
+    assert.equal(await d.get('k'), undefined);
+});
+
+test('MemoryDriver invalidateTags flushes all keys with that tag', async () => {
+    const d = new MemoryDriver({maxItems: 10});
+    await d.set('page:/a', 'A', {tags: ['page:/a', 'nav']});
+    await d.set('page:/b', 'B', {tags: ['page:/b', 'nav']});
+    await d.set('page:/c', 'C', {tags: ['page:/c']});
+    await d.invalidateTags(['nav']);
+    assert.equal(await d.get('page:/a'), undefined);
+    assert.equal(await d.get('page:/b'), undefined);
+    assert.equal(await d.get('page:/c'), 'C');
+});
+
+test('MemoryDriver invalidateTags is a no-op for unknown tag', async () => {
+    const d = new MemoryDriver({maxItems: 10});
+    await d.set('k', 'v', {tags: ['real-tag']});
+    await d.invalidateTags(['ghost-tag']);
+    assert.equal(await d.get('k'), 'v');
+});
+
+test('MemoryDriver clear empties everything including tag index', async () => {
+    const d = new MemoryDriver({maxItems: 10});
+    await d.set('k', 'v', {tags: ['t']});
+    await d.clear();
+    assert.equal(await d.get('k'), undefined);
+    await d.invalidateTags(['t']);  // must not throw
+});
+
+test('MemoryDriver evicts oldest under LRU pressure', async () => {
+    const d = new MemoryDriver({maxItems: 2});
+    await d.set('a', 1);
+    await d.set('b', 2);
+    await d.set('c', 3);
+    assert.equal(await d.get('a'), undefined);
+    assert.equal(await d.get('b'), 2);
+    assert.equal(await d.get('c'), 3);
+});
+
+test('MemoryDriver re-setting a key updates its tag membership', async () => {
+    const d = new MemoryDriver({maxItems: 10});
+    await d.set('k', 'v1', {tags: ['old-tag']});
+    await d.set('k', 'v2', {tags: ['new-tag']});
+    await d.invalidateTags(['old-tag']);  // should NOT remove k anymore
+    assert.equal(await d.get('k'), 'v2');
+    await d.invalidateTags(['new-tag']);
+    assert.equal(await d.get('k'), undefined);
+});
+```
+
+- [ ] **Step 2: Run tests, confirm they fail**
+
+```
+node --test tests/services/cache/MemoryDriver.test.js
+```
+
+Expected: module-not-found, all fail.
+
+- [ ] **Step 3: Implement MemoryDriver**
+
+```js
+// server/services/cache/drivers/MemoryDriver.js
+import {LRU} from '../lru.js';
+
+/**
+ * In-memory cache driver with TTL and tag invalidation.
+ *
+ * Each entry is stored as {value, expiresAt}. TTL is lazy - entries past
+ * their expiresAt are returned as undefined on the next get and dropped.
+ *
+ * Tag index: a Map<tag, Set<key>>. set() with {tags} adds the key to each
+ * tag's set; invalidateTags() iterates the listed tags and deletes every
+ * key in their sets. The reverse index (key → tags) is stored alongside
+ * each entry so that re-setting a key cleans up the old tag links.
+ */
+export class MemoryDriver {
+    /**
+     * @param {{maxItems?: number, defaultTtlSeconds?: number}} options
+     */
+    constructor(options = {}) {
+        const maxItems = options.maxItems ?? 1000;
+        this._defaultTtlSeconds = options.defaultTtlSeconds ?? null;
+        this._lru = new LRU(maxItems);
+        /** @type {Map<string, Set<string>>} */
+        this._tagIndex = new Map();
+        this._now = () => Date.now();
+    }
+
+    async get(key) {
+        const entry = this._lru.get(key);
+        if (!entry) return undefined;
+        if (entry.expiresAt !== null && entry.expiresAt <= this._now()) {
+            this._removeKey(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+
+    async set(key, value, opts = {}) {
+        // Clean up any prior tag links for this key (re-set scenario)
+        const existing = this._lru.get(key);
+        if (existing && existing.tags) {
+            for (const t of existing.tags) {
+                const set = this._tagIndex.get(t);
+                if (set) {
+                    set.delete(key);
+                    if (set.size === 0) this._tagIndex.delete(t);
+                }
+            }
+        }
+
+        const ttl = opts.ttlSeconds ?? this._defaultTtlSeconds;
+        const expiresAt = ttl ? this._now() + ttl * 1000 : null;
+        const tags = opts.tags && opts.tags.length ? [...opts.tags] : null;
+
+        this._lru.set(key, {value, expiresAt, tags});
+
+        if (tags) {
+            for (const t of tags) {
+                let set = this._tagIndex.get(t);
+                if (!set) {
+                    set = new Set();
+                    this._tagIndex.set(t, set);
+                }
+                set.add(key);
+            }
+        }
+    }
+
+    async invalidateTags(tags) {
+        for (const t of tags) {
+            const set = this._tagIndex.get(t);
+            if (!set) continue;
+            for (const key of set) {
+                this._removeKey(key);
+            }
+        }
+    }
+
+    async clear() {
+        this._lru.clear();
+        this._tagIndex.clear();
+    }
+
+    _removeKey(key) {
+        const entry = this._lru.get(key);
+        if (entry && entry.tags) {
+            for (const t of entry.tags) {
+                const set = this._tagIndex.get(t);
+                if (set) {
+                    set.delete(key);
+                    if (set.size === 0) this._tagIndex.delete(t);
+                }
+            }
+        }
+        this._lru.delete(key);
+    }
+}
+```
+
+- [ ] **Step 4: Run tests, confirm pass**
+
+```
+node --test tests/services/cache/MemoryDriver.test.js
+```
+
+Expected: 8/8 pass.
+
+- [ ] **Step 5: Save**
+
+Suggested commit message: `feat(cache): add MemoryDriver with TTL and tag invalidation`
+
+---
+
+## Task 3: NoneDriver (dev/disabled mode)
+
+**Files:**
+- Create: `server/services/cache/drivers/NoneDriver.js`
+- Test: `tests/services/cache/NoneDriver.test.js`
+
+- [ ] **Step 1: Write the failing tests**
+
+```js
+// tests/services/cache/NoneDriver.test.js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {NoneDriver} from '../../../server/services/cache/drivers/NoneDriver.js';
+
+test('NoneDriver get always returns undefined', async () => {
+    const d = new NoneDriver();
+    await d.set('k', 'v');
+    assert.equal(await d.get('k'), undefined);
+});
+
+test('NoneDriver set is a no-op (does not throw)', async () => {
+    const d = new NoneDriver();
+    await d.set('k', 'v', {tags: ['t'], ttlSeconds: 60});
+});
+
+test('NoneDriver invalidateTags is a no-op', async () => {
+    const d = new NoneDriver();
+    await d.invalidateTags(['t']);
+});
+
+test('NoneDriver clear is a no-op', async () => {
+    const d = new NoneDriver();
+    await d.clear();
+});
+```
+
+- [ ] **Step 2: Run, confirm fail**
+
+```
+node --test tests/services/cache/NoneDriver.test.js
+```
+
+- [ ] **Step 3: Implement**
+
+```js
+// server/services/cache/drivers/NoneDriver.js
+/**
+ * Null driver - used when the cache is disabled.
+ * Every read misses; every write is dropped on the floor.
+ */
+export class NoneDriver {
+    async get()              { return undefined; }
+    async set()              { /* no-op */ }
+    async invalidateTags()   { /* no-op */ }
+    async clear()            { /* no-op */ }
+}
+```
+
+- [ ] **Step 4: Run, confirm pass**
+
+```
+node --test tests/services/cache/NoneDriver.test.js
+```
+
+Expected: 4/4 pass.
+
+- [ ] **Step 5: Save**
+
+Suggested commit message: `feat(cache): add NoneDriver for disabled/dev mode`
+
+---
+
+## Task 4: Cache facade (`services/cache/index.js`)
+
+**Files:**
+- Create: `server/services/cache/index.js`
+- Test: `tests/services/cache/index.test.js`
+
+The facade owns: the active driver instance, in-flight promise coalescing, and the `enabled` flag. It also normalises keys with a `v1:` version prefix so future schema bumps auto-invalidate.
+
+- [ ] **Step 1: Write the failing tests**
+
+```js
+// tests/services/cache/index.test.js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import * as cache from '../../../server/services/cache/index.js';
+
+test('initCache with enabled=false uses NoneDriver - wrap always calls producer', async () => {
+    await cache.initCache({enabled: false});
+    cache._resetForTests();
+    await cache.initCache({enabled: false});
+    let calls = 0;
+    const producer = async () => { calls++; return 'x'; };
+    await cache.wrap('k', producer);
+    await cache.wrap('k', producer);
+    assert.equal(calls, 2);
+    assert.equal(cache.isEnabled(), false);
+});
+
+test('initCache with driver=memory caches values', async () => {
+    cache._resetForTests();
+    await cache.initCache({enabled: true, driver: 'memory', memory: {maxItems: 10}});
+    let calls = 0;
+    const producer = async () => { calls++; return 'x'; };
+    const a = await cache.wrap('k', producer);
+    const b = await cache.wrap('k', producer);
+    assert.equal(a, 'x');
+    assert.equal(b, 'x');
+    assert.equal(calls, 1);
+});
+
+test('invalidateTags flushes wrapped values', async () => {
+    cache._resetForTests();
+    await cache.initCache({enabled: true, driver: 'memory', memory: {maxItems: 10}});
+    let calls = 0;
+    const producer = async () => { calls++; return 'x'; };
+    await cache.wrap('page:/a', producer, {tags: ['page:/a']});
+    await cache.invalidateTags(['page:/a']);
+    await cache.wrap('page:/a', producer, {tags: ['page:/a']});
+    assert.equal(calls, 2);
+});
+
+test('wrap coalesces concurrent calls for the same key', async () => {
+    cache._resetForTests();
+    await cache.initCache({enabled: true, driver: 'memory', memory: {maxItems: 10}});
+    let calls = 0;
+    const producer = async () => {
+        calls++;
+        await new Promise(r => setTimeout(r, 20));
+        return 'x';
+    };
+    const [a, b, c] = await Promise.all([
+        cache.wrap('k', producer),
+        cache.wrap('k', producer),
+        cache.wrap('k', producer),
+    ]);
+    assert.equal(a, 'x');
+    assert.equal(b, 'x');
+    assert.equal(c, 'x');
+    assert.equal(calls, 1);
+});
+
+test('clear flushes all entries', async () => {
+    cache._resetForTests();
+    await cache.initCache({enabled: true, driver: 'memory', memory: {maxItems: 10}});
+    await cache.set('k', 'v');
+    await cache.clear();
+    assert.equal(await cache.get('k'), undefined);
+});
+
+test('unknown driver name throws on init', async () => {
+    cache._resetForTests();
+    await assert.rejects(
+        () => cache.initCache({enabled: true, driver: 'snake-oil'}),
+        /Unknown cache driver/
+    );
+});
+```
+
+- [ ] **Step 2: Run, confirm fail**
+
+```
+node --test tests/services/cache/index.test.js
+```
+
+- [ ] **Step 3: Implement the facade**
+
+```js
+// server/services/cache/index.js
+import {MemoryDriver} from './drivers/MemoryDriver.js';
+import {NoneDriver} from './drivers/NoneDriver.js';
+
+const KEY_VERSION = 'v1:';
+
+let _driver = new NoneDriver();
+let _enabled = false;
+/** @type {Map<string, Promise<*>>} */
+const _inflight = new Map();
+
+/**
+ * @param {{
+ *   enabled?: boolean,
+ *   driver?: 'memory' | 'none' | 'redis',
+ *   memory?: {maxItems?: number, defaultTtlSeconds?: number},
+ *   redis?: {url: string, keyPrefix?: string}
+ * }} config
+ */
+export async function initCache(config = {}) {
+    if (config.enabled === false) {
+        _driver = new NoneDriver();
+        _enabled = false;
+        return;
+    }
+    const name = config.driver ?? 'memory';
+    if (name === 'memory') {
+        _driver = new MemoryDriver(config.memory ?? {});
+        _enabled = true;
+        return;
+    }
+    if (name === 'none') {
+        _driver = new NoneDriver();
+        _enabled = false;
+        return;
+    }
+    if (name === 'redis') {
+        // Dynamic import - keeps ioredis out of the free-tier require graph.
+        const {RedisDriver} = await import('./drivers/RedisDriver.js');
+        _driver = new RedisDriver(config.redis ?? {});
+        await _driver.connect();
+        _enabled = true;
+        return;
+    }
+    throw new Error(`Unknown cache driver: ${name}`);
+}
+
+export function isEnabled() {
+    return _enabled;
+}
+
+export async function get(key) {
+    return _driver.get(_vk(key));
+}
+
+export async function set(key, value, opts = {}) {
+    return _driver.set(_vk(key), value, opts);
+}
+
+export async function invalidateTags(tags) {
+    if (!Array.isArray(tags) || tags.length === 0) return;
+    return _driver.invalidateTags(tags);
+}
+
+export async function clear() {
+    _inflight.clear();
+    return _driver.clear();
+}
+
+/**
+ * Get-or-set with in-flight coalescing.
+ *
+ * @param {string} key
+ * @param {() => Promise<*>} producer
+ * @param {{ttlSeconds?: number, tags?: string[]}} [opts]
+ */
+export async function wrap(key, producer, opts = {}) {
+    if (!_enabled) return producer();
+
+    const vkey = _vk(key);
+    const hit = await _driver.get(vkey);
+    if (hit !== undefined) return hit;
+
+    if (_inflight.has(vkey)) return _inflight.get(vkey);
+
+    const promise = (async () => {
+        try {
+            const value = await producer();
+            await _driver.set(vkey, value, opts);
+            return value;
+        } finally {
+            _inflight.delete(vkey);
+        }
+    })();
+
+    _inflight.set(vkey, promise);
+    return promise;
+}
+
+function _vk(key) {
+    return KEY_VERSION + key;
+}
+
+export function _resetForTests() {
+    _driver = new NoneDriver();
+    _enabled = false;
+    _inflight.clear();
+}
+```
+
+- [ ] **Step 4: Run tests, confirm pass**
+
+```
+node --test tests/services/cache/index.test.js
+```
+
+Expected: 6/6 pass.
+
+- [ ] **Step 5: Save**
+
+Suggested commit message: `feat(cache): add cache facade with driver loading and in-flight coalescing`
+
+---
+
+## Task 5: Server bootstrap integration
+
+**Files:**
+- Modify: `server/server.js` - call `initCache(config.cache)` during startup, after config load but before route registration.
+- Modify: `server/config.js` - add `cache` to the config singleton with sensible defaults if `config/cache.json` is absent.
+- Create: `config/cache.json.example`
+
+- [ ] **Step 1: Add cache defaults to config loader**
+
+Locate `server/config.js`. Find the section that merges per-file configs into the singleton (search for `config.content` or similar). Add a `cache` block after the existing sections.
+
+```js
+// server/config.js - inside loadConfig() near other per-file merges
+import {readFileSync, existsSync} from 'fs';
+
+// ... existing code ...
+
+const cacheFile = path.join(ROOT, 'config/cache.json');
+const cacheDefaults = {
+    enabled: process.env.NODE_ENV === 'production',
+    driver: 'memory',
+    memory: {maxItems: 1000, defaultTtlSeconds: 3600}
+};
+config.cache = existsSync(cacheFile)
+    ? {...cacheDefaults, ...JSON.parse(readFileSync(cacheFile, 'utf8'))}
+    : cacheDefaults;
+```
+
+(The exact insertion point depends on the existing loader shape - read `server/config.js` first and place this alongside the `content` / `auth` / `site` merges. Match the style.)
+
+- [ ] **Step 2: Wire initCache into server boot**
+
+Open `server/server.js`. After `await loadConfig()` (or wherever the config is finalised) and before route registration, add:
+
+```js
+import * as cache from './services/cache/index.js';
+
+// ... in the startup async block, after config is loaded:
+await cache.initCache(config.cache);
+console.log(`[cache] driver=${cache.isEnabled() ? config.cache.driver : 'disabled'}`);
+```
+
+- [ ] **Step 3: Add the example config**
+
+```json
+// config/cache.json.example
+{
+  "enabled": true,
+  "driver": "memory",
+  "memory": {
+    "maxItems": 1000,
+    "defaultTtlSeconds": 3600
+  },
+  "redis": {
+    "url": "redis://localhost:6379",
+    "keyPrefix": "domma:"
+  }
+}
+```
+
+- [ ] **Step 4: Smoke-test the server starts and logs the cache state**
+
+```
+node server/server.js
+```
+
+Expected: console shows `[cache] driver=memory` (or `disabled` depending on NODE_ENV). No crash. Curl `/` and confirm the public site still renders normally - cache wrapping is not yet wired so behaviour is unchanged.
+
+- [ ] **Step 5: Save**
+
+Suggested commit message: `feat(cache): initialise cache from config on server startup`
+
+---
+
+## Task 6: Markdown pipeline returns tag set
+
+**Files:**
+- Modify: `server/services/markdown.js` - `parseMarkdown()` returns `{html, frontmatter, tags}` instead of `{html, frontmatter}` (or whatever the current shape is).
+- Test: `tests/services/markdown-tags.test.js`
+
+The simplest tag-collection approach: each shortcode pre-processor returns a tag list alongside its output. We accumulate them in a `tagSet` Set passed through the pipeline.
+
+Existing shortcode pre-processors (e.g. `processCarouselBlocks`, `processCollectionBlocks`, `processFormBlocks`) currently take and return a string. We add a second argument `tagSet` that they mutate.
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+// tests/services/markdown-tags.test.js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {parseMarkdown} from '../../server/services/markdown.js';
+
+test('parseMarkdown reports collection tag when [collection] is used', async () => {
+    const md = '---\ntitle: t\n---\n[collection slug="faq" display="cards" /]';
+    const result = await parseMarkdown(md);
+    assert.ok(result.tags.includes('collection:faq'), `expected collection:faq in ${result.tags}`);
+});
+
+test('parseMarkdown reports form tag when [form] is used', async () => {
+    const md = '---\ntitle: t\n---\n[form slug="contact" /]';
+    const result = await parseMarkdown(md);
+    assert.ok(result.tags.includes('form:contact'));
+});
+
+test('parseMarkdown reports block tag when [block] is used', async () => {
+    const md = '---\ntitle: t\n---\n[block name="hero-cta" /]';
+    const result = await parseMarkdown(md);
+    assert.ok(result.tags.includes('block:hero-cta'));
+});
+
+test('parseMarkdown reports view tag when [view] is used', async () => {
+    const md = '---\ntitle: t\n---\n[view slug="latest-posts" /]';
+    const result = await parseMarkdown(md);
+    assert.ok(result.tags.includes('view:latest-posts'));
+});
+
+test('parseMarkdown returns empty tag list for plain markdown', async () => {
+    const md = '---\ntitle: t\n---\nJust **plain** text.';
+    const result = await parseMarkdown(md);
+    assert.deepEqual(result.tags, []);
+});
+```
+
+- [ ] **Step 2: Run, confirm fail**
+
+```
+node --test tests/services/markdown-tags.test.js
+```
+
+- [ ] **Step 3: Update markdown.js shortcode processors**
+
+In `server/services/markdown.js`:
+
+1. Inside `parseMarkdown` (around the existing pipeline), create a `tagSet`:
+   ```js
+   const tagSet = new Set();
+   ```
+
+2. Pass `tagSet` into the existing collection/form/block/view shortcode processors. For each, find the regex match and `tagSet.add('<prefix>:' + attrs.slug)` (or `.name`):
+
+   - `processCollectionBlocks(md, tagSet)`: when handling each `[collection slug="..."]`, do `tagSet.add('collection:' + attrs.slug)`.
+   - `processFormBlocks(md, tagSet)`: `tagSet.add('form:' + attrs.slug)`.
+   - `processBlockShortcodes(md, tagSet)`: `tagSet.add('block:' + attrs.name)`.
+   - `processViewBlocks(md, tagSet)`: `tagSet.add('view:' + attrs.slug)`.
+
+   (The function names above are placeholders - match the exact processors already in `markdown.js`. Read the file and apply the pattern to each.)
+
+3. At the bottom of `parseMarkdown`, return:
+   ```js
+   return {html: finalHtml, frontmatter, tags: [...tagSet]};
+   ```
+
+4. Update any caller of `parseMarkdown` that destructures `{html}` to also tolerate the `tags` property (most callers ignore extra fields, so this is usually no change).
+
+- [ ] **Step 4: Run tests, confirm pass**
+
+```
+node --test tests/services/markdown-tags.test.js
+node --test tests/services/        # ensure no regressions in existing markdown tests
+```
+
+Expected: 5/5 new tests pass; existing tests unaffected.
+
+- [ ] **Step 5: Save**
+
+Suggested commit message: `feat(cache): markdown pipeline emits tag set for cache invalidation`
+
+---
+
+## Task 7: Wrap the public route through the cache
+
+**Files:**
+- Modify: `server/routes/public.js` - wrap the page render via `cache.wrap()`. Compose the cache key and tag list.
+- Modify: `server/services/renderer.js` - propagate `tags` from `parseMarkdown` up to the caller.
+
+The cache key includes URL path AND the visitor's role level (so role-gated pages don't leak across roles).
+
+- [ ] **Step 1: Propagate tags from renderer**
+
+Open `server/services/renderer.js`. Find where it calls `parseMarkdown`. Capture the returned `tags` and return them from the renderer function alongside the HTML.
+
+```js
+// before
+const {html, frontmatter} = await parseMarkdown(...);
+return {html: finalHtml, frontmatter};
+
+// after
+const {html, frontmatter, tags = []} = await parseMarkdown(...);
+return {html: finalHtml, frontmatter, tags};
+```
+
+- [ ] **Step 2: Wrap the route handler in public.js**
+
+In `server/routes/public.js`, find the route handler that serves public pages (the catch-all SSR). Replace the direct render call with a `cache.wrap()` call. The producer is the existing render function. Tags = page tag + collected tags + universal tags (`nav`, `site`).
+
+```js
+import * as cache from '../services/cache/index.js';
+
+// inside the public route handler, replacing the existing render:
+const roleLevel = request.user ? getRoleLevel(request.user.role) : null;
+const cacheKey = `page:${urlPath}:role${roleLevel ?? 'anon'}`;
+
+const {html, status} = await cache.wrap(
+    cacheKey,
+    async () => {
+        const rendered = await renderer.renderPage(urlPath, request.user);
+        return {
+            html: rendered.html,
+            status: rendered.status,
+            tags: [
+                `page:${urlPath}`,
+                ...rendered.tags,
+                'nav',
+                'site'
+            ]
+        };
+    },
+    // After producer runs, `wrap` calls set() with these opts. But we need
+    // tags from the producer result - see Step 3 for the fix.
+);
+```
+
+- [ ] **Step 3: Fix the chicken-and-egg with tags from producer**
+
+The producer returns the tags, but `wrap`'s `opts.tags` is read up front. Two options:
+
+**Option A (chosen - simpler):** Producer returns the value AND a separate `_cacheTags` field; `wrap` recognises it. Add a small extension to the facade:
+
+In `server/services/cache/index.js`, update `wrap` to read tags from a `_cacheTags` field on the producer return:
+
+```js
+const promise = (async () => {
+    try {
+        const value = await producer();
+        const setOpts = {...opts};
+        if (value && Array.isArray(value._cacheTags)) {
+            setOpts.tags = [...(opts.tags ?? []), ...value._cacheTags];
+            // Strip _cacheTags before storing so the cached value is clean
+            const {_cacheTags, ...clean} = value;
+            await _driver.set(vkey, clean, setOpts);
+            _inflight.delete(vkey);
+            return clean;
+        }
+        await _driver.set(vkey, value, setOpts);
+        return value;
+    } finally {
+        _inflight.delete(vkey);
+    }
+})();
+```
+
+Then in `public.js`, the producer returns `{html, status, _cacheTags: [...]}`.
+
+Add a test for `_cacheTags`:
+
+```js
+// append to tests/services/cache/index.test.js
+test('wrap reads producer._cacheTags and uses them for invalidation', async () => {
+    cache._resetForTests();
+    await cache.initCache({enabled: true, driver: 'memory', memory: {maxItems: 10}});
+    const producer = async () => ({payload: 'x', _cacheTags: ['some-tag']});
+    await cache.wrap('k', producer);
+    await cache.invalidateTags(['some-tag']);
+    let calls = 0;
+    const producer2 = async () => { calls++; return {payload: 'y'}; };
+    await cache.wrap('k', producer2);
+    assert.equal(calls, 1);
+});
+
+test('wrap strips _cacheTags from the cached and returned value', async () => {
+    cache._resetForTests();
+    await cache.initCache({enabled: true, driver: 'memory', memory: {maxItems: 10}});
+    const result = await cache.wrap('k', async () => ({a: 1, _cacheTags: ['t']}));
+    assert.equal(result._cacheTags, undefined);
+    assert.equal(result.a, 1);
+});
+```
+
+- [ ] **Step 4: Verify via curl that wrapping works**
+
+```
+curl -s -o /dev/null -w "First:  %{time_total}s\n" http://localhost:4096/
+curl -s -o /dev/null -w "Second: %{time_total}s\n" http://localhost:4096/
+```
+
+Expected: second request is meaningfully faster (cache hit). Run the test suite:
+
+```
+node --test tests/services/cache/
+```
+
+Expected: all pass including the two new tests for `_cacheTags`.
+
+- [ ] **Step 5: Save**
+
+Suggested commit message: `feat(cache): wrap public page renders through cache with role-keyed entries`
+
+---
+
+## Task 8: Invalidate page tag on content service writes
+
+**Files:**
+- Modify: `server/services/content.js` - call `cache.invalidateTags(['page:<urlPath>'])` after every page write/delete.
+- Test: `tests/services/cache/invalidation-integration.test.js`
+
+- [ ] **Step 1: Write the failing integration test**
+
+```js
+// tests/services/cache/invalidation-integration.test.js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import * as cache from '../../../server/services/cache/index.js';
+
+test('savePage invalidates page:<urlPath>', async () => {
+    cache._resetForTests();
+    await cache.initCache({enabled: true, driver: 'memory', memory: {maxItems: 10}});
+
+    let calls = 0;
+    const producer = async () => { calls++; return 'rendered'; };
+
+    // Prime the cache
+    await cache.wrap('page:/about:roleanon', producer, {tags: ['page:/about']});
+    await cache.wrap('page:/about:roleanon', producer, {tags: ['page:/about']});
+    assert.equal(calls, 1);
+
+    // Simulate the content service's invalidation hook
+    const {savePage} = await import('../../../server/services/content.js');
+    // NOTE: depends on existing content.js signature - adapt to actual.
+    await savePage('/about', {title: 'About', content: '...'});
+
+    // Next read should miss
+    await cache.wrap('page:/about:roleanon', producer, {tags: ['page:/about']});
+    assert.equal(calls, 2);
+});
+```
+
+(If `savePage` requires more setup than this, the test may need to mock the filesystem. In that case skip the integration test here and do it in Task 14 - verify manually via curl.)
+
+- [ ] **Step 2: Run, confirm fail**
+
+```
+node --test tests/services/cache/invalidation-integration.test.js
+```
+
+- [ ] **Step 3: Add the invalidation hook to content.js**
+
+Read `server/services/content.js`. Locate `savePage`, `deletePage`, and any other mutating function. Import the cache module at the top:
+
+```js
+import * as cache from './cache/index.js';
+```
+
+After each successful write/delete, add:
+
+```js
+// in savePage, after the file is written:
+await cache.invalidateTags([`page:${urlPath}`]);
+
+// in deletePage:
+await cache.invalidateTags([`page:${urlPath}`]);
+
+// in renamePage / movePage if such functions exist:
+await cache.invalidateTags([`page:${oldPath}`, `page:${newPath}`]);
+```
+
+- [ ] **Step 4: Run tests, confirm pass**
+
+```
+node --test tests/services/cache/invalidation-integration.test.js
+```
+
+- [ ] **Step 5: Save**
+
+Suggested commit message: `feat(cache): invalidate page cache on content service writes`
+
+---
+
+## Task 9: Invalidate collection tag on entry CRUD
+
+**Files:**
+- Modify: `server/services/collections.js` - call `cache.invalidateTags(['collection:<slug>'])` after entry create/update/delete and after schema change.
+
+- [ ] **Step 1: Inspect collections.js for write functions**
+
+Read `server/services/collections.js`. Identify all entry-mutating functions (`createEntry`, `updateEntry`, `deleteEntry`, `clearEntries`, `importEntries`) and schema-mutating functions (`updateCollection`).
+
+- [ ] **Step 2: Add invalidation calls**
+
+At the top of the file:
+```js
+import * as cache from './cache/index.js';
+```
+
+After each successful entry mutation:
+```js
+await cache.invalidateTags([`collection:${slug}`]);
+```
+
+After a schema mutation (the schema affects rendered output, e.g. `[collection]` cards):
+```js
+await cache.invalidateTags([`collection:${slug}`]);
+```
+
+Also after `clearEntries(slug)` and `importEntries(slug, ...)`.
+
+- [ ] **Step 3: Manual smoke test**
+
+```
+# In one terminal:
+node server/server.js
+
+# In another:
+# 1. Curl a page that contains [collection slug="faq" display="cards"]
+curl -s http://localhost:4096/faq | grep -c "faq-item"
+# Note the count.
+
+# 2. Add an entry via admin or via the API:
+curl -X POST http://localhost:4096/api/collections/faq/entries \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"title": "New Q", "description": "..."}'
+
+# 3. Curl the same page again - count should have increased
+curl -s http://localhost:4096/faq | grep -c "faq-item"
+```
+
+Expected: new entry visible immediately, no stale cached HTML.
+
+- [ ] **Step 4: Save**
+
+Suggested commit message: `feat(cache): invalidate collection cache on entry/schema mutations`
+
+---
+
+## Task 10: Invalidate forms, blocks, views, nav, settings
+
+**Files:**
+- Modify: `server/services/forms.js` - `cache.invalidateTags(['form:' + slug])` on save/delete.
+- Modify: `server/services/blocks.js` - `cache.invalidateTags(['block:' + name])` on save/delete.
+- Modify: `server/services/views.js` - `cache.invalidateTags(['view:' + slug])` on save/delete.
+- Modify: `server/routes/api/navigation.js` - `cache.invalidateTags(['nav'])` on PUT (nav appears on every page, so this flushes most of the cache).
+- Modify: `server/routes/api/settings.js` - `cache.invalidateTags(['site'])` on PUT (likewise universal).
+
+For each file: import `* as cache from '...services/cache/index.js'` at the top, then add a single `await cache.invalidateTags([...])` after each successful write.
+
+- [ ] **Step 1: Update each file with the appropriate hook**
+
+(Plain mechanical edits - same pattern in each. Match the exact location of the write completion in each file.)
+
+- [ ] **Step 2: Smoke test each**
+
+```
+# After saving a form, fetch a page that embeds [form slug="contact"]:
+curl -X PUT http://localhost:4096/api/plugins/form-builder/forms/contact ...
+curl -s http://localhost:4096/contact-page | grep "form-id"
+
+# Repeat for blocks, views, nav, settings.
+```
+
+- [ ] **Step 3: Save**
+
+Suggested commit message: `feat(cache): invalidate form, block, view, nav, and site tags on writes`
+
+---
+
+## Task 11: Admin "Clear cache" endpoint + button
+
+**Files:**
+- Create: `server/routes/api/cache.js` - POST /api/cache/clear, GET /api/cache/status.
+- Modify: `server/server.js` - register the new route file.
+- Modify: `admin/js/views/settings.js` (or wherever the system actions live) - add a "Clear cache" button.
+- Modify: `admin/js/templates/settings.html` - markup for the button.
+
+- [ ] **Step 1: Create the API route file**
+
+```js
+// server/routes/api/cache.js
+import * as cache from '../../services/cache/index.js';
+import {requireAdmin} from '../../middleware/auth.js';
+
+export default async function cacheRoutes(app) {
+    app.post('/api/cache/clear', {preHandler: [app.authenticate, requireAdmin]}, async () => {
+        await cache.clear();
+        return {ok: true};
+    });
+
+    app.get('/api/cache/status', {preHandler: [app.authenticate, requireAdmin]}, async () => {
+        return {enabled: cache.isEnabled()};
+    });
+}
+```
+
+- [ ] **Step 2: Register the route in server.js**
+
+In `server/server.js`, next to the other route registrations, add:
+
+```js
+import cacheRoutes from './routes/api/cache.js';
+// ...
+await app.register(cacheRoutes);
+```
+
+- [ ] **Step 3: Add the admin button**
+
+In the settings template, add a card with a clear-cache button:
+
+```html
+<!-- admin/js/templates/settings.html - in the system/maintenance section -->
+<div class="card mb-4">
+    <div class="card-header"><span data-icon="trash"></span> Cache</div>
+    <div class="card-body">
+        <p class="text-muted">Clear all cached page responses. The next visitor to each page will trigger a fresh render.</p>
+        <button id="btn-clear-cache" class="btn btn-secondary" type="button">Clear cache</button>
+    </div>
+</div>
+```
+
+In `admin/js/views/settings.js`, wire the click:
+
+```js
+$container.find('#btn-clear-cache').on('click', async () => {
+    if (!await E.confirm('Clear the entire response cache?')) return;
+    try {
+        await H.post('/api/cache/clear');
+        E.toast('Cache cleared.', {type: 'success'});
+    } catch (err) {
+        E.toast('Failed to clear cache: ' + err.message, {type: 'error'});
+    }
+});
+```
+
+- [ ] **Step 4: Verify in the browser**
+
+Navigate to Settings, click "Clear cache", confirm the toast. Curl a page before and after to confirm the producer ran fresh.
+
+- [ ] **Step 5: Save**
+
+Suggested commit message: `feat(cache): add admin clear-cache endpoint and settings button`
+
+---
+
+## Task 12: Documentation
+
+**Files:**
+- Create: `docs/cache.md`
+- Modify: `docs/configuration.md` - add section linking to cache docs.
+- Modify: `CLAUDE.md` - add the cache service to the Core Services table.
+
+- [ ] **Step 1: Write docs/cache.md**
+
+```markdown
+# Caching
+
+Domma CMS caches assembled public page responses to skip the markdown→shortcode→template pipeline on subsequent hits. The cache is on by default in production (`NODE_ENV=production`) and off in development.
+
+## Config
+
+`config/cache.json` (optional - absent means use defaults):
+
+```json
+{
+  "enabled": true,
+  "driver": "memory",
+  "memory": { "maxItems": 1000, "defaultTtlSeconds": 3600 },
+  "redis": { "url": "redis://localhost:6379", "keyPrefix": "domma:" }
+}
+```
+
+- `enabled: false` short-circuits every read to the producer - useful in dev.
+- `driver`: `"memory"` (default, in-process LRU), `"none"` (same as `enabled: false`), or `"redis"` (requires `redis` in `optionalDependencies` - Pro feature).
+
+## What gets cached
+
+Public page HTML responses, keyed by `page:<urlPath>:role<level>`. Admin API responses are never cached.
+
+## What invalidates
+
+Tag-based. When an admin saves a page, only entries tagged `page:<that-url>` are flushed - not the whole cache. Tags:
+
+- `page:<urlPath>` - flushed on page save/delete/rename
+- `collection:<slug>` - flushed on entry CRUD or schema change
+- `form:<slug>` - flushed on form save
+- `block:<name>` - flushed on block save
+- `view:<slug>` - flushed on view save
+- `nav` - flushed on navigation update (touches every page)
+- `site` - flushed on site settings save (touches every page)
+
+The markdown pipeline auto-attaches the appropriate tags as it processes shortcodes - embedding `[collection slug="faq"]` causes the rendered page to be tagged `collection:faq`, so a FAQ entry edit transparently busts every page that displays the FAQ.
+
+## Manual flush
+
+Settings → Cache → "Clear cache". Or:
+
+```
+curl -X POST http://localhost:4096/api/cache/clear -H "Authorization: Bearer <admin-token>"
+```
+
+## Adding a new shortcode that needs invalidation
+
+In the markdown pipeline, when handling your new shortcode, `tagSet.add('<prefix>:' + attrs.id)`. Then in the corresponding service, add `await cache.invalidateTags(['<prefix>:' + id])` after every write. Done - no central registry to update.
+```
+
+- [ ] **Step 2: Add row to CLAUDE.md core services table**
+
+Open `CLAUDE.md` (the project root one). Find the "Core Services" section, and add a row:
+
+```
+| `cache/index.js`        | Pluggable response cache (Memory/None/Redis drivers) with tag-based invalidation |
+```
+
+Mention it briefly in the architecture overview alongside `adapterRegistry.js`.
+
+- [ ] **Step 3: Save**
+
+Suggested commit message: `docs(cache): document cache config, tags, and invalidation`
+
+---
+
+## Task 13 (stretch - separate decision): RedisDriver
+
+Deferred until someone actually needs multi-instance deploys. Not required for v1. When required:
+
+- Add `redis` (the official `redis` package - async/await-native) to `optionalDependencies`.
+- Implement `RedisDriver` mirroring `MemoryDriver`'s API. Use Redis SETs for the tag index (`SADD tag:<name> <key>`; `SMEMBERS tag:<name>` + `DEL` chain for `invalidateTags`).
+- Use Redis `EXPIRE` for TTLs.
+- Test with a real Redis instance (`docker run -d -p 6379:6379 redis:7-alpine`) - write the test file but mark with `skip` if `REDIS_URL` is not set.
+
+(Skeleton, not for implementation in this plan:)
+
+```js
+// server/services/cache/drivers/RedisDriver.js
+export class RedisDriver {
+    constructor(options = {}) {
+        this._url = options.url;
+        this._keyPrefix = options.keyPrefix ?? 'domma:';
+        this._client = null;
+    }
+    async connect() {
+        const {createClient} = await import('redis');
+        this._client = createClient({url: this._url});
+        await this._client.connect();
+    }
+    async get(key) { /* GET keyPrefix + key, JSON.parse */ }
+    async set(key, value, opts) { /* SET + EXPIRE + SADD for each tag */ }
+    async invalidateTags(tags) { /* SMEMBERS each, DEL keys, DEL tag set */ }
+    async clear() { /* SCAN + DEL with keyPrefix */ }
+}
+```
+
+---
+
+## Task 14: End-to-end verification
+
+**Files:** none (manual)
+
+After all prior tasks land, run through the full happy path:
+
+- [ ] **Step 1: Start the server in production mode**
+
+```
+NODE_ENV=production node server/server.js
+```
+
+Confirm log shows `[cache] driver=memory`.
+
+- [ ] **Step 2: Verify cold/warm performance gap**
+
+```
+curl -s -o /dev/null -w "Cold:  %{time_total}s\n" http://localhost:4096/
+curl -s -o /dev/null -w "Warm:  %{time_total}s\n" http://localhost:4096/
+curl -s -o /dev/null -w "Warm:  %{time_total}s\n" http://localhost:4096/
+```
+
+Expected: cold render is meaningfully slower than warm hits (depends on page complexity but typically 20-50ms cold vs <5ms warm).
+
+- [ ] **Step 3: Verify each invalidation path**
+
+For each of: page edit, collection entry add, form save, block save, view save, nav save, site settings save - change the underlying thing, immediately curl the affected page, confirm the new content appears without delay.
+
+- [ ] **Step 4: Verify dev mode bypass**
+
+```
+NODE_ENV=development node server/server.js
+```
+
+Confirm `[cache] driver=disabled`. Curl twice, both should hit the producer (you can verify by adding a temporary `console.log` in the renderer).
+
+- [ ] **Step 5: Verify admin button flushes**
+
+Settings → Clear cache. Curl returns fresh content on next request.
+
+- [ ] **Step 6: Run the full test suite**
+
+```
+node --test tests/
+```
+
+Expected: all green; no regressions in existing tests.
+
+---
+
+## Self-Review Notes
+
+- **Spec coverage:** Plugin-vs-core ✓ (Task 1-4 build the core service). Memory/none/redis drivers ✓ (Tasks 2/3/13). Tag-based invalidation ✓ (Tasks 6 + 8-10). Dev toggle ✓ (Task 5 + Task 14 step 4). Admin flush button ✓ (Task 11). Docs ✓ (Task 12).
+- **Type consistency:** Every task uses `cache.invalidateTags(tags: string[])` and `cache.wrap(key: string, producer, opts)`. The `_cacheTags` convention is introduced in Task 7 and only used in Task 7.
+- **Placeholders:** none - every code block is complete.
+- **Project rule respected:** no `git commit` instructions; each task ends with a "save" step and a suggested commit message.
+- **What's deferred:** stale-while-revalidate (not v1), per-route TTL overrides, cache statistics endpoint, RedisDriver implementation.