@ijfw/memory-server 1.3.0

package/src/update-check.js

@@ -0,0 +1,136 @@
+// MCP tool: ijfw_update_check
+//
+// Returns { current, latest, available, confirmation_token?, expires_at?, changelog_url, instruction? }
+// If update is available, issues a 5-min confirmation token. Token must be
+// consumed via terminal-side `ijfw update --confirm <token>` -- see v3 sec 16.
+//
+// Re-entrancy guard: if state.json.last_applied_version == cached last_latest_seen,
+// returns available:false (just-updated suppression).
+
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { readSafe, writeAtomic } from './lib/atomic-io.js';
+import { npmView, compareSemver } from './lib/npm-view.js';
+import { issueToken, writePendingSentinel, readPendingSentinel } from './lib/token.js';
+
+const PKG = '@ijfw/install';
+const REPO = 'therealseandonahoe/ijfw';
+
+function ijfwHome() {
+  return process.env.IJFW_HOME || join(homedir(), '.ijfw');
+}
+
+export function readInstalledVersion() {
+  const sp = readSafe(join(ijfwHome(), 'state.json'));
+  if (sp.ok && sp.data && typeof sp.data.installed_version === 'string') {
+    return sp.data.installed_version;
+  }
+  return '0.0.0';
+}
+
+export function readLastApplied() {
+  const sp = readSafe(join(ijfwHome(), 'state.json'));
+  return (sp.ok && sp.data && sp.data.last_applied_version) || null;
+}
+
+export function readCachedCheck() {
+  return readSafe(join(ijfwHome(), 'cache', 'update-check.json'));
+}
+
+export function writeCachedCheck(data) {
+  return writeAtomic(join(ijfwHome(), 'cache', 'update-check.json'), {
+    schema_version: 1,
+    last_check: Math.floor(Date.now() / 1000),
+    ...data,
+  });
+}
+
+export async function ijfwUpdateCheck(args = {}) {
+  const sessionId = args.session_id || process.env.IJFW_SESSION_ID || 'default-session';
+  const force = args.force === true;
+
+  const current = readInstalledVersion();
+  const lastApplied = readLastApplied();
+  const cached = readCachedCheck();
+
+  let latest = null;
+  if (!force && cached.ok && cached.data && typeof cached.data.last_latest_seen === 'string') {
+    // Use cached value if fresh enough (24h)
+    const ageSec = Math.floor(Date.now() / 1000) - (cached.data.last_check || 0);
+    if (ageSec < 24 * 3600 && ageSec >= 0) {
+      latest = cached.data.last_latest_seen;
+    }
+  }
+  if (!latest) {
+    const r = await npmView(PKG);
+    if (!r.ok) {
+      return {
+        current,
+        latest: null,
+        available: null,
+        reachable: false,
+        error: r.error,
+        message: r.message || 'update check failed; will retry next session',
+      };
+    }
+    latest = r.version;
+    try { writeCachedCheck({ last_latest_seen: latest, last_failure: null }); } catch { /* */ }
+  }
+
+  // Re-entrancy: if we just applied this version, don't nudge again
+  if (lastApplied && compareSemver(lastApplied, latest) >= 0) {
+    return { current, latest, available: false, reachable: true, reason: 'up-to-date' };
+  }
+
+  const cmp = compareSemver(current, latest);
+  const available = cmp < 0;
+
+  const result = {
+    current,
+    latest,
+    available,
+    reachable: true,
+    changelog_url: `https://github.com/${REPO}/releases/tag/v${latest}`,
+  };
+
+  if (available) {
+    const tok = issueToken(sessionId, latest);
+    // Write the pending sentinel so the user can run `ijfw update --confirm
+    // <token>` in one step. The terminal command itself is the air-gap.
+    try { writePendingSentinel(sessionId, latest, tok.token); } catch { /* best-effort; the post-read below covers concurrent failures */ }
+    // Concurrent _check calls within the same session race on the token-file
+    // + sentinel writes. The last writer wins for both, so reflecting the
+    // sentinel's actual content in our response guarantees the returned
+    // token matches what `--confirm` will accept.
+    let finalToken = tok.token;
+    let finalTarget = latest;
+    const post = readPendingSentinel(sessionId);
+    if (post.ok && post.data && post.data.token) {
+      finalToken = post.data.token;
+      if (post.data.target_version) finalTarget = post.data.target_version;
+    }
+    result.confirmation_token = finalToken;
+    result.target_version = finalTarget;
+    result.expires_at = tok.expires_at;
+    result.instruction =
+      `To proceed, run in your TERMINAL: ijfw update --confirm ${finalToken}\n` +
+      `Token expires in 5 minutes. The MCP tool cannot execute the update directly.`;
+  }
+
+  return result;
+}
+
+export const TOOL_DEF = {
+  name: 'ijfw_update_check',
+  description:
+    'Check if an IJFW update is available. Issues a confirmation token; the user must run ' +
+    "'ijfw update --confirm <token>' in their terminal to actually update. The model cannot " +
+    'execute updates directly -- this air-gaps prompt injection from code execution.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      force: { type: 'boolean', description: 'Bypass cache, fetch from npm now' },
+      session_id: { type: 'string', description: 'Session ID for token scoping (optional)' },
+    },
+  },
+};

