@tuongaz/seeflow 0.1.82 → 0.1.84

package/src/cli-manifest.ts

@@ -133,9 +133,10 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     name: 'register',
     synopsis: 'seeflow register [--path <dir>] [--flow <file>]',
     description:
-      'Register a demo repo with the studio. Reads <repoPath>/<flow> (defaulting ' +
-      'to ./flow.json), validates the schema, and writes an entry to ' +
-      '~/.seeflow/registry.json. Alias of flows:register.',
+      'Register a demo repo with the studio. Manifest-aware: when <repoPath>/seeflow.json ' +
+      'exists, scans every declared flow under flows/<id>/flow.json and upserts one entry ' +
+      'per flow. Otherwise reads <repoPath>/<flow> (defaulting to ./flow.json) as a ' +
+      'single-flow project. Writes to ~/.seeflow/registry.json. Alias of flows:register.',
     category: 'flows',
     args: [],
     flags: [
@@ -143,20 +144,25 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       {
         name: 'flow',
         valuePlaceholder: '<file>',
-        description: 'Path to flow.json relative to repo root (default: flow.json)',
+        description:
+          'Path to flow.json relative to repo root (default: flow.json). Ignored when seeflow.json exists.',
       },
     ],
     outputs: {
       okExample: { id: 'abc12345', slug: 'checkout' },
-      errorKinds: ['fileNotFound', 'badJson', 'badSchema'],
+      errorKinds: ['fileNotFound', 'badJson', 'badSchema', 'manifestInvalid'],
     },
     requiresStudio: false,
-    examples: ['seeflow register', 'seeflow register --path ./my-app'],
+    examples: [
+      'seeflow register',
+      'seeflow register --path ./my-app',
+      'seeflow register --path ./checkout  # manifest-aware re-scan',
+    ],
   },
   {
     name: 'flows:register',
     synopsis: 'seeflow flows:register [--path <dir>] [--flow <file>]',
-    description: 'Register a demo repo. Identical behaviour to `register`.',
+    description: 'Register a demo repo. Identical behaviour to `register` (manifest-aware).',
     category: 'flows',
     args: [],
     flags: [
@@ -164,27 +170,40 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       {
         name: 'flow',
         valuePlaceholder: '<file>',
-        description: 'Path to flow.json relative to repo root (default: flow.json)',
+        description:
+          'Path to flow.json relative to repo root (default: flow.json). Ignored when seeflow.json exists.',
       },
     ],
     body: { schemaRef: 'RegisterBody' },
     outputs: {
       okExample: { id: 'abc12345', slug: 'checkout' },
-      errorKinds: ['fileNotFound', 'badJson', 'badSchema'],
+      errorKinds: ['fileNotFound', 'badJson', 'badSchema', 'manifestInvalid'],
     },
     requiresStudio: false,
     examples: ['seeflow flows:register --path ./my-app'],
   },
   {
     name: 'flows:list',
-    synopsis: 'seeflow flows:list',
-    description: 'List every registered flow with id, slug, name, repoPath, and valid flag.',
+    synopsis: 'seeflow flows:list [--project <p>]',
+    description:
+      'List every registered flow with id, slug, name, repoPath, and valid flag. With ' +
+      '--project <p>, filters to one project and returns { projectSlug, flows: [{ flowSlug, ' +
+      'name, icon?, isDefault, valid }] }.',
     category: 'flows',
     args: [],
-    flags: [],
-    outputs: { okExample: { flows: [{ id: 'abc12345', slug: 'checkout', name: 'Checkout' }] } },
+    flags: [
+      {
+        name: 'project',
+        valuePlaceholder: '<p>',
+        description: 'Project slug — filters output to flows under this project',
+      },
+    ],
+    outputs: {
+      okExample: { flows: [{ id: 'abc12345', slug: 'checkout', name: 'Checkout' }] },
+      errorKinds: ['projectNotFound'],
+    },
     requiresStudio: false,
-    examples: ['seeflow flows:list'],
+    examples: ['seeflow flows:list', 'seeflow flows:list --project order-pipeline'],
   },
   {
     name: 'flows:summary',
@@ -488,6 +507,33 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       'seeflow projects:create --path ./checkout --name "Checkout" --description "Cart + payments flow"',
     ],
   },
