aigma 0.1.1 → 0.1.2

package/AGENTS.md

@@ -0,0 +1,168 @@
+# aigma — Agent Integration Guide
+
+This file is for AI agents using the `aigma` CLI. If you are an agent and just installed `aigma`, read this end-to-end before issuing other commands.
+
+Run `aigma agent-help` at any time to print this document.
+
+## What `aigma` does
+
+`aigma` lets you create HTML "nodes" on a user's Aigma canvas from the command line. Each call to `aigma create-node`:
+
+1. Generates a self-contained HTML fragment from your prompt.
+2. Publishes it to a public URL: `https://aigma.co/p/{slug}`.
+3. Drops a draft node onto the user's canvas. The user sees it within ~5s of opening that canvas in the web app.
+
+A user can have **multiple canvases** (think of them as separate projects). You should usually target a specific canvas; otherwise the draft lands on the user's most-recently-edited canvas.
+
+## Authentication
+
+`aigma login` is interactive — it opens a browser. **You cannot run `aigma login` autonomously.** If `aigma create-node` exits with code `3` ("Not authenticated"), report this back to the user and ask them to run `aigma login` themselves.
+
+Once the user has logged in, credentials live at `~/.aigma/credentials.json` and the CLI handles refresh transparently.
+
+## Recommended workflow
+
+```
+1. aigma list-canvases --json
+2. Choose / create a canvas (see below)
+3. aigma create-node --prompt "..." --canvas <id> --json
+```
+
+### Step 1 — list canvases
+
+```bash
+aigma list-canvases --json
+```
+
+Returns:
+
+```json
+{
+  "ok": true,
+  "canvases": [
+    {
+      "id": "uuid",
+      "name": "SaaS Landing",
+      "created_at": "2026-04-01T...",
+      "updated_at": "2026-05-08T...",
+      "node_count": 12,
+      "frames": [
+        { "id": "uuid", "name": "Hero section", "type": "webframe" },
+        { "id": "uuid", "name": "Pricing table", "type": "webframe" }
+      ]
+    }
+  ]
+}
+```
+
+`name` is user-chosen. `frames[]` lists the top-level frames already on that canvas with their AI-generated names — use these to judge what each canvas is about.
+
+### Step 2 — pick or create a canvas
+
+Decision rule:
+
+- If the user's task clearly refers to an existing project and one canvas's `name` or `frames[].name` matches, use that canvas's `id`.
+- If nothing fits, or the user is starting something new, create a canvas:
+
+```bash
+aigma create-canvas --name "Landing v2" --json
+```
+
+Response:
+
+```json
+{
+  "ok": true,
+  "canvas": { "id": "uuid", "name": "Landing v2", ... }
+}
+```
+
+Use the returned `id` for the next step.
+
+### Step 3 — create the node
+
+```bash
+aigma create-node \
+  --prompt "Hero section for an AI photo editor with two CTAs and product screenshot" \
+  --canvas <uuid> \
+  --json
+```
+
+Response:
+
+```json
+{
+  "ok": true,
+  "node_id": "uuid",
+  "draft_id": "uuid",
+  "html": "<section>...</section>",
+  "slug": "abc1234",
+  "public_url": "https://aigma.co/p/abc1234",
+  "canvas_url": "https://aigma.co/nodes?draft=uuid",
+  "canvas": { "id": "uuid", "name": "Landing v2" }
+}
+```
+
+The user can immediately:
+- Visit `public_url` to see the rendered page.
+- Open the canvas (`canvas_url` deep-links to it) and the WebFrame appears within ~5s.
+
+## --canvas argument
+
+You can pass either:
+- A UUID: `--canvas 0f6e2b1a-...`
+- An exact (case-insensitive) name: `--canvas "SaaS Landing"`
+
+If a name matches multiple canvases, the server returns HTTP 400 with a `matches` array — re-issue the call with one of the listed UUIDs.
+
+If `--canvas` is omitted entirely, the server defaults to the user's most-recently-updated canvas. Prefer being explicit.
+
+## Output discipline
+
+| Stream | Content |
+|---|---|
+| stdout | JSON only when `--json` is passed. Pipe-safe (`aigma … --json \| jq`). |
+| stderr | Human-readable progress and errors. |
+
+Always use `--json` when scripting.
+
+## Exit codes
+
+| Code | Meaning | Recovery |
+|---|---|---|
+| 0 | Success | continue |
+| 1 | Generic failure | inspect stderr / `error` field in JSON |
+| 2 | Validation error (missing/bad args) | fix args |
+| 3 | Auth required | tell the user to run `aigma login` |
+
+## Iteration
+
+You can call `create-node` repeatedly — every call creates a new node, so variations sit side-by-side on the canvas. To replace a node you don't want, the user can delete it manually in the web app (no CLI delete command in v0.2).
+
+## Constraints worth knowing
+
+- Prompt is capped at 4000 characters.
+- The HTML fragment is rendered inside a 1280×800 frame on the canvas. Don't include `<html>`, `<head>`, or `<body>` wrappers — the model is instructed to avoid them but you can mention "single self-contained block" in your prompt for safety.
+- No `<script>` tags will be generated.
+- Token usage is metered against the user's Aigma plan. A 429 means they hit their limit.
+
+## Configuration
+
+Override defaults via env (rarely needed):
+
+```bash
+AIGMA_SUPABASE_URL=...
+AIGMA_SUPABASE_ANON_KEY=...
+AIGMA_WEB_BASE=...
+```
+
+## Quickref
+
+```bash
+aigma login                                    # interactive — user only
+aigma list-canvases --json
+aigma create-canvas --name "Project" --json
+aigma create-node --prompt "..." --canvas <id> --json
+aigma create-node --prompt "..." --canvas <id> --output out.html
+aigma agent-help                               # print this guide
+```