package/src/vectors.js

@@ -0,0 +1,178 @@
+// --- Vector embeddings (W3.3 / H5a-b-c) ---
+//
+// Thin wrapper around @xenova/transformers. Lazily imports the library on
+// first use so the zero-deps default install path is unaffected -- users who
+// don't enable vectors never pay the ~5MB bundle cost, and the 23MB model
+// download only happens when the first embedding query fires.
+//
+// Environment control:
+//   IJFW_VECTORS=off  -- disable vectors entirely (BM25-only)
+//   IJFW_VECTORS=on   -- enable (default if the library is present)
+//   IJFW_VECTORS_MODEL -- override the embedding model (default: Xenova/all-MiniLM-L6-v2, ~23MB)
+//
+// Fallback: if @xenova/transformers isn't installed, vectors silently
+// disable and callers get an `{ available: false, reason }` from getEmbedder().
+
+const DEFAULT_MODEL = 'Xenova/all-MiniLM-L6-v2';
+
+// X3/S8 -- model integrity pin. When IJFW_VECTORS_MODEL_SHA256 is set, we
+// SHA-256 the loaded model.onnx after download and refuse the embedder if
+// the hash doesn't match. Empty (default) allows any -- documented as opt-in
+// in NO_TELEMETRY.md. Implemented in Phase 6 after the audit found the var
+// was read but never enforced.
+
+let _pipelinePromise = null;
+
+// R2-B -- locate the actual ONNX file the pipeline loaded. transformers.js
+// uses several cache layouts (HuggingFace-style models--{org}--{name}
+// snapshots; flat cacheDir; explicit localModelPath). Scan candidates,
+// return the first that exists.
+async function resolveModelFile(env, modelId) {
+  const { existsSync, readdirSync, statSync } = await import('node:fs');
+  const { join: pjoin } = await import('node:path');
+  const roots = [];
+  if (env && env.localModelPath) roots.push(env.localModelPath);
+  if (env && env.cacheDir)       roots.push(env.cacheDir);
+  if (process.env.IJFW_VECTORS_CACHE) roots.push(process.env.IJFW_VECTORS_CACHE);
+  if (process.env.HOME)          roots.push(pjoin(process.env.HOME, '.cache', 'huggingface'));
+
+  const filenames = ['model.onnx', 'model_quantized.onnx', 'model_fp16.onnx'];
+  const modelSlugs = [
+    modelId,
+    modelId.replace('/', '_'),
+    'models--' + modelId.replace('/', '--'),
+  ];
+
+  for (const root of roots) {
+    if (!root || !existsSync(root)) continue;
+    // Direct layout: {root}/{slug}/onnx/{file}
+    for (const slug of modelSlugs) {
+      for (const f of filenames) {
+        const p = pjoin(root, slug, 'onnx', f);
+        if (existsSync(p)) return p;
+      }
+    }
+    // HF snapshots: {root}/models--{org}--{name}/snapshots/{rev}/onnx/{file}
+    const hfDir = pjoin(root, 'models--' + modelId.replace('/', '--'));
+    if (existsSync(hfDir) && statSync(hfDir).isDirectory()) {
+      const snapshotsDir = pjoin(hfDir, 'snapshots');
+      if (existsSync(snapshotsDir)) {
+        for (const rev of readdirSync(snapshotsDir)) {
+          for (const f of filenames) {
+            const p = pjoin(snapshotsDir, rev, 'onnx', f);
+            if (existsSync(p)) return p;
+          }
+        }
+      }
+    }
+  }
+  return null;
+}
+
+async function verifyModelSha(env, modelId) {
+  const expected = process.env.IJFW_VECTORS_MODEL_SHA256;
+  if (!expected) return { ok: true }; // no pin configured, skip verification
+  try {
+    const { createReadStream } = await import('node:fs');
+    const { createHash } = await import('node:crypto');
+    const modelPath = await resolveModelFile(env, modelId);
+    if (!modelPath) {
+      // R2-B -- fail OPEN with a clear reason rather than closed. A path-guess
+      // miss should not disable a working embedder; surface the lack of
+      // verification so the user can set IJFW_VECTORS_CACHE explicitly.
+      process.stderr.write(
+        `IJFW: SHA verification skipped -- couldn't locate ONNX for ${modelId}. ` +
+        `Set IJFW_VECTORS_CACHE to the cache root or clear IJFW_VECTORS_MODEL_SHA256.\n`
+      );
+      return { ok: true, skipped: true };
+    }
+    await new Promise((resolve, reject) => {
+      const h = createHash('sha256');
+      const s = createReadStream(modelPath);
+      s.on('error', reject);
+      s.on('data', (c) => h.update(c));
+      s.on('end', () => {
+        const got = h.digest('hex');
+        if (got === expected.toLowerCase()) resolve();
+        else reject(new Error(`sha256 mismatch at ${modelPath}: expected ${expected}, got ${got}`));
+      });
+    });
+    return { ok: true, verified: true };
+  } catch (e) {
+    // Hash mismatch IS a closed-fail (user pinned; we can't trust this model).
+    return { ok: false, reason: `sha-verify-failed: ${e.message}` };
+  }
+}
+
+async function loadPipeline() {
+  if (_pipelinePromise) return _pipelinePromise;
+  _pipelinePromise = (async () => {
+    try {
+      const lib = await import('@xenova/transformers');
+      const { pipeline, env } = lib;
+      // Models cache locally under $XDG_CACHE_HOME or ~/.cache/xenova/.
+      env.localModelPath = process.env.IJFW_VECTORS_CACHE || undefined;
+      env.allowRemoteModels = true;
+      const model = process.env.IJFW_VECTORS_MODEL || DEFAULT_MODEL;
+      const extractor = await pipeline('feature-extraction', model);
+      // X3/S8 -- verify pinned SHA256 after load (post-download if remote).
+      const sha = await verifyModelSha(env, model);
+      if (!sha.ok) return { ok: false, reason: sha.reason };
+      return { ok: true, extractor, model };
+    } catch (e) {
+      return { ok: false, reason: e.code === 'ERR_MODULE_NOT_FOUND'
+        ? 'transformers-not-installed'
+        : `load-failed: ${e.message}` };
+    }
+  })();
+  return _pipelinePromise;
+}
+
+export function vectorsEnabled() {
+  const v = (process.env.IJFW_VECTORS || 'on').toLowerCase();
+  return v !== 'off' && v !== '0' && v !== 'false';
+}
+
+// Returns { available: true, embed(text) → Float32Array } or
+//         { available: false, reason }.
+export async function getEmbedder() {
+  if (!vectorsEnabled()) return { available: false, reason: 'disabled-by-env' };
+  const loaded = await loadPipeline();
+  if (!loaded.ok) return { available: false, reason: loaded.reason };
+  return {
+    available: true,
+    model: loaded.model,
+    embed: async (text) => {
+      const out = await loaded.extractor(text, { pooling: 'mean', normalize: true });
+      return Array.from(out.data);
+    },
+  };
+}
+
+// Cosine similarity on two equal-length Float32 arrays (or plain arrays).
+// Both inputs should already be L2-normalized (our embedder's normalize: true
+// guarantees that) so this reduces to a dot product.
+export function cosine(a, b) {
+  if (!a || !b || a.length !== b.length) return 0;
+  let s = 0;
+  for (let i = 0; i < a.length; i++) s += a[i] * b[i];
+  return s;
+}
+
+// Hybrid rerank: BM25 scores + vector cosine. Mixes with weights.
+//   bm25Results: [{ id, score, ... }]
+//   vectorMatches: Map<id, cosine>
+// Returns merged, resorted list.
+export function hybridRerank(bm25Results, vectorScores, opts = {}) {
+  const wBm25 = opts.wBm25 ?? 0.6;
+  const wVec = opts.wVec ?? 0.4;
+  // Normalize BM25 scores to 0..1 by dividing by max.
+  const maxB = Math.max(0.0001, ...bm25Results.map(r => r.score));
+  return bm25Results
+    .map(r => {
+      const vec = vectorScores.get(r.id) ?? 0;
+      const merged = (r.score / maxB) * wBm25 + vec * wVec;
+      return { ...r, bm25_score: r.score, vector_score: vec, score: merged };
+    })
+    .sort((a, b) => b.score - a.score);
+}