+  {
+    name: 'projects:list',
+    synopsis: 'seeflow projects:list',
+    description:
+      'List every registered project: groups the registry by projectSlug and reads each ' +
+      'seeflow.json for the human-readable name + defaultFlow. Falls back to the ' +
+      "projectSlug and the registry's isDefault entry when a manifest is missing or " +
+      'malformed, so a partially-broken project still surfaces.',
+    category: 'project',
+    args: [],
+    flags: [],
+    outputs: {
+      okExample: {
+        projects: [
+          {
+            projectSlug: 'checkout',
+            name: 'Checkout',
+            defaultFlow: 'main',
+            flowCount: 2,
+            repoPath: '/abs/path/to/.seeflow/checkout',
+          },
+        ],
+      },
+    },
+    requiresStudio: false,
+    examples: ['seeflow projects:list'],
+  },
   // ---- nodes -------------------------------------------------------------
   {
     name: 'nodes:add',
@@ -823,7 +869,7 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
   },
   {
     name: 'schema',
-    synopsis: 'seeflow schema [<category>] [--jq <filter>]',
+    synopsis: 'seeflow schema [<category> [<subname>]] [--jq <filter>]',
     description:
       'Introspect the SeeFlow flow.json / style.json / spec.json schemas at ' +
       'runtime. Call without arguments to list the six categories (flow, node, ' +
@@ -831,9 +877,13 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       'get its full JSON Schema(s) (Draft-07) plus a `notes` array of cross-' +
       "field invariants the schema can't express. The `node` payload includes " +
       "all 13 flat variants (including type:'component', whose `spec` field " +
-      'lives in a sidecar — drill into `componentSpec` for that shape). Use ' +
-      'this before authoring any flow.json / spec.json write — never memorise ' +
-      'field shapes.\n\n' +
+      'lives in a sidecar — drill into `componentSpec` for that shape).\n\n' +
+      'Pass a third positional `subname` to get just one named schema within ' +
+      'the category — e.g. `seeflow schema node component`, `seeflow schema ' +
+      'node rectangle`, `seeflow schema action playAction`. The category-' +
+      'level `notes` ride along unchanged because the cross-variant invariants ' +
+      'still apply when looking at one variant. Use this before authoring any ' +
+      'flow.json / spec.json write — never memorise field shapes.\n\n' +
       'Pass --jq <filter> to extract a slice of the response with a jq path ' +
       'expression. Supported subset: identity (`.`), field access ' +
       '(`.foo.bar`), bracket access (`.["foo"]`, `.[3]`, negative indices ' +
@@ -849,6 +899,16 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
         required: false,
         description: 'One of: flow, node, connector, action, componentSpec, style',
       },
