@tuongaz/seeflow 0.1.57 → 0.1.63

package/src/cli-manifest.ts

@@ -134,7 +134,7 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     synopsis: 'seeflow register [--path <dir>] [--flow <file>]',
     description:
       'Register a demo repo with the studio. Reads <repoPath>/<flow> (defaulting ' +
-      'to ./.seeflow/flow.json), validates the schema, and writes an entry to ' +
+      'to ./flow.json), validates the schema, and writes an entry to ' +
       '~/.seeflow/registry.json. Alias of flows:register.',
     category: 'flows',
     args: [],
@@ -143,12 +143,12 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       {
         name: 'flow',
         valuePlaceholder: '<file>',
-        description: 'Path to flow.json relative to repo root (default: .seeflow/flow.json)',
+        description: 'Path to flow.json relative to repo root (default: flow.json)',
       },
     ],
     outputs: {
-      okExample: { id: 'abc12345', slug: 'checkout', sdk: { outcome: 'skipped', filePath: null } },
-      errorKinds: ['fileNotFound', 'badJson', 'badSchema', 'sdkWriteFailed'],
+      okExample: { id: 'abc12345', slug: 'checkout' },
+      errorKinds: ['fileNotFound', 'badJson', 'badSchema'],
     },
     requiresStudio: false,
     examples: ['seeflow register', 'seeflow register --path ./my-app'],
@@ -164,13 +164,13 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       {
         name: 'flow',
         valuePlaceholder: '<file>',
-        description: 'Path to flow.json relative to repo root (default: .seeflow/flow.json)',
+        description: 'Path to flow.json relative to repo root (default: flow.json)',
       },
     ],
     body: { schemaRef: 'RegisterBody' },
     outputs: {
-      okExample: { id: 'abc12345', slug: 'checkout', sdk: { outcome: 'skipped', filePath: null } },
-      errorKinds: ['fileNotFound', 'badJson', 'badSchema', 'sdkWriteFailed'],
+      okExample: { id: 'abc12345', slug: 'checkout' },
+      errorKinds: ['fileNotFound', 'badJson', 'badSchema'],
     },
     requiresStudio: false,
     examples: ['seeflow flows:register --path ./my-app'],
