@mugwork/mug 0.1.0

package/dist/src/commands/sync.js

@@ -0,0 +1,991 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, cpSync, rmSync } from "node:fs";
+import { join, relative } from "node:path";
+import Database from "better-sqlite3";
+import { ensureDevEmail, getAccountToken } from "./login.js";
+import { templates, skillTemplates, docTemplates } from "../templates.js";
+import { readFilesManifest, readDatabasesManifest, writeFilesManifest, writeDatabasesManifest, computeFileSha256 } from "../manifest.js";
+import { checkCliVersion } from "../version-check.js";
+import { migrateConfig, configNeedsMigration } from "../connector-migration.js";
+const MUG_START = "<!-- mug:start -->";
+const MUG_END = "<!-- mug:end -->";
+function loadMugJson(dir) {
+    const path = join(dir, "mug.json");
+    if (!existsSync(path)) {
+        console.error("No mug.json found. Run `mug init` first.");
+        process.exit(1);
+    }
+    return JSON.parse(readFileSync(path, "utf-8"));
+}
+function generateInstructions(config, cwd) {
+    const name = config.name;
+    const databases = config.databases ?? {};
+    const sources = config.sources ?? {};
+    const workflows = config.workflows ?? {};
+    let md = `## Mug Workspace: ${name}\n\n`;
+    md += `This is a Mug workspace. Write TypeScript using Mug's framework APIs.\n\n`;
+    md += `### Framework APIs\n\n`;
+    md += `**Sources** — sync external data (use \`/connector\` skill for guided setup):\n`;
+    md += `- \`import { source } from "@mugwork/mug"\`\n`;
+    md += `- \`source({ name, database, tables: [{ name, primaryKey, fetch(ctx) }] })\`\n`;
+    md += `- \`ctx.credential(name?)\` — returns API key/token from workspace secrets\n`;
+    md += `- Place connector files in \`connectors/\` — auto-discovered by \`mug deploy\`\n`;
+    md += `- Trigger: \`curl -X POST http://localhost:8787/sync/my-api\`\n\n`;
+    md += `**AI** — multi-provider with tier-based routing (use \`/ai\` skill for guided setup, \`.mug/docs/ai.md\` for full reference):\n`;
+    md += `- \`ctx.ai("fast", { prompt, system })\` — use workspace's fast model (cheapest). **You must set \`prompt\` (user message) and \`system\` (system prompt).**\n`;
+    md += `- \`ctx.ai("balanced", { prompt, system })\` — mid-tier model. \`ctx.ai("powerful", { prompt, system })\` — strongest model.\n`;
+    md += `- \`ctx.ai("auto", { prompt, system })\` — Mug picks the tier based on prompt complexity\n`;
+    md += `- \`ctx.ai("provider/model", { prompt, system })\` — direct call: \`"openai/gpt-5.4-nano"\`, \`"anthropic/claude-sonnet-4-6"\`\n`;
+    md += `- Tiers configured in \`mug.json\` \`ai.routing\` (fast/balanced/powerful → provider/model)\n`;
+    md += `- **BYOK**: \`mug secret set ai.anthropic=<key>\` → set \`"ai.anthropic"\` in \`mug.json\` \`ai.billing\` for unlimited AI at zero Mug credit cost\n`;
+    md += `- Per-call billing: \`billing: "ai.anthropic"\` or \`billing: "mug-metered"\`. Per-workflow: \`workflow(name, handler, { billing: "ai.anthropic" })\`\n\n`;
+    md += `**Search** — find relevant data across synced sources:\n`;
+    md += `- FTS5 auto-indexing: every synced text column gets a full-text index automatically. Query via \`ctx.query(db, "SELECT * FROM {table}_fts WHERE {table}_fts MATCH ? ORDER BY rank", [keyword])\`\n`;
+    md += `- \`ctx.search(query, { source?, limit? })\` — semantic similarity search. Returns \`{ score, table, primaryKey, row }[]\`. Requires deployed workspace (uses Vectorize).\n`;
+    md += `- \`ctx.ask(question, { source?, limit?, model?, system? })\` — full RAG: searches relevant data, feeds to LLM, returns grounded answer. Returns \`{ answer, sources, usage }\`.\n`;
+    md += `- Three layers: FTS5 for keyword search (free, local), \`ctx.search()\` for semantic (deployed), \`ctx.ask()\` for natural language answers (deployed).\n`;
+    md += `- See \`.mug/docs/api.md\` for full signatures and \`.mug/docs/ai.md\` for when to use each layer.\n\n`;
+    md += `**Workflows** — multi-step automation (use \`/workflow\` skill for guided setup):\n`;
+    md += `- \`workflow(name, async (ctx) => { ... }, options?)\` — register a workflow. Options: \`{ description?, billing?, webhook?: true | { auth, secret }, inbound?: "sms" | "email" | "slack", trigger?: { source, table?, on?, includeInitialSync? } }\`\n`;
+    md += `- Every workflow must have a \`description\` in options. Add \`//\` comments above each \`ctx.*\` call and \`return\` — these appear as step descriptions in the explorer.\n`;
+    md += `- \`ctx.query(database, sql, params?)\` — read from any workspace database\n`;
+    md += `- \`ctx.exec(database, sql, params?)\` — write to any workspace database\n`;
+    md += `- \`ctx.ai()\` — see **AI** section above\n`;
+    md += `- \`ctx.notify.email({ to, message, subject?, fromName?, cta? })\` / \`.sms({ to, message })\` / \`.slack({ to, message, blocks?, thread_ts? })\` / \`.channel(name, options)\` for custom channels\n`;
+    md += `- \`ctx.surfaceUrl(surfaceId, path?)\` — generate URL to a surface (dev/prod-aware)\n`;
+    md += `- \`ctx.file(path)\` — read a file from \`files/\` as ArrayBuffer (R2 in prod, local in dev)\n`;
+    md += `- \`ctx.fileText(path)\` — read a file as UTF-8 string\n`;
+    md += `- \`ctx.secret(name)\` — read a workspace secret by name (from \`.mug/secrets\`). Throws if not found.\n`;
+    md += `- \`ctx.waitFor(eventName, options?)\` — pause workflow until an external event arrives. Returns \`{ payload, type, timedOut }\`. Options: \`{ timeout?: "1 hour" | "24 hours", message?: string }\`. Zero cost while waiting.\n`;
+    md += `- \`ctx.waitForUrl(eventName)\` — generate a one-time callback URL for embedding in notifications. Returns a URL that, when visited, sends the event to the waiting workflow.\n`;
+    md += `- \`ctx.http(url, options?)\` — outbound HTTP request. Returns \`{ status, headers, body, json, ok }\`. Throws on non-2xx by default (\`throwOnError: false\` to handle manually). Auto-retries connection errors and 429 with exponential backoff. Options: \`{ method?, headers?, body?, throwOnError?, retry?: { attempts? } | false, timeout?, sign?: { secret, header? } }\`\n`;
+    md += `- \`ctx.respond(body, status?)\` — set a custom HTTP response for webhook-triggered workflows. First call wins. Use for Slack challenge verification, Twilio TwiML, etc. If not called, webhook returns default \`{ ok: true }\`.\n`;
+    md += `- Place workflow files in \`workflows/\` — auto-discovered by \`mug deploy\`\n\n`;
+    md += `**Notifications** — email and SMS from workflows (use \`/notify\` skill for guided setup):\n`;
+    md += `- \`ctx.notify.email({ to, message, subject?, fromName?, cta?: { label, url } })\` — styled HTML email with optional CTA button\n`;
+    md += `- \`ctx.notify.sms({ to, message })\` — SMS via Twilio (E.164 format)\n`;
+    md += `- \`ctx.surfaceUrl("approvals")\` — returns correct URL for dev (\`localhost:8787\`) or prod (\`workspace.mug.work\`)\n`;
+    md += `- In local dev, emails send via Resend (real delivery) + console log\n`;
+    md += `- BYOK: set your own Resend/Twilio keys via \`mug secret set\` for unlimited sends\n`;
+    md += `- **Usage limits**: email/SMS/AI have per-tier limits. \`ctx.notify\` and \`ctx.ai\` throw when limits are exceeded — catch in workflows to handle gracefully. \`mug buy-pack\` or \`mug workspace plan\` to increase limits. BYOK bypasses metered limits. See \`.mug/docs/billing.md\` for tier details.\n\n`;
+    md += `**Slack surface** — send Block Kit messages, slash commands, interactive buttons, Home Tab (use \`/slack\` skill for guided setup):\n`;
+    md += `- \`ctx.notify.slack({ to, message, blocks?, thread_ts? })\` — send messages with raw Block Kit. \`to\` is a channel ID or name.\n`;
+    md += `- \`ctx.slack.updateMessage({ channel, ts, text?, blocks? })\` — update a message after an action (replace buttons with result)\n`;
+    md += `- \`ctx.slack.openModal({ triggerId, view })\` — open a modal from a slash command workflow\n`;
+    md += `- Action ID convention: \`mug:<workflow>:<action>\` routes button clicks to specific workflows\n`;
+    md += `- Slash command trigger: \`"trigger": { "type": "slack_command", "command": "/dispatch" }\` in workflow config\n`;
+    md += `- Event trigger: \`"trigger": { "type": "slack_event", "event": "message" }\` in workflow config\n`;
+    md += `- Slack data auto-synced: \`slack_users\` (user_id, email, display_name) and \`slack_channels\` (channel_id, name) tables\n`;
+    md += `- Block Kit reference: agents already know Block Kit — use it directly, no Mug abstraction layer\n`;
+    md += `- Slack API docs (LLM-optimized): \`https://docs.slack.dev/apis/web-api.md\`\n\n`;
+    md += `**Inbound messages** — receive SMS replies, email replies, Slack interactions:\n`;
+    md += `- Configure in workflow options: \`workflow("handle-sms", handler, { inbound: "sms" })\`\n`;
+    md += `- Webhook URLs shown after \`mug deploy\`: \`https://api.mug.work/inbound/sms/<workspace>\`, etc. Run \`mug webhooks\` to see all URLs.\n`;
+    md += `- SMS workflow receives: \`ctx.params = { channel: "sms", from: "+1...", body: "YES", messageSid: "SM..." }\`\n`;
+    md += `- Email workflow receives: \`ctx.params = { channel: "email", from: "user@...", subject: "Re: ...", body: "..." }\`\n`;
+    md += `- Slack workflow receives: \`ctx.params = { channel: "slack", userId: "U...", actionId: "approve_btn", actionValue: "..." }\`\n`;
+    md += `- **Pattern**: "send and wait for reply" uses two workflows — one sends + sets a status field in DB, the other catches the inbound reply + checks that field to determine what to do\n\n`;
+    md += `**Forms** — collect data from users (use \`/form\` skill for guided setup):\n`;
+    md += `- Config-driven JSON files in \`surfaces/<name>.json\` with \`"type": "form"\` — form is live immediately in \`mug dev\`\n`;
+    md += `- Field types: text, email, phone, number, select, multiselect, date, textarea, file, calculated, hidden\n`;
+    md += `- **Field names must be unique across the entire form** (including across pages and showWhen fields) — duplicates cause silent data loss. \`mug form validate\` catches this.\n`;
+    md += `- Field properties: \`default\` (static value), \`prefill\` (from auth row, URL param, or DB), \`locked\` (read-only + server-enforced), \`helpText\` (hint below label), \`validate\` (custom rules with error messages)\n`;
+    md += `- Validation + help text support \`{{column}}\` templates resolved from auth row (e.g., \`helpText: "You have {{pto_hours}} hours available"\`)\n`;
+    md += `- Conditional fields: \`showWhen: [{ field, op, value }]\` (ops: eq, neq, in, gt, lt, filled, empty)\n`;
+    md += `- Multi-page: \`pages: [{ id, title, fields }]\` with optional branching\n`;
+    md += `- Access modes: \`public\` (anyone), \`identify\` (verify email/phone), \`auth\` (restricted to known users — also provides auth row for prefill)\n`;
+    md += `- Handler workflow receives submissions via \`ctx.params\`. Place handler in \`workflows/handle-<name>.ts\` — auto-discovered.\n`;
+    md += `- Auth prefill: \`prefill: { source: "auth", column: "name" }\` auto-fills from the user's auth row. Combine with \`locked: true\` for identity fields. Use \`access.query\` with \`:identity\` placeholder for computed columns (JOINs, calculations) — no denormalized state needed.\n`;
+    md += `- Dynamic forms: \`ctx.collect(options)\` creates forms programmatically at runtime (advanced — see \`.mug/docs/forms.md\`)\n`;
+    md += `- Breadcrumbs: add \`?from=/portal&fromLabel=Back to Portal\` to surface links — target surface shows a back link above the header\n\n`;
+    md += `**Portals** — tabbed, section-based data pages (use \`/portal\` skill for guided setup):\n`;
+    md += `- Config-driven JSON files in \`surfaces/<name>.json\` with \`"type": "portal"\`\n`;
+    md += `- \`tabs\` — array of tabs, each with \`id\`, \`label\`, and \`sections\` array. Single-tab portals hide the tab bar. Tab options: \`color\` (text/underline color), \`countQuery\` (dynamic badge count).\n`;
+    md += `- Top-level \`sections\` on the config render above the tab bar and stay visible on all tabs. Stats items support \`href\` to make cards clickable links (e.g., \`"href": "?tab=pending"\`).\n`;
+    md += `- Section types: \`table\` (paginated rows → detail pages → action buttons), \`stats\` (metric cards), \`progress\` (progress bars), \`text\` (markdown), \`chart\` (bar/donut SVG), \`gallery\` (image grid), \`accordion\` (collapsible container)\n`;
+    md += `- Table sections have \`query\`, \`columns\`, \`detail\`, \`actions\`, \`pageSize\`. Use \`:user\` in SQL for session identity, \`:auth.column\` for any auth table column.\n`;
+    md += `- Action button styles: \`"success"\` (green), \`"danger"\` (red), \`"warning"\` (amber), \`"primary"\` (accent), \`"default"\` (gray). Add \`"color": "#hex"\` for custom override. Use success/danger for approve/deny.\n`;
+    md += `- Actions are **optimistic** — button replaced instantly with status message. \`afterMessage\`: custom text (\`{{timestamp}}\` for date/time). \`afterColor\`: hex color for the status message. \`afterActions\`: follow-up buttons (e.g., revoke/undo) that fire the same workflow.\n`;
+    md += `- **Timeline playback**: action buttons can trigger scripted visual sequences instead of workflows. Set \`"timeline"\` (array) instead of \`"workflow"\` (string). Events: \`toast\` (notification popup), \`preview\` (email/SMS card), \`stream\` (char-by-char AI-style text), \`update\` (swap table cell value), \`highlight\` (pulse-highlight row via \`row\` or button via \`action\`, with optional \`message\` badge). Each event has \`delay\` (seconds from trigger). Button disabled during playback.\n`;
+    md += `- **Autoplay**: portal config accepts \`"autoplay": []\` — same event array, fires on page load. Use for guided demos (\`highlight\` with \`delay: 0\`) or AI summary streams on dashboards.\n`;
+    md += `- **Embed mode**: append \`?embed=true\` to any surface URL to strip header chrome (logo, session, logout, breadcrumbs) for iframe embedding. CSP allows framing from \`mug.work\` and \`*.mug.work\`.\n`;
+    md += `- Stats \`valueColor\`: \`"match"\` (inherit border color — default when \`color\` set), \`"neutral"\` (dark text), or hex. Badge \`badgeColors\`: \`{ "PTO": "#3b82f6" }\` for custom non-status values.\n`;
+    md += `- Access modes: same as forms (\`public\`, \`identify\`, \`auth\`)\n`;
+    md += `- Column \`dateFormat\`: \`"short"\` for compact dates (\`5/15/26, 3:30 PM\`). Default is long format (\`May 15, 2026, 3:30 PM\`).\n`;
+    md += `- Column/field/stat formats: \`"currency"\` ($X,XXX.XX in tables, whole in stats), \`"currency-whole"\` ($X,XXX), \`"currency-short"\` ($12.5K/$1.2M), \`"number"\` (comma-separated), \`"percent"\` (XX%). Stat values that overflow auto-abbreviate to K/M.\n`;
+    md += `- Chart sections: \`labelColumn\`/\`valueColumn\` default to \`"label"\`/\`"value"\`. \`colors\`: \`{ "complete": "#16a34a", "error": "#ef4444" }\` maps label values to colors.\n`;
+    md += `- All \`date\`/\`datetime\` columns render in the workspace timezone (\`settings.timezone\` in mug.json). Override per-surface with \`"timezone": "America/New_York"\` in the surface JSON.\n\n`;
+    md += `**Demo mode** — share deployed auth'd surfaces with stakeholders without requiring them to verify:\n`;
+    md += `- \`mug demo enable <surface> --as <email-or-phone>\` — surface renders pre-authenticated as that identity\n`;
+    md += `- Use \`_home\` as the surface ID to demo the workspace home screen (e.g. \`mug demo enable _home --as demo@example.com\`)\n`;
+    md += `- \`mug demo disable <surface>\` / \`mug demo status\` — manage active demos\n`;
+    md += `- Notification routing (automatic, no code guards needed):\n`;
+    md += `  - \`--notify demo-user\` (default) — notifications redirect to \`--as\` identity (matching channels only, others suppressed)\n`;
+    md += `  - \`--notify dev\` — notifications redirect to the developer's account email\n`;
+    md += `  - \`--notify off\` — suppress all notifications (logged but not sent)\n`;
+    md += `  - Per-channel overrides: \`--email-to <addr>\`, \`--sms-to <phone>\`, \`--slack-to <channel>\` (override any mode)\n`;
+    md += `- \`--no-workflows\` — suppress workflow execution entirely (surface still renders and accepts input)\n`;
+    md += `- \`ctx.isDemo\` is \`true\` in demo workflows — use to guard non-notification side effects (destructive writes, external API calls)\n`;
+    md += `- Create a demo persona (e.g. \`demo@example.com\`) in your auth table with curated data. The demo viewer sees exactly what that user would see.\n\n`;
+    md += `**Branding** — custom logo and accent color on all surfaces and emails:\n`;
+    md += `- Configure in \`mug.json\`: \`"branding": { "logo": "assets/logo.png", "logoSquare": "assets/icon.png", "accentColor": "#1a5276", "ogImage": "assets/og-image.png" }\`\n`;
+    md += `- Two logo variants: \`logo\` (rectangle, for headers) and \`logoSquare\` (square, for icons). If only one provided, used everywhere.\n`;
+    md += `- \`ogImage\` — custom 1200x630 PNG for link previews (Slack, iMessage, LinkedIn, Discord). Falls back to Mug default if not set.\n`;
+    md += `- Logo paths are relative to workspace root. Uploaded to R2 on \`mug deploy\`, served at \`https://<workspace>.mug.work/_branding/\`\n`;
+    md += `- Accent color applies to buttons, links, focus rings, progress bars via CSS variable \`--accent\`. Also tints the browser favicon.\n`;
+    md += `- All surfaces automatically emit Open Graph and Twitter Card meta tags (title, description, image) for link previews.\n`;
+    md += `- Emails automatically use workspace branding (logo in header, accent on CTA buttons)\n`;
+    md += `- **Per-surface overrides**: add \`"branding": { "logoSquare": "files/logo.png", "accentColor": "#2563eb" }\` to any surface JSON to override workspace branding for that surface. Surface branding takes precedence; workspace branding is the fallback.\n`;
+    md += `- In dev, logos served from local files. Changes to mug.json branding hot-reload.\n\n`;
+    md += `**Home Screen** — workspace root URL (\`subdomain.mug.work/\`) shows branded auth + surface directory:\n`;
+    md += `- By default, the home screen requires authentication — visitors verify via email/phone before seeing content.\n`;
+    md += `- **Public mode**: add \`"access": { "mode": "public" }\` to \`_home.json\` to show public surfaces without auth. Optional \`"showLogin": true\` adds a "Log in" button (only renders if at least one surface has non-public access).\n`;
+    md += `- Auth is configless: scans workspace owner/admin + all surface auth tables. No setup needed.\n`;
+    md += `- Auth flow: demo mode check → session cookie check → auth gate (email/phone verification).\n`;
+    md += `- After login, shows a directory of surfaces the user has access to.\n`;
+    md += `- Demo mode: \`mug demo enable _home --as <identity>\` — the home screen is surface ID \`_home\` for demo purposes.\n`;
+    md += `- Configure layout in \`surfaces/_home.json\`: \`{ "title": "...", "description": "...", "groups": [...] }\`\n`;
+    md += `- \`title\` → rendered as heading in header, page title, OG meta (fallback: title-cased workspace slug). \`description\` → rendered below title in header + OG/Twitter meta.\n`;
+    md += `- Groups combine a button row (actions) with card list (destinations):\n`;
+    md += `  \`{ "label": "HR", "description": "...", "icon": "users", "buttons": [{ "surface": "time-off", "label": "Request Time Off" }], "cards": [{ "surface": "portal", "label": "Dashboard", "description": "...", "icon": "layout-dashboard" }] }\`\n`;
+    md += `- Optional \`color\` on groups (tints border + bg + title + icons), buttons (bg override), cards (colored border + tint).\n`;
+    md += `- Optional \`icon\` on groups and cards — any [Lucide icon](https://lucide.dev) name (e.g., \`"hard-hat"\`, \`"receipt"\`, \`"bar-chart-3"\`).\n`;
+    md += `- Optional \`"collapsible": true\` on groups — renders as accordion. \`"collapsed": true\` starts closed (default: open).\n`;
+    md += `- Named color palette: Red \`#dc2626\`, Orange \`#ea580c\`, Gold \`#ca8a04\`, Brown \`#92400e\`, Green \`#16a34a\`, Teal \`#0f766e\`, Blue \`#2563eb\`, Navy \`#1e3a8a\`, Purple \`#7c3aed\`, Pink \`#db2777\`, Maroon \`#6b2140\`, Gray \`#475569\`.\n`;
+    md += `- Surfaces not in any group appear at the bottom as default cards.\n`;
+    md += `- No \`_home.json\` = all surfaces shown alphabetically as cards.\n`;
+    md += `- Uses workspace branding (logo, accent color, OG meta). Fully mobile responsive.\n`;
+    md += `- In dev, \`localhost:8787/\` shows home screen with all surfaces and dev identity. Changes to \`_home.json\` hot-reload.\n\n`;
+    md += `**CLI commands:**\n`;
+    md += `\`\`\`bash\n`;
+    md += `mug dev                              # start local dev server (auto-detects ports from 8787)\n`;
+    md += `mug dev --port <port>                # pin to a specific port\n`;
+    md += `mug dev --tunnel                     # expose via Cloudflare Quick Tunnel (requires cloudflared)\n`;
+    md += `mug shutdown                         # gracefully stop the running dev server\n`;
+    md += `mug run <workflow>                   # run workflow locally\n`;
+    md += `mug run <workflow> --production      # run in production (CF Workflows)\n`;
+    md += `mug logs [workflow]                  # view execution log (--json, --limit N, --production)\n`;
+    md += `mug status <workflow> <instanceId>   # check production status (--json)\n`;
+    md += `mug sql <db> <sql>                   # run SQL against databases/<db>.db (--json, --production, --dev, --port)\n`;
+    md += `mug usage                            # usage across all 6 billing dimensions (--json, --period)\n`;
+    md += `mug workspace plan                   # view or change workspace plan tier (opens Stripe for paid tiers)\n`;
+    md += `mug buy-pack                         # purchase 25% overage pack for current period\n`;
+    md += `mug billing                          # view/update billing settings (--auto-packs, --max-packs, --email)\n`;
+    md += `mug deploy                           # deploy to production (includes database push)\n`;
+    md += `mug push databases/<name>            # upload local database to production\n`;
+    md += `mug push --all                       # upload all local files and databases\n`;
+    md += `mug push --all --force               # push all without confirmation prompt\n`;
+    md += `mug pull databases/<name>            # download production database locally\n`;
+    md += `mug pull --all                       # download all remote files and databases\n`;
+    md += `mug form init <name>                 # scaffold form + handler workflows\n`;
+    md += `mug form validate                    # check form schemas for errors\n`;
+    md += `mug form list                        # list forms and URLs\n`;
+    md += `mug portal init <name>               # scaffold portal config in surfaces/\n`;
+    md += `mug portal list                      # list portal surfaces and URLs\n`;
+    md += `mug secret set KEY=VALUE             # store secret (--production to sync)\n`;
+    md += `mug secret list                      # show stored secret keys\n`;
+    md += `mug secret remove KEY                # remove a secret\n`;
+    md += `mug connector search <query>         # search community connector catalog\n`;
+    md += `mug connector pull --slug <name>    # download connector spec from catalog\n`;
+    md += `mug connector discover <product>     # record API availability\n`;
+    md += `mug connector gather --slug <name>   # produce OpenAPI spec\n`;
+    md += `mug connector verify --slug <name>   # verify against live API\n`;
+    md += `mug connector scaffold --slug <name> # generate TypeScript source\n`;
+    md += `mug connector init <product>         # full pipeline (discover→gather→verify→scaffold)\n`;
+    md += `mug auth <provider>                  # connect provider via OAuth (e.g. airtable)\n`;
+    md += `mug demo enable <surface> --as <id>  # share surface pre-auth'd (--expires, --notify, --no-workflows)\n`;
+    md += `mug demo disable <surface>           # revoke demo access\n`;
+    md += `mug demo status                      # show active demos\n`;
+    md += `mug webhooks                          # list webhook URLs, inbound channels, event triggers\n`;
+    md += `mug brain <agent>                     # inspect agent brain memory (struggles, entities, outcomes, sessions)\n`;
+    md += `mug brain <agent> struggles           # review unresolved struggles — knowledge gaps and edge cases\n`;
+    md += `mug login                             # authenticate via email verification\n`;
+    md += `mug create workspace <name>          # register workspace (--subdomain, --tier free|starter|pro|business)\n`;
+    md += `mug workspace status                 # workspace info and plan tier\n`;
+    md += `mug workspace plan                   # view or change plan tier\n`;
+    md += `mug workspace invite <email>         # invite admin to workspace\n`;
+    md += `mug workspace transfer <email>       # transfer ownership (sends invite)\n`;
+    md += `mug workspace remove <email>         # remove member\n`;
+    md += `mug workspace members                # list members + pending invites\n`;
+    md += `mug workspace cancel-invite <id>     # cancel a pending invite\n`;
+    md += `mug workspace check-subdomain <slug> # check subdomain availability\n`;
+    md += `mug workspace archive                # archive workspace (365-day retention)\n`;
+    md += `mug workspace restore                # restore an archived workspace\n`;
+    md += `mug workspace delete                 # permanently delete archived workspace\n`;
+    md += `mug workspace export                 # export workspace data (--categories, --all) as .tar\n`;
+    md += `mug account email <new-email>        # change email (verifies both old and new)\n`;
+    md += `mug account invites                  # show pending incoming and sent invites\n`;
+    md += `mug account accept <id>              # accept a workspace invite\n`;
+    md += `mug account decline <id>             # decline a workspace invite\n`;
+    md += `mug whoami                            # show account, workspaces, and pending invites\n`;
+    md += `mug issue                            # file a bug report or feature request\n`;
+    md += `\`\`\`\n`;
+    md += `Use \`/mug dev\`, \`/mug sync\`, or \`/mug deploy\` to run these commands via the \`/mug\` skill.\n\n`;
+    md += `### Building Sources\n\n`;
+    md += `Use \`/connector <product>\` to build a source — it walks through the full pipeline step by step.\n\n`;
+    md += `The pipeline: **discover → gather → verify → scaffold**. You research the API, the CLI handles storage, normalization, and code generation. Run \`mug connector --help\` for CLI reference.\n\n`;
+    md += `**Source config in mug.json** (metadata only — no credentials here):\n`;
+    md += `\`\`\`json\n`;
+    md += `"sources": {\n`;
+    md += `  "<name>": {\n`;
+    md += `    "auth": { "type": "bearer|api-key|basic|oauth2", "value": "<credential>" },\n`;
+    md += `    "baseUrl": "<API root URL>",\n`;
+    md += `    "syncs": { "<sync-name>": { "database": "<db>", "schedule": "*/15 * * * *" } }\n`;
+    md += `  }\n`;
+    md += `}\n`;
+    md += `\`\`\`\n\n`;
+    md += `### Credentials\n\n`;
+    md += `Store API keys and secrets in \`.mug/secrets\` (gitignored), not in mug.json:\n`;
+    md += `\`\`\`bash\n`;
+    md += `mug secret set AIRTABLE_API_KEY=pat_xxxxx    # writes to .mug/secrets\n`;
+    md += `mug secret list                               # shows keys (not values)\n`;
+    md += `\`\`\`\n`;
+    md += `Secrets are loaded automatically by \`mug dev\` and sent to production by \`mug deploy\`.\n\n`;
+    md += `### Deploy to Production\n\n`;
+    md += `\`\`\`bash\n`;
+    md += `mug secret set MUG_API_KEY=<your-key>          # one-time setup (workspace API key)\n`;
+    md += `mug dev                                        # test locally first\n`;
+    md += `mug deploy                                     # bundle and deploy to Cloudflare\n`;
+    md += `\`\`\`\n`;
+    md += `MUG_API_KEY is used for all production operations: deploy, run --production, status, usage.\n\n`;
+    md += `### Platform Docs\n\n`;
+    md += `Full API reference with detailed examples in \`.mug/docs/\`:\n`;
+    md += `- \`.mug/docs/api.md\` — **unified API reference**: all ctx.* methods, ctx.params shapes, error handling, data patterns, mug.json config, CLI quick reference\n`;
+    md += `- \`.mug/docs/sources.md\` — SourceDef, pagination, rate limits, sync config\n`;
+    md += `- \`.mug/docs/workflows.md\` — workflow registration, scheduling, two-workflow pattern, webhook workflows\n`;
+    md += `- \`.mug/docs/forms.md\` — field types, conditionals, multi-page, access modes, file uploads\n`;
+    md += `- \`.mug/docs/portals.md\` — portal tabs, section types (table/stats/progress/text/chart/gallery/accordion), actions, :user queries\n`;
+    md += `- \`.mug/docs/notifications.md\` — email templates, CTA buttons, markdown support, BYOK\n`;
+    md += `- \`.mug/docs/cli.md\` — complete CLI command reference\n`;
+    md += `- \`.mug/docs/demo.md\` — demo mode: notification routing, workflow suppression, ctx.isDemo\n`;
+    md += `- \`.mug/docs/slack.md\` — slack.json schema, Home Tab sections, shortcuts, unfurl, deploy process\n\n`;
+    md += `### Conventions\n\n`;
+    md += `- **Always filter deleted rows** when querying synced data: \`WHERE _mug_deleted_at IS NULL\`. Synced tables have \`_mug_synced_at\` and \`_mug_deleted_at\` system columns.\n`;
+    md += `- **databases/ is the local source of truth.** Each \`databases/<name>.db\` is a SQLite file. \`mug sql\` reads/writes these directly — no dev server needed. \`mug push\`/\`mug pull\` sync them with production.\n`;
+    md += `- When running \`mug dev\`, databases are seeded into Durable Objects on startup and written back on shutdown (also on \`mug shutdown\`). If data seems stale after a workflow run, the DO writeback may be pending — check \`databases/<name>.db\` directly.\n`;
+    md += `- The dev server has **hot reload** — file changes to surfaces, workflows, agents, and connectors auto-refresh the browser. The workspace explorer at \`/explorer\` updates live.\n`;
+    md += `- Test individual workflows via \`/_dev/run/<workflow-name>\` (POST) — returns step-by-step results with timing.\n`;
+    md += `- The \`_mug_ops\` database is implicit (workflow_runs, workflow_steps)\n`;
+    md += `- All \`ctx.*\` methods throw on failure — use try/catch for graceful error handling\n`;
+    md += `- Use \`"auto"\` for AI calls — smart routing picks the cheapest model that works\n`;
+    md += `- Workflows can be triggered by schedule, CLI (\`mug run\`), form submissions, portal actions, or webhooks\n\n`;
+    if (Object.keys(sources).length > 0) {
+        md += `### Sources\n\n`;
+        for (const [key, val] of Object.entries(sources)) {
+            const src = val;
+            const auth = src.auth;
+            const authType = auth?.type ?? "unknown";
+            const baseUrl = src.baseUrl ?? "";
+            const syncs = src.syncs ?? {};
+            const syncCount = Object.keys(syncs).length;
+            md += `- **${key}** — auth: ${authType}${baseUrl ? `, base: \`${baseUrl}\`` : ""}${syncCount > 0 ? `, ${syncCount} sync(s)` : ""}\n`;
+        }
+        md += `\n`;
+    }
+    if (Object.keys(databases).length > 0) {
+        md += `### Databases\n\n`;
+        for (const [dbName, val] of Object.entries(databases)) {
+            const db = val;
+            const tables = db.tables ? Object.keys(db.tables) : [];
+            md += `- **${dbName}** — tables: ${tables.length > 0 ? tables.join(", ") : "(none yet)"}\n`;
+        }
+        md += `\n`;
+    }
+    if (Object.keys(workflows).length > 0) {
+        md += `### Workflows\n\n`;
+        for (const [wfName, val] of Object.entries(workflows)) {
+            const wf = val;
+            const file = wf.file ?? `workflows/${wfName}.ts`;
+            const schedule = wf.schedule ? `schedule: \`${wf.schedule}\`` : "manual";
+            md += `- **${wfName}** — ${schedule} → \`${file}\`\n`;
+        }
+        md += `\n`;
+    }
+    md += `### Agents\n\n`;
+    md += `**Custom AI agents** — autonomous multi-step work with tools, memory, and structured output.\n\n`;
+    md += `Each agent is a folder in \`agents/<name>/\` with:\n`;
+    md += `- \`agent.json\` — config: model, tools, caps, memory, requireApproval\n`;
+    md += `- \`soul.md\` — core identity, role, and primary instructions (always loaded)\n`;
+    md += `- \`skills/\` — agent-specific skills (auto-discovered, loaded on demand)\n`;
+    md += `- \`brain.db\` — persistent memory (created on first deploy, managed by runtime)\n\n`;
+    md += `Shared skills available to all agents: \`agents/shared-skills/<skill-name>/SKILL.md\`\n\n`;
+    md += `**agent.json fields:**\n`;
+    md += `- \`model\`: \`"claude-sonnet"\` (fixed) or \`{ "fast": "claude-haiku", "balanced": "claude-sonnet", "powerful": "claude-opus" }\` (dynamic routing)\n`;
+    md += `- \`tools\`: \`["query", "search", "ask", "notify", "http", "workspace", "ai"]\`\n`;
+    md += `- \`memory\`: \`{ "entities": true, "outcomes": true, "struggles": true }\`\n`;
+    md += `- \`caps\`: \`{ "maxTurns": 30, "maxCredits": 200, "maxDuration": 300 }\`\n`;
+    md += `- \`requireApproval\`: \`["notify"]\` — pause for human approval before these tools\n\n`;
+    md += `**Invoke from workflows:** \`const result = await ctx.agent("name", { goal, context? })\`\n`;
+    md += `- \`result\`: \`{ response, output?, usage: { credits, turns, duration }, capped? }\`\n`;
+    md += `- Agents run autonomously (multiple turns with tools), unlike \`ctx.ai()\` which is single-shot\n\n`;
+    const agentsDir = cwd ? (existsSync(join(cwd, "agents")) ? join(cwd, "agents") : join(cwd, "src", "agents")) : null;
+    if (agentsDir && existsSync(agentsDir)) {
+        const agentFolders = readdirSync(agentsDir).filter((f) => {
+            if (f === "shared-skills")
+                return false;
+            const p = join(agentsDir, f);
+            return statSync(p).isDirectory() && existsSync(join(p, "agent.json"));
+        });
+        if (agentFolders.length > 0) {
+            md += `**Configured agents:**\n`;
+            for (const folder of agentFolders) {
+                const configPath = join(agentsDir, folder, "agent.json");
+                try {
+                    const config = JSON.parse(readFileSync(configPath, "utf-8"));
+                    const model = typeof config.model === "string" ? config.model : "dynamic routing";
+                    const tools = Array.isArray(config.tools) ? config.tools.join(", ") : "none";
+                    const agentBase = agentsDir.includes("/src/agents") ? "src/agents" : "agents";
+                    md += `- **${folder}** → \`${agentBase}/${folder}/\` (model: ${model}, tools: ${tools})\n`;
+                }
+                catch {
+                    const agentBase = agentsDir.includes("/src/agents") ? "src/agents" : "agents";
+                    md += `- **${folder}** → \`${agentBase}/${folder}/\` (invalid agent.json)\n`;
+                }
+            }
+            md += `\n`;
+        }
+        const sharedSkillsDir = join(agentsDir, "shared-skills");
+        if (existsSync(sharedSkillsDir)) {
+            const sharedSkills = readdirSync(sharedSkillsDir).filter((f) => {
+                const p = join(sharedSkillsDir, f);
+                return statSync(p).isDirectory() && existsSync(join(p, "SKILL.md"));
+            });
+            if (sharedSkills.length > 0) {
+                md += `**Shared agent skills:** ${sharedSkills.join(", ")}\n\n`;
+            }
+        }
+    }
+    md += `### Workspace Structure\n\n`;
+    const isNew = cwd ? isNewStructure(cwd) : false;
+    if (isNew) {
+        md += `\`\`\`\n`;
+        md += `agents/           — AI agents (each agent is a folder with agent.json + soul.md + skills/)\n`;
+        md += `connectors/       — data sync from external APIs\n`;
+        md += `workflows/        — automation logic\n`;
+        md += `surfaces/         — forms, portals, dashboards (.json)\n`;
+        md += `files/            — static files synced to R2 (assets, templates, CSVs)\n`;
+        md += `databases/        — local SQLite files synced to production DOs (.db files gitignored)\n`;
+        md += `mug.json          — workspace config\n`;
+        md += `slack.json        — Slack app config\n`;
+        md += `\`\`\`\n`;
+    }
+    else {
+        md += `\`\`\`\n`;
+        md += `src/sources/      — data sync from external APIs\n`;
+        md += `src/workflows/    — automation logic\n`;
+        md += `src/agents/       — AI agents (each agent is a folder with agent.json + soul.md + skills/)\n`;
+        md += `files/            — static files synced to R2 (assets, templates, CSVs)\n`;
+        md += `databases/        — local SQLite files synced to production DOs (.db files gitignored)\n`;
+        md += `mug.json          — workspace config\n`;
+        md += `\`\`\`\n`;
+    }
+    return md;
+}
+function injectBlock(content, block) {
+    const startIdx = content.indexOf(MUG_START);
+    const endIdx = content.indexOf(MUG_END);
+    if (startIdx === -1 || endIdx === -1)
+        return content;
+    return content.slice(0, startIdx + MUG_START.length) + "\n" + block + "\n" + content.slice(endIdx);
+}
+export function repairScaffolding(cwd) {
+    const dirs = ["files", "databases"];
+    for (const d of dirs) {
+        const dirPath = join(cwd, d);
+        if (!existsSync(dirPath)) {
+            mkdirSync(dirPath, { recursive: true });
+            console.log(`Created ${d}/`);
+        }
+        const remotePath = join(dirPath, ".remote");
+        if (!existsSync(remotePath)) {
+            const empty = d === "files"
+                ? { synced_at: null, files: {} }
+                : { synced_at: null, databases: {} };
+            writeFileSync(remotePath, JSON.stringify(empty, null, 2) + "\n");
+            console.log(`Created ${d}/.remote`);
+        }
+    }
+    // Ensure new-structure dirs exist if workspace uses new layout
+    if (isNewStructure(cwd)) {
+        for (const d of ["agents", "connectors", "workflows", "surfaces"]) {
+            if (!existsSync(join(cwd, d))) {
+                mkdirSync(join(cwd, d), { recursive: true });
+            }
+        }
+        if (!existsSync(join(cwd, "slack.json"))) {
+            writeFileSync(join(cwd, "slack.json"), JSON.stringify({ enabled: false }, null, 2) + "\n");
+            console.log("Created slack.json");
+        }
+    }
+}
+const API_URL = "https://api.mug.work";
+function walkDir(dir) {
+    const results = [];
+    if (!existsSync(dir))
+        return results;
+    for (const entry of readdirSync(dir)) {
+        if (entry === ".remote")
+            continue;
+        const fullPath = join(dir, entry);
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+            results.push(...walkDir(fullPath));
+        }
+        else {
+            results.push(fullPath);
+        }
+    }
+    return results;
+}
+export async function syncLocalFiles(cwd, config) {
+    const workspaceId = config.id;
+    const workspaceName = config.name;
+    if (!workspaceId)
+        return;
+    let token;
+    try {
+        token = getAccountToken();
+    }
+    catch {
+        return;
+    }
+    const filesDir = join(cwd, "files");
+    const localFiles = walkDir(filesDir);
+    if (localFiles.length === 0)
+        return;
+    const manifest = readFilesManifest(cwd);
+    const toUpload = [];
+    for (const localPath of localFiles) {
+        const remotePath = relative(filesDir, localPath).replace(/\\/g, "/");
+        const sha256 = computeFileSha256(localPath);
+        const existing = manifest.files[remotePath];
+        if (!existing || existing.sha256 !== sha256) {
+            toUpload.push({ localPath, remotePath, sha256 });
+        }
+    }
+    if (toUpload.length === 0)
+        return;
+    let uploaded = 0;
+    for (const file of toUpload) {
+        try {
+            const content = readFileSync(file.localPath);
+            const res = await fetch(`${API_URL}/workspace/${workspaceName}/files/upload`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "X-File-Path": file.remotePath,
+                    "X-File-SHA256": file.sha256,
+                },
+                body: content,
+                signal: AbortSignal.timeout(30000),
+            });
+            if (res.ok) {
+                manifest.files[file.remotePath] = {
+                    size: content.byteLength,
+                    sha256: file.sha256,
+                    updated_at: new Date().toISOString(),
+                };
+                uploaded++;
+            }
+            else {
+                console.warn(`  Failed to upload ${file.remotePath}: ${res.statusText}`);
+            }
+        }
+        catch (err) {
+            console.warn(`  Failed to upload ${file.remotePath}: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    if (uploaded > 0) {
+        manifest.synced_at = new Date().toISOString();
+        writeFilesManifest(cwd, manifest);
+        console.log(`Uploaded ${uploaded} file${uploaded !== 1 ? "s" : ""} (${toUpload.map((f) => f.remotePath).join(", ")})`);
+    }
+}
+export async function syncLocalDatabases(cwd, config) {
+    const workspaceId = config.id;
+    const workspaceName = config.name;
+    if (!workspaceId)
+        return;
+    let token;
+    try {
+        token = getAccountToken();
+    }
+    catch {
+        return;
+    }
+    const dbDir = join(cwd, "databases");
+    if (!existsSync(dbDir))
+        return;
+    const dbFiles = readdirSync(dbDir).filter((f) => f.endsWith(".db"));
+    if (dbFiles.length === 0)
+        return;
+    const manifest = readDatabasesManifest(cwd);
+    let uploaded = 0;
+    for (const dbFile of dbFiles) {
+        const dbPath = join(dbDir, dbFile);
+        const dbName = dbFile.replace(/\.db$/, "");
+        const localSha = computeFileSha256(dbPath);
+        const existing = manifest.databases[dbName];
+        if (existing && existing.updated_at) {
+            const localMtime = statSync(dbPath).mtime.toISOString();
+            if (existing.updated_at >= localMtime)
+                continue;
+        }
+        let db;
+        try {
+            db = new Database(dbPath, { readonly: true });
+        }
+        catch (err) {
+            console.warn(`  Skipping ${dbFile}: not a valid SQLite database`);
+            continue;
+        }
+        try {
+            const tableRows = db.prepare("SELECT name, sql FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'").all();
+            const tables = {};
+            for (const { name, sql: ddl } of tableRows) {
+                const rows = db.prepare(`SELECT * FROM "${name}"`).all();
+                tables[name] = { ddl, rows };
+            }
+            const res = await fetch(`${API_URL}/workspace/${workspaceName}/db/${dbName}/upload`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ tables }),
+                signal: AbortSignal.timeout(60000),
+            });
+            if (res.ok) {
+                const result = (await res.json());
+                manifest.databases[dbName] = {
+                    size_mb: Math.round(statSync(dbPath).size / 1024 / 1024 * 10) / 10,
+                    tables: Object.fromEntries(Object.entries(tables).map(([tName, tData]) => [
+                        tName,
+                        {
+                            columns: db.prepare(`PRAGMA table_info("${tName}")`).all().map((c) => ({
+                                name: String(c.name),
+                                type: String(c.type || "TEXT"),
+                            })),
+                            row_count: tData.rows.length,
+                        },
+                    ])),
+                    updated_at: new Date().toISOString(),
+                };
+                uploaded++;
+                console.log(`  ${dbName}: ${result.tables_created} table${result.tables_created !== 1 ? "s" : ""}, ${result.rows_inserted} row${result.rows_inserted !== 1 ? "s" : ""}`);
+            }
+            else {
+                console.warn(`  Failed to upload ${dbName}: ${res.statusText}`);
+            }
+        }
+        finally {
+            db.close();
+        }
+    }
+    if (uploaded > 0) {
+        manifest.synced_at = new Date().toISOString();
+        writeDatabasesManifest(cwd, manifest);
+        console.log(`Uploaded ${uploaded} database${uploaded !== 1 ? "s" : ""}`);
+    }
+}
+async function syncRemoteManifests(cwd, config) {
+    const workspaceId = config.id;
+    const workspaceName = config.name;
+    if (!workspaceId)
+        return;
+    let token;
+    try {
+        token = getAccountToken();
+    }
+    catch {
+        return;
+    }
+    const databases = config.databases ?? {};
+    const sourcesConfig = config.sources ?? {};
+    const dbNames = new Set(Object.keys(databases));
+    for (const src of Object.values(sourcesConfig)) {
+        for (const sync of Object.values(src.syncs ?? {})) {
+            if (sync.database)
+                dbNames.add(sync.database);
+        }
+    }
+    dbNames.add("_mug_ops");
+    const dbParam = [...dbNames].join(",");
+    try {
+        const res = await fetch(`${API_URL}/workspace/${workspaceName}/manifest?databases=${dbParam}`, {
+            headers: { Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(10000),
+        });
+        if (!res.ok) {
+            if (res.status === 401)
+                return;
+            console.warn(`  Remote manifest fetch failed: ${res.statusText}`);
+            return;
+        }
+        const data = (await res.json());
+        const filesManifest = {
+            synced_at: new Date().toISOString(),
+            files: {},
+        };
+        for (const f of data.files) {
+            filesManifest.files[f.path] = { size: f.size, sha256: f.sha256, updated_at: f.uploaded_at };
+        }
+        writeFilesManifest(cwd, filesManifest);
+        const dbManifest = {
+            synced_at: new Date().toISOString(),
+            databases: {},
+        };
+        for (const [dbName, schema] of Object.entries(data.databases)) {
+            const tables = {};
+            const dbSchema = schema;
+            for (const [tableName, info] of Object.entries(dbSchema.tables)) {
+                tables[tableName] = { columns: info.columns, row_count: info.row_count };
+            }
+            dbManifest.databases[dbName] = {
+                size_mb: 0,
+                tables,
+                updated_at: new Date().toISOString(),
+            };
+        }
+        writeDatabasesManifest(cwd, dbManifest);
+        const fileCount = data.files.length;
+        const dbCount = Object.keys(data.databases).length;
+        const tableCount = Object.values(data.databases).reduce((sum, db) => sum + Object.keys(db.tables).length, 0);
+        if (fileCount > 0 || dbCount > 0) {
+            console.log(`Remote: ${dbCount} database${dbCount !== 1 ? "s" : ""} (${tableCount} table${tableCount !== 1 ? "s" : ""}), ${fileCount} file${fileCount !== 1 ? "s" : ""}`);
+        }
+    }
+    catch {
+        // offline or timeout — skip silently
+    }
+}
+function ensureAiDefaults(mugJsonPath) {
+    const raw = JSON.parse(readFileSync(mugJsonPath, "utf-8"));
+    let changed = false;
+    if (!raw.ai) {
+        raw.ai = {};
+        changed = true;
+    }
+    if (!raw.ai.routing) {
+        raw.ai.routing = {
+            fast: "openai/gpt-5.4-nano",
+            balanced: "@cf/moonshotai/kimi-k2.6",
+            powerful: "anthropic/claude-sonnet-4-6",
+        };
+        changed = true;
+    }
+    if (!raw.ai.billing) {
+        raw.ai.billing = {
+            default: "mug-metered",
+            fast: "mug-metered",
+            balanced: "mug-metered",
+            powerful: "mug-metered",
+        };
+        changed = true;
+    }
+    if (changed) {
+        writeFileSync(mugJsonPath, JSON.stringify(raw, null, 2) + "\n");
+    }
+}
+export function ensureSettings(mugJsonPath) {
+    const raw = JSON.parse(readFileSync(mugJsonPath, "utf-8"));
+    let changed = false;
+    if (!raw.settings) {
+        raw.settings = {};
+        changed = true;
+    }
+    if (!raw.settings.timezone) {
+        raw.settings.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        changed = true;
+    }
+    if (changed) {
+        writeFileSync(mugJsonPath, JSON.stringify(raw, null, 2) + "\n");
+    }
+}
+export function migrateMugJsonSources(mugJsonPath) {
+    if (!existsSync(mugJsonPath))
+        return;
+    const raw = JSON.parse(readFileSync(mugJsonPath, "utf-8"));
+    if (!configNeedsMigration(raw))
+        return;
+    const sources = migrateConfig(raw);
+    raw.sources = sources;
+    delete raw.connections;
+    delete raw.connectors;
+    writeFileSync(mugJsonPath, JSON.stringify(raw, null, 2) + "\n");
+    console.log("Migrated mug.json: connections + connectors → sources");
+}
+const FRAMEWORK_TEMPLATES = {
+    "app.ts": "app.ts",
+    "source.ts": "source.ts",
+    "sync-runtime.ts": "sync-runtime.ts",
+    "context.ts": "context.ts",
+    "form-types.ts": "form-types.ts",
+    "types.ts": "types.ts",
+    "workflow.ts": "workflow.ts",
+    "workflow-entrypoint.ts": "workflow-entrypoint.ts",
+    "do/workspace-database.ts": "do/workspace-database.ts",
+    "ai-router.ts": "ai-router.ts",
+    "agent-types.ts": "agent-types.ts",
+    "chunker.ts": "chunker.ts",
+};
+function isNewStructure(cwd) {
+    return existsSync(join(cwd, "connectors")) || existsSync(join(cwd, "workflows")) && !existsSync(join(cwd, "src", "workflows"));
+}
+export function syncFrameworkFiles(cwd) {
+    if (isNewStructure(cwd))
+        return 0;
+    const prefix = "src";
+    let updated = 0;
+    for (const [fileName, templateKey] of Object.entries(FRAMEWORK_TEMPLATES)) {
+        const filePath = join(prefix, fileName);
+        const fullPath = join(cwd, filePath);
+        const latest = templates[templateKey];
+        if (!latest)
+            continue;
+        const current = existsSync(fullPath) ? readFileSync(fullPath, "utf-8") : null;
+        if (current !== latest) {
+            mkdirSync(join(cwd, filePath, ".."), { recursive: true });
+            writeFileSync(fullPath, latest);
+            updated++;
+        }
+    }
+    return updated;
+}
+function migrateToRootStructure(cwd) {
+    // Detect old structure: src/workflows/ exists but root workflows/ does not
+    const hasOldWorkflows = existsSync(join(cwd, "src", "workflows"));
+    const hasNewWorkflows = existsSync(join(cwd, "workflows"));
+    if (!hasOldWorkflows || hasNewWorkflows)
+        return;
+    console.log("\nMigrating workspace to root-level structure...");
+    const moved = [];
+    // Move user code directories
+    const migrations = [
+        ["src/workflows", "workflows"],
+        ["src/sources", "connectors"],
+        ["src/agents", "agents"],
+    ];
+    for (const [oldDir, newDir] of migrations) {
+        const oldPath = join(cwd, oldDir);
+        if (!existsSync(oldPath))
+            continue;
+        const files = readdirSync(oldPath);
+        if (files.length === 0)
+            continue;
+        mkdirSync(join(cwd, newDir), { recursive: true });
+        cpSync(oldPath, join(cwd, newDir), { recursive: true });
+        rmSync(oldPath, { recursive: true });
+        moved.push(`${oldDir}/ → ${newDir}/`);
+    }
+    // Surfaces: may be in src/surfaces/ (not always created in old init)
+    const oldSurfaces = join(cwd, "src", "surfaces");
+    if (existsSync(oldSurfaces) && readdirSync(oldSurfaces).length > 0) {
+        mkdirSync(join(cwd, "surfaces"), { recursive: true });
+        cpSync(oldSurfaces, join(cwd, "surfaces"), { recursive: true });
+        rmSync(oldSurfaces, { recursive: true });
+        moved.push("src/surfaces/ → surfaces/");
+    }
+    // Delete framework files from src/ — runtime comes from CLI package now
+    const frameworkFiles = ["app.ts", "source.ts", "workflow.ts", "workflow-entrypoint.ts", "context.ts",
+        "types.ts", "form-types.ts", "ai-router.ts", "agent-types.ts", "sync-runtime.ts", "chunker.ts",
+        "index.ts", "connector.ts"];
+    for (const f of frameworkFiles) {
+        const old = join(cwd, "src", f);
+        if (existsSync(old))
+            rmSync(old);
+    }
+    try {
+        rmSync(join(cwd, "src", "do"), { recursive: true });
+    }
+    catch { }
+    moved.push("Removed framework files from src/ (runtime comes from CLI package)");
+    // Clean up empty src/ if possible
+    try {
+        const remaining = readdirSync(join(cwd, "src"));
+        if (remaining.length === 0) {
+            rmSync(join(cwd, "src"), { recursive: true });
+            moved.push("Removed empty src/");
+        }
+    }
+    catch { }
+    // Rewrite imports in user .ts files: "../workflow.js" → "@mugwork/mug"
+    const importRewrites = [
+        [/from\s+["']\.\.\/workflow\.js["']/g, 'from "@mugwork/mug"'],
+        [/from\s+["']\.\.\/source\.js["']/g, 'from "@mugwork/mug"'],
+        [/from\s+["']\.\.\/connector\.js["']/g, 'from "@mugwork/mug"'],
+        [/from\s+["']\.\.\/agent-types\.js["']/g, 'from "@mugwork/mug"'],
+    ];
+    for (const dir of ["workflows", "connectors", "agents"]) {
+        const dirPath = join(cwd, dir);
+        if (!existsSync(dirPath))
+            continue;
+        for (const f of readdirSync(dirPath, { recursive: true })) {
+            if (!f.endsWith(".ts") && !f.endsWith(".js"))
+                continue;
+            const filePath = join(dirPath, f);
+            if (!statSync(filePath).isFile())
+                continue;
+            let content = readFileSync(filePath, "utf-8");
+            let changed = false;
+            for (const [pattern, replacement] of importRewrites) {
+                const updated = content.replace(pattern, replacement);
+                if (updated !== content) {
+                    content = updated;
+                    changed = true;
+                }
+            }
+            if (changed) {
+                writeFileSync(filePath, content);
+            }
+        }
+    }
+    // Create slack.json if missing
+    if (!existsSync(join(cwd, "slack.json"))) {
+        writeFileSync(join(cwd, "slack.json"), JSON.stringify({ enabled: false }, null, 2) + "\n");
+        moved.push("Created slack.json");
+    }
+    // Migrate mug.json slack key → slack.json
+    const mugJsonPath = join(cwd, "mug.json");
+    const raw = JSON.parse(readFileSync(mugJsonPath, "utf-8"));
+    if (raw.slack && existsSync(join(cwd, "slack.json"))) {
+        const slackJson = JSON.parse(readFileSync(join(cwd, "slack.json"), "utf-8"));
+        if (!slackJson.enabled && raw.slack.enabled) {
+            writeFileSync(join(cwd, "slack.json"), JSON.stringify(raw.slack, null, 2) + "\n");
+            delete raw.slack;
+            writeFileSync(mugJsonPath, JSON.stringify(raw, null, 2) + "\n");
+            moved.push("Migrated mug.json slack → slack.json");
+        }
+    }
+    // Update tsconfig.json
+    const tsconfigPath = join(cwd, "tsconfig.json");
+    if (existsSync(tsconfigPath)) {
+        try {
+            const tsconfig = JSON.parse(readFileSync(tsconfigPath, "utf-8"));
+            if (JSON.stringify(tsconfig.include) === '["src/**/*"]') {
+                tsconfig.include = ["**/*.ts"];
+                writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2) + "\n");
+                moved.push("Updated tsconfig.json include");
+            }
+        }
+        catch { }
+    }
+    // Print deprecation notices for mug.json object sections
+    if (raw.workflows && Object.keys(raw.workflows).length > 0) {
+        console.log("  ⚠ mug.json \"workflows\" section is deprecated — move schedule/trigger config to workflow .ts options");
+    }
+    if (raw.surfaces && Object.keys(raw.surfaces).length > 0) {
+        console.log("  ⚠ mug.json \"surfaces\" section is deprecated — surfaces are auto-discovered from surfaces/ directory");
+    }
+    if (moved.length > 0) {
+        console.log("  " + moved.join("\n  "));
+        console.log("Migration complete.\n");
+    }
+}
+export async function sync(dir) {
+    const cwd = dir || process.cwd();
+    checkCliVersion();
+    ensureDevEmail(join(cwd, "mug.json"));
+    ensureAiDefaults(join(cwd, "mug.json"));
+    ensureSettings(join(cwd, "mug.json"));
+    migrateMugJsonSources(join(cwd, "mug.json"));
+    migrateToRootStructure(cwd);
+    repairScaffolding(cwd);
+    const config = loadMugJson(cwd);
+    const instructions = generateInstructions(config, cwd);
+    const targets = [
+        "CLAUDE.md",
+        "AGENTS.md",
+        join(".cursor", "rules", "mug.mdc"),
+    ];
+    let updated = 0;
+    for (const target of targets) {
+        const path = join(cwd, target);
+        if (!existsSync(path))
+            continue;
+        const content = readFileSync(path, "utf-8");
+        const newContent = injectBlock(content, instructions);
+        if (newContent !== content) {
+            writeFileSync(path, newContent);
+            updated++;
+        }
+    }
+    let frameworkUpdated = syncFrameworkFiles(cwd);
+    // Migrate old monolithic src/index.ts → src/app.ts + slim index.ts
+    const indexPath = join(cwd, "src", "index.ts");
+    if (existsSync(indexPath)) {
+        const indexContent = readFileSync(indexPath, "utf-8");
+        if (indexContent.includes("new Hono") && indexContent.includes('app.get("/health"')) {
+            const lines = indexContent.split("\n");
+            const userImports = [];
+            for (const line of lines) {
+                if (/^import\s+["']\.\/(connectors|sources)\//.test(line) ||
+                    /^import\s+["']\.\/workflows\//.test(line) ||
+                    /^import\s+["']\.\/agents\//.test(line)) {
+                    userImports.push(line);
+                }
+            }
+            const sourceImports = userImports.filter(l => l.includes("/connectors/") || l.includes("/sources/"));
+            const workflowImports = userImports.filter(l => l.includes("/workflows/") || l.includes("/agents/"));
+            const newIndex = [
+                "// Import sources here:",
+                ...sourceImports,
+                "",
+                "// Import workflows here:",
+                ...workflowImports,
+                "",
+                'export { WorkspaceDatabase } from "./do/workspace-database.js";',
+                'export { default } from "./app.js";',
+                "",
+            ].join("\n");
+            writeFileSync(indexPath, newIndex);
+            frameworkUpdated++;
+            console.log("  Migrated src/index.ts → src/app.ts (framework routes extracted)");
+        }
+    }
+    // Update skills from CLI templates
+    const skillPaths = {};
+    for (const [skillPath, content] of Object.entries(skillTemplates)) {
+        const parts = skillPath.split("/");
+        const skillName = parts[0];
+        const fileName = parts[parts.length - 1];
+        if (fileName.endsWith(".md")) {
+            skillPaths[join(".claude", "skills", skillName, fileName)] = content;
+            skillPaths[join(".agents", "skills", skillName, fileName)] = content;
+        }
+        if (fileName.endsWith(".mdc")) {
+            skillPaths[join(".cursor", "rules", fileName)] = content;
+        }
+    }
+    let skillsUpdated = 0;
+    for (const [filePath, content] of Object.entries(skillPaths)) {
+        const fullPath = join(cwd, filePath);
+        const current = existsSync(fullPath) ? readFileSync(fullPath, "utf-8") : null;
+        if (current !== content) {
+            mkdirSync(join(fullPath, ".."), { recursive: true });
+            writeFileSync(fullPath, content);
+            skillsUpdated++;
+        }
+    }
+    // Update docs from CLI templates
+    let docsUpdated = 0;
+    for (const [docName, content] of Object.entries(docTemplates)) {
+        const fullPath = join(cwd, ".mug", "docs", docName);
+        const current = existsSync(fullPath) ? readFileSync(fullPath, "utf-8") : null;
+        if (current !== content) {
+            mkdirSync(join(fullPath, ".."), { recursive: true });
+            writeFileSync(fullPath, content);
+            docsUpdated++;
+        }
+    }
+    const parts = [`Synced ${updated} instruction file${updated !== 1 ? "s" : ""}`];
+    if (frameworkUpdated > 0)
+        parts.push(`${frameworkUpdated} framework file${frameworkUpdated !== 1 ? "s" : ""}`);
+    if (skillsUpdated > 0)
+        parts.push(`${skillsUpdated} skill${skillsUpdated !== 1 ? "s" : ""}`);
+    if (docsUpdated > 0)
+        parts.push(`${docsUpdated} doc${docsUpdated !== 1 ? "s" : ""}`);
+    console.log(parts.join(", "));
+    await syncLocalFiles(cwd, config);
+    await syncLocalDatabases(cwd, config);
+    await syncRemoteManifests(cwd, config);
+}