@tuongaz/seeflow 0.1.77 → 0.1.81

package/src/api.ts

@@ -1,8 +1,9 @@
-import { existsSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { Hono } from 'hono';
 import { streamSSE } from 'hono/streaming';
 import { z } from 'zod';
+import { registerProject } from './cli-ops.ts';
 import { runComponentAction } from './component-action-runner.ts';
 import {
   AssembleRequestSchema,
@@ -37,10 +38,11 @@ import {
   runReset as defaultRunReset,
   stopAllPlays as defaultStopAllPlays,
 } from './proxy.ts';
-import type { Registry } from './registry.ts';
+import type { FlowEntry, Registry } from './registry.ts';
+import { resolveProjectFlow } from './route-resolve.ts';
 import { getSchemaCategory, listSchemaCategories, schemaCategoryNames } from './schema-catalog.ts';
-import type { ComponentAction } from './schema.ts';
-import { FlowSchema, ResolvedFlowSchema } from './schema.ts';
+import type { ComponentAction, SeeflowManifest } from './schema.ts';
+import { FlowIdPattern, FlowSchema, ResolvedFlowSchema, SeeflowManifestSchema } from './schema.ts';
 import { type Spawner, defaultSpawner } from './shellout.ts';
 import { ID_TYPES, MAX_ID_COUNT, generateIds, isIdType } from './short-id.ts';
 import type { StatusRunner } from './status-runner.ts';
@@ -55,6 +57,37 @@ const EmitBodySchema = z.object({
   payload: z.unknown().optional(),
 });
 
+// Body for POST /api/projects/:project/flows (US-015). The flow id reuses
+// FlowIdPattern from schema.ts — same constraint the seeflow.json manifest
+// enforces, so a manifest round-trip after this route runs cannot fail
+// validation on the new entry's id.
+const CreateFlowBodySchema = z.object({
+  id: z.string().regex(FlowIdPattern, {
+    message: 'flow id must match /^[a-z0-9][a-z0-9-]*$/',
+  }),
+  name: z.string().min(1),
+  icon: z.string().min(1).optional(),
+});
+
+// Body for PATCH /api/projects/:project/flows/:flow (US-016). All three
+// fields are optional; the .refine() rejects an empty body so callers can't
+// no-op the route. The same FlowIdPattern that guards POST guards id renames
+// here, so a renamed flow's id stays manifest-compatible.
+const PatchFlowBodySchema = z
+  .object({
+    id: z
+      .string()
+      .regex(FlowIdPattern, {
+        message: 'flow id must match /^[a-z0-9][a-z0-9-]*$/',
+      })
+      .optional(),
+    name: z.string().min(1).optional(),
+    icon: z.string().min(1).optional(),
+  })
+  .refine((b) => b.id !== undefined || b.name !== undefined || b.icon !== undefined, {
+    message: 'body must include at least one of id, name, icon',
+  });
+
 type RelativePathCheck = { kind: 'ok' } | { kind: 'invalid'; reason: string };
 
 // Reject absolute paths and `..` traversal before any filesystem touch.
@@ -91,12 +124,16 @@ type ResolvedProjectFile =
 // (defense against symlink escapes). Returns the realpath of an existing file
 // on success, or `fileMissing` with the would-be absolute path so callers can
 // soft-fail with that path included for clipboard fallback.
+//
+// Project addressing is by `projectSlug` (post-US-008): the first registry
+// entry whose `projectSlug` matches supplies `repoPath` since every entry in
+// a project shares the same on-disk root.
 function resolveProjectFile(
   registry: Registry,
-  projectId: string,
+  projectSlug: string,
   relPath: string,
 ): ResolvedProjectFile {
-  const entry = registry.getById(projectId);
+  const entry = registry.list().find((e) => e.projectSlug === projectSlug);
   if (!entry) return { kind: 'unknownProject' };
 
   const guard = validateRelativePath(relPath);
@@ -126,6 +163,22 @@ function resolveProjectFile(
   return { kind: 'ok', absPath: realTarget, projectRoot: realRoot };
 }
 
+// Read + validate `<repoPath>/seeflow.json` for the project listing routes.
+// Returns `null` for missing or malformed manifests so callers can fall back
+// to derived defaults (projectSlug + isDefault entry) instead of failing the
+// whole listing on one bad project.
+function readProjectManifest(repoPath: string): SeeflowManifest | null {
+  const manifestPath = join(repoPath, 'seeflow.json');
+  if (!existsSync(manifestPath)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const parsed = SeeflowManifestSchema.safeParse(raw);
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+
 // Allowed extensions for /nodes/:nodeId/files/upload. Lowercased; matched after dropping the
 // leading `.`. Stored as a Set so future expansion (PDF, video) is one-edit.
 const UPLOAD_ALLOWED_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg']);
@@ -222,6 +275,9 @@ export function createApi(options: ApiOptions): Hono {
     }
 
     const result = await ops.registerFlow(parsed.data);
+    if (result.kind === 'ok') {
+      events?.broadcast({ type: 'registry:reload', flowId: '__registry__', payload: {} });
+    }
     switch (result.kind) {
       case 'ok':
         return c.json(result.data);
@@ -234,6 +290,42 @@ export function createApi(options: ApiOptions): Hono {
     }
   });
 
+  // POST /api/projects/register — manifest-driven registration. Reads
+  // <repoPath>/seeflow.json + walks declared flows under flows/<id>/flow.json,
+  // upserting one FlowEntry per declared flow with the manifest's name +
+  // per-flow names (vs. /api/flows/register which is the legacy single-flow
+  // path that uses the same name for both project and flow).
+  api.post('/projects/register', async (c) => {
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+    const parsed = z.object({ repoPath: z.string().min(1) }).safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid register body', issues: parsed.error.issues }, 400);
+    }
+    const result = registerProject({ repoPath: parsed.data.repoPath, registry });
+    if (result.kind === 'ok') {
+      for (const entry of result.entries) watcher?.watch(entry.id);
+      events?.broadcast({ type: 'registry:reload', flowId: '__registry__', payload: {} });
+      return c.json({
+        ok: true as const,
+        projectSlug: result.projectSlug,
+        entries: result.entries.map((e) => ({
+          id: e.id,
+          slug: e.slug,
+          projectSlug: e.projectSlug,
+          flowSlug: e.flowSlug,
+          name: e.name,
+          isDefault: e.isDefault,
+        })),
+      });
+    }
+    return c.json({ ok: false as const, error: result.kind }, 400);
+  });
+
   // POST /api/flows/validate — dry-run validation. The skill's diagram
   // pipeline calls this between assemble and register to decide whether to
   // rewire. Runs the Zod schema, the soft node cap, and the tier playability
@@ -498,8 +590,399 @@ export function createApi(options: ApiOptions): Hono {
     return c.json(result.data);
   });
 
-  api.get('/flows/:id', async (c) => {
-    const result = await ops.getFlow(c.req.param('id'));
+  // GET /api/projects — projects landing index. Groups registry.list() by
+  // projectSlug and reads each project's `seeflow.json` for the human-readable
+  // name + defaultFlow. When the manifest is missing or malformed, falls back
+  // to the projectSlug for name and the flowSlug of the registry's
+  // `isDefault: true` entry for defaultFlow — so a partially-broken project
+  // still surfaces in the picker.
+  api.get('/projects', (c) => {
+    const grouped = new Map<string, FlowEntry[]>();
+    for (const entry of registry.list()) {
+      const existing = grouped.get(entry.projectSlug);
+      if (existing) {
+        existing.push(entry);
+      } else {
+        grouped.set(entry.projectSlug, [entry]);
+      }
+    }
+    const projects: Array<{
+      projectSlug: string;
+      name: string;
+      description?: string;
+      defaultFlow: string;
+      flowCount: number;
+      repoPath: string;
+    }> = [];
+    for (const [projectSlug, entries] of grouped) {
+      const head = entries[0];
+      if (!head) continue;
+      const manifest = readProjectManifest(head.repoPath);
+      const defaultEntry = entries.find((e) => e.isDefault) ?? head;
+      projects.push({
+        projectSlug,
+        name: manifest?.name ?? projectSlug,
+        description: manifest?.description,
+        defaultFlow: manifest?.defaultFlow ?? defaultEntry.flowSlug,
+        flowCount: entries.length,
+        repoPath: head.repoPath,
+      });
+    }
+    return c.json({ projects });
+  });
+
+  // GET /api/projects/:project — per-project metadata + flow entries. 404s
+  // with `project-not-found` when no registry entry shares the slug — same
+  // shape the flow-scoped routes (US-007) use for resolution failures, so
+  // clients have a single error pattern across the projects/* tree. The
+  // manifest read is best-effort (missing/malformed → null) so the route
+  // never depends on disk state for the slug check itself.
+  api.get('/projects/:project', (c) => {
+    const projectSlug = c.req.param('project');
+    const flows = registry.list().filter((e) => e.projectSlug === projectSlug);
+    const head = flows[0];
+    if (!head) {
+      return c.json({ ok: false as const, error: 'project-not-found' as const }, 404);
+    }
+    const manifest = readProjectManifest(head.repoPath);
+    const defaultEntry = flows.find((e) => e.isDefault) ?? head;
+    return c.json({
+      projectSlug,
+      name: manifest?.name ?? projectSlug,
+      description: manifest?.description,
+      defaultFlow: manifest?.defaultFlow ?? defaultEntry.flowSlug,
+      flows,
+    });
+  });
+
+  // GET /api/projects/:project/flows — per-project flow listing. Powers the
+  // canvas page's Figma-style flow switcher popover (US-024). Returns the
+  // narrow shape the picker needs — id, flowSlug, name, icon, isDefault —
+  // rather than the full FlowEntry; clients that need repoPath/flowPath go
+  // through `GET /api/projects/:project` instead. 404s with `project-not-found`
+  // when no registry entry shares the slug (same shape US-007 + the
+  // GET /api/projects/:project route above use for resolution failures).
+  api.get('/projects/:project/flows', (c) => {
+    const projectSlug = c.req.param('project');
+    const entries = registry.list().filter((e) => e.projectSlug === projectSlug);
+    if (entries.length === 0) {
+      return c.json({ ok: false as const, error: 'project-not-found' as const }, 404);
+    }
+    const flows = entries.map((e) => ({
+      id: e.id,
+      flowSlug: e.flowSlug,
+      name: e.name,
+      icon: e.icon,
+      isDefault: e.isDefault,
+    }));
+    return c.json({ flows });
+  });
+
+  // POST /api/projects/:project/flows — create a new flow within an existing
+  // project (US-015). Atomically: write `flows/<id>/flow.json` with an empty
+  // envelope → append the new entry to `seeflow.json` → `registry.upsert()`.
+  // If the manifest write fails after the flow folder is on disk, the folder
+  // is removed so the project state stays consistent with the manifest. New
+  // flows are never the project default — the caller has to use PATCH
+  // /projects/:project/flows/:flow (US-016) to flip defaultFlow.
+  api.post('/projects/:project/flows', async (c) => {
+    const projectSlug = c.req.param('project');
+    const entries = registry.list().filter((e) => e.projectSlug === projectSlug);
+    const head = entries[0];
+    if (!head) {
+      return c.json({ ok: false as const, error: 'project-not-found' as const }, 404);
+    }
+
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+    const parsed = CreateFlowBodySchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid create flow body', issues: parsed.error.issues }, 400);
+    }
+    const { id, name, icon } = parsed.data;
+
+    // Duplicate check: any registered flow in the project or any pre-existing
+    // folder under `flows/<id>/` (covers manual edits that never made it to
+    // the registry) collides. Manifest entry duplication is structurally
+    // impossible if the registry is the source of truth, but the disk check
+    // catches drift.
+    if (entries.some((e) => e.flowSlug === id)) {
+      return c.json({ ok: false as const, error: 'duplicate-flow-id' as const }, 409);
+    }
+
+    const repoPath = head.repoPath;
+    const manifestPath = join(repoPath, 'seeflow.json');
+    const manifest = readProjectManifest(repoPath);
+    if (!manifest) {
+      return c.json(
+        {
+          ok: false as const,
+          error: 'manifest-missing-or-invalid' as const,
+          path: manifestPath,
+        },
+        500,
+      );
+    }
+    if (manifest.flows.some((f) => f.id === id)) {
+      return c.json({ ok: false as const, error: 'duplicate-flow-id' as const }, 409);
+    }
+
+    const flowDir = join(repoPath, 'flows', id);
+    if (existsSync(flowDir)) {
+      return c.json({ ok: false as const, error: 'duplicate-flow-id' as const }, 409);
+    }
+
+    // 1. Create the flow folder + flow.json. Atomic write guarantees no
+    //    half-written file lands; mkdir is recursive in case `flows/` itself
+    //    is missing on a partially-scaffolded project.
+    try {
+      mkdirSync(flowDir, { recursive: true });
+      const envelope = { version: 2 as const, name, nodes: [], connectors: [] };
+      writeFileAtomic(join(flowDir, 'flow.json'), `${JSON.stringify(envelope, null, 2)}\n`);
+    } catch (err) {
+      try {
+        rmSync(flowDir, { recursive: true, force: true });
+      } catch {
+        // best-effort cleanup
+      }
+      return c.json(
+        { ok: false as const, error: 'scaffold-failed' as const, detail: String(err) },
+        500,
+      );
+    }
+
+    // 2. Append the new entry to the manifest. Roll the folder back if the
+    //    write fails so the project never has an orphan `flows/<id>/`.
+    const manifestEntry: { id: string; name: string; icon?: string } = { id, name };
+    if (icon !== undefined) manifestEntry.icon = icon;
+    const updatedManifest = {
+      ...manifest,
+      flows: [...manifest.flows, manifestEntry],
+    };
+    try {
+      writeFileAtomic(manifestPath, `${JSON.stringify(updatedManifest, null, 2)}\n`);
+    } catch (err) {
+      try {
+        rmSync(flowDir, { recursive: true, force: true });
+      } catch {
+        // best-effort cleanup
+      }
+      return c.json(
+        { ok: false as const, error: 'manifest-write-failed' as const, detail: String(err) },
+        500,
+      );
+    }
+
+    // 3. Register the new entry. `flowPath` is project-relative — matches the
+    //    scanner output for manifest-driven projects.
+    const entry = registry.upsert({
+      name,
+      repoPath,
+      flowPath: `flows/${id}/flow.json`,
+      projectSlug,
+      flowSlug: id,
+      isDefault: false,
+      icon,
+      valid: true,
+    });
+    watcher?.watch(entry.id);
+    events?.broadcast({ type: 'registry:reload', flowId: '__registry__', payload: {} });
+
+    return c.json(entry, 201);
+  });
+
+  // PATCH /api/projects/:project/flows/:flow — rename a flow id and/or update
+  // its name / icon (US-016). Two modes:
+  //   1. id change → rename `flows/<oldId>/` to `flows/<newId>/`, rewrite the
+  //      manifest entry (and `defaultFlow` if it pointed at the renamed flow),
+  //      then re-bind the registry entry + watcher under the new flowPath. On
+  //      manifest-write failure, the folder rename is rolled back.
+  //   2. name/icon only → manifest-only edit; the filesystem layout and the
+  //      registry entry id are untouched, only `name` / `icon` are refreshed.
+  // The handler is single-flight in the no-collision sense: it serialises
+  // through the registry + filesystem so two concurrent id renames against
+  // the same project cannot interleave to produce a duplicate folder.
+  api.patch('/projects/:project/flows/:flow', async (c) => {
+    const projectSlug = c.req.param('project');
+    const flowSlug = c.req.param('flow');
+    const resolved = resolveProjectFlow(registry, projectSlug, flowSlug);
+    if (resolved.kind === 'error') {
+      return c.json({ ok: false as const, error: resolved.code }, 404);
+    }
+    const entry = resolved.entry;
+
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+    const parsed = PatchFlowBodySchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid patch flow body', issues: parsed.error.issues }, 400);
+    }
+    const { id: requestedId, name: requestedName, icon: requestedIcon } = parsed.data;
+
+    const repoPath = entry.repoPath;
+    const manifestPath = join(repoPath, 'seeflow.json');
+    const manifest = readProjectManifest(repoPath);
+    if (!manifest) {
+      return c.json(
+        {
+          ok: false as const,
+          error: 'manifest-missing-or-invalid' as const,
+          path: manifestPath,
+        },
+        500,
+      );
+    }
+
+    const manifestEntryIdx = manifest.flows.findIndex((f) => f.id === entry.flowSlug);
+    if (manifestEntryIdx === -1) {
+      // Registry and manifest are out of sync — the entry knows itself by
+      // flowSlug but the manifest disagrees. Bail rather than rebuild the
+      // manifest unilaterally; a future `seeflow reconcile` verb could repair.
+      return c.json({ ok: false as const, error: 'manifest-entry-missing' as const }, 500);
+    }
+    const existingManifestEntry = manifest.flows[manifestEntryIdx];
+    if (!existingManifestEntry) {
+      return c.json({ ok: false as const, error: 'manifest-entry-missing' as const }, 500);
+    }
+
+    const idChanging = requestedId !== undefined && requestedId !== entry.flowSlug;
+
+    // Branch 1: id rename. The folder move is the only side-effect we have to
+    // undo on manifest-write failure, so it goes BEFORE the manifest write.
+    if (idChanging) {
+      const newId = requestedId;
+      if (newId === undefined) {
+        // Narrowing for TS — `idChanging` already implies non-undefined.
+        return c.json({ ok: false as const, error: 'duplicate-flow-id' as const }, 409);
+      }
+
+      // Collision checks: manifest, registry, on-disk folder. Each catches a
+      // different drift; cheapest first.
+      if (manifest.flows.some((f) => f.id === newId)) {
+        return c.json({ ok: false as const, error: 'duplicate-flow-id' as const }, 409);
+      }
+      const projectEntries = registry.list().filter((e) => e.projectSlug === projectSlug);
+      if (projectEntries.some((e) => e.flowSlug === newId)) {
+        return c.json({ ok: false as const, error: 'duplicate-flow-id' as const }, 409);
+      }
+      const oldFolder = join(repoPath, 'flows', entry.flowSlug);
+      const newFolder = join(repoPath, 'flows', newId);
+      if (existsSync(newFolder)) {
+        return c.json({ ok: false as const, error: 'duplicate-flow-id' as const }, 409);
+      }
+
+      // 1. Move the folder.
+      try {
+        renameSync(oldFolder, newFolder);
+      } catch (err) {
+        return c.json(
+          { ok: false as const, error: 'folder-rename-failed' as const, detail: String(err) },
+          500,
+        );
+      }
+
+      // 2. Build + atomically write the updated manifest.
+      const finalName = requestedName ?? existingManifestEntry.name;
+      const finalIcon = requestedIcon !== undefined ? requestedIcon : existingManifestEntry.icon;
+      const updatedFlowEntry: { id: string; name: string; icon?: string } = {
+        id: newId,
+        name: finalName,
+      };
+      if (finalIcon !== undefined) updatedFlowEntry.icon = finalIcon;
+      const updatedManifest: SeeflowManifest = {
+        ...manifest,
+        defaultFlow: manifest.defaultFlow === entry.flowSlug ? newId : manifest.defaultFlow,
+        flows: manifest.flows.map((f, i) => (i === manifestEntryIdx ? updatedFlowEntry : f)),
+      };
+
+      try {
+        writeFileAtomic(manifestPath, `${JSON.stringify(updatedManifest, null, 2)}\n`);
+      } catch (err) {
+        try {
+          renameSync(newFolder, oldFolder);
+        } catch {
+          // best-effort rollback
+        }
+        return c.json(
+          { ok: false as const, error: 'manifest-write-failed' as const, detail: String(err) },
+          500,
+        );
+      }
+
+      // 3. Rebind the registry entry under the new flowPath. The shortId
+      //    changes — registry slugs are addressed via projectSlug/flowSlug, so
+      //    clients re-resolve via the new URL. Watcher is unwatch-then-watch
+      //    because the flowPath that the watcher reads is sourced from the
+      //    new registry entry.
+      watcher?.unwatch(entry.id);
+      registry.remove(entry.id);
+      const newEntry = registry.upsert({
+        name: finalName,
+        description: entry.description,
+        repoPath,
+        flowPath: `flows/${newId}/flow.json`,
+        projectSlug,
+        flowSlug: newId,
+        isDefault: entry.isDefault,
+        icon: finalIcon,
+        valid: entry.valid,
+      });
+      watcher?.watch(newEntry.id);
+      events?.broadcast({ type: 'registry:reload', flowId: '__registry__', payload: {} });
+
+      return c.json(newEntry);
+    }
+
+    // Branch 2: name / icon only. Filesystem layout untouched.
+    const finalName = requestedName ?? existingManifestEntry.name;
+    const finalIcon = requestedIcon !== undefined ? requestedIcon : existingManifestEntry.icon;
+    const updatedFlowEntry: { id: string; name: string; icon?: string } = {
+      id: existingManifestEntry.id,
+      name: finalName,
+    };
+    if (finalIcon !== undefined) updatedFlowEntry.icon = finalIcon;
+    const updatedManifest: SeeflowManifest = {
+      ...manifest,
+      flows: manifest.flows.map((f, i) => (i === manifestEntryIdx ? updatedFlowEntry : f)),
+    };
+
+    try {
+      writeFileAtomic(manifestPath, `${JSON.stringify(updatedManifest, null, 2)}\n`);
+    } catch (err) {
+      return c.json(
+        { ok: false as const, error: 'manifest-write-failed' as const, detail: String(err) },
+        500,
+      );
+    }
+
+    const updatedEntry = registry.upsert({
+      name: finalName,
+      description: entry.description,
+      repoPath,
+      flowPath: entry.flowPath,
+      projectSlug,
+      flowSlug: entry.flowSlug,
+      isDefault: entry.isDefault,
+      icon: finalIcon,
+      valid: entry.valid,
+    });
+    events?.broadcast({ type: 'registry:reload', flowId: '__registry__', payload: {} });
+
+    return c.json(updatedEntry);
+  });
+
+  api.get('/projects/:project/flows/:flow', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const result = await ops.getFlow(resolved.entry.id);
     switch (result.kind) {
       case 'ok':
         return c.json(result.data);
@@ -511,9 +994,11 @@ export function createApi(options: ApiOptions): Hono {
   });
 
   // Flow skeleton without per-node file content (detail.md / view.html).
-  // Pairs with GET /flows/:id/nodes/:nodeId for full per-node detail.
-  api.get('/flows/:id/graph', async (c) => {
-    const result = await ops.getFlowGraph(c.req.param('id'));
+  // Pairs with GET /projects/:project/flows/:flow/nodes/:nodeId for full per-node detail.
+  api.get('/projects/:project/flows/:flow/graph', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const result = await ops.getFlowGraph(resolved.entry.id);
     switch (result.kind) {
       case 'ok':
         return c.json(result.data);
@@ -528,8 +1013,10 @@ export function createApi(options: ApiOptions): Hono {
     }
   });
 
-  api.get('/flows/:id/nodes/:nodeId', async (c) => {
-    const result = await ops.getNode(c.req.param('id'), c.req.param('nodeId'));
+  api.get('/projects/:project/flows/:flow/nodes/:nodeId', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const result = await ops.getNode(resolved.entry.id, c.req.param('nodeId'));
     switch (result.kind) {
       case 'ok':
         return c.json(result.data);
@@ -546,11 +1033,13 @@ export function createApi(options: ApiOptions): Hono {
     }
   });
 
-  // GET /api/projects/:id/files/<path> — stream a project-scoped file from
-  // <repoPath>/<path>. Path safety is layered: textual rejection (absolute /
-  // traversal), then realpath check that the resolved file stays inside the
-  // project root (defends against symlink escapes).
-  api.get('/projects/:id/files/:path{.+}', async (c) => {
+  // GET /api/projects/:project/files/<path> — stream a project-scoped file
+  // from <repoPath>/<path>. Path safety is layered: textual rejection
+  // (absolute / traversal), then realpath check that the resolved file stays
+  // inside the project root (defends against symlink escapes). The route is
+  // shared across every flow within the project — assets that live at the
+  // project root or under a sibling flow folder are addressable here.
+  api.get('/projects/:project/files/:path{.+}', async (c) => {
     const rawPath = c.req.param('path');
     let relPath: string;
     try {
@@ -559,7 +1048,7 @@ export function createApi(options: ApiOptions): Hono {
       return c.json({ error: 'invalid path encoding' }, 400);
     }
 
-    const resolved = resolveProjectFile(registry, c.req.param('id'), relPath);
+    const resolved = resolveProjectFile(registry, c.req.param('project'), relPath);
     switch (resolved.kind) {
       case 'unknownProject':
         return c.json({ error: 'unknown project' }, 404);
@@ -582,12 +1071,12 @@ export function createApi(options: ApiOptions): Hono {
     });
   });
 
-  // POST /api/projects/:id/files/open — shell out to `$EDITOR <abs>` so the
-  // user can edit a project-scoped file (type:'html' block, image asset) in
-  // their IDE. The endpoint always returns the resolved absolute path in
+  // POST /api/projects/:project/files/open — shell out to `$EDITOR <abs>` so
+  // the user can edit a project-scoped file (type:'html' block, image asset)
+  // in their IDE. The endpoint always returns the resolved absolute path in
   // the response body so the frontend can copy-to-clipboard when $EDITOR
   // isn't set or the spawn fails. Path safety mirrors the GET route.
-  api.post('/projects/:id/files/open', async (c) => {
+  api.post('/projects/:project/files/open', async (c) => {
     let body: unknown;
     try {
       body = await c.req.json();
@@ -599,7 +1088,7 @@ export function createApi(options: ApiOptions): Hono {
       return c.json({ error: 'Invalid open body', issues: parsed.error.issues }, 400);
     }
 
-    const resolved = resolveProjectFile(registry, c.req.param('id'), parsed.data.path);
+    const resolved = resolveProjectFile(registry, c.req.param('project'), parsed.data.path);
     switch (resolved.kind) {
       case 'unknownProject':
         return c.json({ error: 'unknown project' }, 404);
@@ -621,12 +1110,12 @@ export function createApi(options: ApiOptions): Hono {
     return c.json({ ok: true, absPath: resolved.absPath });
   });
 
-  // POST /api/projects/:id/files/reveal — open the OS file manager with the
-  // target file selected. Platform commands: `open -R <abs>` (macOS),
+  // POST /api/projects/:project/files/reveal — open the OS file manager with
+  // the target file selected. Platform commands: `open -R <abs>` (macOS),
   // `explorer /select,<abs>` (Windows), `xdg-open <dir>` (Linux — selects the
   // containing directory; xdg has no portable "select-this-file" verb). Same
   // fallback shape as /open: response always includes `absPath` for clipboard.
-  api.post('/projects/:id/files/reveal', async (c) => {
+  api.post('/projects/:project/files/reveal', async (c) => {
     let body: unknown;
     try {
       body = await c.req.json();
@@ -638,7 +1127,7 @@ export function createApi(options: ApiOptions): Hono {
       return c.json({ error: 'Invalid reveal body', issues: parsed.error.issues }, 400);
     }
 
-    const resolved = resolveProjectFile(registry, c.req.param('id'), parsed.data.path);
+    const resolved = resolveProjectFile(registry, c.req.param('project'), parsed.data.path);
     switch (resolved.kind) {
       case 'unknownProject':
         return c.json({ error: 'unknown project' }, 404);
@@ -672,17 +1161,21 @@ export function createApi(options: ApiOptions): Hono {
     return c.json({ ok: true, absPath: resolved.absPath });
   });
 
-  // POST /api/projects/:id/nodes/:nodeId/files/upload — accept a multipart
-  // image upload and persist it under `<project>/nodes/<nodeId>/`. Multipart
-  // shape: `file` (Blob) and optional `filename` (the original OS name).
-  // Allowlist + 5 MB cap guard against arbitrary uploads; the destination
-  // folder is scoped to the node, so delete_node's removeNodeDir cascade
-  // cleans up the asset along with the node row.
-  api.post('/projects/:id/nodes/:nodeId/files/upload', async (c) => {
-    const projectId = c.req.param('id');
+  // POST /api/projects/:project/flows/:flow/nodes/:nodeId/files/upload —
+  // accept a multipart image upload and persist it under
+  // `<repoPath>/<dirname(entry.flowPath)>/nodes/<nodeId>/`. For manifest-
+  // driven projects this resolves to `flows/<flow>/nodes/<nodeId>/`; for
+  // legacy single-flow registrations (flow.json at the project root) it
+  // collapses to `nodes/<nodeId>/`. Multipart shape: `file` (Blob) and
+  // optional `filename` (the original OS name). Allowlist + 5 MB cap guard
+  // against arbitrary uploads; the destination folder is scoped to the node,
+  // so delete_node's removeNodeDir cascade cleans up the asset along with
+  // the node row.
+  api.post('/projects/:project/flows/:flow/nodes/:nodeId/files/upload', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const entry = resolved.entry;
     const nodeId = c.req.param('nodeId');
-    const entry = registry.getById(projectId);
-    if (!entry) return c.json({ error: 'unknown project' }, 404);
 
     // node id shape: `node-<10 base62 chars>` (matches shortId() output).
     if (!/^node-[A-Za-z0-9]{10}$/.test(nodeId)) {
@@ -712,7 +1205,8 @@ export function createApi(options: ApiOptions): Hono {
       return c.json({ error: 'invalid filename or extension' }, 400);
     }
 
-    const nodeDir = join(entry.repoPath, 'nodes', nodeId);
+    const flowDir = dirname(entry.flowPath);
+    const nodeDir = join(entry.repoPath, flowDir, 'nodes', nodeId);
     try {
       mkdirSync(nodeDir, { recursive: true });
     } catch (err) {
@@ -738,25 +1232,149 @@ export function createApi(options: ApiOptions): Hono {
     return c.json({ path: `nodes/${nodeId}/${finalName}` });
   });
 
-  api.delete('/flows/:id', (c) => {
-    const result = ops.deleteFlow(c.req.param('id'));
-    switch (result.kind) {
-      case 'ok':
-        return c.json({ ok: true });
-      case 'notFound':
-        return c.json({ ok: false, error: 'not found' }, 404);
+  // DELETE /api/projects/:project/flows/:flow — manifest-aware delete (US-017).
+  // Guards:
+  //   - last-flow: refuse when the target is the only flow in the project.
+  //   - default-flow-no-replacement: refuse when target is manifest.defaultFlow
+  //     and no `?newDefault=<other-flow-id>` query arg is supplied.
+  //   - invalid-new-default: the supplied newDefault must exist in the
+  //     manifest and must not be the flow being deleted.
+  // On success: rename the flow folder to a sibling `.deleted-*` snapshot
+  // (atomic on POSIX), write the updated manifest atomically, then rm the
+  // snapshot and drop the registry entry. On manifest-write failure the
+  // snapshot is renamed back so the externally-observable state is preserved.
+  api.delete('/projects/:project/flows/:flow', (c) => {
+    const projectSlug = c.req.param('project');
+    const flowSlug = c.req.param('flow');
+    const newDefault = c.req.query('newDefault');
+
+    const resolved = resolveProjectFlow(registry, projectSlug, flowSlug);
+    if (resolved.kind === 'error') {
+      return c.json({ ok: false as const, error: resolved.code }, 404);
+    }
+    const entry = resolved.entry;
+
+    const projectEntries = registry.list().filter((e) => e.projectSlug === projectSlug);
+    if (projectEntries.length <= 1) {
+      return c.json({ ok: false as const, error: 'last-flow' as const }, 409);
+    }
+
+    const repoPath = entry.repoPath;
+    const manifestPath = join(repoPath, 'seeflow.json');
+    const manifest = readProjectManifest(repoPath);
+    if (!manifest) {
+      return c.json(
+        {
+          ok: false as const,
+          error: 'manifest-missing-or-invalid' as const,
+          path: manifestPath,
+        },
+        500,
+      );
+    }
+
+    const targetIsDefault = manifest.defaultFlow === entry.flowSlug;
+    if (targetIsDefault && (newDefault === undefined || newDefault.length === 0)) {
+      return c.json({ ok: false as const, error: 'default-flow-no-replacement' as const }, 409);
+    }
+    if (targetIsDefault && newDefault !== undefined) {
+      if (newDefault === entry.flowSlug) {
+        return c.json({ ok: false as const, error: 'invalid-new-default' as const }, 400);
+      }
+      if (!manifest.flows.some((f) => f.id === newDefault)) {
+        return c.json({ ok: false as const, error: 'invalid-new-default' as const }, 400);
+      }
+    }
+
+    const flowDir = join(repoPath, 'flows', entry.flowSlug);
+    const tmpHolder = join(repoPath, 'flows', `.deleted-${entry.flowSlug}-${Date.now()}`);
+
+    // Snapshot the folder by renaming it to a sibling tmp location. Same
+    // filesystem → POSIX guarantees the rename is atomic. If the folder is
+    // missing on disk (manual `rm -rf` between registration and delete), skip
+    // the snapshot — the manifest+registry mutation still proceeds.
+    let movedToTmp = false;
+    if (existsSync(flowDir)) {
+      try {
+        renameSync(flowDir, tmpHolder);
+        movedToTmp = true;
+      } catch (err) {
+        return c.json(
+          { ok: false as const, error: 'folder-rename-failed' as const, detail: String(err) },
+          500,
+        );
+      }
     }
+
+    const updatedManifest: SeeflowManifest = {
+      ...manifest,
+      defaultFlow: targetIsDefault ? (newDefault as string) : manifest.defaultFlow,
+      flows: manifest.flows.filter((f) => f.id !== entry.flowSlug),
+    };
+
+    try {
+      writeFileAtomic(manifestPath, `${JSON.stringify(updatedManifest, null, 2)}\n`);
+    } catch (err) {
+      if (movedToTmp) {
+        try {
+          renameSync(tmpHolder, flowDir);
+        } catch {
+          // best-effort restore — caller surfaces the original write error
+        }
+      }
+      return c.json(
+        { ok: false as const, error: 'manifest-write-failed' as const, detail: String(err) },
+        500,
+      );
+    }
+
+    // Manifest committed — drop the snapshot.
+    if (movedToTmp) {
+      try {
+        rmSync(tmpHolder, { recursive: true, force: true });
+      } catch {
+        // best-effort cleanup — manifest is the source of truth now
+      }
+    }
+
+    // Promote the new default in the registry (the upsert finds the existing
+    // entry by repoPath + flowPath and updates in place, preserving its id).
+    if (targetIsDefault && newDefault !== undefined) {
+      const promoted = projectEntries.find((e) => e.flowSlug === newDefault);
+      if (promoted) {
+        registry.upsert({
+          name: promoted.name,
+          description: promoted.description,
+          repoPath: promoted.repoPath,
+          flowPath: promoted.flowPath,
+          projectSlug: promoted.projectSlug,
+          flowSlug: promoted.flowSlug,
+          isDefault: true,
+          icon: promoted.icon,
+          valid: promoted.valid,
+        });
+      }
+    }
+
+    watcher?.unwatch(entry.id);
+    registry.remove(entry.id);
+    events?.broadcast({ type: 'registry:reload', flowId: '__registry__', payload: {} });
+
+    return c.json({ ok: true });
   });
 
-  // POST /api/flows/:id/layout — registered-flow ELK layout. Reads flow.json
-  // from disk via the registry entry, computes layout, writes style.json
-  // atomically next to flow.json, and broadcasts flow:reload so any open
-  // canvas refreshes. Body is empty or `{ options? }`. Response on success is
-  // just `{ ok: true }` — the layout is already on disk. On schema failure
-  // returns `{ ok: false, issues }` mirroring /api/validate; on missing flow
-  // file / unknown id / bad JSON / write failure returns HTTP 4xx/5xx.
-  api.post('/flows/:id/layout', async (c) => {
-    const id = c.req.param('id');
+  // POST /api/projects/:project/flows/:flow/layout — registered-flow ELK
+  // layout. Reads flow.json from disk via the registry entry, computes
+  // layout, writes style.json atomically next to flow.json, and broadcasts
+  // flow:reload so any open canvas refreshes. Body is empty or `{ options? }`.
+  // Response on success is just `{ ok: true }` — the layout is already on
+  // disk. On schema failure returns `{ ok: false, issues }` mirroring
+  // /api/validate; on missing flow file / bad JSON / write failure returns
+  // HTTP 4xx/5xx.
+  api.post('/projects/:project/flows/:flow/layout', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const id = resolved.entry.id;
 
     // Empty body is valid — the skill always uses defaults. Only parse if the
     // caller actually sent something.
@@ -794,11 +1412,12 @@ export function createApi(options: ApiOptions): Hono {
     }
   });
 
-  api.post('/flows/:id/play/:nodeId', async (c) => {
-    const id = c.req.param('id');
+  api.post('/projects/:project/flows/:flow/play/:nodeId', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const entry = resolved.entry;
+    const id = entry.id;
     const nodeId = c.req.param('nodeId');
-    const entry = registry.getById(id);
-    if (!entry) return c.json({ error: 'unknown demo' }, 404);
     if (!events) return c.json({ error: 'events not enabled' }, 500);
 
     // Always re-read from disk so the user's most recent edit (validated or
@@ -852,20 +1471,22 @@ export function createApi(options: ApiOptions): Hono {
     return c.json(result);
   });
 
-  // POST /api/flows/:id/nodes/:nodeId/actions/:name — dispatch a component
-  // node's named action over HTTP. Only `script`-kind actions cross this seam;
-  // `set`-kind actions mutate canvas state locally and never round-trip
-  // through the API (the runner rejects them with statusHint 400).
-  // Payload is the JSON request body (defaults to {} on parse failure) and is
-  // piped to the script's stdin by `runComponentAction`. Response is the
-  // script's parsed JSON stdout on success.
-  api.post('/flows/:id/nodes/:nodeId/actions/:name', async (c) => {
-    const id = c.req.param('id');
+  // POST /api/projects/:project/flows/:flow/nodes/:nodeId/actions/:name —
+  // dispatch a component node's named action over HTTP. Only `script`-kind
+  // actions cross this seam; `set`-kind actions mutate canvas state locally
+  // and never round-trip through the API (the runner rejects them with
+  // statusHint 400). Payload is the JSON request body (defaults to {} on
+  // parse failure) and is piped to the script's stdin by
+  // `runComponentAction`. Response is the script's parsed JSON stdout on
+  // success.
+  api.post('/projects/:project/flows/:flow/nodes/:nodeId/actions/:name', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const entry = resolved.entry;
+    const id = entry.id;
     const nodeId = c.req.param('nodeId');
     const actionName = c.req.param('name');
 
-    const entry = registry.getById(id);
-    if (!entry) return c.json({ error: 'unknown demo' }, 404);
     if (!events) return c.json({ error: 'events not enabled' }, 500);
 
     const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
@@ -888,11 +1509,15 @@ export function createApi(options: ApiOptions): Hono {
     if (!action) return c.json({ error: `Unknown action: ${actionName}` }, 404);
 
     const payload = await c.req.json().catch(() => ({}));
+    // US-031: per-node sidecar scripts now anchor at
+    // `<repoPath>/<dirname(flowPath)>/nodes/<id>/` post-multi-flow migration —
+    // the runner still resolves scripts as `<cwd>/nodes/<nodeId>/<scriptPath>`,
+    // so feed the per-flow folder as `cwd`.
     const result = await runComponentAction({
       events,
       flowId: id,
       nodeId,
-      cwd: entry.repoPath,
+      cwd: join(entry.repoPath, dirname(entry.flowPath)),
       actionName,
       action,
       payload,
@@ -904,7 +1529,8 @@ export function createApi(options: ApiOptions): Hono {
     return c.json(result.body);
   });
 
-  // POST /api/flows/:id/reset — the "Restart demo" workflow (US-008). Order:
+  // POST /api/projects/:project/flows/:flow/reset — the "Restart demo"
+  // workflow (US-008). Order:
   //   1. Stop every live play-script + every long-running status-script for
   //      this demo in parallel — both must complete before any reset script
   //      spawns so the script sees no stragglers.
@@ -914,10 +1540,11 @@ export function createApi(options: ApiOptions): Hono {
   //   4. Fire-and-forget `statusRunner.restart` so the next status batch is
   //      spawning by the time the response lands. Individual spawn failures
   //      surface via console.warn but never fail the /reset call.
-  api.post('/flows/:id/reset', async (c) => {
-    const id = c.req.param('id');
-    const entry = registry.getById(id);
-    if (!entry) return c.json({ error: 'unknown demo' }, 404);
+  api.post('/projects/:project/flows/:flow/reset', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const entry = resolved.entry;
+    const id = entry.id;
     if (!events) return c.json({ error: 'events not enabled' }, 500);
 
     const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
@@ -981,8 +1608,10 @@ export function createApi(options: ApiOptions): Hono {
   // PATCH a single node's position back into the on-disk flow.json. Atomic
   // write via tempfile + rename keeps editor diffs clean and avoids
   // corruption mid-write.
-  api.patch('/flows/:id/nodes/:nodeId/position', async (c) => {
-    const id = c.req.param('id');
+  api.patch('/projects/:project/flows/:flow/nodes/:nodeId/position', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const id = resolved.entry.id;
     const nodeId = c.req.param('nodeId');
 
     let body: unknown;
@@ -1022,8 +1651,10 @@ export function createApi(options: ApiOptions): Hono {
   // toBack (remove + push/unshift), and toIndex (pin to an absolute index)
   // which the undo path uses to faithfully revert forward/backward gestures
   // even if the array changed between the original op and the undo.
-  api.patch('/flows/:id/nodes/:nodeId/order', async (c) => {
-    const id = c.req.param('id');
+  api.patch('/projects/:project/flows/:flow/nodes/:nodeId/order', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const id = resolved.entry.id;
     const nodeId = c.req.param('nodeId');
 
     let body: unknown;
@@ -1063,8 +1694,10 @@ export function createApi(options: ApiOptions): Hono {
   // doesn't yet recognize survive round-trips) and the WHOLE resulting demo
   // is re-validated through ResolvedFlowSchema before commit, preventing partial
   // writes from breaking invariants like the connector→node superRefine.
-  api.patch('/flows/:id/nodes/:nodeId', async (c) => {
-    const id = c.req.param('id');
+  api.patch('/projects/:project/flows/:flow/nodes/:nodeId', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const id = resolved.entry.id;
     const nodeId = c.req.param('nodeId');
 
     let body: unknown;
@@ -1100,8 +1733,10 @@ export function createApi(options: ApiOptions): Hono {
   // POST a new node into the demo. Body is the node payload (id auto-generated
   // server-side if absent). Atomicity + final-ResolvedFlowSchema validation match the
   // PATCH path above, so a malformed node never produces a half-written file.
-  api.post('/flows/:id/nodes', async (c) => {
-    const id = c.req.param('id');
+  api.post('/projects/:project/flows/:flow/nodes', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const id = resolved.entry.id;
 
     let body: unknown;
     try {
@@ -1137,8 +1772,10 @@ export function createApi(options: ApiOptions): Hono {
   // nodes added in the same call; the parse sees the merged graph as a whole.
   // Intended for skill/LLM seeding where multiple singular calls would burn
   // tokens and round-trip latency.
-  api.post('/flows/:id/bulk', async (c) => {
-    const id = c.req.param('id');
+  api.post('/projects/:project/flows/:flow/bulk', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const id = resolved.entry.id;
 
     let body: unknown;
     try {
@@ -1186,8 +1823,10 @@ export function createApi(options: ApiOptions): Hono {
   // is still run after the mutation — connector cascade closure means it
   // should always pass, but the check makes the failure mode honest if the
   // file had a pre-existing schema violation we'd otherwise paper over.
-  api.delete('/flows/:id/nodes/:nodeId', async (c) => {
-    const id = c.req.param('id');
+  api.delete('/projects/:project/flows/:flow/nodes/:nodeId', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const id = resolved.entry.id;
     const nodeId = c.req.param('nodeId');
 
     const result = await ops.deleteNode(id, nodeId);
@@ -1216,8 +1855,10 @@ export function createApi(options: ApiOptions): Hono {
   // union catches missing-required-fields (e.g. kind='event' without
   // eventName) and the superRefine still gates source/target referential
   // integrity.
-  api.patch('/flows/:id/connectors/:connId', async (c) => {
-    const id = c.req.param('id');
+  api.patch('/projects/:project/flows/:flow/connectors/:connId', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const id = resolved.entry.id;
     const connId = c.req.param('connId');
 
     let body: unknown;
@@ -1254,8 +1895,10 @@ export function createApi(options: ApiOptions): Hono {
   // server-side if absent and `kind` defaults to 'default' (the no-semantics
   // user-drawn variant). Source/target referential integrity is enforced by
   // ResolvedFlowSchema's superRefine on the post-mutation parse.
-  api.post('/flows/:id/connectors', async (c) => {
-    const id = c.req.param('id');
+  api.post('/projects/:project/flows/:flow/connectors', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const id = resolved.entry.id;
 
     let body: unknown;
     try {
@@ -1286,8 +1929,10 @@ export function createApi(options: ApiOptions): Hono {
 
   // DELETE a connector. Just removes the entry from demo.connectors — node
   // deletion is what cascades, not connector deletion.
-  api.delete('/flows/:id/connectors/:connId', async (c) => {
-    const id = c.req.param('id');
+  api.delete('/projects/:project/flows/:flow/connectors/:connId', async (c) => {
+    const resolved = resolveProjectFlow(registry, c.req.param('project'), c.req.param('flow'));
+    if (resolved.kind === 'error') return c.json({ ok: false, error: resolved.code }, 404);
+    const id = resolved.entry.id;
     const connId = c.req.param('connId');
 
     const result = await ops.deleteConnector(id, connId);