feat(docs): update CLAUDE and README for new features and tools

- Added linting and formatting commands to CLAUDE.md.
- Updated architecture section in CLAUDE.md to include new packages: pen-engine and pen-mcp.
- Enhanced README with new sections on style guides, embeddable SDK, and design system kit.
- Clarified prerequisites for building agent-native from source.
- Improved descriptions of AI features and multi-agent support in the README.

Author: Kayshen-X

CLAUDE.md

@@ -11,13 +11,16 @@ Detailed module docs are in `packages/CLAUDE.md`, `apps/web/CLAUDE.md`, `apps/de
 - **Run all tests:** `bun --bun run test` (Vitest)
 - **Run a single test:** `bun --bun vitest run path/to/test.ts`
 - **Type check:** `npx tsc --noEmit`
+- **Lint:** `bun run lint` (oxlint)
+- **Format:** `bun run format` (oxfmt)
 - **Install dependencies:** `bun install`
 - **Bump version:** `bun run bump <version>` (syncs all package.json files)
 - **Electron dev:** `bun run electron:dev` (starts Vite + Electron together)
 - **Electron compile:** `bun run electron:compile` (esbuild electron/ to out/desktop/)
 - **Electron build:** `bun run electron:build` (full web build + compile + electron-builder package)
 - **CLI compile:** `bun run cli:compile` (esbuild CLI to apps/cli/dist/)
 - **CLI dev:** `bun run cli:dev` (run CLI from source via Bun)
+- **MCP dev:** `bun run mcp:dev` (run MCP server from source)
 - **Publish beta:** `bun run publish:beta [N]` (publish all npm packages with beta tag)
 
 ## Architecture
@@ -33,17 +36,20 @@ openpencil/
 ├── packages/
 │   ├── pen-types/     Type definitions for PenDocument model
 │   ├── pen-core/      Document tree ops, layout engine, variables, boolean ops, clone utilities
+│   ├── pen-engine/    Headless design engine — framework-free document, selection, history, viewport
+│   ├── pen-react/     React UI SDK — DesignProvider, DesignCanvas, hooks, panels, toolbar
 │   ├── pen-codegen/   Multi-platform code generators
 │   ├── pen-figma/     Figma .fig file parser and converter
 │   ├── pen-renderer/  Standalone CanvasKit/Skia renderer
+│   ├── pen-mcp/       MCP server — tools, routes, document manager for external CLI integration
 │   ├── pen-sdk/       Umbrella SDK (re-exports all packages)
 │   ├── pen-ai-skills/ AI prompt skill engine (phase-driven prompt loading + design memory)
-│   └── agent/         Domain-agnostic AI agent SDK (Vercel AI SDK, multi-provider, agent teams)
+│   └── agent-native/  Native AI agent runtime (Zig NAPI, multi-provider, agent teams)
 ├── scripts/           Build and publish scripts
 └── .githooks/         Pre-commit version sync from branch name
 ```
 
-**Key technologies:** React 19, CanvasKit/Skia WASM (canvas engine), Paper.js (boolean path operations), Zustand v5 (state management), TanStack Router (file-based routing), Tailwind CSS v4, shadcn/ui (UI primitives), Vite 7, Nitro (server), Electron 35 (desktop), Vercel AI SDK v6 (agent framework), i18next (15 locales), TypeScript (strict mode).
+**Key technologies:** React 19, CanvasKit/Skia WASM (canvas engine), Paper.js (boolean path operations), Zustand v5 (state management), TanStack Router (file-based routing), Tailwind CSS v4, shadcn/ui (UI primitives), Vite 7, Nitro (server), Electron 35 (desktop), Vercel AI SDK v6 (agent framework), i18next (15 locales), TypeScript (strict mode), oxlint/oxfmt (linting & formatting).
 
 ### Data Flow
 

README.md

@@ -48,7 +48,7 @@ Describe any UI in natural language. Watch it appear on the infinite canvas in r
 
 ### 🤖 Concurrent Agent Teams
 
-The orchestrator decomposes complex pages into spatial sub-tasks. Multiple AI agents work on different sections simultaneously — hero, features, footer — all streaming in parallel.
+The orchestrator decomposes complex pages into spatial sub-tasks. Multiple AI agents work on different sections simultaneously — hero, features, footer — all streaming in parallel with per-member canvas indicators.
 
 </td>
 </tr>
@@ -71,33 +71,60 @@ One-click install into Claude Code, Codex, Gemini, OpenCode, Kiro, or Copilot CL
 <tr>
 <td width="50%">
 
+### 🎨 Style Guides
+
+Built-in style guide library with tag-based fuzzy matching. Apply visual styles (glassmorphism, brutalist, retro, etc.) to AI-generated designs. MCP tools for external agent access.
+
+</td>
+<td width="50%">
+
 ### 📦 Design-as-Code
 
 `.op` files are JSON — human-readable, Git-friendly, diffable. Design variables generate CSS custom properties. Code export to React + Tailwind or HTML + CSS.
 
 </td>
