wize-dev-kit 0.1.4 → 0.2.0

package/src/web-overlay/stack-catalog.md

@@ -0,0 +1,208 @@
+---
+catalog: web-stack
+owner: wize-agent-architect   # Tony (with Fury on strategy)
+applies_when: web-overlay active
+status: ready
+---
+
+# Web Stack Catalog — Tony's Reference
+
+Tony reads this during the architecture interview. The catalog is opinionated but lists trade-offs honestly; the final pick depends on the PRD audience, Fury's NFR budget, and team comfort.
+
+## 1. Decision dimensions
+
+Pick by **dimension order**, not "which framework I like":
+
+1. **Audience reach** — public marketing + SEO, or authenticated app?
+2. **Latency budget** — sub-1s LCP on 3G, or richer-but-slower OK?
+3. **Team familiarity** — favor the boring choice the team has shipped before.
+4. **Backend coupling** — separate API, fullstack monolith, or BaaS?
+5. **Deploy target** — edge platform, container, or self-managed?
+
+## 2. Front-end frameworks
+
+### Next.js (React)
+
+| | |
+|---|---|
+| **Pick when** | SEO-critical pages + product app in one codebase. Strong ecosystem. |
+| **Strengths** | App Router (RSC), edge runtime, ISR, large hiring pool. |
+| **Costs** | RSC mental model still maturing; vendor lock-in toward Vercel optional but present. |
+| **Bundle baseline** | React runtime ~45 KB gz + framework code. |
+| **Best for** | Public products needing SEO + auth product behind same domain. |
+
+### Nuxt 3 (Vue)
+
+| | |
+|---|---|
+| **Pick when** | Vue-shop wanting Next-tier DX. |
+| **Strengths** | Composition API ergonomics, auto-imports, modules ecosystem. |
+| **Costs** | Smaller third-party SDK coverage than React. |
+| **Bundle baseline** | Vue runtime ~30 KB gz. |
+| **Best for** | Marketing + dashboard hybrid where Vue is the team's stack. |
+
+### SvelteKit
+
+| | |
+|---|---|
+| **Pick when** | Smallest runtime + fastest TTI. |
+| **Strengths** | Compile-to-no-runtime, intuitive reactivity, edge-first. |
+| **Costs** | Smaller hiring pool, fewer enterprise integrations. |
+| **Bundle baseline** | ~0 KB framework runtime; only your code. |
+| **Best for** | Latency-sensitive products, content-heavy + interactive. |
+
+### Astro
+
+| | |
+|---|---|
+| **Pick when** | Content-first (docs, marketing, blog) with islands of interactivity. |
+| **Strengths** | Zero-JS by default; mix frameworks per island. |
+| **Costs** | Not a SPA; not the right tool for heavy state apps. |
+| **Bundle baseline** | ~0 KB unless you opt into an island. |
+| **Best for** | Marketing sites, docs portals, mostly-static products. |
+
+### Remix
+
+| | |
+|---|---|
+| **Pick when** | Forms + nested routes + progressive enhancement matter. |
+| **Strengths** | Web fundamentals first; great for "works without JS" requirements. |
+| **Costs** | Smaller community than Next; some patterns ported back to Next. |
+| **Bundle baseline** | React runtime + Remix glue. |
+| **Best for** | Form-heavy apps (admin, e-commerce flows). |
+
+### SPAs without SSR (CRA-style, Vite + React/Vue/Svelte)
+
+| | |
+|---|---|
+| **Pick when** | Authenticated app behind login; SEO not required. |
+| **Strengths** | Simplest mental model; fast iteration. |
+| **Costs** | Slow LCP for first-time visitors; no SEO. |
+| **Best for** | Internal tools, dashboards, B2B authenticated apps. |
+
+### Laravel + Vue (Inertia)
+
+| | |
+|---|---|
+| **Pick when** | PHP back-end exists + team is PHP-fluent. |
+| **Strengths** | Server-rendered routing + SPA UX; great DX in monolith mode. |
+| **Costs** | PHP hosting realities; smaller real-time ecosystem. |
+| **Best for** | Brownfield Laravel apps modernizing the front-end. |
+
+## 3. Back-end / data layer
+
+### Supabase
+
+| | |
+|---|---|
+| **Pick when** | Need Postgres + auth + storage + realtime with low setup. |
+| **Strengths** | Full Postgres power, RLS, edge functions, GoTrue auth. |
+| **Costs** | Lock-in to Supabase service surface (mitigated by being Postgres underneath). |
+
+### PlanetScale / Neon (managed Postgres)
+
+| | |
+|---|---|
+| **Pick when** | Need managed serverless Postgres without the rest of Supabase. |
+| **Strengths** | Branching DBs, generous free tiers, edge-friendly. |
+| **Costs** | You ship your own auth, storage, realtime. |
+
+### Drizzle ORM
+
+| | |
+|---|---|
+| **Pick when** | TypeScript-first ORM, edge-runtime compatibility matters. |
+| **Strengths** | Tiny runtime, SQL-y; great for serverless. |
+| **Costs** | Smaller ecosystem than Prisma. |
+
+### Prisma
+
+| | |
+|---|---|
+| **Pick when** | Larger team; tooling and migrations are paramount. |
+| **Strengths** | Excellent migrations, generated client, mature ecosystem. |
+| **Costs** | Heavier runtime; edge story improved but not as native as Drizzle. |
+
+### tRPC
+
+| | |
+|---|---|
+| **Pick when** | Single TS monorepo, server + client share types. |
+| **Strengths** | Type-safe end-to-end; minimal overhead. |
+| **Costs** | Not language-agnostic; OpenAPI shim needed for external consumers. |
+
+### GraphQL (Apollo / urql / Relay)
+
+| | |
+|---|---|
+| **Pick when** | Many client consumers, federated data sources. |
+| **Strengths** | Per-client shape, schema-first design. |
+| **Costs** | Server complexity; caching nuance; not always worth it for one client. |
+
+## 4. Authentication
+
+| Choice | Pick when |
+|---|---|
+| Supabase Auth (GoTrue) | Using Supabase already. |
+| Clerk / Auth0 | Need polished UI + SSO out of the box; team avoids auth complexity. |
+| WorkOS | Enterprise SSO + SCIM from day one. |
+| Lucia | Self-hosted, TS, full control, smaller team. |
+| Roll-your-own | Almost never. |
+
+## 5. Hosting / deploy
+
+| Choice | Pick when |
+|---|---|
+| **Vercel** | Next.js / Nuxt / SvelteKit, edge functions, generous DX. |
+| **Cloudflare Pages + Workers** | Latency, global edge, low cost. |
+| **Fly.io** | Need a real container with TCP, sticky regions. |
+| **Coolify** (self-hosted PaaS) | Want Vercel-ish DX on own infra. |
+| **Render / Railway** | Container apps + databases under one billing. |
+| **Self-hosted Docker** | Heavy compliance constraints. |
+
+## 6. Styling
+
+| Choice | Pick when |
+|---|---|
+| **Tailwind CSS** | Token-first design system, utility-class team comfort. |
+| **CSS Modules** | Component-scoped, no runtime, easy SSR. |
+| **Vanilla Extract** | Type-safe styling at build time. |
+| **shadcn-ui / Radix Primitives** | Need accessible primitives without ceding design. |
+| **Linaria / Compiled** | CSS-in-JS without runtime cost. |
+
+Mantis owns tokens (`.wize/solutioning/design-system/tokens.json`); Tony picks the system that maps those tokens cleanly.
+
+## 7. State management
+
+| Choice | Pick when |
+|---|---|
+| **React Server Components / Suspense** | Most data is server-derived. |
+| **TanStack Query** | Heavy client-side data + caching. |
+| **Zustand** | Small global state; no boilerplate. |
+| **Jotai** | Atoms feel right for the domain. |
+| **Pinia** (Vue) | Default Vue store. |
+| **Redux Toolkit** | Time-travel, complex async pipelines, large team. |
+
+## 8. Forms
+
+| Choice | Pick when |
+|---|---|
+| **React Hook Form + Zod** | Type-safe schemas, low re-render count. |
+| **Conform** | Server-progressive enhancement (Remix). |
+| **TanStack Form** | TanStack ecosystem, schema-agnostic. |
+
+## 9. Anti-patterns Tony flags fast
+
+- Mixing **SSR + heavy client state** without a clear seam.
+- Loading `lodash` for one function.
+- Using **Redux for an app with 3 stores** of 5 keys each.
+- Picking a tech because it's on a HackerNews front page.
+- Defaulting to GraphQL for a one-client app.
+
+## 10. Recording the choice
+
+Tony writes the chosen stack into:
+
+- `.wize/planning/tech-vision.md` (Fury): family + non-negotiables.
+- `.wize/solutioning/architecture.md` (Tony): concrete picks + reasons.
+- `.wize/solutioning/adrs/ADR-001-stack.md`: the trade-off log for future readers.