package/README.md

@@ -14,9 +14,18 @@ npm install -g aigma
 # Sign in via your browser (Google or Apple)
 aigma login
 
-# Generate a node from a prompt
+# List canvases
+aigma list-canvases
+
+# Create a canvas
+aigma create-canvas --name "My Project"
+
+# Generate a node from a prompt (lands on most-recently-edited canvas)
 aigma create-node --prompt "Hero section for an AI photo editor"
 
+# Or target a specific canvas (by UUID or exact name)
+aigma create-node --prompt "Pricing section" --canvas "My Project"
+
 # Save the generated HTML to a file
 aigma create-node --prompt "Pricing section" --output pricing.html
 
@@ -24,6 +33,10 @@ aigma create-node --prompt "Pricing section" --output pricing.html
 aigma create-node --prompt "Footer with links" --json
 ```
 
+## For AI agents
+
+If you're an AI agent integrating with `aigma`, run `aigma agent-help` to print the full integration guide (also visible at [AGENTS.md](./AGENTS.md)).
+
 Each `create-node` call:
 
 1. Generates a self-contained HTML fragment with Gemini.

package/dist/commands/agent-help.js

@@ -0,0 +1,26 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+export async function runAgentHelp() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // dist/commands/agent-help.js → ../../AGENTS.md (npm package root)
+    const candidates = [
+        join(here, '..', '..', 'AGENTS.md'),
+        join(here, '..', '..', '..', 'AGENTS.md'),
+    ];
+    for (const p of candidates) {
+        try {
+            const md = await readFile(p, 'utf8');
+            process.stdout.write(md);
+            if (!md.endsWith('\n'))
+                process.stdout.write('\n');
+            return;
+        }
+        catch {
+            /* try next */
+        }
+    }
+    process.stderr.write('AGENTS.md not found in package; reinstall aigma.\n');
+    process.exit(1);
+}
+//# sourceMappingURL=agent-help.js.map

package/dist/commands/agent-help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-help.js","sourceRoot":"","sources":["../../src/commands/agent-help.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,mEAAmE;IACnE,MAAM,UAAU,GAAG;QACjB,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC;QACnC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC;KAC1C,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YACrC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACzB,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACnD,OAAO;QACT,CAAC;QAAC,MAAM,CAAC;YACP,cAAc;QAChB,CAAC;IACH,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oDAAoD,CAAC,CAAC;IAC3E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/commands/create-canvas.js

@@ -0,0 +1,50 @@
+import { authenticatedClient } from '../lib/session.js';
+import { FUNCTIONS_BASE, SUPABASE_ANON_KEY } from '../lib/config.js';
+import { success, json, error, ExitCode } from '../lib/output.js';
+export async function runCreateCanvas(opts) {
+    if (!opts.name?.trim()) {
+        error('--name is required');
+        process.exit(ExitCode.Validation);
+    }
+    const auth = await authenticatedClient();
+    if (!auth) {
+        error('Not authenticated. Run `aigma login` first.');
+        process.exit(ExitCode.AuthRequired);
+    }
+    let res;
+    try {
+        res = await fetch(`${FUNCTIONS_BASE}/cli-create-canvas`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${auth.accessToken}`,
+                apikey: SUPABASE_ANON_KEY,
+            },
+            body: JSON.stringify({ name: opts.name.trim() }),
+        });
+    }
+    catch (err) {
+        error(`Network error: ${err.message}`);
+        process.exit(ExitCode.Generic);
+    }
+    let payload;
+    try {
+        payload = (await res.json());
+    }
+    catch {
+        error(`Server returned non-JSON (status ${res.status})`);
+        process.exit(ExitCode.Generic);
+    }
+    if (!res.ok || payload.error || !payload.canvas) {
+        error(payload.error || `Request failed (status ${res.status})`);
+        process.exit(res.status === 401 ? ExitCode.AuthRequired : ExitCode.Generic);
+    }
+    success(`Created canvas: ${payload.canvas.name}`);
+    if (opts.json) {
+        json(payload);
+    }
+    else {
+        process.stderr.write(`  id: ${payload.canvas.id}\n`);
+    }
+}
+//# sourceMappingURL=create-canvas.js.map