+      {
+        name: 'subname',
+        required: false,
+        description:
+          'Optional named schema within the category — e.g. for `node`: ' +
+          'rectangle, ellipse, sticky, text, database, server, user, queue, ' +
+          'cloud, image, html, icon, component. For `action`: playAction, ' +
+          'statusAction, resetAction, statusReport, componentAction. For ' +
+          '`componentSpec`: componentSpec, componentSpecElement.',
+      },
     ],
     flags: [
       {
@@ -868,6 +928,9 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     examples: [
       'seeflow schema',
       'seeflow schema node',
+      'seeflow schema node component',
+      'seeflow schema node rectangle',
+      'seeflow schema action playAction',
       'seeflow schema connector',
       'seeflow schema componentSpec',
       'seeflow schema node --jq .schemas.rectangle',

package/src/cli.ts

@@ -178,6 +178,8 @@ if (argv.includes('--version') || argv.includes('-v')) {
   await runRegister();
 } else if (sub === 'projects:create') {
   await runProjectsCreate();
+} else if (sub === 'projects:list') {
+  await runProjectsList();
 } else if (sub === 'flows:list') {
   await runFlowsList();
 } else if (sub === 'flows:summary') {
@@ -243,10 +245,11 @@ Usage:
 Commands (work without a running studio):
   start                Start the SeeFlow Studio server (default port 4321) — default when no command is given
   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
+  register             Register a demo repo. Manifest-aware: when <repoPath>/seeflow.json exists, re-scans every declared flow; otherwise reads <repoPath>/<flow> (defaults to flow.json) as a single-flow project (alias of flows:register)
+  flows:register       Register a demo repo (manifest-aware — same behaviour as register)
   projects:create      Scaffold a new project (writes <path>/seeflow.json + <path>/flows/main/flow.json) — (--path <dir> --name <name> [--description <text>])
-  flows:list           List registered flows
+  projects:list        List every registered project with projectSlug, name, defaultFlow, flowCount
+  flows:list           List registered flows. With --project <p>, filters to one project (returns flowSlug, name, icon?, isDefault per flow)
   flows:summary        List registered flows (id + name + description only)
   flows:get            Get flow details (--project <p> --flow <f>)
   flows:graph          List nodes + connectors without inlined file content (--project <p> --flow <f>)
@@ -265,8 +268,11 @@ Commands (work without a running studio):
   connectors:patch <connId>  Patch a connector (--project <p> --flow <f>) [--json/--file/--stdin]
   connectors:delete <connId> Delete a connector (--project <p> --flow <f>)
   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
+  schema [<category> [<subname>]]
+                       Get the flow.json schema. No arg → category index;
+                       category arg → full JSON Schema(s) for that category;
+                       subname arg → just that named schema (e.g.
+                       'schema node component', 'schema node rectangle')
   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
@@ -591,12 +597,24 @@ function isEsrch(err: unknown): boolean {
 
 async function runRegister() {
   const repoPath = resolve(flagValue('path') ?? '.');
-  const demoPathArg = flagValue('flow') ?? DEFAULT_FLOW_PATH;
 
+  // Manifest-aware path: if <repoPath>/seeflow.json is on disk, scan and
+  // upsert every declared flow in one shot.
+  if (existsSync(join(repoPath, 'seeflow.json'))) {
+    await runRegisterManifest(repoPath);
+    return;
+  }
+
+  // Legacy single-flow path: pre-manifest projects (and skill tests that
+  // exercise registerFlow directly) still pass a bare flow.json at the
+  // root. Read it, schema-validate, upsert one entry.
+  const demoPathArg = flagValue('flow') ?? DEFAULT_FLOW_PATH;
   const fullPath = isAbsolute(demoPathArg) ? demoPathArg : join(repoPath, demoPathArg);
   if (!existsSync(fullPath)) {
     console.error(`No demo file at ${fullPath}`);
-    console.error(`Create ${DEFAULT_FLOW_PATH} in your repo, or pass --flow <path>.`);
+    console.error(
+      `Create ${DEFAULT_FLOW_PATH} in your repo, or pass --flow <path>. For manifest-driven projects, place a seeflow.json at the repo root.`,
+    );
     process.exit(1);
   }
 
@@ -640,6 +658,48 @@ async function runRegister() {
   }
 }
 
+async function runRegisterManifest(repoPath: string) {
+  const outcome = registerProject({ repoPath });
+  if (outcome.kind !== 'ok') {
+    switch (outcome.kind) {
+      case 'manifest-invalid':
+        console.error(`${join(repoPath, 'seeflow.json')} is invalid: ${outcome.message}`);
+        process.exit(2);
+        break;
+      case 'manifest-missing':
+        // Defensive — runRegister gated on existsSync, so this should not fire.
+        console.error(`No seeflow.json at ${repoPath}`);
+        process.exit(3);
+        break;
+      case 'legacy-root-flow':
+        console.error(
+          `${repoPath} has a legacy root flow.json but no seeflow.json. Migrate it into the new flows/<id>/ layout before re-registering.`,
+        );
+        process.exit(3);
+        break;
+      case 'flow-json-missing':
+        console.error(
+          `Manifest declares flow "${outcome.flowId}" but ${outcome.flowPath} is missing.`,
+        );
+        process.exit(3);
+        break;
+    }
+    process.exit(1);
+  }
+
+  const pid = readPid();
+  const live = pid !== undefined && isPidAlive(pid);
+  const overrideUrl = process.env.SEEFLOW_STUDIO_URL?.replace(/\/+$/, '');
+  const baseUrl = live ? (overrideUrl ?? studioUrl(readConfig())) : null;
+
+  for (const entry of outcome.entries) {
+    const tail = baseUrl
+      ? ` → ${baseUrl}/projects/${outcome.projectSlug}/flows/${entry.flowSlug}`
+      : ` (slug: ${entry.slug})`;
+    console.log(`Registered "${entry.name}"${tail}`);
+  }
+}
+
 async function ensureStudioRunning(url: string, port: number, noStart: boolean) {
   if (await healthOk(url)) return;
 
@@ -706,10 +766,23 @@ async function runProjectsCreate() {
 
 async function runFlowsList() {
   const ops = createCliOperations();
+  const project = flagValue('project');
+  if (project) {
+    const result = ops.listFlowsByProject(project);
+    if (result.kind !== 'ok') printOutcome(result);
+    printOk({ projectSlug: result.data.projectSlug, flows: result.data.flows });
+    return;
+  }
   const result = ops.listFlows();
   printOk({ flows: result.data });
 }
 
+function runProjectsList() {
+  const ops = createCliOperations();
+  const result = ops.listProjects();
+  printOk({ projects: result.data });
+}
+
 async function runFlowsSummary() {
   const ops = createCliOperations();
   const result = ops.listFlowsSummary();
@@ -1025,8 +1098,10 @@ async function runValidate() {
 
 async function runSchema() {
   const category = argv[1] && !argv[1].startsWith('--') ? argv[1] : undefined;
+  const subname = argv[2] && !argv[2].startsWith('--') ? argv[2] : undefined;
   const jqFilter = flagValue('jq');
-  const { listSchemaCategories, getSchemaCategory } = await import('./schema-catalog.ts');
+  const { listSchemaCategories, getSchemaCategory, getCategorySubschema, listCategorySubnames } =
+    await import('./schema-catalog.ts');
   if (!category) {
     const base = { categories: listSchemaCategories() };
     if (jqFilter !== undefined) {
@@ -1034,6 +1109,44 @@ async function runSchema() {
     }
     printOk(base);
   }
+  // Drill into a single named schema within the category — e.g.
+  // `seeflow schema node component`. Notes ride along unchanged because the
+  // cross-variant invariants (image path prefix, scriptPath rooting, etc.)
+  // are still relevant when you're looking at one variant.
+  if (subname) {
+    const single = getCategorySubschema(category as string, subname);
+    if (!single) {
+      const availableSubs = listCategorySubnames(category as string);
+      if (availableSubs === null) {
+        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);
+      }
+      const message = `unknown schema subname: ${subname}`;
+      process.stderr.write(
+        `${JSON.stringify({
+          error: message,
+          code: 'notFound',
+          category,
+          available: availableSubs,
+        })}\n`,
+      );
+      process.exit(3);
+    }
+    const base = {
+      name: category,
+      subname,
+      schemas: single.schemas,
+      notes: single.notes,
+    };
+    if (jqFilter !== undefined) {
+      printOk({ name: category, subname, result: applyJqOrDie(base, jqFilter) });
+    }
+    printOk(base);
+  }
   const payload = getSchemaCategory(category as string);
   if (!payload) {
     const available = listSchemaCategories().map((c) => c.name);

package/src/mcp.ts

@@ -29,7 +29,13 @@ import {
   flowBulkNonEmpty,
 } from './operations.ts';
 import type { Registry } from './registry.ts';
-import { getSchemaCategory, listSchemaCategories, schemaCategoryNames } from './schema-catalog.ts';
+import {
+  getCategorySubschema,
+  getSchemaCategory,
+  listCategorySubnames,
+  listSchemaCategories,
+  schemaCategoryNames,
+} from './schema-catalog.ts';
 import { ID_TYPES, MAX_ID_COUNT, generateIds, isIdType } from './short-id.ts';
 import type { FlowWatcher } from './watcher.ts';
 
@@ -280,13 +286,18 @@ const buildTools = (ops: Operations, ctx: ToolContext): McpTool[] => [
     name: 'seeflow_schema',
     description:
       'Get the SeeFlow flow.json / spec.json schemas. 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, component spec, or ' +
-      'flow envelope looks like before authoring writes. Categories: `flow`, ' +
-      '`node` (13 flat variants — rectangle/ellipse/sticky/text/database/server/' +
-      'user/queue/cloud/image/html/icon/component), `connector`, `action` ' +
-      '(playAction/statusAction/resetAction/statusReport/componentAction), ' +
-      "`componentSpec` (sidecar shape for type:'component' nodes), `style`.",
+      "category index; call with `name` for one category's full JSON Schemas; " +
+      'call with `name` + `subname` for just one named schema within that ' +
+      "category (e.g. name='node', subname='component' → just the component " +
+      "node variant; name='node', subname='rectangle' → just the rectangle " +
+      "node variant; name='action', subname='playAction' → just the playAction " +
+      'shape). Use this to learn what a node, connector, action, component ' +
+      'spec, or flow envelope looks like before authoring writes. Categories: ' +
+      '`flow`, `node` (13 flat variants — rectangle/ellipse/sticky/text/' +
+      'database/server/user/queue/cloud/image/html/icon/component), ' +
+      '`connector`, `action` (playAction/statusAction/resetAction/statusReport/' +
+      "componentAction), `componentSpec` (sidecar shape for type:'component' " +
+      'nodes), `style`.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -294,20 +305,58 @@ const buildTools = (ops: Operations, ctx: ToolContext): McpTool[] => [
           type: 'string',
           description: 'Optional category name. Omit for the index.',
         },
+        subname: {
+          type: 'string',
+          description:
+            'Optional named schema within the category (requires `name`). For ' +
+            "name='node': rectangle, ellipse, sticky, text, database, server, " +
+            'user, queue, cloud, image, html, icon, component. For ' +
+            "name='action': playAction, statusAction, resetAction, statusReport, " +
+            "componentAction. For name='componentSpec': componentSpec, " +
+            'componentSpecElement.',
+        },
       },
       additionalProperties: false,
     },
     handler: async (args) => {
-      const name =
+      const argObj =
         args && typeof args === 'object' && !Array.isArray(args)
-          ? (args as { name?: unknown }).name
-          : undefined;
+          ? (args as { name?: unknown; subname?: unknown })
+          : {};
+      const name = argObj.name;
+      const subname = argObj.subname;
       if (name === undefined || name === null || name === '') {
+        if (subname !== undefined && subname !== null && subname !== '') {
+          return errorResult('Invalid arguments: `subname` requires `name` to be set');
+        }
         return okResult({ categories: listSchemaCategories() });
       }
       if (typeof name !== 'string') {
         return errorResult('Invalid arguments: `name` must be a string when present');
       }
+      if (subname !== undefined && subname !== null && subname !== '') {
+        if (typeof subname !== 'string') {
+          return errorResult('Invalid arguments: `subname` must be a string when present');
+        }
+        const single = getCategorySubschema(name, subname);
+        if (single) {
+          return okResult({
+            name,
+            subname,
+            schemas: single.schemas,
+            notes: single.notes,
+          });
+        }
+        const availableSubs = listCategorySubnames(name);
+        if (availableSubs === null) {
+          return errorResult(
+            `unknown schema category: ${name} (available: ${schemaCategoryNames().join(', ')})`,
+          );
+        }
+        return errorResult(
+          `unknown schema subname: ${subname} in category ${name} (available: ${availableSubs.join(', ')})`,
+        );
+      }
       const payload = getSchemaCategory(name);
       if (!payload) {
         return errorResult(

package/src/operations.ts

@@ -22,8 +22,8 @@ import {
   removeNodeDir,
   writeNodeFile,
 } from './node-files.ts';
-import { scanProject } from './project-scanner.ts';
-import { type Registry, slugify } from './registry.ts';
+import { readProjectManifest, scanProject } from './project-scanner.ts';
+import { type FlowEntry, type Registry, slugify } from './registry.ts';
 import {
   ColorTokenSchema,
   ComponentSpecSchema,
@@ -404,6 +404,31 @@ export interface CreateProjectSuccess {
 
 export type ListFlowsOutcome = { kind: 'ok'; data: FlowListItem[] };
 
+export interface ProjectListItem {
+  projectSlug: string;
+  name: string;
+  description?: string;
+  defaultFlow: string;
+  flowCount: number;
+  repoPath: string;
+}
+
+export type ListProjectsOutcome = { kind: 'ok'; data: ProjectListItem[] };
+
+export interface ProjectFlowListItem {
+  id: string;
+  slug: string;
+  flowSlug: string;
+  name: string;
+  icon?: string;
+  isDefault: boolean;
+  valid: boolean;
+}
+
+export type ListFlowsByProjectOutcome =
+  | { kind: 'ok'; data: { projectSlug: string; flows: ProjectFlowListItem[] } }
+  | { kind: 'projectNotFound'; projectSlug: string };
+
 // Minimal projection for agent/CLI discovery — `description` and `name` come
 // from the live watcher snapshot when available so author edits to flow.json
 // surface immediately; fall back to the registry value at startup before
@@ -951,6 +976,52 @@ export function listDemosImpl(deps: OperationsDeps): ListFlowsOutcome {
   return { kind: 'ok', data };
 }
 
+export function listProjectsImpl(deps: OperationsDeps): ListProjectsOutcome {
+  const grouped = new Map<string, FlowEntry[]>();
+  for (const entry of deps.registry.list()) {
+    const existing = grouped.get(entry.projectSlug);
+    if (existing) existing.push(entry);
+    else grouped.set(entry.projectSlug, [entry]);
+  }
+  const data: ProjectListItem[] = [];
+  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;
+    data.push({
+      projectSlug,
+      name: manifest?.name ?? projectSlug,
+      ...(manifest?.description !== undefined ? { description: manifest.description } : {}),
+      defaultFlow: manifest?.defaultFlow ?? defaultEntry.flowSlug,
+      flowCount: entries.length,
+      repoPath: head.repoPath,
+    });
+  }
+  return { kind: 'ok', data };
+}
+
+export function listFlowsByProjectImpl(
+  deps: OperationsDeps,
+  projectSlug: string,
+): ListFlowsByProjectOutcome {
+  const entries = deps.registry.list().filter((e) => e.projectSlug === projectSlug);
+  if (entries.length === 0) return { kind: 'projectNotFound', projectSlug };
+  const flows: ProjectFlowListItem[] = entries.map((e) => {
+    const fileExists = existsSync(resolveFilePath(e.repoPath, e.flowPath));
+    return {
+      id: e.id,
+      slug: e.slug,
+      flowSlug: e.flowSlug,
+      name: e.name,
+      ...(e.icon !== undefined ? { icon: e.icon } : {}),
+      isDefault: e.isDefault,
+      valid: e.valid && fileExists,
+    };
+  });
+  return { kind: 'ok', data: { projectSlug, flows } };
+}
+
 export function listFlowsSummaryImpl(deps: OperationsDeps): ListFlowsSummaryOutcome {
   const { registry, watcher } = deps;
   const data = registry.list().map((e) => {
@@ -1899,6 +1970,8 @@ export async function applyLayoutImpl(
 export interface Operations {
   listFlows(): ReturnType<typeof listDemosImpl>;
   listFlowsSummary(): ReturnType<typeof listFlowsSummaryImpl>;
+  listProjects(): ReturnType<typeof listProjectsImpl>;
+  listFlowsByProject(projectSlug: string): ReturnType<typeof listFlowsByProjectImpl>;
   getFlow(id: string): ReturnType<typeof getFlowImpl>;
   getFlowGraph(id: string): ReturnType<typeof getFlowGraphImpl>;
   getNode(flowId: string, nodeId: string): ReturnType<typeof getNodeImpl>;
@@ -1946,6 +2019,8 @@ export function createOperations(deps: OperationsDeps): Operations {
   return {
     listFlows: () => listDemosImpl(deps),
     listFlowsSummary: () => listFlowsSummaryImpl(deps),
+    listProjects: () => listProjectsImpl(deps),
+    listFlowsByProject: (projectSlug) => listFlowsByProjectImpl(deps, projectSlug),
     getFlow: (id) => getFlowImpl(deps, id),
     getFlowGraph: (id) => getFlowGraphImpl(deps, id),
     getNode: (flowId, nodeId) => getNodeImpl(deps, flowId, nodeId),

package/src/project-scanner.ts

@@ -47,6 +47,24 @@ export type ScanResult =
 const MANIFEST_FILENAME = 'seeflow.json';
 const LEGACY_FLOW_FILENAME = 'flow.json';
 
+/**
+ * Best-effort manifest read for listing routes / CLI listing verbs.
+ * Returns `null` when the manifest is missing or malformed — callers fall
+ * back to derived defaults (projectSlug, isDefault entry) so one broken
+ * project does not collapse the whole listing.
+ */
+export function readProjectManifest(repoPath: string): SeeflowManifest | null {
+  const manifestPath = join(repoPath, MANIFEST_FILENAME);
+  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;
+  }
+}
+
 export function scanProject(repoPath: string): ScanResult {
   const manifestPath = join(repoPath, MANIFEST_FILENAME);
   if (!existsSync(manifestPath)) {

package/src/schema-catalog.ts

@@ -151,3 +151,26 @@ export function getSchemaCategory(name: string): SchemaPayload | null {
 export function schemaCategoryNames(): string[] {
   return CATEGORIES.map((c) => c.name);
 }
+
+// Drill into one named schema inside a category — e.g. ('node', 'rectangle')
+// returns just the rectangle variant. The category-level notes ride along
+// unchanged because they describe cross-variant invariants the caller still
+// needs (image path prefix, scriptPath rooting, etc.). Returns null if either
+// the category or the subname is unknown; callers use listCategorySubnames
+// to build a helpful "available" list in that case.
+export function getCategorySubschema(category: string, subname: string): SchemaPayload | null {
+  const payload = PAYLOADS[category];
+  if (!payload) return null;
+  const schema = payload.schemas[subname];
+  if (schema === undefined) return null;
+  return { schemas: { [subname]: schema }, notes: [...payload.notes] };
+}
+
+// Returns the subname keys (rectangle, ellipse, …) for a known category, or
+// null if the category itself is unknown. Used to surface "available" lists
+// on lookup failures so the error message is self-correcting.
+export function listCategorySubnames(category: string): string[] | null {
+  const payload = PAYLOADS[category];
+  if (!payload) return null;
+  return Object.keys(payload.schemas);
+}

package/dist/web/assets/channel-gvIm48Rt.js

@@ -1 +0,0 @@
-import{U as a,C as n}from"./mermaid.core-tY2raeE_.js";const t=(r,o)=>a.lang.round(n.parse(r)[o]);export{t as c};

package/dist/web/assets/classDiagram-4FO5ZUOK-eMNtcBZw.js

@@ -1 +0,0 @@
-import{s as a,a as s,c as e,C as t}from"./chunk-727SXJPM-DFEMoCvZ.js";import{a as i}from"./mermaid.core-tY2raeE_.js";import"./index-AGsIlqaG.js";import"./chunk-FMBD7UC4-LXLjZhT_.js";import"./chunk-ND2GUHAM-C8IKIBCh.js";import"./chunk-55IACEB6-D44BQXvr.js";import"./chunk-2J33WTMH-pmw8bFhw.js";import"./purify.es-CLGrRn1w.js";import"./step-CWvwoXpJ.js";var b={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{b as diagram};

package/dist/web/assets/classDiagram-v2-Q7XG4LA2-eMNtcBZw.js

@@ -1 +0,0 @@
-import{s as a,a as s,c as e,C as t}from"./chunk-727SXJPM-DFEMoCvZ.js";import{a as i}from"./mermaid.core-tY2raeE_.js";import"./index-AGsIlqaG.js";import"./chunk-FMBD7UC4-LXLjZhT_.js";import"./chunk-ND2GUHAM-C8IKIBCh.js";import"./chunk-55IACEB6-D44BQXvr.js";import"./chunk-2J33WTMH-pmw8bFhw.js";import"./purify.es-CLGrRn1w.js";import"./step-CWvwoXpJ.js";var b={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{b as diagram};

package/dist/web/assets/stateDiagram-v2-BHNVJYJU-CNXxJnrL.js

@@ -1 +0,0 @@
-import{b as r,a as e,s as a,S as s}from"./chunk-AQP2D5EJ-DDIMOnRk.js";import{a as i}from"./mermaid.core-tY2raeE_.js";import"./index-AGsIlqaG.js";import"./chunk-55IACEB6-D44BQXvr.js";import"./chunk-2J33WTMH-pmw8bFhw.js";import"./purify.es-CLGrRn1w.js";import"./step-CWvwoXpJ.js";var n={parser:a,get db(){return new s(2)},renderer:e,styles:r,init:i(t=>{t.state||(t.state={}),t.state.arrowMarkerAbsolute=t.arrowMarkerAbsolute},"init")};export{n as diagram};