@@ -303,22 +303,36 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
   // ---- project -----------------------------------------------------------
   {
     name: 'projects:create',
-    synopsis: 'seeflow projects:create --name <name>',
+    synopsis: 'seeflow projects:create --path <dir> --name <name> [--description <text>]',
     description:
-      'Scaffold a new project under ~/.seeflow/<slug>/ with an empty flow.json and ' +
-      'register it. The flow id is returned for follow-up writes.',
+      'Scaffold a new project at <path> with an empty flow.json and register it. ' +
+      'Errors if <path>/flow.json already exists — use flows:register for ' +
+      'an existing project.',
     category: 'project',
     args: [],
     flags: [
+      {
+        name: 'path',
+        valuePlaceholder: '<dir>',
+        description: 'Project folder (created if it does not exist)',
+        required: true,
+      },
       { name: 'name', valuePlaceholder: '<name>', description: 'Project name', required: true },
+      {
+        name: 'description',
+        valuePlaceholder: '<text>',
+        description: 'Optional human description, written into flow.json',
+      },
     ],
     body: { schemaRef: 'CreateProjectBody' },
     outputs: {
-      okExample: { id: 'abc12345', slug: 'checkout', scaffolded: true },
-      errorKinds: ['scaffoldFailed'],
+      okExample: { id: 'abc12345', slug: 'checkout' },
+      errorKinds: ['alreadyExists', 'scaffoldFailed'],
     },
     requiresStudio: false,
-    examples: ['seeflow projects:create --name "Checkout"'],
+    examples: [
+      'seeflow projects:create --path ./checkout --name "Checkout" --description "Cart + payments flow"',
+    ],
   },
   // ---- nodes -------------------------------------------------------------
   {
@@ -331,7 +345,7 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     body: {
       example: {
         type: 'stateNode',
-        data: { name: 'hello', kind: 'state', stateSource: { kind: 'request' } },
+        data: { name: 'hello', stateSource: { kind: 'request' } },
       },
     },
     outputs: {
@@ -514,7 +528,64 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     ],
     outputs: { okExample: { ok: true } },
     requiresStudio: false,
-    examples: ['seeflow validate --file .seeflow/flow.json'],
+    examples: ['seeflow validate --file flow.json'],
+  },
+  {
+    name: 'ids',
+    synopsis: 'seeflow ids <type> <count>',
+    description:
+      'Generate <count> canonical short ids of the given <type>, one per line ' +
+      'on stdout. <type> must be `node` (emits `node-<10 base62 chars>`) or ' +
+      '`connector` (emits `conn-<10 base62 chars>`). <count> must be an ' +
+      'integer in [1, 100]. Uses the same alphabet, length, and rejection-' +
+      'sampling logic as the canvas / server / upload regex, so skill-minted ' +
+      'ids match every other id producer in the studio. Pure compute — no ' +
+      'studio required. Call once per type (i.e. one call for nodes, one for ' +
+      'connectors) when seeding a flow.json.',
+    category: 'meta',
+    args: [
+      {
+        name: 'type',
+        required: true,
+        description: "Id kind to generate: 'node' (→ `node-…`) or 'connector' (→ `conn-…`)",
+      },
+      {
+        name: 'count',
+        required: true,
+        description: 'How many ids to print (integer, 1..100)',
+      },
+    ],
+    flags: [],
+    outputKind: 'text',
+    outputs: {},
+    requiresStudio: false,
+    examples: ['seeflow ids node 10', 'seeflow ids connector 5'],
+  },
+  {
+    name: 'schema',
+    synopsis: 'seeflow schema [<category>]',
+    description:
+      'Introspect the SeeFlow flow.json / style.json schemas at runtime. Call ' +
+      'without arguments to list the five categories (flow, node, connector, ' +
+      'action, style); call with a category name to get its full JSON Schema(s) ' +
+      '(Draft-07) plus a `notes` array of cross-field invariants the schema ' +
+      "can't express. Use this before authoring any flow.json write — never " +
+      'memorise field shapes.',
+    category: 'meta',
+    args: [
+      {
+        name: 'category',
+        required: false,
+        description: 'One of: flow, node, connector, action, style',
+      },
+    ],
+    flags: [],
+    outputs: {
+      okExample: { categories: [{ name: 'flow', description: 'Top-level flow.json envelope.' }] },
+      errorKinds: ['notFound'],
+    },
+    requiresStudio: false,
+    examples: ['seeflow schema', 'seeflow schema node', 'seeflow schema connector'],
   },
   // ---- live --------------------------------------------------------------
   {
@@ -536,6 +607,49 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     requiresStudio: true,
     examples: ['seeflow e2e abc12345'],
   },