+</tr>
+<tr>
 <td width="50%">
 
 ### 🖥️ Runs Everywhere
 
 Web app + native desktop on macOS, Windows, and Linux via Electron. Auto-updates from GitHub Releases. `.op` file association — double-click to open.
 
 </td>
-</tr>
-<tr>
 <td width="50%">
 
 ### ⌨️ CLI — `op`
 
 Control the design tool from your terminal. `op design`, `op insert`, `op export` — batch design DSL, node manipulation, code export. Pipe in from files or stdin. Works with desktop app or web server.
 
 </td>
+</tr>
+<tr>
 <td width="50%">
 
 ### 🎯 Multi-Platform Code Export
 
 Export to React + Tailwind, HTML + CSS, Vue, Svelte, Flutter, SwiftUI, Jetpack Compose, React Native — all from one `.op` file. Design variables become CSS custom properties.
 
+</td>
+<td width="50%">
+
+### 🧩 Embeddable SDK
+
+`pen-engine` (headless) + `pen-react` (React UI SDK) — embed the design engine in your own app. DesignProvider, DesignCanvas, hooks, panels, and toolbar components out of the box.
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### 🛡️ Design System Kit
+
+Manage reusable UIKits with style switching and component composition. Import/export kits from `.pen` files. Built-in registry with MCP tools for external access.
+
+</td>
+<td width="50%">
 </td>
 </tr>
 </table>
@@ -142,7 +169,7 @@ Or run as a desktop app:
 bun run electron:dev
 ```
 
-> **Prerequisites:** [Bun](https://bun.sh/) >= 1.0 and [Node.js](https://nodejs.org/) >= 18
+> **Prerequisites:** [Bun](https://bun.sh/) >= 1.0 and [Node.js](https://nodejs.org/) >= 18. Optional: [Zig](https://ziglang.org/) >= 0.14 for building `agent-native` from source (a prebuilt binary will be downloaded automatically if Zig is not installed).
 
 ### Docker
 
@@ -198,10 +225,13 @@ docker build --target full -t openpencil-full .
 
 **Prompt to UI**
 
-- **Text-to-design** — describe a page, get it generated on canvas in real-time with streaming animation
+- **Text-to-design** — describe a page, get it generated on canvas in real-time with SSE streaming animation
 - **Orchestrator** — decomposes complex pages into spatial sub-tasks for parallel generation
+- **Agent Teams** — concurrent team members with delegate tool, per-member canvas indicators, and fallback strategies
 - **Design modification** — select elements, then describe changes in natural language
 - **Vision input** — attach screenshots or mockups for reference-based design
+- **Style Guides** — apply visual styles (glassmorphism, brutalist, retro, etc.) via tag-based fuzzy matching
+- **Anti-slop** — cross-generation diversity tracking to avoid repetitive AI output
 
 **Multi-Agent Support**
 
@@ -220,11 +250,12 @@ docker build --target full -t openpencil-full .
 
 **MCP Server**
 
-- Built-in MCP server — one-click install into Claude Code / Codex / Gemini / OpenCode / Kiro / Copilot CLIs
+- Built-in MCP server (`pen-mcp` package) — one-click install into Claude Code / Codex / Gemini / OpenCode / Kiro / Copilot CLIs
 - Auto-detects Node.js — if not installed, falls back to HTTP transport and auto-starts the MCP HTTP server
 - Design automation from terminal: read, create, and modify `.op` files via any MCP-compatible agent
 - **Layered design workflow** — `design_skeleton` → `design_content` → `design_refine` for higher-fidelity multi-section designs
 - **Segmented prompt retrieval** — load only the design knowledge you need (schema, layout, roles, icons, planning, etc.)
+- **Style guide tools** — `get_style_guide_tags` and `get_style_guide` for applying visual styles via MCP
 - Multi-page support — create, rename, reorder, and duplicate pages via MCP tools
 
 **Code Generation**
@@ -288,12 +319,14 @@ Supports three input methods: inline string, `@filepath` (read from file), or `-
 | --------------- | -------------------------------------------------------------------------------- |
 | **Frontend**    | React 19 · TanStack Start · Tailwind CSS v4 · shadcn/ui · i18next                |
 | **Canvas**      | CanvasKit/Skia (WASM, GPU-accelerated)                                           |
+| **Engine**      | pen-engine (headless) · pen-react (React UI SDK)                                 |
 | **State**       | Zustand v5                                                                       |
 | **Server**      | Nitro                                                                            |
 | **Desktop**     | Electron 35                                                                      |
 | **CLI**         | `op` — terminal control, batch design DSL, code export                           |