package/dist/commands/create-canvas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-canvas.js","sourceRoot":"","sources":["../../src/commands/create-canvas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAelE,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAsC;IAC1E,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;QACvB,KAAK,CAAC,oBAAoB,CAAC,CAAC;QAC5B,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACpC,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,mBAAmB,EAAE,CAAC;IACzC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,KAAK,CAAC,6CAA6C,CAAC,CAAC;QACrD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,cAAc,oBAAoB,EAAE;YACvD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,IAAI,CAAC,WAAW,EAAE;gBAC3C,MAAM,EAAE,iBAAiB;aAC1B;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;SACjD,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,KAAK,CAAC,kBAAmB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAClD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,OAA6B,CAAC;IAClC,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAyB,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,KAAK,CAAC,oCAAoC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;QACzD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QAChD,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,0BAA0B,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;QAChE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC9E,CAAC;IAED,OAAO,CAAC,mBAAmB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAClD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,IAAI,CAAC,OAAO,CAAC,CAAC;IAChB,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC;IACvD,CAAC;AACH,CAAC"}

package/dist/commands/create-node.js

@@ -22,7 +22,10 @@ export async function runCreateNode(opts) {
                 Authorization: `Bearer ${auth.accessToken}`,
                 apikey: SUPABASE_ANON_KEY,
             },