+  {
+    name: 'emit',
+    synopsis:
+      'seeflow emit <flowId> <nodeId> <status> [--run-id <id>] [--payload <json>] [--studio-url <url>]',
+    description:
+      'Broadcast a node-status event to the studio (status: running | done | error). ' +
+      'User apps shell out to this command instead of importing an in-repo helper; ' +
+      "the studio re-broadcasts the event on the flow's SSE stream.",
+    category: 'live',
+    args: [
+      { name: 'flowId', required: true, description: 'Flow id or slug' },
+      { name: 'nodeId', required: true, description: 'Node id in the flow' },
+      { name: 'status', required: true, description: 'Status: running | done | error' },
+    ],
+    flags: [
+      {
+        name: 'run-id',
+        valuePlaceholder: '<id>',
+        description: 'Correlate events emitted within a single run',
+      },
+      {
+        name: 'payload',
+        valuePlaceholder: '<json>',
+        description: 'JSON string merged into the event payload',
+      },
+      {
+        name: 'studio-url',
+        valuePlaceholder: '<url>',
+        description: 'Override studio base URL (skips auto-start; targets the URL as-is)',
+      },
+      { name: 'no-start', description: 'Fail if the studio is not already running' },
+    ],
+    outputs: {
+      okExample: { ok: true },
+      errorKinds: [],
+    },
+    requiresStudio: true,
+    examples: [
+      'seeflow emit abc12345 api-charge done',
+      'seeflow emit abc12345 api-charge error --payload \'{"code":402}\'',
+      'seeflow emit abc12345 api-charge running --run-id run-9b3 --studio-url http://localhost:4321',
+    ],
+  },
 ];
 
 function resolveSchemaRef(ref: string): unknown {

package/src/cli.ts

@@ -12,7 +12,7 @@ import {
   NodePatchBodySchema,
   ReorderBodySchema,
 } from './operations.ts';
-import { seeflowHome } from './paths.ts';
+import { PROJECT_FLOW_FILENAME, seeflowHome } from './paths.ts';
 import { defaultProcessSpawner } from './process-spawner.ts';
 import { type Registry, createRegistry } from './registry.ts';
 import {
@@ -28,9 +28,10 @@ import {
 } from './runtime.ts';
 import { FlowSchema } from './schema.ts';
 import { serve } from './server.ts';
+import { MAX_ID_COUNT, generateIds, isIdType } from './short-id.ts';
 import { createStatusRunner } from './status-runner.ts';
 
-const DEFAULT_FLOW_PATH = '.seeflow/flow.json';
+const DEFAULT_FLOW_PATH = PROJECT_FLOW_FILENAME;
 const HEALTH_TIMEOUT_MS = 10_000;
 const HEALTH_POLL_INTERVAL_MS = 150;
 const STOP_TIMEOUT_MS = 5_000;
@@ -157,8 +158,14 @@ if (argv.includes('--version') || argv.includes('-v')) {
   await runConnectorsDelete();
 } else if (sub === 'validate') {
   await runValidate();
+} else if (sub === 'schema') {
+  await runSchema();
+} else if (sub === 'ids') {
+  await runIds();
 } else if (sub === 'e2e') {
   await runE2e();
+} else if (sub === 'emit') {
+  await runEmit();
 } else {
   console.error(`Unknown subcommand: ${sub}`);
   printHelp();
@@ -178,7 +185,7 @@ Commands (work without a running studio):
   stop                 Stop a background studio instance
   register             Register a demo repo, writing to ~/.seeflow/registry.json (alias of flows:register)
   flows:register       Register a demo repo
-  projects:create      Create a new project (--name <name>)
+  projects:create      Create a new project (--path <dir> --name <name> [--description <text>])
   flows:list           List registered flows
   flows:summary        List registered flows (id + name + description only)
   flows:get <id>       Get flow details
@@ -196,9 +203,18 @@ Commands (work without a running studio):
   connectors:patch <id> <connId>  Patch a connector (--json/--file/--stdin)
   connectors:delete <id> <connId> Delete a connector
   validate             Schema-validate a flow.json (--file <file> [--style <file>])
+  schema [<category>]  Get the flow.json schema. No arg → category index;
+                       category arg → full JSON Schema(s) for that category
+  ids <type> <count>   Print <count> short ids of the given <type>, one per
+                       line. <type> is 'node' (-> 'node-...') or 'connector'
+                       (-> 'conn-...'). <count> is 1..100. Call once per type
+                       when seeding a flow.json (e.g. 'ids node 10', then
+                       'ids connector 12').
 
 Commands (require a running studio):
   flows:play <id> <n>  Trigger a play on node <n>
+  emit <id> <n> <st>   Broadcast a status event for node <n> (st: running|done|error)
+                       [--run-id <id>] [--payload <json>] [--studio-url <url>]
   e2e <id>             End-to-end validate a registered flow (--skip-nodes a,b)
 
 Meta:
@@ -223,14 +239,14 @@ Options (start):
 Options (register):
   --path <dir>         Path to repo root (default: current directory)
   --flow <file>        Path to flow JSON, relative to repo root
-                       (default: .seeflow/flow.json)
+                       (default: flow.json)
 
 Examples:
   npx -y @tuongaz/seeflow@latest
   npx -y @tuongaz/seeflow@latest --port 8080
   npx -y @tuongaz/seeflow@latest start --foreground
   npx -y @tuongaz/seeflow@latest register --path ./my-app
-  npx -y @tuongaz/seeflow@latest projects:create --name "Checkout"
+  npx -y @tuongaz/seeflow@latest projects:create --path ./checkout --name "Checkout"
   npx -y @tuongaz/seeflow@latest flows:list
   npx -y @tuongaz/seeflow@latest stop
 `.trim(),
@@ -251,6 +267,7 @@ async function runHelp() {
 }
 
 async function runStart() {
+  mkdirSync(seeflowHome(), { recursive: true });
   const config = readConfig();
   const portArg = flagValue('port');
   // --port wins; otherwise always fall back to the schema default (not the
@@ -316,7 +333,7 @@ async function seedExamples(registry: Registry) {
 
 async function seedExample(registry: Registry, exampleName: string) {
   const destDir = join(seeflowHome(), exampleName);
-  const flowPath = '.seeflow/flow.json';
+  const flowPath = PROJECT_FLOW_FILENAME;
 
   // Always sync from source so that schema changes and example updates are
   // reflected on every startup, even when the dest directory already exists.
@@ -410,6 +427,25 @@ function reportDaemonFailure(logPath: string | undefined) {
   console.error(tail || '(log is empty — daemon exited before writing anything)');
 }
 
+async function runIds() {
+  const typeArg = argv[1];
+  if (!typeArg || typeArg.startsWith('--')) {
+    printError("Missing required positional argument: type (expected 'node' or 'connector')");
+  }
+  if (!isIdType(typeArg)) {
+    printError(`Invalid type: ${typeArg} (expected 'node' or 'connector')`);
+  }
+  const rawCount = argv[2];
+  if (!rawCount || rawCount.startsWith('--')) {
+    printError(`Missing required positional argument: count (integer 1..${MAX_ID_COUNT})`);
+  }
+  const count = Number.parseInt(rawCount as string, 10);
+  if (!Number.isFinite(count) || count < 1 || count > MAX_ID_COUNT) {
+    printError(`Invalid count: ${rawCount} (expected an integer in [1, ${MAX_ID_COUNT}])`);
+  }
+  for (const id of generateIds(typeArg, count)) process.stdout.write(`${id}\n`);
+}
+
 async function printVersion() {
   const pkgPath = join(import.meta.dir, '../package.json');
   const pkg = (await Bun.file(pkgPath).json()) as { version?: string };
@@ -524,12 +560,6 @@ async function runRegister() {
   } else {
     console.log(`Registered "${parsed.data.name}" (slug: ${body.slug})`);
   }
-
-  if (body.sdk?.outcome === 'written') {
-    console.log(`Wrote ${body.sdk.filePath} (event-bound state node detected)`);
-  } else if (body.sdk?.outcome === 'present') {
-    console.log(`SDK helper already present at ${body.sdk.filePath} (skipped)`);
-  }
 }
 
 async function ensureStudioRunning(url: string, port: number, noStart: boolean) {
@@ -581,10 +611,18 @@ async function waitForHealth(url: string, timeoutMs: number): Promise<boolean> {
 // ---- HTTP-passthrough subcommands ----------------------------------------
 
 async function runProjectsCreate() {
+  const rawPath = flagValue('path');
+  if (!rawPath) printError('Missing required flag: --path');
   const name = flagValue('name');
   if (!name) printError('Missing required flag: --name');
+  const description = flagValue('description');
+
   const ops = createCliOperations();
-  const result = await ops.createProject({ name: name as string });
+  const result = await ops.createProject({
+    path: resolve(rawPath as string),
+    name: name as string,
+    ...(description !== undefined ? { description } : {}),
+  });
   printOutcome(result);
 }
 
@@ -646,6 +684,45 @@ async function runFlowsPlay() {
   printOk(out);
 }
 
+async function runEmit() {
+  const flowId = requireArg(1, '<flowId>');
+  const nodeId = requireArg(2, '<nodeId>');
+  const status = requireArg(3, '<status>');
+  if (status !== 'running' && status !== 'done' && status !== 'error') {
+    printError(`Invalid status: ${status} (expected running | done | error)`);
+  }
+
+  const runId = flagValue('run-id');
+  const rawPayload = flagValue('payload');
+  let payload: unknown;
+  if (rawPayload !== undefined) {
+    try {
+      payload = JSON.parse(rawPayload);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      printError(`--payload must be valid JSON: ${message}`);
+    }
+  }
+
+  // Explicit --studio-url targets a specific instance; skip auto-start since
+  // the caller is asserting where the studio lives.
+  const studioUrlFlag = flagValue('studio-url');
+  let url: string;
+  if (studioUrlFlag) {
+    url = studioUrlFlag.replace(/\/+$/, '');
+  } else {
+    ({ url } = await studioUrlOrDie(hasFlag('no-start')));
+  }
+
+  const body: Record<string, unknown> = { flowId, nodeId, status };
+  if (runId !== undefined) body.runId = runId;
+  if (payload !== undefined) body.payload = payload;
+
+  const res = await postJson(`${url}/api/emit`, body);
+  const out = (await handleResponse(res)) as object;
+  printOk(out);
+}
+
 async function runNodesAdd() {
   const flowId = requireArg(1, '<flowId>');
   const body = await bodyFromFlags();
@@ -800,6 +877,22 @@ async function runValidate() {
   printOk(body);
 }
 
+async function runSchema() {
+  const category = argv[1] && !argv[1].startsWith('--') ? argv[1] : undefined;
+  const { listSchemaCategories, getSchemaCategory } = await import('./schema-catalog.ts');
+  if (!category) {
+    printOk({ categories: listSchemaCategories() });
+  }
+  const payload = getSchemaCategory(category as string);
+  if (!payload) {
+    const available = listSchemaCategories().map((c) => c.name);
+    const message = `unknown schema category: ${category}`;
+    process.stderr.write(`${JSON.stringify({ error: message, code: 'notFound', available })}\n`);
+    process.exit(3);
+  }
+  printOk({ name: category, schemas: payload.schemas, notes: payload.notes });
+}
+
 async function runE2e() {
   const flowId = requireArg(1, '<flowId>');
   const skipNodesRaw = flagValue('skip-nodes');

package/src/diagram.ts

@@ -225,7 +225,6 @@ const normalizeConnectors = (
     const key = [
       source,
       target,
-      String(raw.kind ?? ''),
       String(raw.sourceHandle ?? ''),
       String(raw.targetHandle ?? ''),
     ].join('\t');

package/src/file-ref.ts

@@ -19,24 +19,25 @@ const looksLikeFlowNode = (obj: Record<string, unknown>): obj is { id: string; d
 
 /**
  * Resolve every `file://<relative-path>` string in `raw` by reading the file
- * under `<seeflowRoot>/nodes/<nodeId>/` (node-relative) and substituting its
+ * under `<projectRoot>/nodes/<nodeId>/` (node-relative) and substituting its
  * UTF-8 content. Strings outside any enclosing flow node are treated as
  * invalid — every supported file:// ref currently lives inside `node.data`.
  *
- * Returns the mutated tree plus the sorted, de-duplicated list of seeflow-root-relative
- * paths that resolved cleanly (the watcher tracks these for live reload, so the
- * external contract uses `nodes/<id>/<file>` even though the source string is short).
+ * Returns the mutated tree plus the sorted, de-duplicated list of project-
+ * root-relative paths that resolved cleanly (the watcher tracks these for
+ * live reload, so the external contract uses `nodes/<id>/<file>` even though
+ * the source string is short).
  */
 export function resolveFileRefs(
   raw: unknown,
-  seeflowRoot: string,
+  projectRoot: string,
 ): { resolved: unknown; refs: string[] } {
   const refs = new Set<string>();
-  let seeflowRealRoot: string;
+  let projectRealRoot: string;
   try {
-    seeflowRealRoot = existsSync(seeflowRoot) ? realpathSync(seeflowRoot) : seeflowRoot;
+    projectRealRoot = existsSync(projectRoot) ? realpathSync(projectRoot) : projectRoot;
   } catch {
-    seeflowRealRoot = seeflowRoot;
+    projectRealRoot = projectRoot;
   }
 
   const resolveString = (s: string, nodeId: string | null): string => {
@@ -45,26 +46,26 @@ export function resolveFileRefs(
     if (!isCleanRelativePath(relPath)) return invalidMarker(relPath);
     if (nodeId === null) return invalidMarker(relPath);
 
-    const seeflowRelPath = `nodes/${nodeId}/${relPath}`;
-    const abs = join(seeflowRoot, seeflowRelPath);
-    if (!existsSync(abs)) return missingMarker(seeflowRelPath);
+    const projectRelPath = `nodes/${nodeId}/${relPath}`;
+    const abs = join(projectRoot, projectRelPath);
+    if (!existsSync(abs)) return missingMarker(projectRelPath);
 
     // Symlink-escape defense: resolve realpath and confirm it stays inside root.
     let realAbs: string;
     try {
       realAbs = realpathSync(abs);
     } catch {
-      return missingMarker(seeflowRelPath);
+      return missingMarker(projectRelPath);
     }
-    const rel = relative(seeflowRealRoot, realAbs);
+    const rel = relative(projectRealRoot, realAbs);
     if (rel.startsWith('..') || isAbsolute(rel)) return invalidMarker(relPath);
 
     try {
       const content = readFileSync(realAbs, 'utf8');
-      refs.add(seeflowRelPath);
+      refs.add(projectRelPath);
       return content;
     } catch {
-      return missingMarker(seeflowRelPath);
+      return missingMarker(projectRelPath);
     }
   };
 

package/src/mcp.ts

@@ -20,13 +20,13 @@ import {
   flowBulkNonEmpty,
 } from './operations.ts';
 import type { Registry } from './registry.ts';
+import { getSchemaCategory, listSchemaCategories, schemaCategoryNames } from './schema-catalog.ts';
+import { ID_TYPES, MAX_ID_COUNT, generateIds, isIdType } from './short-id.ts';
 import type { FlowWatcher } from './watcher.ts';
 
 export interface CreateMcpServerOptions {
   registry: Registry;
   watcher?: FlowWatcher;
-  /** Override base directory for new projects. Defaults to ~/.seeflow. Tests inject a tmp dir. */
-  projectBaseDir?: string;
 }
 
 // Tools are pushed into this in-memory list inside `createMcpServer`. Each
@@ -193,6 +193,94 @@ const buildTools = (ops: Operations): McpTool[] => [
       return okResult(result.data);
     },
   },
+  {
+    name: 'seeflow_schema',
+    description:
+      'Get the SeeFlow flow.json schema. Call with no args for a category index; ' +
+      "call with `name` for one category's full JSON Schemas. Use this to learn " +
+      'what a node, connector, action, or flow envelope looks like before authoring ' +
+      'writes. Categories: `flow`, `node`, `connector`, `action`, `style`.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Optional category name. Omit for the index.',
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: async (args) => {
+      const name =
+        args && typeof args === 'object' && !Array.isArray(args)
+          ? (args as { name?: unknown }).name
+          : undefined;
+      if (name === undefined || name === null || name === '') {
+        return okResult({ categories: listSchemaCategories() });
+      }
+      if (typeof name !== 'string') {
+        return errorResult('Invalid arguments: `name` must be a string when present');
+      }
+      const payload = getSchemaCategory(name);
+      if (!payload) {
+        return errorResult(
+          `unknown schema category: ${name} (available: ${schemaCategoryNames().join(', ')})`,
+        );
+      }
+      return okResult({ name, schemas: payload.schemas, notes: payload.notes });
+    },
+  },
+  {
+    name: 'seeflow_ids',
+    description:
+      'Batch-mint canonical short ids. `type` is `node` (emits `node-<10 base62 chars>`) ' +
+      'or `connector` (emits `conn-<10 base62 chars>`); `count` is an integer in ' +
+      '[1, 100]. Pure compute — no flow side effects, no studio state read. Use ' +
+      'before authoring a flow.json so minted ids match every other id producer ' +
+      'in the studio (canvas, server, upload regex). Call once per type when ' +
+      'seeding a flow (one call for nodes, one for connectors).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type: {
+          type: 'string',
+          enum: [...ID_TYPES],
+          description: "Id kind: 'node' (→ `node-…`) or 'connector' (→ `conn-…`)",
+        },
+        count: {
+          type: 'integer',
+          minimum: 1,
+          maximum: MAX_ID_COUNT,
+          description: `How many ids to mint (1..${MAX_ID_COUNT})`,
+        },
+      },
+      required: ['type', 'count'],
+      additionalProperties: false,
+    },
+    handler: async (args) => {
+      const body =
+        args && typeof args === 'object' && !Array.isArray(args)
+          ? (args as { type?: unknown; count?: unknown })
+          : {};
+      const { type, count } = body;
+      if (!isIdType(type)) {
+        return errorResult(
+          `invalid type: ${String(type)} (expected one of: ${ID_TYPES.join(', ')})`,
+        );
+      }
+      if (
+        typeof count !== 'number' ||
+        !Number.isInteger(count) ||
+        count < 1 ||
+        count > MAX_ID_COUNT
+      ) {
+        return errorResult(
+          `invalid count: ${String(count)} (expected an integer in [1, ${MAX_ID_COUNT}])`,
+        );
+      }
+      return okResult({ ids: generateIds(type, count) });
+    },
+  },
   {
     name: 'validate_seeflow',
     description:
@@ -330,8 +418,6 @@ const buildTools = (ops: Operations): McpTool[] => [
           return errorResult(
             `Flow file failed schema validation: ${JSON.stringify(result.issues)}`,
           );
-        case 'sdkWriteFailed':
-          return errorResult(`Failed to write SDK helper: ${result.message}`);
       }
     },
   },