-| **AI**          | Vercel AI SDK v6 · Anthropic SDK · Claude Agent SDK · OpenCode SDK · Copilot SDK |
+| **AI**          | agent-native (Zig NAPI) · Anthropic SDK · Claude Agent SDK · OpenCode SDK · Copilot SDK |
 | **Runtime**     | Bun · Vite 7                                                                     |
+| **Lint**        | oxlint · oxfmt                                                                   |
 | **File format** | `.op` — JSON-based, human-readable, Git-friendly                                 |
 
 ## Project Structure
@@ -308,7 +341,6 @@ openpencil/
 │   │   │   ├── services/ai/ AI chat, orchestrator, design generation, streaming
 │   │   │   ├── services/codegen/ Code generation service wrappers
 │   │   │   ├── stores/      Zustand — canvas, document, pages, history, AI
-│   │   │   ├── mcp/         MCP server tools for external CLI integration
 │   │   │   ├── hooks/       Keyboard shortcuts, file drop, Figma paste, MCP sync
 │   │   │   ├── i18n/        Internationalization — 15 locales
 │   │   │   └── uikit/       Reusable component kit system
@@ -327,12 +359,15 @@ openpencil/
 ├── packages/
 │   ├── pen-types/           Type definitions for PenDocument model
 │   ├── pen-core/            Document tree ops, layout engine, variables
+│   ├── pen-engine/          Headless design engine — document, selection, history, viewport
+│   ├── pen-react/           React UI SDK — provider, canvas, hooks, panels, toolbar
 │   ├── pen-codegen/         Code generators (React, HTML, Vue, Flutter, ...)
 │   ├── pen-figma/           Figma .fig file parser and converter
 │   ├── pen-renderer/        Standalone CanvasKit/Skia renderer
+│   ├── pen-mcp/             MCP server — tools, routes, document manager
 │   ├── pen-sdk/             Umbrella SDK (re-exports all packages)
 │   ├── pen-ai-skills/       AI prompt skill engine (phase-driven prompt loading)
-│   └── agent/               AI agent SDK (Vercel AI SDK, multi-provider, agent teams)
+│   └── agent-native/        Native AI agent runtime (Zig NAPI, multi-provider, teams)
 └── .githooks/               Pre-commit version sync from branch name
 ```
 
@@ -361,11 +396,14 @@ bun --bun run dev          # Dev server (port 3000)
 bun --bun run build        # Production build
 bun --bun run test         # Run tests (Vitest)
 npx tsc --noEmit           # Type check
+bun run lint               # Lint (oxlint)
+bun run format             # Format (oxfmt)
 bun run bump <version>     # Sync version across all package.json
 bun run electron:dev       # Electron dev
 bun run electron:build     # Electron package
 bun run cli:dev            # Run CLI from source
 bun run cli:compile        # Compile CLI to dist
+bun run mcp:dev            # Run MCP server from source
 ```
 
 ## Contributing
@@ -393,6 +431,10 @@ Contributions are welcome! See [CLAUDE.md](./CLAUDE.md) for architecture details
 - [x] CLI tool (`op`) for terminal control
 - [x] Built-in AI agent SDK with multi-provider support
 - [x] i18n — 15 languages
+- [x] Headless design engine (`pen-engine`) + React UI SDK (`pen-react`)
+- [x] Style Guides with tag-based matching and MCP tools
+- [x] Concurrent Agent Teams with delegate tool and canvas indicators
+- [x] Native agent runtime (`agent-native` — Zig NAPI)
 - [ ] Collaborative editing
 - [ ] Plugin system
 

apps/web/server/api/ai/agent.ts

@@ -13,6 +13,9 @@ import {
   runTeam,
   addTeamMember,
   resolveTeamToolResult,
+  teamRegisterDelegate,
+  runTeamMember,
+  destroyIterator,
 } from '@zseven-w/agent-native';
 import type { AuthLevel } from '../../../src/types/agent';
 import { agentSessions, cleanup, abortSession, type AgentSession } from '../../utils/agent-sessions';
