synabun 1.3.0 → 2.0.0-beta

package/mcp-server/src/tools/remember.ts

@@ -1,115 +1,223 @@
-import { z } from 'zod';
-import { v4 as uuidv4 } from 'uuid';
-import { generateEmbedding } from '../services/local-embeddings.js';
-import { upsertMemory } from '../services/sqlite.js';
-import { validateCategory } from '../services/categories.js';
-import { coerceStringArray } from './utils.js';
-import type { MemoryPayload, MemorySource } from '../types.js';
-import { detectProject } from '../config.js';
-import { computeChecksums } from '../services/file-checksums.js';
-import { invalidateCache } from '../services/neural-interface.js';
-import { text } from './response.js';
-
-export function buildRememberSchema() {
-  return {
-    content: z
-      .string()
-      .describe('The information to remember. Be specific and include context.'),
-    category: z
-      .string()
-      .describe('Category name. Call category tool with action "list" to see valid categories.'),
-  project: z
-    .string()
-    .optional()
-    .describe(
-      'Project this belongs to (e.g. "criticalpixel"). Defaults to auto-detected from working directory.'
-    ),
-  tags: coerceStringArray()
-    .optional()
-    .describe('Tags for categorization (e.g. ["redis", "cache", "pricing"])'),
-  importance: z
-    .coerce.number()
-    .min(1)
-    .max(10)
-    .optional()
-    .describe(
-      '1=trivial, 5=normal, 7=significant, 8+=critical. Default 5. Use 8+ for hard-won bug fixes and architecture decisions.'
-    ),
-  subcategory: z
-    .string()
-    .optional()
-    .describe(
-      'Optional refinement: architecture, bug-fix, api-quirk, performance, config, deployment, etc.'
-    ),
-  source: z
-    .enum(['user-told', 'self-discovered', 'auto-saved'] as const)
-    .optional()
-    .describe(
-      'How this was learned. user-told=user explicitly shared, self-discovered=found during work, auto-saved=session context.'
-    ),
-  related_files: coerceStringArray()
-    .optional()
-    .describe('File paths this memory relates to.'),
-  };
-}
-
-export const rememberSchema = buildRememberSchema();
-
-export const rememberDescription =
-  'Store a piece of information in persistent memory. Use this when you learn something important, make a decision, discover a pattern, fix a hard bug, or want to preserve context for future sessions.';
-
-export async function handleRemember(args: {
-  content: string;
-  category: string;
-  project?: string;
-  tags?: string[];
-  importance?: number;
-  subcategory?: string;
-  source?: string;
-  related_files?: string[];
-}) {
-  const catCheck = validateCategory(args.category);
-  if (!catCheck.valid) {
-    return text(catCheck.error!);
-  }
-
-  const content = args.content;
-  const category = args.category;
-  const project = args.project || detectProject();
-  const tags = args.tags || [];
-  const importance = args.importance ?? 5;
-  const subcategory = args.subcategory;
-  const source = (args.source as MemorySource) || 'self-discovered';
-  const related_files = args.related_files;
-
-  const id = uuidv4();
-  const now = new Date().toISOString();
-
-  const payload: MemoryPayload = {
-    content,
-    category,
-    subcategory,
-    project,
-    tags,
-    importance,
-    source,
-    created_at: now,
-    updated_at: now,
-    accessed_at: now,
-    access_count: 0,
-    related_files,
-    file_checksums: (() => {
-      if (!related_files?.length) return undefined;
-      const cs = computeChecksums(related_files);
-      return Object.keys(cs).length > 0 ? cs : undefined;
-    })(),
-  };
-
-  const vector = await generateEmbedding(content);
-  await upsertMemory(id, vector, payload);
-
-  // Invalidate Neural Interface link cache (fire-and-forget)
-  invalidateCache('remember');
-
-  return text(`Remembered [${id}] (${category}/${project}, importance: ${importance}): "${content.slice(0, 100)}${content.length > 100 ? '...' : ''}"`);
-}
+import { randomUUID } from 'node:crypto';
+import { writeMemory, IdempotencyConflict, type WriteMemoryResult } from '../services/memory-writer.js';
+import { z } from 'zod';
+import { categoryExists, getAllCategories, getCategories } from '../services/categories.js';
+import { coerceStringArray } from './utils.js';
+import type { MemoryPayload, MemorySource } from '../types.js';
+import { detectProject, projectRoot } from '../config.js';
+import { computeChecksums } from '../services/file-checksums.js';
+import { text } from './response.js';
+import { callerMemoryContext } from '../services/identity.js';
+import { redactSecrets } from '../services/secret-gate.js';
+import { judgeCategory, type CategoryJudgment } from '../services/memory-judgments.js';
+import { surfaceConfig, relinkTypeSafeLog } from '../services/typesafe-config.js';
+import { getDb } from '../services/sqlite.js';
+
+const MAX_CATEGORY_OPTIONS = 60;
+
+/**
+ * The categories a memory could be filed under, with their descriptions —
+ * leaves only (parents are containers). Above the cap, keep the caller's
+ * siblings and the top-level leaves so the request stays affordable.
+ */
+export function categoryOptions(current: string): Record<string, string | null> {
+  const all = getCategories();
+  const byName = new Map(all.map(c => [c.name, c]));
+  let pool = all.filter(c => !c.is_parent);
+  if (pool.length > MAX_CATEGORY_OPTIONS) {
+    const parent = byName.get(current)?.parent;
+    pool = pool.filter(c => c.name === current || (parent ? c.parent === parent : !c.parent)).slice(0, MAX_CATEGORY_OPTIONS);
+  }
+  const options: Record<string, string | null> = {};
+  for (const c of pool) options[c.name] = c.description || null;
+  if (!(current in options)) options[current] = byName.get(current)?.description || null;
+  return options;
+}
+
+/** Record what the judgment thought beside the writer's pick. Never re-routes. */
+export function recordCategoryJudgment(memoryId: string, verdict: CategoryJudgment | null): void {
+  if (!verdict || verdict.category === 'none-of-these') return;
+  try {
+    getDb().prepare('UPDATE memory_metadata SET category_judged=?, category_confidence=? WHERE memory_id=?').run(verdict.category, verdict.confidence, memoryId);
+  } catch { /* the judgment is advisory; a missing column or row must not fail the write */ }
+}
+
+export function buildRememberSchema() {
+  return {
+    idempotency_key: z.string().min(1).max(200).optional().describe('Retry key scoped to project and category. Same key/content returns the existing UUID.'),
+    kind: z.enum(['note','decision','issue','preference','fact','session']).optional().describe('Memory kind; defaults to note.'),
+    source_ref: z.string().max(2000).optional().describe('Local session/event identifier or source reference.'),
+    content: z
+      .string()
+      .describe('The information to remember. Be specific and include context.'),
+    // category and project are REQUIRED on purpose. They were optional, and the
+    // description used to end "If omitted, a project default is used" — so hosts
+    // routinely sent { content } alone. Everything then landed in the fallback
+    // bucket, and the Claude Code stop hook (which keys off category) never
+    // cleared. A JSON Schema `required` entry is enforcement; a description is
+    // only advice, and the advice was already being ignored.
+    category: z
+      .string()
+      .min(1)
+      .describe(
+        'REQUIRED. Category name (top-level bucket) to file this memory under. ' +
+        'Call the category tool with action "list" for valid names, or action "create" ' +
+        'if nothing fits. Distinct from subcategory. An unrecognized name is still ' +
+        'accepted and remapped to a project default, but the memory is then filed in ' +
+        'the wrong bucket — pass a real one.'
+      ),
+  project: z
+    .string()
+    .min(1)
+    .describe(
+      'REQUIRED. Project this belongs to, lowercase kebab-case (e.g. "my-web-app", ' +
+      '"synabun"). Use the project named in your session context — this is NOT reliably ' +
+      'auto-detected over the HTTP transport, where every caller shares one process.'
+    ),
+  tags: coerceStringArray()
+    .optional()
+    .describe('Tags for categorization (e.g. ["redis", "cache", "pricing"])'),
+  importance: z
+    .coerce.number()
+    .min(1)
+    .max(10)
+    .optional()
+    .describe(
+      'Set this deliberately on every call: 1=trivial, 5=routine, 7=significant, ' +
+      '8+=critical. Use 8+ for hard-won bug fixes and architecture decisions. ' +
+      'Omit only when the work is genuinely routine (defaults to 5).'
+    ),
+  subcategory: z
+    .string()
+    .optional()
+    .describe(
+      'Optional refinement: architecture, bug-fix, api-quirk, performance, config, deployment, etc.'
+    ),
+  source: z
+    .enum(['user-told', 'self-discovered', 'auto-saved'] as const)
+    .optional()
+    .describe(
+      'How this was learned. user-told=user explicitly shared, self-discovered=found during work, auto-saved=session context.'
+    ),
+  related_files: coerceStringArray()
+    .optional()
+    .describe('File paths this memory relates to.'),
+  };
+}
+
+export const rememberSchema = buildRememberSchema();
+
+export const rememberDescription =
+  'Store a piece of information in persistent memory. Use this when you learn something important, make a decision, discover a pattern, fix a hard bug, or want to preserve context for future sessions.';
+
+/**
+ * Resolve the category to store under. If the caller supplied a valid category,
+ * use it verbatim. Otherwise fall back to a project default so a memory is never
+ * lost just because the required field was omitted or misspelled.
+ * Returns the chosen category and whether a fallback was applied.
+ */
+function resolveCategory(requested: string | undefined, project: string): { category: string; fallback: boolean } {
+  if (requested && categoryExists(requested)) {
+    return { category: requested, fallback: false };
+  }
+  const all = getAllCategories();
+  const projectDefault = `${project}-project`;
+  const chosen =
+    (all.includes(projectDefault) && projectDefault) ||
+    (all.includes('conversations') && 'conversations') ||
+    all[0] ||
+    'conversations';
+  return { category: chosen, fallback: true };
+}
+
+export async function handleRemember(args: {
+  content: string;
+  idempotency_key?: string; kind?: string; source_ref?: string;
+  // Required by the schema, but kept permissive here so the runtime fallbacks
+  // below still apply to non-validating callers (direct imports, tests).
+  category?: string;
+  project?: string;
+  tags?: string[];
+  importance?: number;
+  subcategory?: string;
+  source?: string;
+  related_files?: string[];
+}) {
+  const project = args.project || detectProject();
+  // The id is chosen before any judgment so every write-time judgment
+  // (secret, category, duplicate) is logged against the memory it produced.
+  const provisionalId = randomUUID();
+  const judgeContext = { origin: 'tool' as const, entityId: provisionalId, project, sessionId: callerMemoryContext().session ?? null };
+  // Secret gate first: nothing credential-shaped gets embedded or stored.
+  const gate = await redactSecrets(args.content, judgeContext);
+  if (gate.refused) {
+    return { ...text('Refused: this memory would be nothing but a credential. Store where the secret lives (the file path or the environment variable name), never the secret itself.'), isError: true };
+  }
+  const content = gate.text;
+  const { category, fallback: categoryFallback } = resolveCategory(args.category, project);
+  const tags = [...(args.tags || [])];
+  if (gate.redactions.length && !tags.includes('redacted')) tags.push('redacted');
+  const importance = args.importance ?? 5;
+  const subcategory = args.subcategory;
+  const source = (args.source as MemorySource) || 'self-discovered';
+  const related_files = args.related_files;
+
+  const now = new Date().toISOString();
+
+  const payload: MemoryPayload = {
+    content,
+    category,
+    subcategory,
+    project,
+    tags,
+    importance,
+    source,
+    created_at: now,
+    updated_at: now,
+    accessed_at: now,
+    access_count: 0,
+    related_files,
+    file_checksums: (() => {
+      if (!related_files?.length) return undefined;
+      const cs = computeChecksums(related_files, projectRoot(project));
+      return Object.keys(cs).length > 0 ? cs : undefined;
+    })(),
+  };
+
+  // The category check runs beside the write (both are round trips); its
+  // answer is recorded and reported, never applied.
+  const categorySettings = surfaceConfig('category-check');
+  const check: Promise<CategoryJudgment | null> = categorySettings.enabled
+    ? judgeCategory(content, category, categoryOptions(category), judgeContext).catch(() => null)
+    : Promise.resolve(null);
+  let result: WriteMemoryResult;
+  let verdict: CategoryJudgment | null = null;
+  try {
+    [result, verdict] = await Promise.all([
+      writeMemory(payload, { idempotencyKey: args.idempotency_key, kind: args.kind, sourceRef: args.source_ref || callerMemoryContext().session, id: provisionalId, judge: judgeContext }),
+      check,
+    ]);
+  } catch (error) {
+    if (error instanceof IdempotencyConflict) return { ...text(error.message), isError: true };
+    throw error;
+  }
+  const { id, pending } = result;
+  // A duplicate or a retry answers with an existing id; point the rows logged
+  // under the id that was never stored at the memory the write resolved to.
+  if (id !== provisionalId) relinkTypeSafeLog(provisionalId, id);
+  if (result.duplicate) {
+    return text(`Not stored — duplicate of [${id}] (P=${result.duplicate.probability.toFixed(2)}): that memory already states this. Use \`reflect\` on it to add what is new.`);
+  }
+  if (result.existing) return text(`Remembered [${id}] (existing retry; no duplicate created).`);
+  recordCategoryJudgment(id, verdict);
+
+  const notes: string[] = [];
+  if (categoryFallback) notes.push(`category ${args.category ? `"${args.category}" not found` : 'omitted'} — defaulted to "${category}"; pass a valid category next time`);
+  if (gate.redactions.length) notes.push(`redacted ${gate.redactions.length} credential-looking value${gate.redactions.length === 1 ? '' : 's'}${gate.judged ? '' : ' (pattern match only)'}`);
+  if (verdict && verdict.confidence >= (categorySettings.minConfidence ?? 0.6)) {
+    if (verdict.category === 'none-of-these') notes.push(`category check: no existing category fits well (${Math.round(verdict.confidence * 100)}%)`);
+    else if (verdict.category !== category) notes.push(`category check: Jev suggests "${verdict.category}" (${Math.round(verdict.confidence * 100)}%) — stored under "${category}" as asked; review in Settings → Judgments → Misfiled`);
+  }
+  const note = notes.length ? ` (${notes.join('; ')})` : '';
+  return text(`Remembered [${id}] (${category}/${project}, importance: ${importance}): "${content.slice(0, 100)}${content.length > 100 ? '...' : ''}"${note}${pending ? ' (Saved durably; local semantic indexing pending.)' : ''}`);
+}