@@ -353,7 +439,8 @@ const buildTools = (ops: Operations): McpTool[] => [
   },
   {
     name: 'seeflow_create_project',
-    description: 'Create a new SeeFlow project folder, or register an existing one.',
+    description:
+      'Scaffold a new SeeFlow project at the given path. Errors if a project already exists there.',
     inputSchema: inputSchemaFromZod(CreateProjectBodySchema),
     handler: async (args) => {
       const parsed = CreateProjectBodySchema.safeParse(args);
@@ -364,23 +451,17 @@ const buildTools = (ops: Operations): McpTool[] => [
       switch (result.kind) {
         case 'ok':
           return okResult(result.data);
-        case 'badJson':
-          return errorResult(`Existing demo file is not valid JSON: ${result.detail}`);
-        case 'badSchema':
-          return errorResult(
-            `Existing demo file failed schema validation: ${JSON.stringify(result.issues)}`,
-          );
+        case 'alreadyExists':
+          return errorResult(`Project already exists at ${result.path}`);
         case 'scaffoldFailed':
           return errorResult(`Failed to scaffold project: ${result.message}`);
-        case 'sdkWriteFailed':
-          return errorResult(`Failed to write SDK helper: ${result.message}`);
       }
     },
   },
   {
     name: 'seeflow_add_node',
     description:
-      'Append a new node to a flow (cascade-safe; id auto-generated when omitted). Text content fields (detail on every node; html on htmlNode) are auto-externalized to <project>/.seeflow/nodes/<id>/ and stored as file:// refs in flow.json; reads inline the resolved content transparently.',
+      'Append a new node to a flow (cascade-safe; id auto-generated when omitted). Text content fields (detail on every node; html on htmlNode) are auto-externalized to <project>/nodes/<id>/ and stored as file:// refs in flow.json; reads inline the resolved content transparently.',
     inputSchema: inputSchemaFromZod(AddNodeInputSchema),
     handler: async (args) => {
       const parsed = AddNodeInputSchema.safeParse(args);
@@ -504,7 +585,7 @@ const buildTools = (ops: Operations): McpTool[] => [
   {
     name: 'seeflow_patch_node',
     description:
-      'Update fields on an existing node (position, name, description, detail, icon, colors, border, font, shape, dimensions, autoSize, plus iconNode-only color/strokeWidth/alt). Setting detail (every node) or html (htmlNode) writes the content to <project>/.seeflow/nodes/<id>/{detail.md|view.html}; the file:// ref on the node persists. Empty-string detail empties the file but keeps the ref.',
+      'Update fields on an existing node (position, name, description, detail, icon, colors, border, font, shape, dimensions, autoSize, plus iconNode-only color/strokeWidth/alt). Setting detail (every node) or html (htmlNode) writes the content to <project>/nodes/<id>/{detail.md|view.html}; the file:// ref on the node persists. Empty-string detail empties the file but keeps the ref.',
     inputSchema: inputSchemaFromZod(PatchNodeInputSchema),
     handler: async (args) => {
       const parsed = PatchNodeInputSchema.safeParse(args);
@@ -672,7 +753,6 @@ export function createMcpServer(options: CreateMcpServerOptions): Server {
   const ops = createOperations({
     registry: options.registry,
     watcher: options.watcher,
-    projectBaseDir: options.projectBaseDir,
   });
   const tools = buildTools(ops);