@plumbus/ui 0.1.0

package/instructions/client-generator.md

@@ -0,0 +1,149 @@
+# Client Generator
+
+Generates typed fetch-based API clients and React hooks from capability contracts and flow definitions.
+
+## Configuration
+
+```ts
+interface ClientGeneratorConfig {
+  /** Base URL for API requests (default: "") */
+  baseUrl?: string;
+  /** Include JSDoc comments in generated code */
+  includeJsDoc?: boolean;
+}
+```
+
+## Individual Generators
+
+### `generateCapabilityTypes(cap)`
+
+Produces TypeScript type aliases for a capability's input and output:
+
+```ts
+generateCapabilityTypes({ name: "getUser", kind: "query", domain: "users", ... })
+// → export type GetUserInput = Record<string, unknown>;
+//   export type GetUserOutput = Record<string, unknown>;
+```
+
+### `generateTypedClient(cap, config?)`
+
+Produces an async fetch function for a capability. Route path follows `GET /api/{domain}/{kebab-name}` for queries, `POST` for actions/jobs:
+
+```ts
+generateTypedClient({ name: "getUser", kind: "query", domain: "users", ... })
+// → export async function getUser(input: GetUserInput, options?): Promise<GetUserOutput> { ... }
+```
+
+- **GET** capabilities serialize input as query parameters via `URLSearchParams`.
+- **POST** capabilities send input as `JSON.stringify(input)` in the request body.
+- All functions accept `options?: { headers?: Record<string, string>; signal?: AbortSignal }`.
+- Non-OK responses throw an error with `status`, `code`, and `metadata` properties.
+
+### `generateQueryHook(cap, config?)`
+
+Produces a React hook that auto-fetches on mount/input change:
+
+```ts
+generateQueryHook({ name: "getUser", kind: "query", domain: "users", ... })
+// → export function useGetUser(input: GetUserInput) {
+//     const [data, setData] = useState<GetUserOutput | null>(null);
+//     ...
+//     return { data, loading, error };
+//   }
+```
+
+- Uses `useState` + `useEffect` with cancellation.
+- Re-fetches when `JSON.stringify(input)` changes.
+
+### `generateMutationHook(cap, config?)`
+
+Produces a React hook for manual invocation (actions, jobs):
+
+```ts
+generateMutationHook({ name: "createUser", kind: "action", domain: "users", ... })
+// → export function useCreateUser() {
+//     ...
+//     return { mutate, data, loading, error, reset };
+//   }
+```
+
+- `mutate(input)` triggers the request and returns the result.
+- `reset()` clears data and error state.
+
+### `generateReactHook(cap, config?)`
+
+Dispatches to `generateQueryHook` or `generateMutationHook` based on `cap.kind`:
+- `kind === "query"` → query hook
+- Anything else → mutation hook
+
+### `generateFlowTrigger(flow, config?)`
+
+Produces a function to start a flow execution:
+
+```ts
+interface FlowTriggerInput {
+  name: string;
+  domain?: string;
+  description?: string;
+}
+
+generateFlowTrigger({ name: "orderFulfillment", domain: "orders" })
+// → export async function startOrderFulfillment(input, options?)
+//     : Promise<{ executionId: string; status: string }> { ... }
+```
+
+- POSTs to `/api/{domain}/{kebab-name}/start`.
+
+### `generateErrorTypes()`
+
+Produces `PlumbusApiError` interface and `isPlumbusApiError()` type guard — always included in module output.
+
+## Module Generators
+
+### `generateClientModule(capabilities, flows, config?)`
+
+Combines all generators into a single client file:
+
+```ts
+const code = generateClientModule(
+  [getUser, createUser, deleteUser],
+  [{ name: "orderFulfillment", domain: "orders" }],
+  { baseUrl: "/api", includeJsDoc: true },
+);
+// Output: .plumbus/generated/ui/client.ts (written by CLI)
+```
+
+Output order: error types → capability types → flow types → client functions → flow triggers.
+
+### `generateHooksModule(capabilities, config?)`
+
+Produces a React hooks file that imports from the client module:
+
+```ts
+const code = generateHooksModule([getUser, createUser]);
+// Output: .plumbus/generated/ui/hooks.ts (written by CLI)
+```
+
+- Auto-imports `useState`, `useEffect` from React.
+- Auto-imports types and functions from `./client`.
+
+## URL Routing Convention
+
+| Capability Kind | HTTP Method | URL Pattern |
+|----------------|-------------|-------------|
+| query | GET | `/api/{domain}/{kebab-name}` |
+| action | POST | `/api/{domain}/{kebab-name}` |
+| job | POST | `/api/{domain}/{kebab-name}` |
+| eventHandler | POST | `/api/{domain}/{kebab-name}` |
+
+Flow triggers always POST to `/api/{domain}/{kebab-name}/start`.
+
+## Internal Helpers
+
+| Helper | Purpose |
+|--------|---------|
+| `toCamelCase(str)` | Capability function names — `getUser` |
+| `toPascalCase(str)` | Type names — `GetUser` |
+| `toKebabCase(str)` | URL path segments — `get-user` |
+| `httpMethod(kind)` | `"query" → "GET"`, everything else → `"POST"` |
+| `capabilityPath(domain, name)` | `/api/{domain}/{kebab-name}` |