package/mcp-server/src/tools/style-guide-tools.ts

@@ -0,0 +1,250 @@
+import { z } from 'zod';
+import { resolve } from 'path';
+import { existsSync, lstatSync, readFileSync } from 'fs';
+import * as ni from '../services/neural-interface.js';
+import { text } from './response.js';
+
+// ═══════════════════════════════════════════
+// style_guide — a project's brand and design system
+// ═══════════════════════════════════════════
+//
+// Reads the SynaBun Style Guide through the Neural Interface (docs/style-guide.md):
+// the summary agents work from, the full DESIGN.md, the tokens in any export format,
+// contrast for two colors. The one thing it can change is a proposal: a merge patch
+// the user accepts or rejects in the Style Guide panel. It never writes the store.
+
+const ACTIONS = ['get', 'summary', 'tokens', 'contrast', 'propose', 'proposals', 'export', 'list'] as const;
+const TOKEN_FORMATS = ['json', 'dtcg', 'css', 'tailwind-v4', 'tailwind-v3'] as const;
+const EXPORT_FORMATS = ['design-md', 'dtcg', 'css', 'tailwind-v4', 'tailwind-v3', 'tailwind'] as const;
+
+export const styleGuideSchema = {
+  action: z.enum(ACTIONS).default('get').describe(
+    '"summary": the compact brand block (start here). "get": summary + the full DESIGN.md (or one `section`). "tokens": the tokens in a `format`. "contrast": WCAG ratio + APCA for `fg` on `bg`. "propose": suggest a change (`changes` + `reason`) for the user to review. "proposals": list them. "export": write DESIGN.md and the token files into the project now. "list": registered projects and whether each has a guide.'
+  ),
+  projectPath: z.string().optional().describe(
+    'The project root or any path inside it (your working directory). The default is the server\'s cwd, which is usually NOT your project — pass it.'
+  ),
+  section: z.string().optional().describe('get: only this DESIGN.md section, e.g. "Colors", "Typography", "Components", "Do\'s and Don\'ts".'),
+  format: z.enum(TOKEN_FORMATS).optional().describe('tokens: "json" (resolved values, default), "dtcg" (W3C design tokens), "css" (custom properties), "tailwind-v4" (@theme) or "tailwind-v3" (theme.extend).'),
+  theme: z.enum(['light', 'dark']).optional().describe('tokens / contrast: one theme (default: the guide\'s default theme).'),
+  taskClass: z.string().optional().describe('summary: the kind of work (e.g. "image_gen" or "video_gen" puts imagery and the generation prefix first).'),
+  fg: z.string().optional().describe('contrast: the text color — a hex, rgb(), hsl(), oklch(), or an alias like "{semantic.text}" or "{primary.500}".'),
+  bg: z.string().optional().describe('contrast: the background color, same forms as fg.'),
+  size: z.enum(['normal', 'large']).optional().describe('contrast: "large" for text ≥ 24px (or ≥ 18.66px bold) and UI components.'),
+  changes: z.record(z.unknown()).optional().describe(
+    'propose: a JSON merge patch (RFC 7396) against the guide, e.g. {"colors":{"status":{"danger":"#dc2626"}}}. null deletes a key. agents and exports settings cannot be proposed.'
+  ),
+  reason: z.string().optional().describe('propose: why the guide should change (required).'),
+  status: z.enum(['pending', 'accepted', 'rejected']).optional().describe('proposals: only this status.'),
+  formats: z.array(z.enum(EXPORT_FORMATS)).optional().describe('export: which files to write (default: the ones the guide has enabled).'),
+  runId: z.string().optional().describe('propose: the dispatched run id, if known.'),
+  provider: z.string().optional().describe('propose: the authoring provider, if known.'),
+  model: z.string().optional().describe('propose: the authoring model, if known.'),
+};
+
+export const styleGuideDescription =
+  'A project\'s SynaBun Style Guide: brand, colors (light/dark), type, spacing, motion, components and rules, as a summary, the full DESIGN.md or tokens (CSS variables, Tailwind theme, W3C design tokens). Call it BEFORE UI, design, copy, marketing, image or video work and use its tokens instead of inventing values. Pass projectPath (your working directory). To change the guide, use action "propose": the user reviews proposals; never edit DESIGN.md or the token files by hand.';
+
+type Args = {
+  action?: string;
+  projectPath?: string;
+  section?: string;
+  format?: string;
+  theme?: string;
+  taskClass?: string;
+  fg?: string;
+  bg?: string;
+  size?: string;
+  changes?: Record<string, unknown>;
+  reason?: string;
+  status?: string;
+  formats?: string[];
+  runId?: string;
+  provider?: string;
+  model?: string;
+};
+
+type WrittenFile = { format: string; path: string; exists?: boolean; changed?: boolean };
+type DiffRow = { path: string; from: unknown; to: unknown };
+
+const PASS_PATH = 'Pass projectPath: your project root or any path inside it (your working directory). The default is the SynaBun server\'s working directory, which is usually not your project. Action "list" shows the registered projects.';
+
+/** What to tell the caller when the Neural Interface refused or could not be reached. */
+function failure(what: string, res: ni.NiResponse, projectPath: string): string {
+  if (res.code === 'PROJECT_NOT_REGISTERED' || /not registered/i.test(String(res.error || ''))) {
+    return `${what}: no registered SynaBun project contains "${projectPath}". ${PASS_PATH}`;
+  }
+  return `${what}: ${res.error}`;
+}
+
+const short = (value: unknown): string => {
+  const out = typeof value === 'string' ? value : JSON.stringify(value);
+  return out === undefined ? 'null' : out.length > 80 ? `${out.slice(0, 79)}…` : out;
+};
+const diffLines = (diff: DiffRow[], max = 20): string[] => [
+  ...diff.slice(0, max).map((row) => `- ${row.path}: ${row.from === null ? '(none)' : short(row.from)} → ${row.to === null ? '(removed)' : short(row.to)}`),
+  ...(diff.length > max ? [`- … and ${diff.length - max} more`] : []),
+];
+
+/** The `## <name>` section of a Markdown file (case-insensitive, prefix match), or null with the names it has. */
+export function markdownSection(markdown: string, name: string): { section: string | null; names: string[] } {
+  const lines = markdown.split('\n');
+  const heads: Array<{ title: string; line: number }> = [];
+  let fence = false;
+  lines.forEach((line, index) => {
+    if (/^\s*(```|~~~)/.test(line)) fence = !fence;
+    const match = !fence && /^##\s+(.+?)\s*$/.exec(line);
+    if (match) heads.push({ title: match[1], line: index });
+  });
+  const wanted = name.trim().toLowerCase();
+  const at = heads.findIndex((head) => head.title.toLowerCase() === wanted);
+  const index = at >= 0 ? at : heads.findIndex((head) => head.title.toLowerCase().startsWith(wanted));
+  if (index < 0) return { section: null, names: heads.map((head) => head.title) };
+  const end = index + 1 < heads.length ? heads[index + 1].line : lines.length;
+  return { section: lines.slice(heads[index].line, end).join('\n').trim(), names: heads.map((head) => head.title) };
+}
+
+function filesLine(written: WrittenFile[]): string {
+  const there = written.filter((file) => file.exists);
+  if (!there.length) return 'Files: none written into the project yet.';
+  return `Files: ${there.map((file) => file.path).join(' · ')}`;
+}
+
+export async function handleStyleGuide(args: Args) {
+  try { return await handleStyleGuideAction(args); } catch (error) {
+    return text(`Style Guide ${args.action || 'get'} failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+async function handleStyleGuideAction(args: Args) {
+  const action = args.action || 'get';
+  const projectPath = args.projectPath || process.cwd();
+  const defaulted = args.projectPath ? '' : `\n(No projectPath given: used ${projectPath}. ${PASS_PATH})`;
+
+  if (action === 'list') {
+    const res = await ni.listStyleGuideProjects();
+    if (!Array.isArray(res)) return text(`Failed to list projects: ${(res as ni.NiResponse).error || 'unexpected response'}`);
+    const projects = res as Array<{ path: string; label: string; saved: boolean; revision: number; updatedAt: string | null; hasDesignFile: boolean; proposalsPending: number }>;
+    if (projects.length === 0) return text('No projects registered.');
+    const rows = projects.map((p) => `- ${p.label} (${p.path}) · ${p.saved ? `style guide rev ${p.revision}${p.updatedAt ? `, updated ${p.updatedAt}` : ''}` : 'no style guide saved'}${p.hasDesignFile ? ' · DESIGN.md ✓' : ''}${p.proposalsPending ? ` · ${p.proposalsPending} pending proposal${p.proposalsPending === 1 ? '' : 's'}` : ''}`);
+    return text(`Registered projects (${projects.length}):\n${rows.join('\n')}`);
+  }
+
+  if (action === 'summary') {
+    const res = await ni.getStyleGuideSummary(projectPath, args.taskClass);
+    if (res.error) return text(failure('Failed to load the style guide', res, projectPath));
+    const root = String(res.projectPath || projectPath);
+    return text([
+      `Style Guide summary — ${root} (rev ${res.revision ?? 0}${res.saved ? '' : ', not saved yet: these are the defaults'})`,
+      '',
+      String(res.summary || '(empty)'),
+      '',
+      `More: action "get" (the full DESIGN.md), "tokens" (CSS variables, Tailwind theme, design tokens), "contrast", "propose". Use projectPath "${root}".${defaulted}`,
+    ].join('\n'));
+  }
+
+  if (action === 'tokens') {
+    const format = args.format || 'json';
+    const res = await ni.getStyleGuideExport(projectPath, format, args.theme);
+    if (res.error) return text(failure('Failed to load the tokens', res, projectPath));
+    return text(`Style Guide tokens — ${format}${args.theme ? ` (${args.theme})` : ''}, rev ${res.revision ?? 0}${defaulted}\n\n${String(res.text || '').trim()}`);
+  }
+
+  if (action === 'contrast') {
+    if (!args.fg || !args.bg) return text('contrast needs fg and bg: two colors (hex, rgb(), hsl(), oklch()) or aliases like "{semantic.text}" and "{semantic.background}".');
+    const usesAlias = /\{/.test(`${args.fg}${args.bg}`);
+    const res = await ni.styleGuideContrast({
+      fg: args.fg, bg: args.bg, size: args.size,
+      ...(usesAlias || args.projectPath ? { projectPath } : {}), ...(args.theme ? { theme: args.theme } : {}),
+    });
+    if (res.error) return text(failure('Contrast check failed', res, projectPath));
+    const large = res.size === 'large';
+    const mark = (ok: unknown) => (ok ? 'pass' : 'fail');
+    return text([
+      `${res.fg} on ${res.bg}: ${res.ratio}:1`,
+      `WCAG 2.x ${large ? 'large text / UI' : 'normal text'}: AA ${mark(res.aa)} (needs ${large ? 3 : 4.5}:1) · AAA ${mark(res.aaa)} (needs ${large ? 4.5 : 7}:1)${large ? '' : ` · as large text or UI: AA ${mark(res.aaLarge)} (3:1)`}`,
+      `APCA Lc ${res.apca} (advisory; about 75 for body text, 60 for large text, 45 for headlines)`,
+    ].join('\n'));
+  }
+
+  if (action === 'propose') {
+    if (!args.changes || typeof args.changes !== 'object' || Array.isArray(args.changes) || !Object.keys(args.changes).length) {
+      return text('propose needs changes: a JSON merge patch against the guide, e.g. {"colors":{"status":{"danger":"#dc2626"}}}. Read the current values with action "tokens" or "get" first.');
+    }
+    if (!args.reason || !args.reason.trim()) return text('propose needs a reason: say why the guide should change.');
+    const res = await ni.proposeStyleGuideChange({ projectPath, changes: args.changes, reason: args.reason.trim(),
+      ...(args.runId ? { runId: args.runId } : {}), ...(args.provider ? { provider: args.provider } : {}), ...(args.model ? { model: args.model } : {}),
+    });
+    if (res.error) return text(failure('Proposal not recorded', res, projectPath));
+    const diff = (Array.isArray(res.diff) ? res.diff : []) as DiffRow[];
+    const ignored = (Array.isArray(res.ignored) ? res.ignored : []) as string[];
+    return text([
+      `Proposal ${res.id} recorded (${res.pending} pending). Nothing changed yet: the user accepts or rejects it in the Style Guide panel. Keep working with the current tokens.`,
+      ...(diff.length ? ['It would change:', ...diffLines(diff)] : []),
+      ...(ignored.length ? [`Ignored (not open to proposals): ${ignored.join(', ')}`] : []),
+    ].join('\n'));
+  }
+
+  if (action === 'proposals') {
+    const res = await ni.listStyleGuideProposals(projectPath, args.status);
+    if (!Array.isArray(res)) return text(failure('Failed to list proposals', res as ni.NiResponse, projectPath));
+    const rows = res as Array<{ id: string; at: string; status: string; reason: string; diff?: DiffRow[]; decidedAt?: string | null }>;
+    if (!rows.length) return text(`No ${args.status ? `${args.status} ` : ''}proposals for this project.`);
+    return text([
+      `Proposals (${rows.length}):`,
+      ...rows.flatMap((row) => [
+        `- ${row.id} · ${row.status}${row.decidedAt ? ` ${row.decidedAt}` : ''} · proposed ${row.at} · ${row.reason}`,
+        ...diffLines(row.diff || [], 6).map((line) => `  ${line}`),
+      ]),
+    ].join('\n'));
+  }
+
+  if (action === 'export') {
+    const res = await ni.writeStyleGuideExports(projectPath, args.formats);
+    if (res.error) return text(failure('Export failed', res, projectPath));
+    const written = (Array.isArray(res.written) ? res.written : []) as WrittenFile[];
+    if (!written.length) return text('Nothing to write: every export is turned off for this project (Style Guide → Import & export).');
+    return text(`Wrote ${written.length} file${written.length === 1 ? '' : 's'} from the saved guide:\n${written.map((file) => `- ${file.format} → ${file.path}${file.changed === false ? ' (already current)' : ''}`).join('\n')}`);
+  }
+
+  // action === 'get'
+  const res = await ni.getStyleGuide(projectPath);
+  if (res.error) return text(failure('Failed to load the style guide', res, projectPath));
+  const root = String(res.projectPath || projectPath);
+  const saved = res.saved !== false;
+  const written = (Array.isArray(res.written) ? res.written : []) as WrittenFile[];
+  let design = String(res.designMd || '');
+  let source = 'rendered from the saved guide';
+  // A project with no saved guide may still have a DESIGN.md somebody wrote: that file is its guide.
+  const designPath = resolve(root, 'DESIGN.md');
+  if (!saved && res.hasDesignFile && existsSync(designPath)) {
+    source = 'the defaults: this project has no saved guide';
+    try {
+      const stat = lstatSync(designPath);
+      if (stat.isFile() && !stat.isSymbolicLink() && stat.size <= 2 * 1024 * 1024) {
+        design = readFileSync(designPath, 'utf-8'); source = `the project's own file, ${designPath}`;
+      }
+    } catch { /* keep the rendered defaults */ }
+  } else if (!saved) source = 'the defaults: this project has no saved guide';
+  let body = design.trim() || '(empty)';
+  let sectionNote = '';
+  if (args.section) {
+    const found = markdownSection(design, args.section);
+    if (found.section) { body = found.section; sectionNote = ` · section "${args.section}"`; }
+    else sectionNote = ` · no section "${args.section}" (sections: ${found.names.join(', ')}), showing all`;
+  }
+  const pending = Number(res.proposalsPending) || 0;
+  return text([
+    `Style Guide — ${root} (rev ${res.revision ?? 0}${saved ? '' : ', not saved yet'})`,
+    '',
+    String(res.summary || '(no tokens defined yet)'),
+    '',
+    filesLine(written),
+    ...(pending ? [`Pending proposals: ${pending}`] : []),
+    `To suggest a change: action "propose" with changes + reason. Never edit DESIGN.md or the token files by hand.${defaulted}`,
+    '',
+    `── DESIGN.md (${source})${sectionNote} ──`,
+    '',
+    body,
+  ].join('\n'));
+}

package/mcp-server/src/tools/style-guide.ts

@@ -0,0 +1,16 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+import {
+  styleGuideSchema, styleGuideDescription, handleStyleGuide,
+} from './style-guide-tools.js';
+
+/**
+ * Register the SynaBun Style Guide MCP tool on the given server instance.
+ * Single tool with action-based dispatch:
+ * get | summary | tokens | contrast | propose | proposals | export | list.
+ */
+export function registerStyleGuideTools(server: McpServer) {
+  return [
+    server.tool('style_guide', styleGuideDescription, styleGuideSchema, handleStyleGuide),
+  ];
+}