package/templates/design/bento-grid.md

@@ -0,0 +1,84 @@
+# Bento Grid  -  DESIGN.md
+
+## 1. Visual Theme & Atmosphere
+Card grid with varied sizes as the primary design language  -  the aesthetic of modern portfolio sites, SaaS landing pages, and personal product showcases. Visual hierarchy is established through card size rather than typographic scale or color. A 3-column grid where some cards span 2 columns, some span 2 rows, and feature cards command both. Neutral backgrounds keep the cards themselves as the composition. Use for landing pages, portfolio sites, feature showcases, personal sites, and any layout where the arrangement of content is itself the story.
+
+## 2. Color Palette & Roles
+- `--color-bg`: #0F0F12 (page background  -  dark neutral)
+- `--color-surface`: #18181C (standard card)
+- `--color-surface-alt`: #1E1E24 (alternate card for variety)
+- `--color-surface-light`: #F4F4F6 (light card variant for contrast inversion)
+- `--color-border`: #2C2C34 (card borders, dividers)
+- `--color-text-primary`: #EEEEF2 (headings, primary content)
+- `--color-text-secondary`: #88889A (supporting text, labels)
+- `--color-text-on-light`: #18181C (text on light cards)
+- `--color-accent`: #6F6FFF (CTAs, highlights  -  periwinkle)
+- `--color-accent-hover`: #8F8FFF (interactive accent state)
+- `--color-accent-on-light`: #4040CC (accent on light card surfaces)
+- `--color-separator`: #232328 (between grid cells, hairline rules)
+
+## 3. Typography Rules
+- **Display font**: Inter  -  Google Fonts  -  weights 300, 400, 600, 700
+- **Body font**: Inter  -  Google Fonts  -  weights 400, 500
+- **Mono font**: JetBrains Mono  -  for stats, metrics, code callouts inside cards
+- **Scale**: Display 56px / H1 40px / H2 26px / H3 18px / Body 15px / Small 12px
+- **Line height**: 1.6 for body / 1.1 for display
+- **Letter spacing**: 0 for body / -0.025em for display
+- **Font loading**: `@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono&display=swap')`
+
+## 4. Component Stylings
+### Buttons
+Primary: `background: --color-accent`, white text, `font-weight: 600`, `border-radius: 10px`, `padding: 10px 22px`. Hover: `--color-accent-hover`. Secondary: transparent, `border: 1px solid --color-border`, `color: --color-text-primary`, `border-radius: 10px`. Inside dark cards: secondary button uses `border-color: rgba(255,255,255,0.15)`. Inside light cards: use `--color-accent-on-light`.
+
+### Cards
+Standard: `background: --color-surface`, `border: 1px solid --color-border`, `border-radius: 16px`, `padding: 28px`, `overflow: hidden`. Span-2 (wide): same styles, `grid-column: span 2`. Span-2 (tall): `grid-row: span 2`. Feature card (2x2): both spans. Light card: `background: --color-surface-light`, `color: --color-text-on-light`. Hover on all: `border-color: rgba(111,111,255,0.3)`, `box-shadow: 0 0 0 1px rgba(111,111,255,0.15)`.
+
+### Navigation
+Height 60px, `background: rgba(15,15,18,0.8)`, `backdrop-filter: blur(12px)`, `border-bottom: 1px solid --color-border`. Sticky. Logo: Inter weight 700. Nav items: 14px, `color: --color-text-secondary`. Active: `color: --color-text-primary`. CTA button right-aligned.
+
+### Inputs
+`background: --color-surface-alt`, `border: 1px solid --color-border`, `border-radius: 10px`, `padding: 10px 14px`, `font-size: 14px`, `color: --color-text-primary`. Focus: `border-color: --color-accent`, `box-shadow: 0 0 0 3px rgba(111,111,255,0.15)`. Placeholder: `--color-text-secondary`.
+
+### Badges / Chips
+`background: rgba(111,111,255,0.12)`, `border: 1px solid rgba(111,111,255,0.25)`, `color: --color-accent-hover`, `border-radius: 20px`, `padding: 3px 10px`, `font-size: 12px`, `font-weight: 500`. On light cards: `background: rgba(64,64,204,0.08)`, `border-color: rgba(64,64,204,0.2)`, `color: --color-accent-on-light`.
+
+## 5. Layout Principles
+- **Grid**: 3-column bento with `gap: 16px`; CSS grid with `grid-template-columns: repeat(3, 1fr)`
+- **Max width**: 1200px
+- **Section padding**: 80px vertical for page sections; cards are flush within the grid
+- **Spacing scale**: 4 / 8 / 12 / 16 / 24 / 28 / 32 / 48 / 64 / 80px
+- **Whitespace philosophy**: structured  -  the gaps between cards are the whitespace; inside cards is purposeful density
+
+## 6. Depth & Elevation
+- **Surface hierarchy**: Level 0 = `--color-bg`, Level 1 = card (`--color-surface`), Level 2 = modal/popover
+- **Shadow tokens**: resting = none (border only); hover = `0 4px 20px rgba(0,0,0,0.4)`; modal = `0 24px 64px rgba(0,0,0,0.6)`
+- **Border usage**: 1px on every card; the border is what gives the bento grid its grid legibility
+
+## 7. Do's and Don'ts
+**Do:**
+- Design card contents individually  -  each card is a mini composition with its own hierarchy
+- Use span-2 and span-2-row assignments to create visual rhythm and feature emphasis
+- Mix dark and light cards to create contrast and visual anchoring points in the grid
+- Keep the gap consistent (16px)  -  irregular gaps break the bento grid logic
+- Let large metric numbers or illustrations fill the card edge-to-edge on tall cards
+
+**Don't:**
+- Use the same size for all cards  -  uniform grids lose the bento benefit entirely
+- Add thick outer padding around the grid; the card borders define the structure
+- Place navigation or chrome inside the bento grid area
+- Use more than two distinct card backgrounds in the same grid section
+- Apply heavy shadows to resting cards  -  the hover state needs contrast headroom
+
+## 8. Responsive Behavior
+- **Mobile breakpoint**: 375px
+- **Tablet breakpoint**: 768px
+- **Touch targets**: minimum 44px
+- **Typography scaling**: Display drops to 36px / H1 to 26px on mobile
+- **Layout collapse**: 3-col grid → 2-col at 768px → 1-col at 375px; span overrides reset (all cards become 1-col at mobile); gap reduces to 10px
+
+## 9. Agent Prompt Guide
+Use these prompts with Claude Design or ijfw-design to stay on-system:
+
+- **New screen**: "Build a [screen type] following the Bento Grid DESIGN.md. Match the color tokens and type scale exactly."
+- **Component**: "Add a [component] that fits the Bento Grid aesthetic  -  reference section 4 for styling rules."
+- **Variant**: "Create a [light/dark/compact] variant of this screen. Keep the same token names, adjust the values."