package/instructions/form-generator.md

@@ -0,0 +1,157 @@
+# Form Generator
+
+Extracts form field metadata from Zod schemas attached to capability contracts. Produces structured hints that UI components can consume for rendering form fields with labels, input types, validation, and options.
+
+## Types
+
+```ts
+type FormFieldType = "text" | "number" | "boolean" | "select" | "textarea" | "date" | "hidden";
+
+interface FormFieldHint {
+  name: string;            // Field key from the schema
+  label: string;           // Human-readable label (auto-derived)
+  fieldType: FormFieldType; // Suggested HTML input type
+  required: boolean;        // true unless ZodOptional or ZodDefault
+  defaultValue?: unknown;   // From .default() if set
+  zodType: string;          // Underlying Zod type name (e.g. "ZodString")
+  options?: string[];       // For ZodEnum — the allowed values
+  validation: FormValidation;
+  description?: string;     // From .describe() if set
+}
+
+interface FormValidation {
+  min?: number;         // ZodNumber .min()
+  max?: number;         // ZodNumber .max()
+  minLength?: number;   // ZodString .min()
+  maxLength?: number;   // ZodString .max()
+  pattern?: string;     // ZodString .regex() source, or "email"/"url"
+  nullable?: boolean;   // ZodNullable wrapper
+}
+
+interface FormHints {
+  capabilityName: string;
+  kind: string;
+  fields: FormFieldHint[];
+}
+```
+
+## How It Works
+
+The form generator introspects Zod schemas at runtime via their `_def` property. It does **not** use `z.infer` or code generation — it reads the schema tree directly.
+
+### Schema Unwrapping
+
+Wrapper types are unwrapped to find the underlying type:
+- `ZodOptional` → unwrap `innerType`, mark `required: false`
+- `ZodNullable` → unwrap `innerType`, set `validation.nullable: true`
+- `ZodDefault` → unwrap `innerType`, mark `required: false`, extract default value
+
+### Zod Type → Form Field Type Mapping
+
+| Zod Type | Form Field Type |
+|----------|----------------|
+| ZodString | `"text"` |
+| ZodNumber, ZodBigInt | `"number"` |
+| ZodBoolean | `"boolean"` |
+| ZodDate | `"date"` |
+| ZodEnum, ZodNativeEnum | `"select"` |
+| ZodObject, ZodArray, ZodRecord | `"textarea"` |
+| Other | `"text"` |
+
+### Validation Extraction
+
+Checks are read from `_def.checks` array:
+
+| Check Kind | Extracted As |
+|------------|-------------|
+| `min` (ZodString) | `minLength` |
+| `max` (ZodString) | `maxLength` |
+| `min` (ZodNumber) | `min` |
+| `max` (ZodNumber) | `max` |
+| `regex` | `pattern` (regex source) |
+| `email` | `pattern: "email"` |
+| `url` | `pattern: "url"` |
+
+### Label Generation
+
+Field names are converted to title case: `firstName` → `"First Name"`, `user_email` → `"User Email"`.
+
+## Functions
+
+### `extractFieldHint(name, schema)`
+
+Extract metadata for a single Zod field:
+
+```ts
+import { z } from "zod";
+import { extractFieldHint } from "@plumbus/ui";
+
+const hint = extractFieldHint("email", z.string().email().describe("User's email"));
+// → { name: "email", label: "Email", fieldType: "text", required: true,
+//     zodType: "ZodString", validation: { pattern: "email" }, description: "User's email" }
+```
+
+### `extractFormHints(cap)`
+
+Extract hints for all fields in a capability's `input` schema (must be `ZodObject`):
+
+```ts
+const hints = extractFormHints(createUserCapability);
+// → { capabilityName: "createUser", kind: "action", fields: [...] }
+```
+
+Iterates over the `ZodObject` shape via `_def.shape()`.
+
+### `generateFormHintsCode(cap)`
+
+Produce a TypeScript constant with the extracted hints:
+
+```ts
+generateFormHintsCode(cap)
+// → export const CreateUserFormHints = { ... } as const;
+```
+
+### `generateFormHintsModule(capabilities)`
+
+Produce a module exporting form hints for all capabilities:
+
+```ts
+const code = generateFormHintsModule([createUser, updateUser]);
+// Write to: generated/form-hints.ts
+```
+
+## Usage Pattern
+
+```ts
+// 1. Extract hints at build time
+const hints = extractFormHints(createUserCapability);
+
+// 2. Use hints in a React component
+function DynamicForm({ hints }: { hints: FormHints }) {
+  return (
+    <form>
+      {hints.fields.map((field) => (
+        <div key={field.name}>
+          <label>{field.label}</label>
+          {field.fieldType === "select" ? (
+            <select name={field.name} required={field.required}>
+              {field.options?.map((opt) => <option key={opt}>{opt}</option>)}
+            </select>
+          ) : (
+            <input
+              name={field.name}
+              type={field.fieldType}
+              required={field.required}
+              minLength={field.validation.minLength}
+              maxLength={field.validation.maxLength}
+              min={field.validation.min}
+              max={field.validation.max}
+              defaultValue={field.defaultValue as string}
+            />
+          )}
+        </div>
+      ))}
+    </form>
+  );
+}
+```