-            body: JSON.stringify({ prompt: opts.prompt }),
+            body: JSON.stringify({
+                prompt: opts.prompt,
+                ...(opts.canvas ? { canvas: opts.canvas } : {}),
+            }),
         });
     }
     catch (err) {
@@ -49,11 +52,14 @@ export async function runCreateNode(opts) {
         await fs.writeFile(opts.output, payload.html, 'utf8');
         success(`HTML written to ${opts.output}`);
     }
+    if (payload.canvas) {
+        info(`  Canvas:  ${payload.canvas.name} (${payload.canvas.id})`);
+    }
     if (payload.public_url) {
         info(`  Public:  ${payload.public_url}`);
     }
     if (payload.canvas_url) {
-        info(`  Canvas:  ${payload.canvas_url}`);
+        info(`  Open:    ${payload.canvas_url}`);
     }
     success('Node created');
     if (opts.json) {

package/dist/commands/create-node.js.map

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

package/dist/commands/list-canvases.js

@@ -0,0 +1,52 @@
+import { authenticatedClient } from '../lib/session.js';
+import { FUNCTIONS_BASE, SUPABASE_ANON_KEY } from '../lib/config.js';
+import { info, json, error, ExitCode } from '../lib/output.js';
+export async function runListCanvases(opts) {
+    const auth = await authenticatedClient();
+    if (!auth) {
+        error('Not authenticated. Run `aigma login` first.');
+        process.exit(ExitCode.AuthRequired);
+    }
+    let res;
+    try {
+        res = await fetch(`${FUNCTIONS_BASE}/cli-list-canvases`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${auth.accessToken}`,
+                apikey: SUPABASE_ANON_KEY,
+            },
+            body: '{}',
+        });
+    }
+    catch (err) {
+        error(`Network error: ${err.message}`);
+        process.exit(ExitCode.Generic);
+    }
+    let payload;
+    try {
+        payload = (await res.json());
+    }
+    catch {
+        error(`Server returned non-JSON (status ${res.status})`);
+        process.exit(ExitCode.Generic);
+    }
+    if (!res.ok || payload.error) {
+        error(payload.error || `Request failed (status ${res.status})`);
+        process.exit(res.status === 401 ? ExitCode.AuthRequired : ExitCode.Generic);
+    }
+    const canvases = payload.canvases ?? [];
+    if (opts.json) {
+        json(payload);
+        return;
+    }
+    if (canvases.length === 0) {
+        info('No canvases yet. Create one with `aigma create-canvas --name "<name>"`.');
+        return;
+    }
+    for (const c of canvases) {
+        const frameNames = c.frames.map((f) => f.name).join(', ');
+        info(`  ${c.id}  ${c.name}  (${c.node_count} nodes${frameNames ? `: ${frameNames}` : ''})`);
+    }
+}
+//# sourceMappingURL=list-canvases.js.map

package/dist/commands/list-canvases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-canvases.js","sourceRoot":"","sources":["../../src/commands/list-canvases.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAiB/D,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAwB;IAC5D,MAAM,IAAI,GAAG,MAAM,mBAAmB,EAAE,CAAC;IACzC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,KAAK,CAAC,6CAA6C,CAAC,CAAC;QACrD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,cAAc,oBAAoB,EAAE;YACvD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,IAAI,CAAC,WAAW,EAAE;gBAC3C,MAAM,EAAE,iBAAiB;aAC1B;YACD,IAAI,EAAE,IAAI;SACX,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,KAAK,CAAC,kBAAmB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAClD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,OAA6B,CAAC;IAClC,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAyB,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,KAAK,CAAC,oCAAoC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;QACzD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAC7B,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,0BAA0B,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;QAChE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;IAExC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,IAAI,CAAC,OAAO,CAAC,CAAC;QACd,OAAO;IACT,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,IAAI,CAAC,yEAAyE,CAAC,CAAC;QAChF,OAAO;IACT,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1D,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,UAAU,SAAS,UAAU,CAAC,CAAC,CAAC,KAAK,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9F,CAAC;AACH,CAAC"}

package/dist/index.js

@@ -2,6 +2,9 @@
 import { Command } from 'commander';
 import { runLogin } from './commands/login.js';
 import { runCreateNode } from './commands/create-node.js';
+import { runListCanvases } from './commands/list-canvases.js';
+import { runCreateCanvas } from './commands/create-canvas.js';
+import { runAgentHelp } from './commands/agent-help.js';
 import { exitWith } from './lib/output.js';
 const program = new Command();
 program
@@ -20,16 +23,43 @@ program
         exitWith(1, err.message);
     }
 });
+program
+    .command('list-canvases')
+    .description('List your Aigma canvases')
+    .option('--json', 'output JSON on stdout')
+    .action(async (opts) => {
+    try {
+        await runListCanvases({ json: !!opts.json });
+    }
+    catch (err) {
+        exitWith(1, err.message);
+    }
+});
+program
+    .command('create-canvas')
+    .description('Create a new empty canvas')
+    .requiredOption('-n, --name <name>', 'canvas name')
+    .option('--json', 'output JSON on stdout')
+    .action(async (opts) => {
+    try {
+        await runCreateCanvas({ name: opts.name, json: !!opts.json });
+    }
+    catch (err) {
+        exitWith(1, err.message);
+    }
+});
 program
     .command('create-node')
     .description('Generate an HTML node from a prompt')
     .requiredOption('-p, --prompt <text>', 'prompt describing the node')
+    .option('-c, --canvas <id-or-name>', 'target canvas (UUID or exact name)')
     .option('-o, --output <file>', 'write generated HTML to a file')
     .option('--json', 'output JSON on stdout')
     .action(async (opts) => {
     try {
         await runCreateNode({
             prompt: opts.prompt,
+            canvas: opts.canvas,
             output: opts.output,
             json: !!opts.json,
         });
@@ -38,5 +68,16 @@ program
         exitWith(1, err.message);
     }
 });
+program
+    .command('agent-help')
+    .description('Print the AI-agent integration guide (AGENTS.md)')
+    .action(async () => {
+    try {
+        await runAgentHelp();
+    }
+    catch (err) {
+        exitWith(1, err.message);
+    }
+});
 program.parseAsync(process.argv).catch((err) => exitWith(1, err.message));
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3C,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,OAAO,CAAC;KACb,WAAW,CAAC,sDAAsD,CAAC;KACnE,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO;KACJ,OAAO,CAAC,OAAO,CAAC;KAChB,WAAW,CAAC,mCAAmC,CAAC;KAChD,MAAM,CAAC,QAAQ,EAAE,uBAAuB,CAAC;KACzC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;IACrB,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,QAAQ,CAAC,CAAC,EAAG,GAAa,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,aAAa,CAAC;KACtB,WAAW,CAAC,qCAAqC,CAAC;KAClD,cAAc,CAAC,qBAAqB,EAAE,4BAA4B,CAAC;KACnE,MAAM,CAAC,qBAAqB,EAAE,gCAAgC,CAAC;KAC/D,MAAM,CAAC,QAAQ,EAAE,uBAAuB,CAAC;KACzC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;IACrB,IAAI,CAAC;QACH,MAAM,aAAa,CAAC;YAClB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI;SAClB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,QAAQ,CAAC,CAAC,EAAG,GAAa,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aigma",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Aigma CLI — generate canvas nodes from your terminal",
   "license": "MIT",
   "homepage": "https://aigma.co",
@@ -42,6 +42,7 @@
     "node": ">=18.17.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "AGENTS.md"
   ]
 }