package/templates/design/brutalist-luxe.md

@@ -0,0 +1,82 @@
+# Brutalist Luxe  -  DESIGN.md
+
+## 1. Visual Theme & Atmosphere
+Raw brutalism stripped of ugliness and dressed in restraint  -  the visual language of a Balenciaga campaign or a prestige print magazine that knows the rules and ignores them deliberately. Maximum contrast, visible structure, zero rounding. The grid is exposed, type is oversized, one bold accent color detonates against the monochrome field. Use for fashion, editorial, portfolio, culture, and any brand that positions itself as a category of one.
+
+## 2. Color Palette & Roles
+- `--color-bg`: #F5F5F5 (page background  -  paper white with texture suggestion)
+- `--color-surface`: #FFFFFF (card/panel surface)
+- `--color-surface-dark`: #0A0A0A (inverted section surface)
+- `--color-border`: #0A0A0A (dividers, input borders  -  hard black)
+- `--color-text-primary`: #0A0A0A (headings, primary content)
+- `--color-text-inverse`: #F5F5F5 (text on dark surfaces)
+- `--color-text-secondary`: #555555 (supporting text, labels)
+- `--color-accent`: #E8FF00 (CTAs, highlights  -  electric yellow)
+- `--color-accent-hover`: #D4E800 (interactive accent state)
+- `--color-accent-on-dark`: #E8FF00 (accent on dark surfaces  -  same, still works)
+
+## 3. Typography Rules
+- **Display font**: Bebas Neue  -  Google Fonts  -  weight 400 (this face has no variants; use size for hierarchy)
+- **Body font**: Inter  -  Google Fonts  -  weights 400, 500, 600
+- **Mono font**: JetBrains Mono  -  for data, code, technical detail
+- **Scale**: Display 96px / H1 56px / H2 36px / H3 24px / Body 16px / Small 13px
+- **Line height**: 1.5 for body / 1.0 for display (Bebas Neue is tight by design)
+- **Letter spacing**: 0 for body / 0.03em for display  -  Bebas benefits from slight tracking
+- **Font loading**: `@import url('https://fonts.googleapis.com/css2?family=Bebas+Neue&family=Inter:wght@400;500;600&family=JetBrains+Mono&display=swap')`
+
+## 4. Component Stylings
+### Buttons
+Primary: `background: --color-accent`, `color: #0A0A0A`, `font-family: Inter`, `font-weight: 600`, `border-radius: 0`, `padding: 14px 28px`, `border: 2px solid #0A0A0A`, uppercase, `letter-spacing: 0.06em`. Hover: `background: --color-accent-hover`. Secondary: `background: transparent`, `border: 2px solid #0A0A0A`, `color: #0A0A0A`. No softening anywhere.
+
+### Cards
+`background: --color-surface`, `border: 2px solid --color-border`, `border-radius: 0`, `padding: 28px`. No shadow. Optional: thick left bar `border-left: 6px solid --color-accent`. Dark variant: `background: --color-surface-dark`, `color: --color-text-inverse`, `border-color: --color-surface-dark`.
+
+### Navigation
+Height 60px, `border-bottom: 2px solid --color-border`, background `--color-bg`. Logo in Bebas Neue 28px. Nav links: Inter `font-weight: 600`, `font-size: 13px`, uppercase, `letter-spacing: 0.08em`. Active: `background: --color-accent`, `color: #0A0A0A`, `padding: 4px 10px`.
+
+### Inputs
+`background: --color-bg`, `border: 2px solid --color-border`, `border-radius: 0`, `padding: 11px 12px`, `font-family: Inter`, `font-size: 15px`. Focus: `border-color: #0A0A0A`, `box-shadow: 4px 4px 0 #0A0A0A`. Placeholder: `--color-text-secondary`.
+
+### Badges / Chips
+`background: --color-accent`, `color: #0A0A0A`, `border: 2px solid #0A0A0A`, `border-radius: 0`, `padding: 3px 10px`, `font-size: 11px`, `font-family: Inter`, `font-weight: 600`, uppercase, `letter-spacing: 0.06em`. Inverted variant: `background: #0A0A0A`, `color: --color-accent`.
+
+## 5. Layout Principles
+- **Grid**: 12-column with 2px visible column rules optional  -  the structure is the design
+- **Max width**: 1400px
+- **Section padding**: 80px vertical
+- **Spacing scale**: 4 / 8 / 16 / 24 / 32 / 48 / 64 / 80 / 96px
+- **Whitespace philosophy**: intentional asymmetry  -  some sections are dense, others are a single headline in 40% of the viewport
+
+## 6. Depth & Elevation
+- **Surface hierarchy**: Level 0 = `--color-bg`, Level 1 = `--color-surface` (with 2px border), Level 2 = offset shadow only
+- **Shadow tokens**: none (flat) or offset hard shadow `4px 4px 0 #0A0A0A`  -  no blurred shadows ever
+- **Border usage**: 2px solid black everywhere; borders are structural, not decorative
+
+## 7. Do's and Don'ts
+**Do:**
+- Use Bebas Neue at large sizes only (36px+); below that Inter bold takes over
+- Use the electric yellow accent as a weapon  -  it should feel aggressive when it appears
+- Mix inverted sections (black bg) with light sections for rhythm and drama
+- Let type collide with layout edges; crop is intentional
+- Use the hard 4px offset shadow on interactive cards and focused inputs
+
+**Don't:**
+- Round any corner  -  `border-radius: 0` is a rule, not a suggestion
+- Use more than one accent color; the yellow is the entire accent system
+- Use soft drop shadows (blurred box-shadow); hard offset only
+- Apply subtle animations; transitions are instant or simple slide-in
+- Use imagery with busy compositions  -  high contrast or solid color photos only
+
+## 8. Responsive Behavior
+- **Mobile breakpoint**: 375px
+- **Tablet breakpoint**: 768px
+- **Touch targets**: minimum 44px
+- **Typography scaling**: Display drops to 56px / H1 to 36px on mobile; Bebas Neue stays at all sizes
+- **Layout collapse**: 12-col → single column; column rules removed; padding reduces to 24px; bold borders remain
+
+## 9. Agent Prompt Guide
+Use these prompts with Claude Design or ijfw-design to stay on-system:
+
+- **New screen**: "Build a [screen type] following the Brutalist Luxe DESIGN.md. Match the color tokens and type scale exactly."
+- **Component**: "Add a [component] that fits the Brutalist Luxe aesthetic  -  reference section 4 for styling rules."
+- **Variant**: "Create a [light/dark/compact] variant of this screen. Keep the same token names, adjust the values."