package/tools/installer/commands/agent.js

@@ -0,0 +1,197 @@
+// `wize-dev-kit agent <subcommand>` — manage built-in and custom agents.
+//
+//   list        - show every agent the active install resolves (built-in + custom)
+//   create      - scaffold a brand-new custom agent in .wize/custom/agents/{code}/
+//   edit <code> - override an existing built-in via .wize/custom/agents/{code}/customize.toml
+//
+// All write operations validate the result against schemas/agent.schema.json
+// (lite parser — no dependency on Ajv yet) and do a smoke dry-run before
+// persisting, matching the contract `wize-create-agent` describes.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const prompts = require('prompts');
+const { collectAssets } = require('../render-shared.js');
+
+const VALID_CODE = /^wize-(agent|orchestrator)(?:-[a-z0-9-]+)?$/;
+const VALID_MODULES = ['orchestrator', 'method', 'tea', 'builder', 'core', 'web-overlay', 'app-overlay', 'custom'];
+
+function ensureDir(p) { fs.mkdirSync(p, { recursive: true }); }
+
+function listAgents(kitRoot, projectRoot) {
+  const builtIn = collectAssets(kitRoot, { profiles: ['core', 'web-overlay', 'app-overlay'] })
+    .filter(a => a.kind === 'agent')
+    .map(a => ({ code: a.code, name: a.name, title: a.title, source: 'built-in' }));
+  const customDir = path.join(projectRoot, '.wize/custom/agents');
+  const custom = [];
+  if (fs.existsSync(customDir)) {
+    for (const entry of fs.readdirSync(customDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const yamlPath = path.join(customDir, entry.name, 'agent.yaml');
+      const customizePath = path.join(customDir, entry.name, 'customize.toml');
+      if (fs.existsSync(yamlPath)) {
+        const yaml = fs.readFileSync(yamlPath, 'utf-8');
+        const name = (yaml.match(/^name:\s*(.+)$/m) || [])[1] || entry.name;
+        const title = (yaml.match(/^title:\s*(.+)$/m) || [])[1] || '';
+        custom.push({ code: entry.name, name: name.trim(), title: title.trim(), source: 'custom' });
+      } else if (fs.existsSync(customizePath)) {
+        custom.push({ code: entry.name, name: '(override)', title: '', source: 'override' });
+      }
+    }
+  }
+  return { builtIn, custom };
+}
+
+function cmdAgentList({ kitRoot, projectRoot, log = console.log } = {}) {
+  const { builtIn, custom } = listAgents(kitRoot, projectRoot);
+  log('Built-in agents:');
+  for (const a of builtIn) log(`  ${a.code.padEnd(36)} ${a.name}${a.title ? ' — ' + a.title : ''}`);
+  if (custom.length) {
+    log('\nCustom / override agents (from .wize/custom/agents/):');
+    for (const a of custom) log(`  ${a.code.padEnd(36)} ${a.name}${a.title ? ' — ' + a.title : ''}   [${a.source}]`);
+  } else {
+    log('\nCustom / override agents: (none yet — use `wize-dev-kit agent create`)');
+  }
+  return { builtIn, custom };
+}
+
+function validateAgent(spec, kitRoot) {
+  const errs = [];
+  if (!spec.code) errs.push('code is required');
+  else if (!VALID_CODE.test(spec.code)) errs.push(`code "${spec.code}" must match wize-(agent|orchestrator)[-name]`);
+  if (!spec.name) errs.push('name is required');
+  if (!spec.title) errs.push('title is required');
+  if (!VALID_MODULES.includes(spec.module)) errs.push(`module must be one of: ${VALID_MODULES.join(', ')}`);
+  if (!spec.description || spec.description.length < 10) errs.push('description must be ≥ 10 characters');
+  // Collide check against built-ins when not overriding.
+  const builtinCodes = collectAssets(kitRoot, { profiles: ['core', 'web-overlay', 'app-overlay'] })
+    .filter(a => a.kind === 'agent').map(a => a.code);
+  if (builtinCodes.includes(spec.code) && !spec.allowOverride) {
+    errs.push(`code "${spec.code}" already exists as a built-in. Use \`wize-dev-kit agent edit ${spec.code}\` to override.`);
+  }
+  return errs;
+}
+
+function renderAgentYaml(spec) {
+  return [
+    `code: ${spec.code}`,
+    `name: ${spec.name}`,
+    `title: ${spec.title}`,
+    `icon: "${spec.icon || '🔧'}"`,
+    `team: ${spec.team || 'software-development'}`,
+    `module: ${spec.module}`,
+    '',
+    'description: |',
+    ...spec.description.split('\n').map(l => '  ' + l),
+    ''
+  ].join('\n');
+}
+
+function renderPersonaMd(spec) {
+  const body = (spec.persona || `I am **${spec.name}**. ${spec.description}`).trim();
+  return [
+    `# ${spec.name} — ${spec.title}`,
+    '',
+    body,
+    ''
+  ].join('\n');
+}
+
+// Smoke dry-run: write to temp dir, re-read, assert frontmatter parses.
+function dryRunPersist(spec) {
+  const tmp = path.join(require('node:os').tmpdir(), `wize-agent-${spec.code}-${Date.now()}`);
+  ensureDir(tmp);
+  try {
+    fs.writeFileSync(path.join(tmp, 'agent.yaml'), renderAgentYaml(spec), 'utf-8');
+    fs.writeFileSync(path.join(tmp, 'persona.md'), renderPersonaMd(spec), 'utf-8');
+    const reread = fs.readFileSync(path.join(tmp, 'agent.yaml'), 'utf-8');
+    if (!/^code:\s+/m.test(reread)) throw new Error('emitted agent.yaml has no "code:" line');
+    if (!/^name:\s+/m.test(reread)) throw new Error('emitted agent.yaml has no "name:" line');
+    return { ok: true };
+  } finally {
+    try { fs.rmSync(tmp, { recursive: true, force: true }); } catch (_) {}
+  }
+}
+
+async function cmdAgentCreate({ kitRoot, projectRoot, opts = {} } = {}) {
+  const interactive = process.stdout.isTTY && process.stdin.isTTY && !opts.fromSpec;
+  let spec = opts.fromSpec || {};
+
+  if (interactive) {
+    const a = await prompts([
+      { type: 'text', name: 'code',  message: 'Agent code (e.g. wize-agent-runbooks)',
+        validate: v => VALID_CODE.test(v) || 'must match wize-(agent|orchestrator)[-name]' },
+      { type: 'text', name: 'name',  message: 'Display name (e.g. Riri Williams)', validate: v => !!v.trim() || 'required' },
+      { type: 'text', name: 'title', message: 'Role / title (e.g. Reliability Engineer)', validate: v => !!v.trim() || 'required' },
+      { type: 'text', name: 'icon',  message: 'Icon emoji (optional)', initial: '🔧' },
+      { type: 'text', name: 'team',  message: 'Team', initial: 'software-development' },
+      { type: 'select', name: 'module', message: 'Module', choices: VALID_MODULES.map(v => ({ title: v, value: v })), initial: VALID_MODULES.indexOf('custom') },
+      { type: 'text', name: 'description', message: 'One-paragraph description (≥ 10 chars)', validate: v => v.length >= 10 || 'must be ≥ 10 characters' },
+      { type: 'text', name: 'persona', message: 'Persona body (optional — defaults to description)', initial: '' }
+    ], { onCancel: () => process.exit(130) });
+    spec = { ...spec, ...a };
+  }
+
+  const errs = validateAgent(spec, kitRoot);
+  if (errs.length) {
+    console.error('✖ Validation failed:');
+    for (const e of errs) console.error('  - ' + e);
+    process.exit(2);
+  }
+
+  const dry = dryRunPersist(spec);
+  if (!dry.ok) {
+    console.error('✖ Dry-run failed; aborting.');
+    process.exit(3);
+  }
+
+  const target = path.join(projectRoot, '.wize/custom/agents', spec.code);
+  ensureDir(target);
+  fs.writeFileSync(path.join(target, 'agent.yaml'), renderAgentYaml(spec), 'utf-8');
+  fs.writeFileSync(path.join(target, 'persona.md'), renderPersonaMd(spec), 'utf-8');
+
+  console.log(`✓ Created ${path.relative(projectRoot, target)}/`);
+  console.log('  Run `wize-dev-kit sync` to refresh IDE adapter outputs with the new agent.');
+  return { code: spec.code, path: target };
+}
+
+async function cmdAgentEdit({ kitRoot, projectRoot, code, opts = {} } = {}) {
+  if (!code) {
+    console.error('Usage: wize-dev-kit agent edit <code>');
+    process.exit(1);
+  }
+  const builtinCodes = collectAssets(kitRoot, { profiles: ['core', 'web-overlay', 'app-overlay'] })
+    .filter(a => a.kind === 'agent').map(a => a.code);
+  if (!builtinCodes.includes(code)) {
+    console.error(`✖ "${code}" is not a built-in agent. Use \`wize-dev-kit agent create\` for new agents.`);
+    process.exit(2);
+  }
+
+  const target = path.join(projectRoot, '.wize/custom/agents', code);
+  ensureDir(target);
+  const customize = path.join(target, 'customize.toml');
+  if (fs.existsSync(customize) && !opts.force) {
+    console.log(`= ${path.relative(projectRoot, customize)} already exists. Edit it directly.`);
+    return { code, path: customize };
+  }
+  fs.writeFileSync(customize, `# Wize Dev Kit — overrides for the built-in agent "${code}".
+# This file is loaded on top of the built-in agent's persona.md / agent.yaml
+# at IDE adapter render time. Only the fields you set here are overridden.
+
+[persona]
+# motto      = "your custom motto"
+# voice      = "succinct and irreverent"
+# style      = "show with code, not prose"
+
+[behavior]
+# defer_to   = []         # e.g. ["wize-agent-pm"] to lower priority on certain decisions
+# tools_deny = []         # tool codes the override removes from the agent
+`, 'utf-8');
+  console.log(`✓ Created ${path.relative(projectRoot, customize)}`);
+  console.log('  Edit the file, then run `wize-dev-kit sync` to apply.');
+  return { code, path: customize };
+}
+
+module.exports = { cmdAgentList, cmdAgentCreate, cmdAgentEdit, listAgents, validateAgent };

package/tools/installer/commands/sync.js

@@ -0,0 +1,45 @@
+// `wize-dev-kit sync` — regenerate adapter outputs for the IDE targets the
+// project opted into. Useful after editing .wize/config/project.toml,
+// running `agent create`, or pulling kit changes that don't bump version.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { loadProjectConfig } = require('./update.js');
+
+function cmdSync({ kitRoot, projectRoot, opts = {} } = {}) {
+  const log = opts.log || console.log;
+  const cfg = loadProjectConfig(projectRoot);
+  if (!cfg.project) {
+    log('No .wize/config/project.toml found here. Run `wize-dev-kit install` first.');
+    return { changed: false };
+  }
+  const ideTargets = (cfg.install && cfg.install.ide_targets) || ['claude-code', 'generic'];
+  const profiles = (cfg.install && cfg.install.profiles) || ['core'];
+  log(`Syncing ${ideTargets.length} adapter(s) for profile(s) ${profiles.join(' + ')}:`);
+
+  const results = [];
+  for (const code of ideTargets) {
+    const renderPath = path.join(kitRoot, 'adapters', code, 'render.js');
+    if (!fs.existsSync(renderPath)) {
+      log(`  - ${code}: skipped (adapter missing in installed kit)`);
+      results.push({ code, skipped: true });
+      continue;
+    }
+    delete require.cache[require.resolve(renderPath)];
+    try {
+      const out = require(renderPath).render(kitRoot, projectRoot, { profiles });
+      const n = out && Array.isArray(out.written) ? out.written.length : 0;
+      log(`  ✓ ${code}: ${n} file(s) emitted`);
+      results.push({ code, written: n });
+    } catch (err) {
+      log(`  ✖ ${code}: ${err.message}`);
+      results.push({ code, error: err.message });
+    }
+  }
+  log('\nDone. Restart your IDE if it caches skills at startup.');
+  return { changed: true, adapters: results };
+}
+
+module.exports = { cmdSync };

package/tools/installer/commands/update.js

@@ -0,0 +1,172 @@
+// `wize-dev-kit update` — refresh an installed kit to the version currently
+// resolved by `node_modules/wize-dev-kit`. Preserves .wize/config/user.toml,
+// re-runs the active IDE adapters, and re-applies the .gitignore block when
+// it was opted-in originally.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { applyGitignore } = require('../setup-helpers.js');
+
+// Minimal TOML reader for the subset we write — handles `[section]` headers,
+// `key = "value"` scalars, and `key = ["a", "b"]` string arrays.
+function readToml(file) {
+  if (!fs.existsSync(file)) return {};
+  const content = fs.readFileSync(file, 'utf-8');
+  const out = {};
+  let section = null;
+  for (const raw of content.split('\n')) {
+    const line = raw.replace(/#.*$/, '').trim();
+    if (!line) continue;
+    const head = line.match(/^\[([^\]]+)\]$/);
+    if (head) { section = head[1]; out[section] = out[section] || {}; continue; }
+    const kv = line.match(/^([a-zA-Z_][\w-]*)\s*=\s*(.+)$/);
+    if (!kv) continue;
+    const [, key, valRaw] = kv;
+    const v = parseTomlValue(valRaw.trim());
+    if (section) out[section][key] = v;
+    else out[key] = v;
+  }
+  return out;
+}
+
+function parseTomlValue(raw) {
+  if (raw.startsWith('"') && raw.endsWith('"')) return raw.slice(1, -1);
+  if (raw.startsWith("'") && raw.endsWith("'")) return raw.slice(1, -1);
+  if (raw.startsWith('[') && raw.endsWith(']')) {
+    return raw.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+  }
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  if (!isNaN(Number(raw))) return Number(raw);
+  return raw;
+}
+
+function loadProjectConfig(projectRoot) {
+  return readToml(path.join(projectRoot, '.wize/config/project.toml'));
+}
+
+function loadInstalledKitVersion(kitRoot) {
+  try { return require(path.join(kitRoot, 'package.json')).version; }
+  catch { return null; }
+}
+
+// Returns a list of CHANGELOG entries (markdown blocks) for versions strictly
+// between `from` and `to`. Best-effort — if CHANGELOG layout is unusual,
+// returns an empty list and falls back to a generic note.
+function changelogBetween(kitRoot, fromVersion, toVersion) {
+  const file = path.join(kitRoot, 'CHANGELOG.md');
+  if (!fs.existsSync(file)) return [];
+  const content = fs.readFileSync(file, 'utf-8');
+  const versionRe = /^## \[(\d+\.\d+\.\d+)\][^\n]*\n/gm;
+  const matches = [];
+  let m;
+  while ((m = versionRe.exec(content)) !== null) {
+    matches.push({ v: m[1], start: m.index, headerEnd: versionRe.lastIndex });
+  }
+  for (let i = 0; i < matches.length; i++) {
+    matches[i].end = i + 1 < matches.length ? matches[i + 1].start : content.length;
+  }
+  return matches
+    .filter(x => compare(x.v, fromVersion) > 0 && compare(x.v, toVersion) <= 0)
+    .map(x => content.slice(x.start, x.end).trim());
+}
+
+function compare(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+  }
+  return 0;
+}
+
+// Re-runs every adapter that the project opted into at install time, using
+// the current versions of the kit's renderers.
+function rerunAdapters({ kitRoot, projectRoot, ideTargets, profiles, log }) {
+  const results = [];
+  for (const code of ideTargets) {
+    const renderPath = path.join(kitRoot, 'adapters', code, 'render.js');
+    if (!fs.existsSync(renderPath)) {
+      results.push({ code, skipped: true, reason: 'adapter missing in this kit version' });
+      log(`  - ${code}: skipped (adapter no longer exists)`);
+      continue;
+    }
+    delete require.cache[require.resolve(renderPath)]; // make `update` idempotent in the same process
+    try {
+      const mod = require(renderPath);
+      const out = mod.render(kitRoot, projectRoot, { profiles });
+      const n = out && Array.isArray(out.written) ? out.written.length : 0;
+      results.push({ code, written: n });
+      log(`  ✓ ${code}: ${n} file(s) refreshed`);
+    } catch (err) {
+      results.push({ code, error: err.message });
+      log(`  ✖ ${code}: ${err.message}`);
+    }
+  }
+  return results;
+}
+
+function writeUpdatedProjectToml(projectRoot, currentToml, newKitVersion) {
+  // Surgical rewrite — only updates `kit_version = ...` under `[project]`.
+  // Leaves everything else as the user/team configured it.
+  const file = path.join(projectRoot, '.wize/config/project.toml');
+  if (!fs.existsSync(file)) return false;
+  const content = fs.readFileSync(file, 'utf-8');
+  const updated = content.replace(/^kit_version\s*=\s*".*"$/m, `kit_version = "${newKitVersion}"`);
+  if (updated === content) return false;
+  fs.writeFileSync(file, updated, 'utf-8');
+  return true;
+}
+
+async function cmdUpdate({ kitRoot, projectRoot, opts = {} } = {}) {
+  const log = opts.log || console.log;
+  const cfg = loadProjectConfig(projectRoot);
+  if (!cfg.project) {
+    log('No .wize/config/project.toml found here.');
+    log('Run `wize-dev-kit install` first.');
+    return { changed: false };
+  }
+  const fromVersion = cfg.project.kit_version || '0.0.0';
+  const toVersion = loadInstalledKitVersion(kitRoot) || 'unknown';
+  if (toVersion === 'unknown') {
+    log('Could not read kit version from node_modules. Aborting.');
+    return { changed: false };
+  }
+
+  log(`Wize Dev Kit update: ${fromVersion} → ${toVersion}`);
+  if (fromVersion === toVersion) {
+    log('Already on the same version. Re-rendering adapters anyway (idempotent).');
+  }
+
+  const ideTargets = (cfg.install && cfg.install.ide_targets) || ['claude-code', 'generic'];
+  const profiles = (cfg.install && cfg.install.profiles) || ['core'];
+
+  log('\nRe-rendering active IDE adapters:');
+  const adapterResults = rerunAdapters({ kitRoot, projectRoot, ideTargets, profiles, log });
+
+  if (opts.refreshGitignore !== false) {
+    const r = applyGitignore(projectRoot);
+    if (r.changed) log(`\n✓ .gitignore ${r.mode}`);
+    else            log('\n= .gitignore already up to date');
+  }
+
+  writeUpdatedProjectToml(projectRoot, cfg, toVersion);
+  log(`\n✓ project.toml kit_version → ${toVersion}`);
+
+  const entries = changelogBetween(kitRoot, fromVersion, toVersion);
+  if (entries.length) {
+    log(`\nWhat changed (excerpt from CHANGELOG):`);
+    for (const e of entries) {
+      log(e.split('\n').slice(0, 4).map(l => '  ' + l).join('\n'));
+      log('  …');
+    }
+    log(`\nFull details: ${path.join(kitRoot, 'CHANGELOG.md')}`);
+  }
+
+  log('\nDone. Restart your IDE so the refreshed slash commands are picked up.');
+  return { changed: true, from: fromVersion, to: toVersion, adapters: adapterResults };
+}
+
+module.exports = { cmdUpdate, loadProjectConfig, loadInstalledKitVersion, changelogBetween };