package/instructions/framework.md

@@ -0,0 +1,108 @@
+# @plumbus/ui — UI Code Generation Framework
+
+`@plumbus/ui` is the frontend code generation layer for the Plumbus framework. It reads capability contracts, flow definitions, and auth configuration from `@plumbus/core` and produces ready-to-use TypeScript/React source files — typed API clients, React hooks, auth modules, form metadata, and full Next.js project scaffolds.
+
+## Purpose
+
+All generated output is **source code as strings** — the package does not ship React components or a runtime. Instead, AI agents and CLI tooling call generator functions to produce `.ts`/`.tsx` files that applications import directly.
+
+## Package Layout
+
+```
+packages/ui/
+  src/
+    index.ts                          # Barrel re-exports
+    generators/
+      index.ts                        # Generator barrel
+      client-generator.ts             # Typed fetch clients + React hooks
+      auth-generator.ts               # Auth types, token utils, hooks, route guard
+      form-generator.ts               # Zod schema → form field metadata
+      nextjs-template.ts              # Full Next.js project scaffold
+      __tests__/
+        client-generator.test.ts
+        auth-generator.test.ts
+        form-generator.test.ts
+        nextjs-template.test.ts
+  instructions/                       # AI agent instructions (this directory)
+  package.json
+  tsconfig.json
+  vitest.config.browser.ts
+```
+
+## Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Generator** | A function that takes a contract/config and returns a string of TypeScript/TSX source code |
+| **CapabilityContract** | Imported from `@plumbus/core` — defines name, domain, kind, input/output schemas, access |
+| **Module generator** | Combines multiple generators into a single file with proper imports |
+| **GeneratedFile** | `{ path: string; content: string }` — represents a file to write to disk |
+
+## Generator Categories
+
+| Generator | Input | Output |
+|-----------|-------|--------|
+| **Client** | `CapabilityContract[]`, `FlowTriggerInput[]` | Typed fetch functions, React query/mutation hooks |
+| **Auth** | `AuthHelperConfig` | Login/logout, token utils, useAuth hook, RouteGuard, tenant context |
+| **Form** | `CapabilityContract` (with Zod input schema) | Field metadata (type, label, validation, options) |
+| **Next.js** | `NextjsTemplateConfig`, capabilities | Full project: package.json, layout, pages, middleware, API routes |
+
+## Relationship to @plumbus/core
+
+`@plumbus/ui` depends on `@plumbus/core` for:
+- `CapabilityContract` type — the shape of capability definitions
+- Zod schemas — introspected at runtime for form hint extraction
+- No runtime coupling — generators produce standalone code
+
+## Key Imports
+
+```ts
+import {
+  // Client generators
+  generateClientModule,
+  generateHooksModule,
+  generateTypedClient,
+  generateReactHook,
+  generateCapabilityTypes,
+  generateFlowTrigger,
+  generateErrorTypes,
+
+  // Auth generators
+  generateAuthModule,
+  generateAuthTypes,
+  generateTokenUtils,
+  generateAuthFunctions,
+  generateUseAuthHook,
+  generateUseCurrentUserHook,
+  generateRouteGuard,
+  generateTenantContext,
+
+  // Form generators
+  extractFormHints,
+  extractFieldHint,
+  generateFormHintsCode,
+  generateFormHintsModule,
+
+  // Next.js generators
+  generateNextjsTemplate,
+  generateLayout,
+  generateHomePage,
+  generateCapabilityPage,
+  generateMiddleware,
+  generateApiRouteHelper,
+  generateAuthProvider,
+  generateErrorBoundary,
+  generateLoadingComponent,
+  generatePackageJson,
+  generateTsConfig,
+  generateEnvLocal,
+  generatePlaceholderFiles,
+} from "@plumbus/ui";
+```
+
+## How Agents Should Use This Package
+
+1. **Run `plumbus ui generate`** — auto-detects the frontend directory (e.g., `frontend/`) and writes typed client, hooks, auth, and form-hints modules to `{frontend}/generated/`. Also writes to `.plumbus/generated/ui/` as a contract artifact cache.
+2. **Run `plumbus ui nextjs <dir>`** — scaffolds a Next.js project that includes the generated modules in `{dir}/generated/`. The frontend imports them via `@/generated/hooks`, `@/generated/client`, etc.
+3. **Never copy generated files manually.** Re-running `plumbus ui generate` updates `{frontend}/generated/` in place. The CLI auto-detects the frontend by looking for `tsconfig.json` in `frontend/`, `web/`, `client/`, or `app/`.
+4. To customize the output location: `plumbus ui generate --out-dir path/to/generated`.