package/templates/design/cinematic-dark.md

@@ -0,0 +1,82 @@
+# Cinematic Dark  -  DESIGN.md
+
+## 1. Visual Theme & Atmosphere
+Film-inspired luxury dark  -  the aesthetic of a well-funded production company's website or a prestige tech brand's launch page. Near-absolute black background, cool grey surfaces, silver-white type. Every element is considered and spaced as if a cinematographer approved the composition. Use for flagship product launches, AI products, high-end SaaS, portfolio sites, and anything where first impression must signal quality and ambition.
+
+## 2. Color Palette & Roles
+- `--color-bg`: #080808 (page background  -  near-total black)
+- `--color-surface`: #111114 (card/panel surface  -  cool dark)
+- `--color-surface-mid`: #1A1A1F (elevated panels, modals)
+- `--color-border`: #242428 (dividers, input borders)
+- `--color-border-subtle`: #1C1C20 (lightest surface separator)
+- `--color-text-primary`: #F0F0F2 (headings, primary content  -  silver white)
+- `--color-text-secondary`: #6E6E78 (supporting text, labels)
+- `--color-accent`: #D4D4D8 (CTAs, links  -  cool silver)
+- `--color-accent-hover`: #FFFFFF (interactive accent state  -  full white)
+- `--color-muted`: #3A3A40 (placeholder text, disabled)
+
+## 3. Typography Rules
+- **Display font**: Inter  -  Google Fonts  -  weights 200, 300, 400, 600
+- **Body font**: Inter  -  Google Fonts  -  weights 300, 400
+- **Mono font**: JetBrains Mono  -  for data, stats, technical callouts
+- **Scale**: Display 72px / H1 48px / H2 32px / H3 22px / Body 16px / Small 13px
+- **Line height**: 1.65 for body / 1.05 for display
+- **Letter spacing**: 0.01em for body / -0.03em for display / 0.12em for small caps labels
+- **Font loading**: `@import url('https://fonts.googleapis.com/css2?family=Inter:wght@200;300;400;600&family=JetBrains+Mono&display=swap')`
+
+## 4. Component Stylings
+### Buttons
+Primary: `background: #F0F0F2`, `color: #080808`, `font-weight: 500`, `border-radius: 3px`, `padding: 12px 28px`, `letter-spacing: 0.01em`. Hover: `background: #FFFFFF`. Secondary: transparent, `border: 1px solid --color-border`, `color: --color-text-primary`. No colored accents  -  this palette is intentionally achromatic.
+
+### Cards
+Background `--color-surface`, `border: 1px solid --color-border-subtle`, `border-radius: 6px`, `padding: 32px`. No shadow  -  dark backgrounds absorb light, borders define. For featured cards: `border-color: --color-border`, subtle inner glow `box-shadow: inset 0 1px 0 rgba(255,255,255,0.04)`.
+
+### Navigation
+Height 64px, `border-bottom: 1px solid --color-border-subtle`, background `rgba(8,8,8,0.85)`, `backdrop-filter: blur(12px)`. Sticky. Logo weight 300. Nav items: Inter 14px, `color: --color-text-secondary`. Hover: `color: --color-text-primary`. Active: `color: #FFFFFF`.
+
+### Inputs
+`background: --color-surface`, `border: 1px solid --color-border`, `border-radius: 4px`, `padding: 11px 14px`, `font-size: 15px`, `color: --color-text-primary`. Focus: `border-color: #404048`, `box-shadow: 0 0 0 3px rgba(255,255,255,0.04)`. Placeholder: `--color-muted`.
+
+### Badges / Chips
+`background: --color-surface-mid`, `border: 1px solid --color-border`, `border-radius: 3px`, `padding: 3px 9px`, `font-size: 11px`, `font-weight: 500`, `color: --color-text-secondary`, `letter-spacing: 0.06em`, uppercase. Understated  -  status, not decoration.
+
+## 5. Layout Principles
+- **Grid**: 12-column, 32px gutters
+- **Max width**: 1440px
+- **Section padding**: 120px vertical
+- **Spacing scale**: 8 / 16 / 24 / 32 / 48 / 64 / 96 / 128 / 160px
+- **Whitespace philosophy**: extreme  -  cinema uses darkness as framing; UI should too
+
+## 6. Depth & Elevation
+- **Surface hierarchy**: Level 0 = `--color-bg`, Level 1 = `--color-surface`, Level 2 = `--color-surface-mid`
+- **Shadow tokens**: low = `0 2px 8px rgba(0,0,0,0.5)`; mid = `0 8px 32px rgba(0,0,0,0.7)`; high = `0 24px 64px rgba(0,0,0,0.9)`
+- **Border usage**: very subtle (1px at 14% opacity on surfaces); let darkness define depth more than borders
+
+## 7. Do's and Don'ts
+**Do:**
+- Use Inter at weight 200-300 for large display text  -  ultra-light type on black is cinematic
+- Let large sections be mostly empty; negative space is composition
+- Use full-bleed sections with edge-to-edge dark backgrounds
+- Treat any imagery as frames  -  high contrast, desaturated, or masked
+- Apply `backdrop-filter: blur` for sticky nav only; not for cards
+
+**Don't:**
+- Introduce any color accent  -  the achromatic palette is intentional and load-bearing
+- Use shadows that are lighter than the surface (no glows, no coloured light)
+- Round corners aggressively; max 6px maintains the cinematic edge
+- Add animation that feels playful; motion should feel slow and deliberate
+- Use more than three font weights on any single screen
+
+## 8. Responsive Behavior
+- **Mobile breakpoint**: 390px
+- **Tablet breakpoint**: 768px
+- **Touch targets**: minimum 44px
+- **Typography scaling**: Display drops to 44px / H1 to 32px on mobile; letter-spacing tightens slightly
+- **Layout collapse**: 12-col → single column; section padding reduces to 64px; nav collapses to hamburger
+
+## 9. Agent Prompt Guide
+Use these prompts with Claude Design or ijfw-design to stay on-system:
+
+- **New screen**: "Build a [screen type] following the Cinematic Dark DESIGN.md. Match the color tokens and type scale exactly."
+- **Component**: "Add a [component] that fits the Cinematic Dark aesthetic  -  reference section 4 for styling rules."
+- **Variant**: "Create a [light/dark/compact] variant of this screen. Keep the same token names, adjust the values."

