@aion0/forge 0.5.48 → 0.5.50

package/lib/crafts/runtime.ts

@@ -0,0 +1,208 @@
+// Runtime: load + cache craft server modules; build the ForgeServerApi per request.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import * as esbuild from 'esbuild';
+import { pathToFileURL } from 'node:url';
+import { createTask } from '@/lib/task-manager';
+import type { CraftDescriptor, CraftServerDef, CraftRouteHandler, ForgeServerApi } from './types';
+
+// Module cache: dir → { mtimeMs, mod }
+interface CachedMod { mtimeMs: number; def: CraftServerDef; }
+const cache = new Map<string, CachedMod>();
+
+// Function-wrapped dynamic import so Turbopack doesn't try to statically resolve the URL.
+const dynamicImport = new Function('u', 'return import(u)') as (u: string) => Promise<any>;
+
+async function transpileToFile(src: string, resolveDir: string): Promise<string> {
+  // Compile TS → JS, bundling the @forge/craft/server SDK inline (node_modules stays external).
+  // Cache key includes a salt so older transpile outputs are skipped after format changes.
+  const hash = require('node:crypto').createHash('md5').update('v2:' + src).digest('hex').slice(0, 16);
+  const out = join(tmpdir(), `forge-craft-${hash}.mjs`);
+  if (existsSync(out)) return out;
+  const sdkServerEntry = require('node:path').resolve(process.cwd(), 'lib/craft-sdk/server.ts');
+  const result = await esbuild.build({
+    stdin: { contents: src, loader: 'ts', resolveDir },
+    bundle: true,
+    format: 'esm',
+    platform: 'node',
+    target: 'node20',
+    packages: 'external',
+    alias: {
+      '@forge/craft/server': sdkServerEntry,
+    },
+    write: false,
+  });
+  writeFileSync(out, result.outputFiles[0].text, 'utf8');
+  return out;
+}
+
+export async function loadServer(craft: CraftDescriptor): Promise<CraftServerDef | null> {
+  if (!craft.hasServer) return null;
+  const file = join(craft.__dir, craft.server?.entry || 'server.ts');
+  const stat = statSync(file);
+  const cached = cache.get(craft.__dir);
+  if (cached && cached.mtimeMs === stat.mtimeMs) return cached.def;
+
+  const src = readFileSync(file, 'utf8');
+  const compiled = await transpileToFile(src, craft.__dir);
+  // Bust ESM cache by adding a query string (Node ESM caches by URL).
+  // Use Function() so Turbopack doesn't try to statically analyze the import.
+  const url = pathToFileURL(compiled).href + `?t=${stat.mtimeMs}`;
+  const mod = await dynamicImport(url);
+  const def: CraftServerDef = mod.default ?? mod.craft ?? mod;
+  if (!def || typeof def !== 'object' || !def.routes) {
+    throw new Error(`Craft "${craft.name}" server.ts must export default defineCraftServer({...})`);
+  }
+  cache.set(craft.__dir, { mtimeMs: stat.mtimeMs, def });
+  return def;
+}
+
+// Match a route key like "GET /items/:id" against a request method + path.
+function matchRoute(routeKey: string, method: string, path: string): Record<string, string> | null {
+  const [m, pat] = routeKey.split(/\s+/, 2);
+  if (m.toUpperCase() !== method.toUpperCase()) return null;
+  // Normalize: ensure leading slash on both
+  const cleanPath = path.startsWith('/') ? path : '/' + path;
+  const cleanPat = pat.startsWith('/') ? pat : '/' + pat;
+  const pSegs = cleanPath.split('/').filter(Boolean);
+  const tSegs = cleanPat.split('/').filter(Boolean);
+  if (pSegs.length !== tSegs.length) return null;
+  const params: Record<string, string> = {};
+  for (let i = 0; i < tSegs.length; i++) {
+    const t = tSegs[i];
+    const p = pSegs[i];
+    if (t.startsWith(':')) params[t.slice(1)] = decodeURIComponent(p);
+    else if (t !== p) return null;
+  }
+  return params;
+}
+
+export function findHandler(def: CraftServerDef, method: string, path: string): { handler: CraftRouteHandler; params: Record<string, string> } | null {
+  for (const [key, handler] of Object.entries(def.routes)) {
+    const params = matchRoute(key, method, path);
+    if (params) return { handler, params };
+  }
+  return null;
+}
+
+// ── Forge server-side API ────────────────────────────────
+
+export function buildForgeApi(craft: CraftDescriptor, projectPath: string, projectName?: string): ForgeServerApi {
+  const dataDir = join(craft.__dir, 'data');
+  // For builtin crafts, redirect storage to the project so writes don't go into the install
+  const writableDataDir = craft.__scope === 'builtin'
+    ? join(projectPath, '.forge', 'crafts', craft.name, 'data')
+    : dataDir;
+
+  return {
+    project: { path: projectPath, name: projectName },
+
+    storage: {
+      read<T>(file: string): T | null {
+        const f = join(writableDataDir, file);
+        if (!existsSync(f)) return null;
+        try { return JSON.parse(readFileSync(f, 'utf8')); } catch { return null; }
+      },
+      write(file: string, data: any): void {
+        if (!existsSync(writableDataDir)) mkdirSync(writableDataDir, { recursive: true });
+        writeFileSync(join(writableDataDir, file), JSON.stringify(data, null, 2), 'utf8');
+      },
+      listFiles(): string[] {
+        if (!existsSync(writableDataDir)) return [];
+        return readdirSync(writableDataDir);
+      },
+    },
+
+    exec(cmd, opts = {}) {
+      try {
+        const stdout = execSync(cmd, {
+          cwd: projectPath,
+          timeout: opts.timeout ?? 30000,
+          input: opts.input,
+          encoding: 'utf8',
+          maxBuffer: 10 * 1024 * 1024,
+        }).toString();
+        return { stdout, stderr: '', code: 0 };
+      } catch (e: any) {
+        return { stdout: (e?.stdout || '').toString(), stderr: (e?.stderr || e?.message || '').toString(), code: e?.status ?? 1 };
+      }
+    },
+
+    task(opts) {
+      const task = createTask({
+        projectName: projectName || projectPath.split('/').filter(Boolean).pop() || 'project',
+        projectPath,
+        prompt: opts.prompt,
+        agent: opts.agent,
+      });
+      return { id: task.id };
+    },
+
+    inject(text, opts = {}) {
+      // Reuse migration session-resolver logic inline
+      try {
+        const sessionName = opts.sessionName || resolveBoundSession(projectPath);
+        if (!sessionName) return { ok: false };
+        const buf = join(tmpdir(), `forge-craft-inject-${Date.now()}.txt`);
+        writeFileSync(buf, text);
+        execSync(`tmux load-buffer -t "${sessionName}" "${buf}" && tmux paste-buffer -t "${sessionName}" && sleep 0.2 && tmux send-keys -t "${sessionName}" Enter`, { timeout: 5000 });
+        try { require('node:fs').unlinkSync(buf); } catch {}
+        return { ok: true, sessionName };
+      } catch (e) {
+        return { ok: false };
+      }
+    },
+
+    openapi(specPath) {
+      try {
+        const file = join(projectPath, specPath);
+        if (!existsSync(file)) return null;
+        return JSON.parse(readFileSync(file, 'utf8'));
+      } catch { return null; }
+    },
+
+    log: (...args) => console.log(`[craft:${craft.name}]`, ...args),
+  };
+}
+
+function resolveBoundSession(projectPath: string): string | null {
+  try {
+    const sessions = execSync(`tmux list-sessions -F '#{session_name}'`, { encoding: 'utf8', timeout: 2000 })
+      .trim().split('\n').filter(Boolean).filter(n => /^mw[a-z0-9]*-/.test(n));
+    for (const s of sessions) {
+      try {
+        const cwd = execSync(`tmux display-message -p -t '${s}' '#{pane_current_path}'`, { encoding: 'utf8', timeout: 2000 }).trim();
+        if (cwd === projectPath || cwd.startsWith(projectPath + '/')) return s;
+      } catch {}
+    }
+  } catch {}
+  return null;
+}
+
+// ── UI transpile (TSX → JS) for browser dynamic import ──
+
+export async function transpileUi(craft: CraftDescriptor): Promise<string> {
+  const file = join(craft.__dir, craft.ui?.tab || 'ui.tsx');
+  if (!existsSync(file)) throw new Error('No UI file');
+  const src = readFileSync(file, 'utf8');
+  const result = await esbuild.build({
+    stdin: { contents: src, loader: 'tsx', resolveDir: craft.__dir },
+    bundle: true,
+    format: 'esm',
+    platform: 'browser',
+    target: 'es2022',
+    jsx: 'automatic',
+    write: false,
+    // Mark React + SDK as externals so they share the host page's instances
+    external: ['react', 'react/jsx-runtime', 'react-dom', '@forge/craft'],
+  });
+  // Rewrite SDK + react bare imports → absolute URLs that Forge serves.
+  let code = result.outputFiles[0].text;
+  code = code.replace(/from\s*["']react["']/g, 'from "/api/craft-system/runtime/react"');
+  code = code.replace(/from\s*["']react\/jsx-runtime["']/g, 'from "/api/craft-system/runtime/react-jsx"');
+  code = code.replace(/from\s*["']@forge\/craft["']/g, 'from "/api/craft-system/runtime/sdk"');
+  return code;
+}

package/lib/crafts/types.ts

@@ -0,0 +1,92 @@
+// Craft = a project-scoped mini-app: UI tab + optional API routes.
+// Lives at <project>/.forge/crafts/<name>/ or in lib/builtin-crafts/<name>/.
+
+export interface CraftRequirements {
+  hasFile?: string[];                 // any of these paths must exist (relative to project)
+  hasGlob?: string[];                 // any glob must match (e.g. "**/*.java")
+  // future: language, framework detection
+}
+
+export interface CraftManifest {
+  name: string;                       // unique slug, dir name
+  displayName?: string;               // tab label (default = name)
+  icon?: string;                      // emoji shown in tab
+  description?: string;
+  version?: string;
+  author?: string;                    // marketplace metadata
+  tags?: string[];                    // for marketplace browsing/filtering
+  requires?: CraftRequirements;       // project-type compatibility gate
+
+  ui?: {
+    tab?: string;                     // path to ui.tsx (default 'ui.tsx')
+    showWhen?: string;                // expression: hasFile("X") | always (v2)
+  };
+
+  server?: {
+    entry?: string;                   // path to server.ts (default 'server.ts')
+  };
+
+  // Source of truth — set by loader, not authored.
+  __dir?: string;                     // absolute dir
+  __scope?: 'builtin' | 'project';
+}
+
+export interface CraftDescriptor extends CraftManifest {
+  __dir: string;
+  __scope: 'builtin' | 'project';
+  hasUi: boolean;
+  hasServer: boolean;
+}
+
+export interface CraftRouteHandlerCtx {
+  projectPath: string;
+  projectName?: string;
+  query: Record<string, string>;
+  params: Record<string, string>;
+  body?: any;
+  headers: Record<string, string>;
+  forge: ForgeServerApi;
+}
+
+export type CraftRouteHandler = (ctx: CraftRouteHandlerCtx) => Promise<any> | any;
+
+export interface CraftServerDef {
+  routes: Record<string, CraftRouteHandler>;  // key = "METHOD path", e.g. "GET /items"
+  onLoad?: (ctx: { projectPath: string; forge: ForgeServerApi }) => Promise<void> | void;
+  schedule?: string;                          // optional cron — v2
+}
+
+// Server-side helper bag passed into every handler. Keep small + stable.
+export interface ForgeServerApi {
+  // Project context
+  project: {
+    path: string;
+    name?: string;
+  };
+
+  // Storage scoped to <project>/.forge/crafts/<name>/data/
+  storage: {
+    read<T = any>(file: string): T | null;
+    write(file: string, data: any): void;
+    listFiles(): string[];
+  };
+
+  // Run a shell command in the project cwd
+  exec(cmd: string, opts?: { timeout?: number; input?: string }): {
+    stdout: string;
+    stderr: string;
+    code: number;
+  };
+
+  // Spawn a Forge background task in this project
+  task(opts: { prompt: string; agent?: string }): { id: string };
+
+  // Inject text into the project's bound tmux session (auto-resolves)
+  inject(text: string, opts?: { sessionName?: string }): { ok: boolean; sessionName?: string };
+
+  // Lazy access to OpenAPI loader (when project has one configured)
+  openapi(specPath: string): any | null;
+
+  // Structured logging — visible in Forge logs
+  log: (...args: any[]) => void;
+}

package/lib/forge-skills/craft-builder.md

@@ -0,0 +1,231 @@
+---
+name: craft-builder
+description: Build a Forge "Craft" — a project-scoped mini-app exposed as a tab in Forge. Use when the user asks Forge to "make a tab/dashboard/tool that does X" inside their project.
+---
+
+# Forge Craft Builder
+
+A **Craft** is a project-scoped mini-app that appears as a tab in Forge. It can have:
+
+- A React UI (`ui.tsx`) — renders inside Forge's project view
+- An optional API server (`server.ts`) — handlers run on Forge's Node process
+
+Crafts live at `<project>/.forge/crafts/<craft-name>/` and travel with the project (commit them to git so the team sees the same tabs).
+
+## Your job
+
+When invoked, you produce ALL of these files in `<project>/.forge/crafts/<name>/`:
+
+```
+craft.yaml      # manifest
+ui.tsx          # React component (default export)
+server.ts       # optional — only if user needs server-side work
+prompt.md       # the original user request + iteration history (you maintain this)
+README.md       # 1-paragraph "what it does"
+data/           # auto-created when craft writes via useStore
+```
+
+After writing files, tell the user the new tab will appear in Forge after refresh (or hot-reload if dev mode).
+
+## Naming
+
+Pick a kebab-case `name` based on what the user asked for. Keep it short. Example: "API endpoint dashboard" → `api-dashboard`.
+
+The `displayName` is the tab label — include an emoji prefix matching the function (📊 for dashboards, 🔍 for explorers, ⚡ for runners, 📝 for editors, 🧪 for testers).
+
+## SDK — UI side (`ui.tsx`)
+
+Import from `@forge/craft`. ONLY these hooks are available:
+
+```tsx
+import { useProject, useForgeFetch, useInject, useTask, useStore } from '@forge/craft';
+
+// 1. Project context
+const { projectPath, projectName } = useProject();
+
+// 2. Fetch data — auto-appends ?projectPath=...; returns { data, loading, error, refetch }
+const { data, loading, error, refetch } = useForgeFetch<MyType>('/api/crafts/<your-name>/items');
+// or any Forge core API:
+const git = useForgeFetch('/api/git/status');
+
+// 3. Inject text into the project's bound tmux terminal (auto-resolves session)
+const inject = useInject();
+await inject('Run the test suite');  // sends text + Enter
+
+// 4. Spawn a Forge background task in the project
+const runTask = useTask();
+const t = await runTask('Refactor the auth module per CLAUDE.md');
+const stop = t.watch(entry => console.log(entry), final => console.log('done', final));
+
+// 5. Persistent JSON storage in <project>/.forge/crafts/<name>/data/<file>.json
+const [items, setItems, { loading, reload }] = useStore<Item[]>('items.json', []);
+await setItems([...items!, newItem]);  // writes to disk
+```
+
+Component must `export default` a React component. Use Tailwind classes and Forge CSS variables (`var(--accent)`, `var(--bg-secondary)`, `var(--text-primary)`, `var(--text-secondary)`, `var(--border)`, `var(--bg-primary)`, `var(--bg-tertiary)`) so the tab matches Forge's theme.
+
+The component is rendered inside `<div className="flex-1 flex flex-col min-h-0 overflow-hidden">` — the outermost element should be a fragment or `<div className="flex-1 ...">`.
+
+**Do not** import React directly (it's auto-injected). Do not import any other npm package — only `@forge/craft`.
+
+## SDK — Server side (`server.ts`, optional)
+
+Skip this file entirely if the craft only needs to call existing Forge APIs.
+
+```ts
+import { defineCraftServer } from '@forge/craft/server';
+
+export default defineCraftServer({
+  routes: {
+    'GET /items': async ({ projectPath, query, forge }) => {
+      // Run shell in project cwd
+      const r = forge.exec('git log --oneline -20', { timeout: 10000 });
+      return { lines: r.stdout.split('\n').filter(Boolean) };
+    },
+
+    'POST /create': async ({ body, forge }) => {
+      forge.storage.write('records.json', body);
+      return { ok: true };
+    },
+
+    'GET /load-spec': async ({ forge }) => {
+      const spec = forge.openapi('docs/openapi.json');
+      return { paths: Object.keys(spec?.paths || {}) };
+    },
+
+    'POST /fix': async ({ body, forge }) => {
+      const t = forge.task({ prompt: body.prompt });
+      return { taskId: t.id };
+    },
+
+    'POST /run-cmd': async ({ body, forge }) => {
+      forge.inject(body.cmd);  // paste into bound terminal
+      return { ok: true };
+    },
+  },
+});
+```
+
+`forge` injected helper API:
+- `forge.project` — `{ path, name }`
+- `forge.storage` — `read(file)`, `write(file, data)`, `listFiles()` (scoped to the craft's data dir)
+- `forge.exec(cmd, opts?)` — synchronous shell exec in project cwd, returns `{ stdout, stderr, code }`
+- `forge.task({ prompt, agent? })` — spawn Forge background task, returns `{ id }`
+- `forge.inject(text, opts?)` — paste into bound tmux session
+- `forge.openapi(specPath)` — load + parse OpenAPI JSON from project
+- `forge.log(...)` — structured logging
+
+Routes are auto-mounted at `/api/crafts/<craft-name>/<route>`. The UI calls them via `useForgeFetch`.
+
+## Manifest (`craft.yaml`)
+
+```yaml
+name: api-dashboard           # kebab-case, dir name
+displayName: 📊 API Dashboard  # tab label (with emoji)
+description: One-line summary of what it does
+version: 0.1.0
+icon: "📊"                     # optional, mainly cosmetic
+author: aion0                 # optional, shown in marketplace
+tags:                         # optional — for marketplace browsing
+  - openapi
+  - dashboard
+  - migration
+requires:                     # optional — project-type compatibility gate.
+  hasFile:                    # craft is hidden + can't install if NONE match.
+    - docs/openapi.json
+    - openapi.yaml
+  hasGlob:
+    - "**/*.java"             # any of the matchers passing → compatible
+ui:
+  tab: ui.tsx
+  showWhen: hasFile("docs/openapi.json")  # optional extra UI condition
+server:
+  entry: server.ts             # omit this whole block if no server.ts
+```
+
+**Tags + requires guidance:**
+
+- `tags` are free-form keywords used by the marketplace search. Common ones:
+  language (`java`, `typescript`, `python`), framework (`spring`, `react`),
+  use-case (`migration`, `testing`, `linting`, `debugging`).
+- `requires.hasFile` lists files that MUST exist somewhere in the project for
+  the craft to make sense (any one match = compatible).
+- `requires.hasGlob` is for broader matches like `**/*.java` (project has Java)
+  or `package.json` (Node project).
+- Be specific — a craft tagged `java` + `requires.hasGlob: ["**/*.java"]` won't
+  show up in a TypeScript project's marketplace.
+
+## prompt.md
+
+Always write/update this file with:
+- The original user request (verbatim)
+- Each refine request and what you changed
+- Used by future Refine runs as context
+
+## Iteration
+
+When called to refine an existing craft (the dir already exists), READ existing files first, KEEP what works, change only what the user asked. Append the refine request to `prompt.md`.
+
+## Minimum viable example
+
+```yaml
+# craft.yaml
+name: hello
+displayName: 👋 Hello
+description: Demo craft — counts project files by extension
+version: 0.1.0
+ui:
+  tab: ui.tsx
+server:
+  entry: server.ts
+```
+
+```ts
+// server.ts
+import { defineCraftServer } from '@forge/craft/server';
+
+export default defineCraftServer({
+  routes: {
+    'GET /count': async ({ forge }) => {
+      const r = forge.exec(`git ls-files | awk -F. 'NF>1{print $NF}' | sort | uniq -c | sort -rn | head -20`);
+      return { lines: r.stdout.split('\n').filter(Boolean) };
+    },
+  },
+});
+```
+
+```tsx
+// ui.tsx
+import { useProject, useForgeFetch } from '@forge/craft';
+
+export default function Tab() {
+  const { projectName } = useProject();
+  const { data, loading } = useForgeFetch<{ lines: string[] }>('/api/crafts/hello/count');
+  return (
+    <div className="flex-1 p-4 text-xs overflow-auto">
+      <h2 className="font-semibold mb-2">{projectName} — file counts</h2>
+      {loading && <div className="text-[var(--text-secondary)]">Loading…</div>}
+      {data?.lines.map((l, i) => <div key={i} className="font-mono">{l}</div>)}
+    </div>
+  );
+}
+```
+
+## Style guide
+
+- Tailwind classes only. Use Forge's color variables, not hardcoded colors.
+- Text sizes: `text-xs` (default), `text-[11px]` for dense tables, `text-[10px]` for metadata.
+- Buttons: `text-[10px] px-2 py-1 rounded bg-[var(--accent)]/20 text-[var(--accent)] hover:bg-[var(--accent)]/30`.
+- Sections inside the tab: `flex-1 flex flex-col min-h-0 overflow-auto p-4 gap-3`.
+- For tables/lists, prefer simple `<table>` or `<div>` grids — no extra deps.
+- Match Forge's compact density (rows ~24-28px tall).
+
+## Final report
+
+After writing files, report:
+1. What craft you created (name + displayName)
+2. The route(s) registered (if any server)
+3. The data files used (if any)
+4. Any assumptions you made
+
+End with `[FORGE_DONE]`.

package/lib/help-docs/15-crafts.md

@@ -0,0 +1,127 @@
+# Crafts — project-scoped mini-apps
+
+A **Craft** is a tab inside Forge that lives at `<project>/.forge/crafts/<name>/`. It can be hand-written, AI-generated, or shipped as a Forge builtin (open-source samples). Crafts travel with the project — commit them to git so the team sees the same tabs.
+
+## Quick start
+
+In any project, click **+ Craft** next to the project tabs. Type what you want (e.g. "show all our REST endpoints with migration status, allow batch run + AI fix"). Forge spawns a background task that uses the `craft-builder` skill to generate the files. After ~30-60s the new tab appears.
+
+For an existing craft, switch to its tab and click the small **⚙** badge to refine it ("add a sort button" / "this column should be wider").
+
+## Anatomy
+
+```
+<project>/.forge/crafts/<name>/
+├── craft.yaml      # manifest (name, displayName, icon, conditions)
+├── ui.tsx          # React component (default export)
+├── server.ts       # optional API routes
+├── prompt.md       # original user request + iteration history
+├── README.md       # what this craft does
+└── data/           # craft's persistent JSON storage
+```
+
+## SDK
+
+Imports from `@forge/craft` (UI side):
+
+| Hook | What it does |
+|---|---|
+| `useProject()` | `{ projectPath, projectName }` |
+| `useForgeFetch(path)` | Fetch wrapper, auto-injects `?projectPath=...`, returns `{ data, loading, error, refetch }` |
+| `useInject()` | `(text) => Promise` — paste prompt + Enter into the project's bound tmux session |
+| `useTask()` | `(prompt) => TaskHandle` — spawn Forge background task, watch its log stream |
+| `useStore(file, default)` | `[value, save, { loading, reload }]` — JSON storage in `data/<file>.json` |
+| `useOpenAPI(path)` | Load + parse OpenAPI 3 spec from project |
+| `useFile(path, { watch? })` | Read project file with optional polling |
+| `useShell()` | `(cmd) => Promise<{ stdout, stderr, code }>` — exec in project cwd |
+| `useGit()` | Git status / log info |
+| `useToast()` | `(msg, kind)` — quick top notification |
+
+Server side (`server.ts`):
+
+```ts
+import { defineCraftServer } from '@forge/craft/server';
+
+export default defineCraftServer({
+  routes: {
+    'GET /items': async ({ forge, query, params }) => {
+      const r = forge.exec('git log --oneline -20');
+      return { lines: r.stdout.split('\n') };
+    },
+    'POST /run': async ({ body, forge }) => {
+      const t = forge.task({ prompt: body.prompt });
+      return { taskId: t.id };
+    },
+  },
+});
+```
+
+`forge` injected helpers:
+- `forge.project` — `{ path, name }`
+- `forge.storage` — `read(file)`, `write(file, data)`, `listFiles()` (scoped to craft data dir)
+- `forge.exec(cmd, opts?)` — sync shell exec in project cwd
+- `forge.task({ prompt })` — spawn background task
+- `forge.inject(text)` — paste into bound tmux session
+- `forge.openapi(specPath)` — load + parse OpenAPI JSON
+- `forge.log(...)` — structured logging
+
+Routes are mounted at `/api/crafts/<craft-name>/<route>`. The UI calls them via `useForgeFetch`.
+
+## Manifest
+
+```yaml
+name: api-dashboard           # kebab-case, dir name
+displayName: 📊 API Dashboard  # tab label
+description: One-line summary
+version: 0.1.0
+icon: "📊"
+ui:
+  tab: ui.tsx                 # default
+  showWhen: hasFile("docs/openapi.json")  # optional condition
+server:
+  entry: server.ts            # default; omit if no server
+```
+
+`showWhen` supports `hasFile("path")` (only show tab when file exists) or `always`.
+
+## Builtins
+
+`lib/builtin-crafts/<name>/` is the slot for crafts that ship with Forge by default. Currently empty — every craft is project-local at `<project>/.forge/crafts/<name>/`. Builtins (when present) appear automatically in every project; project-local crafts override builtins by name.
+
+## Marketplace
+
+Crafts can be published to a shared registry (default: `aiwatching/forge-crafts` on GitHub). The marketplace browser is reachable from the **Crafts ▾** dropdown in any project tab — pick **🛒 Marketplace** to see installable crafts filtered by your project's compatibility.
+
+### Browse + install
+- **Compatible / All / Installed** filter
+- Shows version, author, tags, and a per-item Install / Update / Uninstall button
+- Install copies the registry's files into `<project>/.forge/crafts/<name>/`; the new tab appears immediately
+
+### Project-type filtering (`requires`)
+
+Add a `requires` block to `craft.yaml` so the marketplace only suggests the craft to compatible projects:
+
+```yaml
+requires:
+  hasFile:                    # any of these files must exist
+    - docs/openapi.json
+  hasGlob:
+    - "**/*.java"             # any of these globs must match
+```
+
+Either matcher passing is enough (OR logic). With an empty/missing `requires`, the craft is compatible with every project.
+
+### Publish
+
+When a project-local craft is the active tab, the **📦** button next to ⚙ opens the publish modal. It shows:
+1. **How to publish** — step-by-step (open a PR on the registry repo).
+2. **registry.json entry** — JSON snippet to append under `crafts: [...]`.
+3. **Files** — copy each file's contents (`craft.yaml`, `ui.tsx`, `server.ts`, `README.md`) to drop into the registry repo's `<name>/` folder.
+
+Forge does NOT auto-push to GitHub. Submit the PR; once merged, all Forge users see it in their marketplace.
+
+The repo URL is configurable via `craftsRepoUrl` in `~/.forge/data/settings.yaml` so teams can run their own private registry.
+
+## Architectural model
+
+Forge is the **orchestrator**: discovers crafts, mounts UI tabs + API routes, provides the SDK. The craft is **your project's content** — stored in `<project>/.forge/`, not in Forge core. Generic features (Migration Cockpit will eventually move here) end up as crafts that live in your repo, not in Forge.

package/lib/help-docs/CLAUDE.md

@@ -44,7 +44,7 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 | `11-workspace.md` | Workspace (Forge Smiths) — multi-agent orchestration, daemon, message bus, profiles |
 | `12-usage.md` | Token usage analytics — charts, heatmap, cost estimation, by model/project/source |
 | `13-ide-plugins.md` | VSCode extension + IntelliJ plugin — install, tabs, multi-connection, agent terminal launching |
-| `14-migration.md` | API Migration Cockpit — parity testing legacy ↔ new module, doc-driven discovery, batch run, AI fix |
+| `15-crafts.md` | Crafts — project-scoped mini-app tabs with SDK; AI-generated via "+ Craft" button |
 
 ## Matching questions to docs
 
@@ -68,4 +68,4 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 - Sidebar collapse/project tabs/favorites → `07-projects.md`
 - VSCode/IntelliJ/IDE plugin/extension/marketplace → `13-ide-plugins.md`
 - vsce/vsix/JetBrains marketplace publish → `13-ide-plugins.md`
-- Migration/API parity/legacy vs new/501 stub/parity test/diff endpoints → `14-migration.md`
+- Craft/custom tab/mini-app/extend project/AI-generated tab/builder → `15-crafts.md`