package/instructions/nextjs-template.md

@@ -0,0 +1,160 @@
+# Next.js Template Generator
+
+Scaffolds a complete Next.js 14 project wired to a Plumbus backend — layout, pages, auth, middleware, API proxy, error boundary, and environment config.
+
+## Configuration
+
+```ts
+interface NextjsTemplateConfig {
+  appName: string;          // Application display name
+  auth?: boolean;           // Include auth wiring (default: true)
+  apiBaseUrl?: string;      // Backend URL (default: "http://localhost:3000")
+}
+
+interface GeneratedFile {
+  path: string;     // Relative file path within the project
+  content: string;  // File contents
+}
+```
+
+## Full Scaffold
+
+### `generateNextjsTemplate(config, capabilities?)`
+
+Returns `GeneratedFile[]` — a complete Next.js project. Write each file to disk:
+
+```ts
+const files = generateNextjsTemplate(
+  { appName: "My App", auth: true, apiBaseUrl: "http://localhost:3000" },
+  [getUser, createUser],
+);
+
+for (const file of files) {
+  writeFileSync(join(outputDir, file.path), file.content);
+}
+```
+
+### Generated Project Structure
+
+```
+package.json                          # Next.js 14, React 18, TypeScript 5, Tailwind CSS 4
+tsconfig.json                         # Strict, bundler module resolution
+postcss.config.mjs                    # PostCSS config with @tailwindcss/postcss
+.env.local                            # API base URL, auth flag, secrets
+middleware.ts                         # Auth token check, protected paths
+app/
+  globals.css                         # Tailwind import + base resets
+  layout.tsx                          # Root layout (with AuthProvider if auth)
+  page.tsx                            # Home page
+  loading.tsx                         # Global loading skeleton
+  error.tsx                           # Global error boundary
+  {capability-slug}/page.tsx          # Per-capability pages (query or action)
+  api/plumbus/[...path]/route.ts      # API proxy to Plumbus backend
+components/
+  AuthProvider.tsx                    # Context-based auth provider (if auth)
+generated/
+  .gitkeep                            # Placeholder for generated client files
+hooks/
+  .gitkeep                            # Placeholder for custom hooks
+```
+
+## Individual File Generators
+
+### `generatePackageJson(config)`
+
+```json
+{
+  "name": "{kebab-case-app-name}",
+  "dependencies": { "next": "^14", "react": "^18", "react-dom": "^18", "tailwindcss": "^4", "@tailwindcss/postcss": "^4" },
+  "devDependencies": { "typescript": "^5", "@types/react": "^18", "@types/react-dom": "^18" }
+}
+```
+
+### `generateTsConfig()`
+
+Strict TypeScript config for Next.js: `target: "ES2017"`, `module: "esnext"`, `moduleResolution: "bundler"`, `jsx: "preserve"`, path alias `@/*`.
+
+### `generateGlobalsCss()`
+
+Minimal `app/globals.css` with Tailwind CSS import and base resets (box-sizing, margin, antialiased text). Apps customize by extending this file with their own theme tokens.
+
+### `generatePostcssConfig()`
+
+PostCSS config at `postcss.config.mjs` with `@tailwindcss/postcss` plugin. Required for Tailwind CSS 4 processing.
+
+### `generateLayout(config)`
+
+Root layout with `<html>` + `<body>`. Imports `./globals.css` for Tailwind styles. If `auth !== false`, wraps children in `<AuthProvider>`.
+
+### `generateHomePage(config)`
+
+Simple welcome page with app name and description text.
+
+### `generateCapabilityPage(cap)`
+
+Route: `app/{kebab-name}/page.tsx`
+
+Generated page depends on capability kind:
+
+| Kind | UI Pattern |
+|------|-----------|
+| `query` | Auto-fetches with `use{Name}({})`, shows loading/error/data states |
+| `action`/`job` | Form with `handleSubmit`, uses `use{Name}()` mutation hook, shows submit/loading/error/result |
+
+All pages use `"use client"` directive and import hooks from `@/generated/hooks`.
+
+### `generateAuthProvider()`
+
+Context-based provider at `components/AuthProvider.tsx`:
+- Creates `AuthContext` with `AuthState`.
+- On mount: checks stored token, refreshes session.
+- Exports `useAuthContext()` hook.
+- Imports from `@/generated/auth`.
+
+### `generateMiddleware(config)`
+
+Next.js middleware at `middleware.ts`:
+- When auth enabled: checks `auth_token` cookie for protected paths (`/dashboard`, `/settings`, `/api/protected`).
+- Redirects to `/login` if no token.
+- Matcher excludes `_next/static`, `_next/image`, and `favicon.ico`.
+
+### `generateApiRouteHelper(config)`
+
+Catch-all API proxy at `app/api/plumbus/[...path]/route.ts`:
+- Forwards requests to `{apiBaseUrl}/{path}`.
+- Preserves auth headers, query parameters, and request method.
+- Supports GET, POST, PUT, PATCH, DELETE.
+
+### `generateEnvLocal(config)`
+
+Environment variables template:
+```env
+NEXT_PUBLIC_API_BASE_URL=http://localhost:3000
+NEXT_PUBLIC_AUTH_ENABLED=true
+AUTH_SECRET=change-me-in-production
+```
+
+### `generateErrorBoundary()`
+
+Client error component at `app/error.tsx` — logs error, shows message, provides retry button.
+
+### `generateLoadingComponent()`
+
+Loading skeleton at `app/loading.tsx` with `role="status"` and `aria-label="Loading"`.
+
+### `generatePlaceholderFiles()`
+
+Returns `generated/.gitkeep` and `hooks/.gitkeep`.
+
+## Auth Integration
+
+When `auth: true` (default):
+1. `AuthProvider` wraps the app layout.
+2. Middleware protects configured paths.
+3. Generated pages can use `useAuthContext()`.
+4. API proxy forwards `Authorization` headers.
+
+When `auth: false`:
+- No `AuthProvider` import in layout.
+- Middleware runs but skips auth checks.
+- Pages still work for public capabilities.