package/templates/design/data-dense-dashboard.md

@@ -0,0 +1,88 @@
+# Data Dense Dashboard  -  DESIGN.md
+
+## 1. Visual Theme & Atmosphere
+Information density first  -  the aesthetic of tools where the data is the UI. Every pixel that isn't carrying information is a pixel wasted. Compact row heights, monospace data values, status chips with semantic color, and minimal chrome around the content. Dark background keeps the eye on the numbers. Use for monitoring dashboards, analytics platforms, ops tooling, admin panels, and any surface where a user needs to read 40 rows of data without losing their place.
+
+## 2. Color Palette & Roles
+- `--color-bg`: #0C0C0F (page background  -  deep dark)
+- `--color-surface`: #131318 (card/panel surface)
+- `--color-surface-row`: #161619 (table row hover/selected)
+- `--color-border`: #222228 (dividers, table borders)
+- `--color-border-strong`: #2E2E36 (section separators)
+- `--color-text-primary`: #E4E4EF (headings, primary data)
+- `--color-text-secondary`: #6E6E82 (labels, column headers)
+- `--color-text-dim`: #3E3E4E (disabled, empty state)
+- `--color-accent`: #5B6EF5 (active links, primary CTA  -  indigo)
+- `--color-accent-hover`: #7B8EFF (interactive accent state)
+- `--color-success`: #16A34A
+- `--color-success-bg`: rgba(22,163,74,0.1)
+- `--color-error`: #DC2626
+- `--color-error-bg`: rgba(220,38,38,0.1)
+- `--color-warning`: #D97706
+- `--color-warning-bg`: rgba(217,119,6,0.1)
+
+## 3. Typography Rules
+- **Display font**: Inter  -  Google Fonts  -  weights 400, 500, 600
+- **Body font**: Inter  -  Google Fonts  -  weights 400, 500
+- **Mono font**: JetBrains Mono  -  weights 400, 500  -  all data values, numbers, IDs, timestamps, code
+- **Scale**: Display 32px / H1 24px / H2 18px / H3 14px / Body 13px / Small 11px
+- **Line height**: 1.5 for body / 1.2 for display
+- **Letter spacing**: 0 for body / 0.04em for uppercase column headers
+- **Font loading**: `@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap')`
+
+## 4. Component Stylings
+### Buttons
+Primary: `background: --color-accent`, white text, `font-weight: 500`, `border-radius: 5px`, `padding: 6px 14px`, `font-size: 13px`. Hover: `--color-accent-hover`. Secondary: `background: --color-surface`, `border: 1px solid --color-border-strong`, `color: --color-text-primary`, `border-radius: 5px`, same padding. Icon-only buttons are 28x28px, `border-radius: 5px`.
+
+### Cards / Panels
+`background: --color-surface`, `border: 1px solid --color-border`, `border-radius: 6px`, `padding: 16px`. Metric card: large JetBrains Mono number top, Inter label below in `--color-text-secondary`. Table panels have `padding: 0` and let the table fill edge to edge inside the border.
+
+### Navigation
+Height 44px  -  compact. `border-bottom: 1px solid --color-border`, background `--color-bg`. Items: Inter 13px, `font-weight: 500`, `color: --color-text-secondary`. Active: `color: --color-text-primary`, left-border indicator `3px solid --color-accent`. Sidebar variant: 220px wide, `border-right: 1px solid --color-border`.
+
+### Inputs
+`background: --color-bg`, `border: 1px solid --color-border`, `border-radius: 5px`, `padding: 6px 10px`, `font-size: 13px`, `color: --color-text-primary`. Height 32px  -  compact. Focus: `border-color: --color-accent`, `box-shadow: 0 0 0 2px rgba(91,110,245,0.15)`. Search inputs prepend a 14px icon with 8px gap.
+
+### Badges / Chips
+Status chips: `padding: 2px 7px`, `border-radius: 4px`, `font-size: 11px`, `font-weight: 500`, `font-family: Inter`. Success: `background: --color-success-bg`, `color: #4ADE80`. Error: `background: --color-error-bg`, `color: #F87171`. Warning: `background: --color-warning-bg`, `color: #FCD34D`. Neutral: `background: rgba(110,110,130,0.12)`, `color: --color-text-secondary`.
+
+## 5. Layout Principles
+- **Grid**: 12-column, 16px gutters
+- **Max width**: 1600px (dashboards use the full screen)
+- **Section padding**: 24px vertical between panels
+- **Spacing scale**: 2 / 4 / 6 / 8 / 12 / 16 / 24 / 32 / 48px (2px base unit for dense rows)
+- **Whitespace philosophy**: none wasted  -  every gap is intentional breathing room between data groups
+
+## 6. Depth & Elevation
+- **Surface hierarchy**: Level 0 = `#0C0C0F`, Level 1 = `#131318`, Level 2 = `#181820`
+- **Shadow tokens**: low = `0 1px 3px rgba(0,0,0,0.5)`; mid = `0 4px 12px rgba(0,0,0,0.6)`; none on most panels  -  borders define everything
+- **Border usage**: 1px borders on all panels; hairline 1px `--color-border` between table rows; `--color-border-strong` between logical sections
+
+## 7. Do's and Don'ts
+**Do:**
+- Use JetBrains Mono for every numeric value, ID, hash, timestamp, and code string
+- Keep table row height at 36-40px; never pad rows to 52px in a data-dense context
+- Use semantic status colors (`--color-success/error/warning`) consistently across every surface
+- Right-align numeric columns; left-align text columns  -  this is a non-negotiable data table rule
+- Show column header units (ms, %, $) in `--color-text-secondary` following the label
+
+**Don't:**
+- Use large section padding (80px+)  -  this is a dashboard, not a landing page
+- Apply border-radius beyond 6px; compact aesthetics have sharp but not brutal edges
+- Use gradients or decorative backgrounds behind data panels
+- Show empty cards when data is loading  -  use skeleton rows at the correct density
+- Mix monospace and proportional fonts on the same data row
+
+## 8. Responsive Behavior
+- **Mobile breakpoint**: 375px
+- **Tablet breakpoint**: 1024px (dashboards are desktop-first; tablet is the collapse point)
+- **Touch targets**: minimum 44px
+- **Typography scaling**: all type stays the same; only layout collapses
+- **Layout collapse**: multi-column dashboard → single column stacked panels; sidebar → top nav; tables get horizontal scroll rather than column hiding
+
+## 9. Agent Prompt Guide
+Use these prompts with Claude Design or ijfw-design to stay on-system:
+
+- **New screen**: "Build a [screen type] following the Data Dense Dashboard DESIGN.md. Match the color tokens and type scale exactly."
+- **Component**: "Add a [component] that fits the Data Dense Dashboard aesthetic  -  reference section 4 for styling rules."
+- **Variant**: "Create a [light/dark/compact] variant of this screen. Keep the same token names, adjust the values."