@mantajs/cli 0.2.0-beta.0

package/dist/spa/generate-spa.d.ts

@@ -0,0 +1,15 @@
+import type { DiscoveredSpa } from '../resource-loader';
+export interface SpaGenerateOptions {
+    cwd: string;
+    spa: DiscoveredSpa;
+    dashboard?: string;
+    preset?: string;
+    /** Backend server port (from PORT env or default 3000) */
+    port?: number;
+}
+/**
+ * Generate all build artifacts for a SPA.
+ * Returns the path to the generated vite.config.ts.
+ */
+export declare function generateSpaArtifacts(options: SpaGenerateOptions): string;
+//# sourceMappingURL=generate-spa.d.ts.map

package/dist/spa/generate-spa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-spa.d.ts","sourceRoot":"","sources":["../../src/spa/generate-spa.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAEvD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,aAAa,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAmBxE"}

package/dist/spa/generate-spa.js

@@ -0,0 +1,357 @@
+// SPA entry point generator — generates .manta/spa/{name}/ with:
+// - index.html (auto-generated)
+// - entry.tsx (imports dashboard shell + routes)
+// - routes.ts (filesystem-derived routing)
+// - vite.config.ts (Vite build config)
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+/**
+ * Generate all build artifacts for a SPA.
+ * Returns the path to the generated vite.config.ts.
+ */
+export function generateSpaArtifacts(options) {
+    const { cwd, spa, dashboard, preset, port = 3000 } = options;
+    const outDir = resolve(cwd, '.manta', 'spa', spa.name);
+    mkdirSync(outDir, { recursive: true });
+    // Generate routes.ts
+    writeFileSync(join(outDir, 'routes.ts'), generateRoutes(spa, cwd));
+    // Generate entry.tsx
+    writeFileSync(join(outDir, 'entry.tsx'), generateEntry(spa, cwd, outDir, dashboard, preset));
+    // Generate index.html
+    writeFileSync(join(outDir, 'index.html'), generateHtml(spa));
+    // Generate vite.config.ts
+    const viteConfigPath = join(outDir, 'vite.config.ts');
+    writeFileSync(viteConfigPath, generateViteConfig(spa, cwd, outDir, dashboard, preset, port));
+    return viteConfigPath;
+}
+function generateRoutes(spa, cwd) {
+    const lines = [
+        '// Auto-generated — do not edit',
+        `// Pages discovered from src/spa/${spa.name}/`,
+        '',
+        "import { lazy } from 'react'",
+        '',
+    ];
+    // Config import (defineSpa)
+    if (spa.configPath) {
+        const relPath = relative(resolve(cwd, '.manta', 'spa', spa.name), spa.configPath).replace(/\.ts$/, '');
+        lines.push(`import spaConfig from '${relPath}'`);
+        lines.push('');
+    }
+    const imports = [];
+    const routeDefs = [];
+    const specImports = [];
+    const specDefs = [];
+    for (const page of spa.pages) {
+        const varName = routeToVarName(page.route);
+        const relPath = relative(resolve(cwd, '.manta', 'spa', spa.name), page.path).replace(/\.tsx?$/, '');
+        const isSpec = page.path.endsWith('.ts') && !page.path.endsWith('.tsx');
+        if (isSpec) {
+            // Spec page (definePage/defineForm) — static import
+            specImports.push(`import ${varName}Spec from '${relPath}'`);
+            specDefs.push(`  { route: '${page.route}', spec: ${varName}Spec },`);
+        }
+        else {
+            // React page — lazy import
+            imports.push(`const ${varName} = lazy(() => import('${relPath}'))`);
+            routeDefs.push(`  { path: '${page.route}', component: ${varName} },`);
+        }
+    }
+    // Block imports
+    const blockImports = [];
+    const blockDefs = [];
+    for (const block of spa.blocks) {
+        const relPath = relative(resolve(cwd, '.manta', 'spa', spa.name), block.path).replace(/\.tsx?$/, '');
+        blockImports.push(`import ${block.type} from '${relPath}'`);
+        blockDefs.push(`  '${block.type}': ${block.type},`);
+    }
+    lines.push(...specImports);
+    lines.push(...imports);
+    if (blockImports.length > 0) {
+        lines.push('');
+        lines.push(...blockImports);
+    }
+    lines.push('');
+    // Export React routes (legacy)
+    lines.push('export const routes = [');
+    lines.push(...routeDefs);
+    lines.push(']');
+    lines.push('');
+    // Export spec pages (definePage/defineForm)
+    lines.push('export const pageSpecs = [');
+    lines.push(...specDefs);
+    lines.push(']');
+    lines.push('');
+    // Export custom blocks
+    if (blockDefs.length > 0) {
+        lines.push('export const customBlocks = {');
+        lines.push(...blockDefs);
+        lines.push('}');
+    }
+    else {
+        lines.push('export const customBlocks = {}');
+    }
+    lines.push('');
+    // Export SPA config
+    if (spa.configPath) {
+        lines.push('export { spaConfig }');
+    }
+    else {
+        lines.push('export const spaConfig = null');
+    }
+    lines.push('');
+    // Export command schemas (for form validation)
+    const schemasPath = relative(resolve(cwd, '.manta', 'spa', spa.name), resolve(cwd, '.manta', 'command-schemas')).replace(/\\/g, '/');
+    lines.push(`export { commandSchemas } from '${schemasPath}'`);
+    lines.push('');
+    return lines.join('\n');
+}
+function generateEntry(spa, cwd, _outDir, dashboard, preset) {
+    // When @mantajs/dashboard is the dashboard shell, generate an entry that uses MantaDashboard
+    // which provides the full admin shell (sidebar, auth, registry, etc.)
+    if (dashboard === '@mantajs/dashboard') {
+        // Resolve the CSS path relative to the generated entry file
+        let cssImport = '// @mantajs/dashboard CSS not found';
+        try {
+            const pkgDir = dirname(require.resolve('@mantajs/dashboard/package.json', { paths: [cwd] }));
+            const distCss = join(pkgDir, 'dist', 'index.css');
+            const cssPath = (existsSync(distCss) ? distCss : join(pkgDir, 'src', 'index.css')).replace(/\\/g, '/');
+            cssImport = `import '${cssPath}'`;
+        }
+        catch {
+            /* not found */
+        }
+        const lines = [
+            '// Auto-generated — do not edit',
+            "import { Suspense } from 'react'",
+            "import { createRoot } from 'react-dom/client'",
+            "import { MantaDashboard } from '@mantajs/dashboard'",
+            "import { routes, pageSpecs, customBlocks, spaConfig, commandSchemas } from './routes'",
+            cssImport,
+            '',
+            'const apiUrl = window.location.origin',
+            '',
+            '// Convert filesystem routes to React Router route objects (wrapped in Suspense for lazy loading)',
+            'const customRoutes = routes.map((r) => ({',
+            "  path: r.path === '/' ? undefined : r.path.replace(/^\\//, ''),",
+            '  element: <Suspense fallback={null}><r.component /></Suspense>,',
+            '}))',
+            '',
+            "createRoot(document.getElementById('root')!).render(",
+            `  <MantaDashboard apiUrl={apiUrl} basename="/${spa.name}" customRoutes={customRoutes} pageSpecs={pageSpecs} customBlocks={customBlocks} spaConfig={spaConfig} commandSchemas={commandSchemas} />,`,
+            ')',
+            '',
+        ];
+        return lines.join('\n');
+    }
+    // Fallback: bare BrowserRouter for custom SPAs without a dashboard shell
+    const lines = [
+        '// Auto-generated — do not edit',
+        "import React, { Suspense } from 'react'",
+        "import { createRoot } from 'react-dom/client'",
+        "import { BrowserRouter, Routes, Route } from 'react-router-dom'",
+        "import { routes } from './routes'",
+    ];
+    if (preset && preset !== '@mantajs/ui') {
+        lines.push(`import '${preset}/styles.css'`);
+    }
+    lines.push('');
+    lines.push('function App() {');
+    lines.push(`  return (
+    <BrowserRouter basename="/${spa.name}">
+      <Suspense fallback={<div>Loading...</div>}>
+        <Routes>
+          {routes.map((r) => (
+            <Route key={r.path} path={r.path} element={<r.component />} />
+          ))}
+        </Routes>
+      </Suspense>
+    </BrowserRouter>
+  )`);
+    lines.push('}');
+    lines.push('');
+    lines.push("createRoot(document.getElementById('root')!).render(<App />)");
+    lines.push('');
+    return lines.join('\n');
+}
+function generateHtml(spa) {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${spa.name.charAt(0).toUpperCase() + spa.name.slice(1)}</title>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="./entry.tsx"></script>
+</body>
+</html>
+`;
+}
+function generateViteConfig(spa, cwd, outDir, dashboard, _preset, port = 3000) {
+    const lines = [
+        `import { defineConfig } from 'vite'`,
+        `import react from '@vitejs/plugin-react'`,
+        `import tailwindcss from '@tailwindcss/vite'`,
+        '',
+        `export default defineConfig({`,
+        `  root: '${outDir.replace(/\\/g, '/')}',`,
+        `  base: '/${spa.name}/',`,
+        `  appType: 'spa',`,
+        `  plugins: [`,
+        `    react(),`,
+        `    tailwindcss(),`,
+        `    {`,
+        `      name: 'manta-trailing-slash',`,
+        `      configureServer(server) {`,
+        `        server.middlewares.use((req, _res, next) => {`,
+        `          if (req.url === '/${spa.name}') req.url = '/${spa.name}/'`,
+        `          next()`,
+        `        })`,
+        `      },`,
+        `    },`,
+        `  ],`,
+        `  server: {`,
+        `    hmr: true,`,
+        `    strictPort: true,`,
+        `    proxy: {`,
+        `      '/api': {`,
+        `        target: 'http://localhost:${port}',`,
+        `        changeOrigin: true,`,
+        `      },`,
+        `    },`,
+        `  },`,
+        `  build: {`,
+        `    outDir: '${resolve(cwd, 'public', spa.name).replace(/\\/g, '/')}',`,
+        `    emptyOutDir: true,`,
+        `  },`,
+        `  resolve: {`,
+        `    preserveSymlinks: true,`,
+        `    alias: {`,
+        `      '~spa': '${spa.path.replace(/\\/g, '/')}',`,
+    ];
+    // Deduplicate React — monorepo packages may resolve different copies
+    // Point to the package directory so sub-path imports (react/jsx-runtime) still work
+    for (const reactPkg of ['react', 'react-dom']) {
+        try {
+            const pkgDir = dirname(require.resolve(`${reactPkg}/package.json`, { paths: [cwd] })).replace(/\\/g, '/');
+            lines.push(`      '${reactPkg}': '${pkgDir}',`);
+        }
+        catch {
+            /* not found */
+        }
+    }
+    // App pages often import peer UI deps directly. In a pnpm workspace those
+    // deps may live under a Manta package node_modules rather than the app root.
+    const depResolvePaths = [cwd];
+    const addDepResolvePath = (path) => {
+        if (!depResolvePaths.includes(path))
+            depResolvePaths.push(path);
+    };
+    try {
+        addDepResolvePath(dirname(require.resolve('@mantajs/dashboard/package.json', { paths: [cwd] })));
+    }
+    catch {
+        /* not found */
+    }
+    try {
+        const uiDir = dirname(require.resolve('@mantajs/ui/package.json', { paths: [cwd] }));
+        addDepResolvePath(uiDir);
+        addDepResolvePath(resolve(dirname(require.resolve('radix-ui', { paths: [uiDir] })), '..'));
+    }
+    catch {
+        /* not found */
+    }
+    const directPeerDeps = [
+        '@ai-sdk/react',
+        '@date-fns/tz',
+        '@hookform/resolvers',
+        '@tanstack/react-query',
+        '@tanstack/react-table',
+        'lucide-react',
+        'zod',
+        'react-router-dom',
+        'recharts',
+        'react-hook-form',
+        'react-helmet-async',
+        'motion',
+        'motion/react',
+        'radix-ui',
+        'react-day-picker',
+        'date-fns',
+        'cmdk',
+        'class-variance-authority',
+        'clsx',
+        'tailwind-merge',
+        'sonner',
+        '@radix-ui/react-slot',
+        '@radix-ui/react-checkbox',
+        '@radix-ui/react-dialog',
+        '@radix-ui/react-popover',
+        '@radix-ui/react-progress',
+        '@radix-ui/react-radio-group',
+        '@radix-ui/react-scroll-area',
+        '@radix-ui/react-select',
+        '@radix-ui/react-switch',
+        '@radix-ui/react-tabs',
+    ];
+    for (const depPkg of directPeerDeps) {
+        try {
+            let resolved = '';
+            let packageDir = '';
+            try {
+                packageDir = dirname(require.resolve(`${depPkg}/package.json`, { paths: depResolvePaths }));
+                resolved = packageDir;
+            }
+            catch {
+                resolved = require.resolve(depPkg, { paths: depResolvePaths });
+                packageDir = dirname(resolved);
+            }
+            addDepResolvePath(packageDir);
+            lines.push(`      '${depPkg}': '${resolved.replace(/\\/g, '/')}',`);
+        }
+        catch {
+            /* not found */
+        }
+    }
+    // Resolve Manta packages for Vite alias
+    const pkgsToResolve = ['@mantajs/sdk', '@mantajs/ui'];
+    if (dashboard)
+        pkgsToResolve.push(dashboard);
+    for (const pkg of pkgsToResolve) {
+        try {
+            const pkgDir = dirname(require.resolve(`${pkg}/package.json`, { paths: [cwd] }));
+            const distDir = join(pkgDir, 'dist');
+            const sourceDir = existsSync(distDir) ? distDir : join(pkgDir, 'src');
+            const hasDist = sourceDir === distDir;
+            const hasTsx = existsSync(join(pkgDir, 'src', 'index.tsx'));
+            const entryFile = hasDist ? 'dist/index.js' : hasTsx ? 'src/index.tsx' : 'src/index.ts';
+            // Exact import → entry file, sub-path imports (e.g. /index.css) → package source/build directory
+            lines.push(`      '${pkg}': '${join(pkgDir, entryFile).replace(/\\/g, '/')}',`);
+            lines.push(`      '${pkg}/': '${sourceDir.replace(/\\/g, '/')}/',`);
+        }
+        catch {
+            // Not resolved — let Vite handle it
+        }
+    }
+    lines.push(`    },`);
+    lines.push(`  },`);
+    lines.push(`})`);
+    return lines.join('\n');
+}
+function routeToVarName(route) {
+    if (route === '/')
+        return 'PageHome';
+    return ('Page' +
+        route
+            .split('/')
+            .filter(Boolean)
+            .map((s) => s
+            .replace(/^:/, '')
+            .split('-')
+            .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+            .join(''))
+            .join(''));
+}
+//# sourceMappingURL=generate-spa.js.map

package/dist/spa/generate-spa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-spa.js","sourceRoot":"","sources":["../../src/spa/generate-spa.ts"],"names":[],"mappings":"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"}

package/dist/templates/agent/nextjs.md

@@ -0,0 +1,129 @@
+# Manta + Next.js — AI Agent Instructions
+
+You are working in a **Next.js App Router project with Manta mounted inline**. The frontend is Next.js (React 19, App Router, TypeScript). The backend is Manta — a filesystem-first framework with integrated database, CQRS, auth, and admin dashboard. **They run in the same process**: Next owns the HTTP server; Manta lives inside a catch-all route handler.
+
+## Stack
+
+- **Runtime**: Next.js 15 App Router
+- **Backend**: Manta (auto-discovered from `src/modules/`, `src/commands/`, `src/queries/`, …)
+- **Database**: PostgreSQL (managed by Manta through its adapters)
+- **API**: Auto-generated from Manta commands, queries, auth, and the query graph
+- **Admin**: `@mantajs/dashboard` mounted as a Next client component (no separate Vite server)
+
+## How they are wired together
+
+The entire integration is 3 files in the Next project:
+
+```typescript
+// next.config.ts
+import { withManta } from '@mantajs/adapter-nextjs'
+export default withManta({})
+```
+
+```typescript
+// app/api/[...manta]/route.ts
+export { GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD } from '@mantajs/adapter-nextjs/handler'
+```
+
+```typescript
+// app/admin/[[...slug]]/page.tsx
+export { default } from '@mantajs/adapter-nextjs/admin'
+```
+
+- The API catch-all forwards every `/api/*` request to Manta's internal HTTP pipeline. All Manta-generated routes (commands, queries, graph, auth, openapi) are reachable this way.
+- The admin catch-all mounts the Manta dashboard as a client component. Next bundles `@mantajs/dashboard` itself via `transpilePackages` (configured by `withManta`). `react-router-dom` inside the dashboard handles sub-routes.
+- `withManta()` sets `transpilePackages` + `serverExternalPackages` so the raw-TS `@mantajs/*` workspace packages and native deps (postgres, pino, drizzle-orm) play nice with Next.
+
+## Project layout
+
+```
+my-app/
+├── app/                        Next.js App Router (frontend + API mount points)
+│   ├── layout.tsx
+│   ├── page.tsx                your public home
+│   ├── api/[...manta]/route.ts 1 line: re-export from @mantajs/adapter-nextjs/handler
+│   ├── admin/[[...slug]]/page.tsx 1 line: re-export from @mantajs/adapter-nextjs/admin
+│   └── (your other Next pages)
+│
+├── lib/                        shared client-side code (hooks, utilities, types)
+│
+├── src/                        Manta backend (filesystem-first, auto-discovered)
+│   ├── modules/{mod}/entities/{entity}/{model,service}.ts
+│   ├── commands/{context}/{name}.ts
+│   ├── queries/{context}/{name,graph}.ts
+│   ├── subscribers/{name}.ts
+│   ├── jobs/{name}.ts
+│   ├── links/{name}.ts
+│   ├── agents/{name}.ts
+│   └── middleware/{context}.ts
+│
+├── manta.config.ts             defineConfig — database, ports, presets
+├── next.config.ts              withManta({})
+├── tsconfig.json
+└── AGENT.md                    this file
+```
+
+## Development workflow
+
+```bash
+pnpm dev          # runs next dev — that's it. No separate Manta process.
+pnpm generate     # regenerate .manta/generated.d.ts (types for defineModel, field, etc.)
+pnpm db:generate  # create SQL migration from model changes
+pnpm db:migrate   # apply migrations to the database
+```
+
+Manta boots lazily inside the Next.js server on the first API request (singleton pattern in `@mantajs/adapter-nextjs/bootstrap`). Subsequent requests reuse the cached app. Hot reload works normally — Next reloads on file changes, and Manta re-boots on module edits.
+
+## Consuming Manta from Next
+
+### From client components (most common)
+
+Use `@mantajs/sdk` hooks — they call the relative `/api/*` endpoints via `fetch`:
+
+```typescript
+'use client'
+import { useQuery, useCommand, useGraphQuery } from '@mantajs/sdk'
+
+const { data } = useQuery('list-products', { status: 'active' })
+const createProduct = useCommand('create-product')
+const { data: products } = useGraphQuery({ entity: 'product', relations: ['inventory_item'] })
+```
+
+### From React Server Components
+
+Two options:
+
+1. **HTTP round-trip** (simplest): `fetch('/api/public/my-query', ...)` from the RSC. Works everywhere, no singleton coupling.
+2. **Direct app access** (zero-latency): import `getMantaApp` from `@mantajs/adapter-nextjs` and call `app.queryService.graph(...)` / `app.commandRegistry.execute(...)` directly. Bypasses HTTP entirely. Use when you need sub-millisecond latency for SSR.
+
+```typescript
+// app/products/page.tsx — RSC
+import { getMantaApp } from '@mantajs/adapter-nextjs'
+
+export default async function ProductsPage() {
+  const app = await getMantaApp()
+  const products = await app.queryService.graph({ entity: 'product', pagination: { take: 20 } })
+  return <ProductList products={products} />
+}
+```
+
+### From Next API routes (for frontend-specific endpoints)
+
+Don't. If you need a new endpoint, create a `defineCommand` or `defineQuery` in `src/`. The only Next API route you should own is the `[...manta]` catch-all. This keeps auth, validation, and auto-docs uniform.
+
+## Critical rules
+
+1. **No Next API routes beyond the catch-all** — Commands and queries ARE the API. Every endpoint goes through `src/commands/` or `src/queries/`. The `/api/[...manta]` catch-all covers everything.
+2. **`app/` is for pages only** (including RSC and client components). Backend logic lives in `src/`.
+3. **`src/spa/admin/pages/` is NOT used in the Next preset** — unlike the Nitro preset, where it feeds a Vite-built SPA. Custom admin pages in Next are inserted via `<MantaDashboard pageSpecs={...} customBlocks={...}>` props if you need them. For most projects the auto-generated dashboard is enough.
+4. **Always use `@mantajs/sdk` hooks in client components** — never hand-roll `fetch('/api/...')`. The SDK handles auth tokens, error normalisation, and React Query integration.
+5. **RSC → `getMantaApp()` path is optional** — prefer it for SSR data fetching, but `fetch('/api/...')` also works and is simpler for static rendering.
+6. **Manta rules still apply** — the 14 primitives below (`defineModel`, `defineCommand`, `defineQuery`, `defineWorkflow`, …) govern the backend exactly as in a standalone Manta project. Entity names PascalCase, 1 entity = 1 service, compensation automatic, etc.
+
+## Deployment
+
+Manta-on-Next is a normal Next app. Deploy to Vercel, Node servers, or any runtime that supports Next 15 + server functions. Make sure `DATABASE_URL` is set in the environment. Manta's cold-start overhead is ~100-200ms on first request (singleton bootstrap).
+
+---
+
+_The sections below are the canonical Manta primitives reference. Everything after this line is identical to the standalone Manta AGENT.md and applies to the `src/` backend in this project._

package/dist/templates/agent/nuxt.md

@@ -0,0 +1,98 @@
+# Manta + Nuxt — AI Agent Instructions
+
+You are working in a **Nuxt project with Manta backend**. The frontend is Nuxt (Vue, auto-imports). The backend is Manta — a tool-first runtime for AI agents with an integrated database.
+
+## Stack
+
+- **Frontend**: Nuxt 3 (Vue 3, auto-imports, Nitro server)
+- **Backend**: Manta (CQRS commands, DML models, compensable workflows)
+- **Database**: PostgreSQL (managed by Manta)
+- **API**: Auto-generated from Manta commands and contexts
+
+## How they connect
+
+Nuxt calls Manta's auto-generated API endpoints via `$fetch` or `useFetch`:
+
+```typescript
+// In a Nuxt page or composable:
+const { data: posts } = await useFetch('http://localhost:9000/api/store/query/blog', {
+  method: 'POST',
+  body: { filters: { status: 'published' }, limit: 10 },
+})
+
+// Execute a command:
+const result = await $fetch('http://localhost:9000/api/admin/command/create-post', {
+  method: 'POST',
+  headers: { Authorization: `Bearer ${token}` },
+  body: { title: 'Hello World', slug: 'hello-world', content: '...' },
+})
+```
+
+## Manta backend structure
+
+The Manta backend lives alongside Nuxt:
+
+```
+my-app/
+├── pages/                # Nuxt pages (frontend)
+├── components/           # Nuxt components
+├── composables/          # Nuxt composables
+├── server/               # Nuxt server routes (if needed)
+├── src/                  # Manta backend
+│   ├── modules/
+│   │   └── blog/
+│   │       ├── entities/
+│   │       │   └── post/
+│   │       │       ├── model.ts
+│   │       │       └── service.ts
+│   │       └── index.ts
+│   ├── commands/
+│   ├── subscribers/
+│   ├── jobs/
+│   ├── links/
+│   └── contexts/
+├── manta.config.ts       # Manta configuration
+├── nuxt.config.ts        # Nuxt configuration
+└── AGENT.md              # This file
+```
+
+## Manta backend rules
+
+Same rules as standalone Manta. See documentation links below.
+
+### The 8 primitives
+
+| Function | Purpose | Location |
+|----------|---------|----------|
+| `defineModel()` | Data entity schema | `src/modules/{mod}/entities/{entity}/model.ts` |
+| `defineService()` | Mutations with compensation | `src/modules/{mod}/entities/{entity}/service.ts` |
+| `defineCommand()` | Workflow entry point | `src/commands/{name}.ts` |
+| `defineSubscriber()` | Event reaction | `src/subscribers/{name}.ts` |
+| `defineJob()` | Cron task | `src/jobs/{name}.ts` |
+| `defineLink()` | Cross-module relation | `src/links/{name}.ts` |
+| `defineContext()` | API surface | `src/contexts/{name}.ts` |
+| `defineConfig()` | Configuration | `manta.config.ts` |
+
+### Critical rules
+
+1. **No API routes in Manta** — Commands are the API. Use Nuxt `server/` routes only for frontend-specific needs.
+2. **1 entity = 1 service** — `model.ts` + `service.ts` per entity.
+3. **Compensation is mandatory** in `service.method()`.
+4. **Use `step.service.*` in commands**.
+5. **Entity names are PascalCase**.
+
+## Running both
+
+```bash
+# Terminal 1: Manta backend
+manta dev
+
+# Terminal 2: Nuxt frontend
+nuxt dev
+```
+
+## Documentation
+
+Complete Manta documentation in `node_modules/@mantajs/core/docs/` — see [00-overview.md](node_modules/@mantajs/core/docs/00-overview.md) to start.
+
+**Read the relevant doc BEFORE writing Manta backend code.**