package/instructions/patterns.md

@@ -0,0 +1,109 @@
+# Patterns & Conventions
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Generator function | `generate{Thing}` | `generateClientModule`, `generateAuthModule` |
+| Extractor function | `extract{Thing}` | `extractFormHints`, `extractFieldHint` |
+| Generated React hook | `use{PascalName}` | `useGetUser`, `useCreateOrder` |
+| Generated client function | `{camelName}` | `getUser`, `createOrder` |
+| Generated type | `{PascalName}Input` / `{PascalName}Output` | `GetUserInput`, `GetUserOutput` |
+| Generated flow trigger | `start{PascalName}` | `startOrderFulfillment` |
+| Generated file | `kebab-case.ts` / `.tsx` | `client.ts`, `auth.ts`, `form-hints.ts` |
+| Test file | `{generator-name}.test.ts` | `client-generator.test.ts` |
+
+## File Structure
+
+```
+packages/ui/
+  src/
+    index.ts                    # Barrel re-exports (types + functions)
+    generators/
+      index.ts                  # Generator barrel
+      client-generator.ts       # Typed clients + React hooks
+      auth-generator.ts         # Auth types, functions, hooks
+      form-generator.ts         # Zod introspection + form hints
+      nextjs-template.ts        # Full Next.js scaffolding
+      __tests__/
+        client-generator.test.ts
+        auth-generator.test.ts
+        form-generator.test.ts
+        nextjs-template.test.ts
+  instructions/                 # AI agent instructions
+  package.json
+  tsconfig.json
+  vitest.config.browser.ts
+```
+
+## Do's
+
+- **Do** use the `CapabilityContract` type from `@plumbus/core` as the input for all generators that work with capabilities.
+- **Do** return plain strings from generators — they produce source code, not runtime objects.
+- **Do** use `GeneratedFile[]` for multi-file generators (Next.js template) so callers can write files to disk.
+- **Do** add the `// Auto-generated by @plumbus/ui — do not edit` comment at the top of module generators.
+- **Do** handle SSR safety in generated auth code — guard `localStorage` with `typeof window === "undefined"`.
+- **Do** import React hooks (`useState`, `useEffect`) in generated hook modules.
+- **Do** use the same naming helpers (`toCamelCase`, `toPascalCase`, `toKebabCase`) consistently across generators.
+- **Do** keep generated code self-contained — each module generator produces a file that works with only its stated imports.
+- **Do** support optional `ClientGeneratorConfig` / `AuthHelperConfig` / `NextjsTemplateConfig` for customization.
+- **Do** unwrap Zod wrappers (`ZodOptional`, `ZodNullable`, `ZodDefault`) before checking the underlying type.
+
+## Don'ts
+
+- **Don't** generate code that depends on `@plumbus/ui` at runtime — generated code imports from React, a client module, or `@/generated/*` paths only.
+- **Don't** use `z.infer` in generators — introspect schemas via `_def` for form hints.
+- **Don't** mutate `CapabilityContract` objects — generators are pure functions.
+- **Don't** hardcode API paths — always derive from `domain` + `name` using `capabilityPath()`.
+- **Don't** embed secrets in generated code — use environment variables (`process.env`).
+- **Don't** add framework-specific runtime dependencies to generated Next.js projects (no `@plumbus/core` import in generated frontend code).
+- **Don't** edit files in `generated/` directories manually — they are regenerated.
+
+## Common Workflows
+
+### Generate a Full Frontend from Capabilities
+
+Use the CLI — never copy files manually:
+
+```bash
+# Scaffold a Next.js app (includes generated modules in frontend/generated/)
+plumbus ui nextjs frontend
+
+# Regenerate UI modules after changing capabilities
+# Auto-detects frontend/ and writes to frontend/generated/
+plumbus ui generate
+```
+
+The `plumbus ui generate` command auto-detects the frontend directory by looking for `tsconfig.json` in `frontend/`, `web/`, `client/`, or `app/`. Override with `--out-dir`.
+
+### Scaffold a New Next.js Application
+
+```ts
+import { generateNextjsTemplate } from "@plumbus/ui";
+
+const files = generateNextjsTemplate({ appName: "My App", auth: true }, capabilities);
+for (const file of files) {
+  mkdirSync(dirname(join(outDir, file.path)), { recursive: true });
+  writeFileSync(join(outDir, file.path), file.content);
+}
+```
+
+### Add a New Generator
+
+1. Create `src/generators/{name}-generator.ts`.
+2. Export individual generator functions + a module-level `generate{Name}Module()`.
+3. Re-export from `src/generators/index.ts` and `src/index.ts`.
+4. Add tests at `src/generators/__tests__/{name}-generator.test.ts`.
+5. Add an instruction file at `instructions/{name}-generator.md`.
+
+## Generated Code Output Conventions
+
+| Convention | Rule |
+|-----------|------|
+| Module header | `// Auto-generated by @plumbus/ui — do not edit` |
+| React imports | `import { useState, useEffect } from "react"` |
+| Client imports | `import { functionName } from "./client"` |
+| Auth imports | `import { getStoredToken, ... } from "@/generated/auth"` |
+| Type imports | `import type { ... } from "./client"` |
+| Error handling | Throw enriched `Error` with `status`, `code`, `metadata` |
+| Cancellation | Query hooks track `cancelled` flag for cleanup |