@@ -167,10 +170,10 @@ export default defineEventHandler(async (event) => {
     }
     try {
       const resultJson = JSON.stringify(body.result);
-      if (session.engine) {
-        resolveToolResult(session.engine, body.toolCallId, resultJson);
-      } else if (session.team) {
+      if (session.team) {
         resolveTeamToolResult(session.team, body.toolCallId, resultJson);
+      } else if (session.engine) {
+        resolveToolResult(session.engine, body.toolCallId, resultJson);
       }
     } catch {
       return { ok: true, ignored: true };
@@ -232,16 +235,19 @@ export default defineEventHandler(async (event) => {
 
     for (const m of body.members) {
       const memberProvider = createProviderHandle(m.providerType, m.apiKey, m.model, m.baseURL);
+      // Members get an EMPTY tool registry — they output JSONL text directly,
+      // not via tool calls. If we registered external tools (generate_design etc.),
+      // the member would call them, but tool results can only be resolved on the
+      // leader engine, not the member — causing the member to block forever.
       const memberTools = createToolRegistry();
-      for (const def of body.toolDefs ?? []) {
-        const params = def.parameters ? { ...def.parameters } : { type: 'object' };
-        delete (params as any).$schema;
-        registerToolSchema(memberTools, def.name, JSON.stringify(params));
-      }
       addTeamMember(team, m.id, memberProvider, memberTools, m.systemPrompt ?? '', 20);
       memberHandles.push({ provider: memberProvider, tools: memberTools });
     }
 
+    // Register delegate tool in leader's registry so the LLM can call
+    // delegate({member_id, task}) to dispatch work to members
+    teamRegisterDelegate(team);
+
     session = { team, provider, tools, memberHandles, createdAt: Date.now(), lastActivity: Date.now() };
   } else {
     // Single engine mode
@@ -294,6 +300,74 @@ export default defineEventHandler(async (event) => {
         let raw: string | null;
         while ((raw = await nextEvent(iter)) !== null) {
           session.lastActivity = Date.now();
+
+          // Intercept delegate tool_use in team mode — run member engine
+          // instead of forwarding to client
+          if (session.team) {
+            try {
+              const evt = JSON.parse(raw);
+              if (evt.tool_use && evt.tool_use.name === 'delegate') {
+                const toolUseId = evt.tool_use.id;
+                let memberIdRaw: string | undefined;
+                let taskRaw: string | undefined;
+
+                // Parse delegate args from input (may be JSON string or object)
+                const inputData = evt.tool_use.input;
+                if (typeof inputData === 'string') {
+                  try {
+                    const parsed = JSON.parse(inputData);
+                    memberIdRaw = parsed.member_id;
+                    taskRaw = parsed.task;
+                  } catch { /* fallback below */ }
+                } else if (inputData && typeof inputData === 'object') {
+                  memberIdRaw = inputData.member_id;
+                  taskRaw = inputData.task;
+                }
+
+                if (memberIdRaw && taskRaw) {
+                  // Emit member_start to client
+                  controller.enqueue(encoder.encode(
+                    `event: member_start\ndata: ${JSON.stringify({ type: 'member_start', memberId: memberIdRaw, task: taskRaw })}\n\n`,
+                  ));
+
+                  // Run member engine
+                  let memberResult = '';
+                  const memberIter = await runTeamMember(session.team, memberIdRaw, taskRaw);
+                  try {
+                    let memberRaw: string | null;
+                    while ((memberRaw = await nextEvent(memberIter)) !== null) {
+                      session.lastActivity = Date.now();
+                      // Forward member events to client (text, thinking, tool_call, etc.)
+                      controller.enqueue(encoder.encode(zigEventToSSE(memberRaw)));
+                      // Collect text for delegate tool result
+                      try {
+                        const mEvt = JSON.parse(memberRaw);
+                        if (mEvt.stream_event?.text && mEvt.stream_event.type === 'text_delta') {
+                          memberResult += mEvt.stream_event.text;
+                        }
+                      } catch { /* ignore parse errors */ }
+                    }
+                  } finally {
+                    destroyIterator(memberIter);
+                  }
+
+                  // Emit member_end to client
+                  controller.enqueue(encoder.encode(
+                    `event: member_end\ndata: ${JSON.stringify({ type: 'member_end', memberId: memberIdRaw, result: '' })}\n\n`,
+                  ));
+
+                  // Resolve delegate tool result back to leader engine
+                  resolveTeamToolResult(
+                    session.team,
+                    toolUseId,
+                    JSON.stringify({ result: memberResult || 'Member completed task.' }),
+                  );
+                  continue; // skip normal forwarding for this event
+                }
+              }
+            } catch { /* not JSON or not delegate — fall through to normal forwarding */ }
+          }
+
           controller.enqueue(encoder.encode(zigEventToSSE(raw)));
         }
       } catch (err: any) {

apps/web/server/api/ai/chat.ts

@@ -1022,7 +1022,11 @@ function streamViaBuiltin(body: ChatBody) {
         } = await import('@zseven-w/agent-native');
 
         const apiKey = body.builtinApiKey;
-        const model = body.model?.trim();
+        const rawModel = body.model?.trim() ?? '';
+        // Model string may be "builtin:<providerId>:<actualModel>" — extract the actual model name
+        const model = rawModel.startsWith('builtin:')
+          ? rawModel.split(':').slice(2).join(':')
+          : rawModel;
         if (!apiKey || !model) throw new Error('Builtin provider requires apiKey and model');
 
         const builtinProvider =