@tuongaz/seeflow 0.1.76 → 0.1.80

package/src/cli-manifest.ts

@@ -201,59 +201,193 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
   },
   {
     name: 'flows:get',
-    synopsis: 'seeflow flows:get <flowId>',
+    synopsis: 'seeflow flows:get --project <p> --flow <f>',
     description: 'Get the full merged flow definition and on-disk state for one flow.',
     category: 'flows',
-    args: [{ name: 'flowId', required: true, description: 'Flow id or slug' }],
-    flags: [],
+    args: [],
+    flags: [
+      { name: 'project', valuePlaceholder: '<p>', description: 'Project slug', required: true },
+      {
+        name: 'flow',
+        valuePlaceholder: '<f>',
+        description: 'Flow id within the project',
+        required: true,
+      },
+    ],
     outputs: { errorKinds: ['notFound', 'fileNotFound'] },
     requiresStudio: false,
-    examples: ['seeflow flows:get abc12345'],
+    examples: ['seeflow flows:get --project order-pipeline --flow main'],
   },
   {
     name: 'flows:graph',
-    synopsis: 'seeflow flows:graph <flowId>',
+    synopsis: 'seeflow flows:graph --project <p> --flow <f>',
     description:
       'Get nodes + connectors for one flow without inlining per-node file-backed ' +
       'content (detail.md, view.html). Cheap topology read.',
     category: 'flows',
-    args: [{ name: 'flowId', required: true, description: 'Flow id or slug' }],
-    flags: [],
+    args: [],
+    flags: [
+      { name: 'project', valuePlaceholder: '<p>', description: 'Project slug', required: true },
+      {
+        name: 'flow',
+        valuePlaceholder: '<f>',
+        description: 'Flow id within the project',
+        required: true,
+      },
+    ],
     outputs: { errorKinds: ['notFound', 'fileNotFound', 'badJson', 'badSchema'] },
     requiresStudio: false,
-    examples: ['seeflow flows:graph abc12345'],
+    examples: ['seeflow flows:graph --project order-pipeline --flow main'],
   },
   {
     name: 'flows:delete',
-    synopsis: 'seeflow flows:delete <flowId>',
-    description: 'Unregister a flow from the studio (the on-disk file is left untouched).',
+    synopsis: 'seeflow flows:delete --project <p> --flow <f> [--new-default <other>]',
+    description:
+      'Delete a flow from a project. Removes the `flows/<flow>/` folder, updates ' +
+      '`seeflow.json`, and drops the registry entry. Refuses to delete the last flow ' +
+      'in a project or the project default without --new-default.',
     category: 'flows',
-    args: [{ name: 'flowId', required: true, description: 'Flow id or slug' }],
-    flags: [],
-    outputs: { okExample: { ok: true }, errorKinds: ['notFound'] },
+    args: [],
+    flags: [
+      {
+        name: 'project',
+        valuePlaceholder: '<p>',
+        description: 'Project slug',
+        required: true,
+      },
+      {
+        name: 'flow',
+        valuePlaceholder: '<f>',
+        description: 'Flow id within the project',
+        required: true,
+      },
+      {
+        name: 'new-default',
+        valuePlaceholder: '<other>',
+        description: 'Required when deleting the project default — names the flow that takes over',
+      },
+    ],
+    outputs: {
+      okExample: { ok: true },
+      errorKinds: ['notFound'],
+    },
     requiresStudio: false,
-    examples: ['seeflow flows:delete abc12345'],
+    examples: [
+      'seeflow flows:delete --project order-pipeline --flow retry',
+      'seeflow flows:delete --project order-pipeline --flow main --new-default retry',
+    ],
+  },
+  {
+    name: 'flows:create',
+    synopsis: 'seeflow flows:create --project <p> --flow <id> --name <n> [--icon <i>]',
+    description:
+      'Create a new flow within an existing project. Writes ' +
+      '`<repoPath>/flows/<id>/flow.json` with an empty envelope and appends the ' +
+      'new entry to the project manifest atomically.',
+    category: 'flows',
+    args: [],
+    flags: [
+      {
+        name: 'project',
+        valuePlaceholder: '<p>',
+        description: 'Project slug',
+        required: true,
+      },
+      {
+        name: 'flow',
+        valuePlaceholder: '<id>',
+        description: 'New flow id (lowercase alphanumeric + dashes)',
+        required: true,
+      },
+      {
+        name: 'name',
+        valuePlaceholder: '<n>',
+        description: 'Human-readable flow name',
+        required: true,
+      },
+      {
+        name: 'icon',
+        valuePlaceholder: '<i>',
+        description: 'Optional icon name shown next to the flow in the switcher',
+      },
+    ],
+    outputs: {
+      okExample: { id: 'abc12345', slug: 'order-pipeline/retry', flowSlug: 'retry' },
+      errorKinds: ['notFound'],
+    },
+    requiresStudio: false,
+    examples: [
+      'seeflow flows:create --project order-pipeline --flow retry --name "Retry"',
+      'seeflow flows:create --project order-pipeline --flow retry --name "Retry" --icon refresh',
+    ],
+  },
+  {
+    name: 'flows:rename',
+    synopsis:
+      'seeflow flows:rename --project <p> --flow <id> [--new-id <x>] [--name <n>] [--icon <i>]',
+    description:
+      "Rename a flow's id, name, and/or icon. Changing --new-id moves the on-disk " +
+      '`flows/<id>/` folder atomically and rewrites the manifest (including ' +
+      '`defaultFlow` if it pointed at the renamed flow). Updating only --name / ' +
+      '--icon edits the manifest in place without touching the filesystem layout.',
+    category: 'flows',
+    args: [],
+    flags: [
+      {
+        name: 'project',
+        valuePlaceholder: '<p>',
+        description: 'Project slug',
+        required: true,
+      },
+      {
+        name: 'flow',
+        valuePlaceholder: '<id>',
+        description: 'Current flow id within the project',
+        required: true,
+      },
+      { name: 'new-id', valuePlaceholder: '<x>', description: 'New flow id (renames the folder)' },
+      { name: 'name', valuePlaceholder: '<n>', description: 'New human-readable name' },
+      { name: 'icon', valuePlaceholder: '<i>', description: 'New icon name' },
+    ],
+    outputs: {
+      okExample: { id: 'abc12345', slug: 'order-pipeline/retry-v2', flowSlug: 'retry-v2' },
+      errorKinds: ['notFound'],
+    },
+    requiresStudio: false,
+    examples: [
+      'seeflow flows:rename --project order-pipeline --flow retry --new-id retry-v2',
+      'seeflow flows:rename --project order-pipeline --flow main --name "Primary"',
+    ],
   },
   {
     name: 'flows:layout',
-    synopsis: 'seeflow flows:layout <flowId> [--json | --file | --stdin]',
+    synopsis: 'seeflow flows:layout --project <p> --flow <f> [--json | --file | --stdin]',
     description:
       'Compute an ELK layout for the flow and write style.json next to flow.json. ' +
       'Body is optional — `{ options? }` shape. Empty body uses defaults.',
     category: 'flows',
-    args: [{ name: 'flowId', required: true, description: 'Flow id or slug' }],
-    flags: BODY_FLAGS,
+    args: [],
+    flags: [
+      { name: 'project', valuePlaceholder: '<p>', description: 'Project slug', required: true },
+      {
+        name: 'flow',
+        valuePlaceholder: '<f>',
+        description: 'Flow id within the project',
+        required: true,
+      },
+      ...BODY_FLAGS,
+    ],
     body: { example: { options: { 'elk.direction': 'RIGHT' } } },
     outputs: {
       okExample: { ok: true },
       errorKinds: ['flowNotFound', 'fileNotFound', 'badJson', 'badSchema', 'writeFailed'],
     },
     requiresStudio: false,
-    examples: ['seeflow flows:layout abc12345'],
+    examples: ['seeflow flows:layout --project order-pipeline --flow main'],
   },
   {
     name: 'flow:add-bulk',
-    synopsis: 'seeflow flow:add-bulk <flowId> [--json | --file | --stdin]',
+    synopsis: 'seeflow flow:add-bulk --project <p> --flow <f> [--json | --file | --stdin]',
     description:
       'Add up to 100 nodes + 100 connectors atomically. Body shape: ' +
       '`{ nodes?: Node[], connectors?: Connector[] }` (at least one non-empty). ' +
@@ -261,8 +395,17 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       'is re-validated post-merge so a dangling source/target — or any per-item ' +
       'schema failure — rolls back both arrays together and emits no broadcast.',
     category: 'flows',
-    args: [{ name: 'flowId', required: true, description: 'Flow id or slug' }],
-    flags: BODY_FLAGS,
+    args: [],
+    flags: [
+      { name: 'project', valuePlaceholder: '<p>', description: 'Project slug', required: true },
+      {
+        name: 'flow',
+        valuePlaceholder: '<f>',
+        description: 'Flow id within the project',
+        required: true,
+      },
+      ...BODY_FLAGS,
+    ],
     body: { schemaRef: 'FlowBulkBody' },
     outputs: {
       okExample: {
@@ -281,29 +424,35 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     },
     requiresStudio: false,
     examples: [
-      'seeflow flow:add-bulk abc12345 --json \'{"nodes":[{"id":"a","type":"rectangle","data":{}}],"connectors":[]}\'',
-      'seeflow flow:add-bulk abc12345 --file batch.json',
+      'seeflow flow:add-bulk --project order-pipeline --flow main --json \'{"nodes":[{"id":"a","type":"rectangle","data":{}}],"connectors":[]}\'',
+      'seeflow flow:add-bulk --project order-pipeline --flow main --file batch.json',
     ],
   },
   {
     name: 'flows:play',
-    synopsis: 'seeflow flows:play <flowId> <nodeId> [--no-start]',
+    synopsis: 'seeflow flows:play --project <p> --flow <f> <nodeId> [--no-start]',
     description:
       "Trigger the node's playAction on the studio and wait for the spawn-level " +
       'result. The studio also broadcasts node:running/done/error events on the ' +
       "flow's SSE stream — subscribe separately if you want live progress. " +
       'Requires a running studio.',
     category: 'live',
-    args: [
-      { name: 'flowId', required: true, description: 'Flow id or slug' },
-      { name: 'nodeId', required: true, description: 'Node id in the flow' },
+    args: [{ name: 'nodeId', required: true, description: 'Node id in the flow' }],
+    flags: [
+      { name: 'project', valuePlaceholder: '<p>', description: 'Project slug', required: true },
+      {
+        name: 'flow',
+        valuePlaceholder: '<f>',
+        description: 'Flow id within the project',
+        required: true,
+      },
+      { name: 'no-start', description: 'Fail if the studio is not already running' },
     ],
-    flags: [{ name: 'no-start', description: 'Fail if the studio is not already running' }],
     outputs: {
       okExample: { runId: 'run-9b3', status: 200, body: { ok: true } },
     },
     requiresStudio: true,
-    examples: ['seeflow flows:play abc12345 api-checkout'],
+    examples: ['seeflow flows:play --project order-pipeline --flow main api-checkout'],
   },
   // ---- project -----------------------------------------------------------
   {
@@ -342,11 +491,20 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
   // ---- nodes -------------------------------------------------------------
   {
     name: 'nodes:add',
-    synopsis: 'seeflow nodes:add <flowId> [--json | --file | --stdin]',
+    synopsis: 'seeflow nodes:add --project <p> --flow <f> [--json | --file | --stdin]',
     description: 'Add a single node to a flow. Body is the node object (auto-id if omitted).',
     category: 'nodes',
-    args: [{ name: 'flowId', required: true, description: 'Flow id or slug' }],
-    flags: BODY_FLAGS,
+    args: [],
+    flags: [
+      { name: 'project', valuePlaceholder: '<p>', description: 'Project slug', required: true },
+      {
+        name: 'flow',
+        valuePlaceholder: '<f>',
+        description: 'Flow id within the project',
+        required: true,
+      },
+      ...BODY_FLAGS,
+    ],
     body: {
       example: {
         type: 'rectangle',
@@ -358,34 +516,47 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       errorKinds: ['flowNotFound', 'fileNotFound', 'badJson', 'badSchema', 'writeFailed'],
     },
     requiresStudio: false,
-    examples: ['seeflow nodes:add abc12345 --json \'{"type":"rectangle","data":{}}\''],
+    examples: [
+      'seeflow nodes:add --project order-pipeline --flow main --json \'{"type":"rectangle","data":{}}\'',
+    ],
   },
   {
     name: 'nodes:get',
-    synopsis: 'seeflow nodes:get <flowId> <nodeId>',
+    synopsis: 'seeflow nodes:get --project <p> --flow <f> <nodeId>',
     description:
       'Get one node with its file-backed content (detail.md, view.html) inlined. ' +
       'Use after flows:graph to drill in.',
     category: 'nodes',
-    args: [
-      { name: 'flowId', required: true, description: 'Flow id or slug' },
-      { name: 'nodeId', required: true, description: 'Node id in the flow' },
+    args: [{ name: 'nodeId', required: true, description: 'Node id in the flow' }],
+    flags: [
+      { name: 'project', valuePlaceholder: '<p>', description: 'Project slug', required: true },
+      {
+        name: 'flow',
+        valuePlaceholder: '<f>',
+        description: 'Flow id within the project',
+        required: true,
+      },
     ],
-    flags: [],
     outputs: { errorKinds: ['notFound', 'fileNotFound', 'unknownNode', 'badJson', 'badSchema'] },
     requiresStudio: false,
-    examples: ['seeflow nodes:get abc12345 api-checkout'],
+    examples: ['seeflow nodes:get --project order-pipeline --flow main api-checkout'],
   },
   {
     name: 'nodes:patch',
-    synopsis: 'seeflow nodes:patch <flowId> <nodeId> [--json | --file | --stdin]',
+    synopsis: 'seeflow nodes:patch --project <p> --flow <f> <nodeId> [--json | --file | --stdin]',
     description: 'Patch fields on an existing node. Validates the partial against NodePatchBody.',
     category: 'nodes',
-    args: [
-      { name: 'flowId', required: true, description: 'Flow id or slug' },
-      { name: 'nodeId', required: true, description: 'Node id in the flow' },
+    args: [{ name: 'nodeId', required: true, description: 'Node id in the flow' }],
+    flags: [
+      { name: 'project', valuePlaceholder: '<p>', description: 'Project slug', required: true },
+      {
+        name: 'flow',
+        valuePlaceholder: '<f>',
+        description: 'Flow id within the project',
+        required: true,
+      },
+      ...BODY_FLAGS,
     ],
-    flags: BODY_FLAGS,
     body: { schemaRef: 'NodePatchBody' },
     outputs: {
       errorKinds: [
@@ -398,18 +569,24 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       ],
     },
     requiresStudio: false,
-    examples: ['seeflow nodes:patch abc12345 api-checkout --json \'{"data":{"name":"renamed"}}\''],
+    examples: [
+      'seeflow nodes:patch --project order-pipeline --flow main api-checkout --json \'{"data":{"name":"renamed"}}\'',
+    ],
   },
   {
     name: 'nodes:move',
-    synopsis: 'seeflow nodes:move <flowId> <nodeId> --x <n> --y <n>',
+    synopsis: 'seeflow nodes:move --project <p> --flow <f> <nodeId> --x <n> --y <n>',
     description: 'Set the node position in style.json (does not touch flow.json).',
     category: 'nodes',
-    args: [
-      { name: 'flowId', required: true, description: 'Flow id or slug' },
-      { name: 'nodeId', required: true, description: 'Node id in the flow' },
-    ],
+    args: [{ name: 'nodeId', required: true, description: 'Node id in the flow' }],
     flags: [
+      { name: 'project', valuePlaceholder: '<p>', description: 'Project slug', required: true },
+      {
+        name: 'flow',
+        valuePlaceholder: '<f>',
+        description: 'Flow id within the project',
+        required: true,
+      },
       { name: 'x', valuePlaceholder: '<n>', description: 'X coordinate', required: true },
       { name: 'y', valuePlaceholder: '<n>', description: 'Y coordinate', required: true },
     ],
@@ -425,19 +602,25 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       ],
     },
     requiresStudio: false,
-    examples: ['seeflow nodes:move abc12345 api-checkout --x 250 --y 320'],
+    examples: [
+      'seeflow nodes:move --project order-pipeline --flow main api-checkout --x 250 --y 320',
+    ],
   },
   {
     name: 'nodes:reorder',
     synopsis:
-      'seeflow nodes:reorder <flowId> <nodeId> --op forward|backward|toFront|toBack|toIndex [--index <n>]',
+      'seeflow nodes:reorder --project <p> --flow <f> <nodeId> --op forward|backward|toFront|toBack|toIndex [--index <n>]',
     description: "Reorder a node's z-position within the flow.",
     category: 'nodes',
-    args: [
-      { name: 'flowId', required: true, description: 'Flow id or slug' },
-      { name: 'nodeId', required: true, description: 'Node id in the flow' },
-    ],
+    args: [{ name: 'nodeId', required: true, description: 'Node id in the flow' }],
     flags: [
+      { name: 'project', valuePlaceholder: '<p>', description: 'Project slug', required: true },
+      {
+        name: 'flow',
+        valuePlaceholder: '<f>',
+        description: 'Flow id within the project',
+        required: true,
+      },
       {
         name: 'op',
         valuePlaceholder: '<op>',
@@ -459,20 +642,25 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     },
     requiresStudio: false,
     examples: [
-      'seeflow nodes:reorder abc12345 api-checkout --op forward',
-      'seeflow nodes:reorder abc12345 api-checkout --op toIndex --index 0',
+      'seeflow nodes:reorder --project order-pipeline --flow main api-checkout --op forward',
+      'seeflow nodes:reorder --project order-pipeline --flow main api-checkout --op toIndex --index 0',
     ],
   },
   {
     name: 'nodes:delete',
-    synopsis: 'seeflow nodes:delete <flowId> <nodeId>',
+    synopsis: 'seeflow nodes:delete --project <p> --flow <f> <nodeId>',
     description: 'Delete a node and any connectors that reference it.',
     category: 'nodes',
-    args: [
-      { name: 'flowId', required: true, description: 'Flow id or slug' },
-      { name: 'nodeId', required: true, description: 'Node id in the flow' },
+    args: [{ name: 'nodeId', required: true, description: 'Node id in the flow' }],
+    flags: [
+      { name: 'project', valuePlaceholder: '<p>', description: 'Project slug', required: true },
+      {
+        name: 'flow',
+        valuePlaceholder: '<f>',
+        description: 'Flow id within the project',
+        required: true,
+      },
     ],
-    flags: [],
     outputs: {
       okExample: { ok: true, removedConnectors: 0 },
       errorKinds: [
@@ -485,18 +673,27 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       ],
     },
     requiresStudio: false,
-    examples: ['seeflow nodes:delete abc12345 api-checkout'],
+    examples: ['seeflow nodes:delete --project order-pipeline --flow main api-checkout'],
   },
   // ---- connectors --------------------------------------------------------
   {
     name: 'connectors:add',
-    synopsis: 'seeflow connectors:add <flowId> [--json | --file | --stdin]',
+    synopsis: 'seeflow connectors:add --project <p> --flow <f> [--json | --file | --stdin]',
     description:
       'Add a connector. Body is the connector object — `source` and `target` are ' +
       'the connected node ids (strings). Auto-generates an id when absent.',
     category: 'connectors',
-    args: [{ name: 'flowId', required: true, description: 'Flow id or slug' }],
-    flags: BODY_FLAGS,
+    args: [],
+    flags: [
+      { name: 'project', valuePlaceholder: '<p>', description: 'Project slug', required: true },
+      {
+        name: 'flow',
+        valuePlaceholder: '<f>',
+        description: 'Flow id within the project',
+        required: true,
+      },
+      ...BODY_FLAGS,
+    ],
     body: {
       example: { source: 'a', target: 'b' },
     },
@@ -505,18 +702,27 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       errorKinds: ['flowNotFound', 'fileNotFound', 'badJson', 'badSchema', 'writeFailed'],
     },
     requiresStudio: false,
-    examples: ['seeflow connectors:add abc12345 --json \'{"source":"a","target":"b"}\''],
+    examples: [
+      'seeflow connectors:add --project order-pipeline --flow main --json \'{"source":"a","target":"b"}\'',
+    ],
   },
   {
     name: 'connectors:patch',
-    synopsis: 'seeflow connectors:patch <flowId> <connectorId> [--json | --file | --stdin]',
+    synopsis:
+      'seeflow connectors:patch --project <p> --flow <f> <connectorId> [--json | --file | --stdin]',
     description: 'Patch fields on an existing connector.',
     category: 'connectors',
-    args: [
-      { name: 'flowId', required: true, description: 'Flow id or slug' },
-      { name: 'connectorId', required: true, description: 'Connector id in the flow' },
+    args: [{ name: 'connectorId', required: true, description: 'Connector id in the flow' }],
+    flags: [
+      { name: 'project', valuePlaceholder: '<p>', description: 'Project slug', required: true },
+      {
+        name: 'flow',
+        valuePlaceholder: '<f>',
+        description: 'Flow id within the project',
+        required: true,
+      },
+      ...BODY_FLAGS,
     ],
-    flags: BODY_FLAGS,
     body: { schemaRef: 'ConnectorPatchBody' },
     outputs: {
       errorKinds: [
@@ -529,18 +735,25 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       ],
     },
     requiresStudio: false,
-    examples: ['seeflow connectors:patch abc12345 conn-1 --json \'{"label":"new"}\''],
+    examples: [
+      'seeflow connectors:patch --project order-pipeline --flow main conn-1 --json \'{"label":"new"}\'',
+    ],
   },
   {
     name: 'connectors:delete',
-    synopsis: 'seeflow connectors:delete <flowId> <connectorId>',
+    synopsis: 'seeflow connectors:delete --project <p> --flow <f> <connectorId>',
     description: 'Delete a connector.',
     category: 'connectors',
-    args: [
-      { name: 'flowId', required: true, description: 'Flow id or slug' },
-      { name: 'connectorId', required: true, description: 'Connector id in the flow' },
+    args: [{ name: 'connectorId', required: true, description: 'Connector id in the flow' }],
+    flags: [
+      { name: 'project', valuePlaceholder: '<p>', description: 'Project slug', required: true },
+      {
+        name: 'flow',
+        valuePlaceholder: '<f>',
+        description: 'Flow id within the project',
+        required: true,
+      },
     ],
-    flags: [],
     outputs: {
       okExample: { ok: true },
       errorKinds: [
@@ -553,7 +766,7 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       ],
     },
     requiresStudio: false,
-    examples: ['seeflow connectors:delete abc12345 conn-1'],
+    examples: ['seeflow connectors:delete --project order-pipeline --flow main conn-1'],
   },
   // ---- validate ----------------------------------------------------------
   {
@@ -610,7 +823,7 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
   },
   {
     name: 'schema',
-    synopsis: 'seeflow schema [<category>]',
+    synopsis: 'seeflow schema [<category>] [--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, ' +
@@ -620,7 +833,15 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       "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.',
+      '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 ' +
+      'allowed), iteration (`.foo[]`), optional `?` (e.g. `.foo?` to suppress ' +
+      'type errors), and pipe (`|`). Single-output filters return the value ' +
+      'under `{ result: <value> }`; multi-output filters (from `[]` or `|`) ' +
+      'return `{ result: [<v1>, <v2>, ...] }`. Bad filters exit with code 2 ' +
+      'and `code:"badJq"`.',
     category: 'meta',
     args: [
       {
@@ -629,10 +850,19 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
         description: 'One of: flow, node, connector, action, componentSpec, style',
       },
     ],
-    flags: [],
+    flags: [
+      {
+        name: 'jq',
+        valuePlaceholder: '<filter>',
+        description:
+          'Apply a jq path-subset filter to the response payload. Examples: ' +
+          '`.schemas.rectangle`, `.schemas.image.properties.data.properties.path`, ' +
+          '`.schemas[]`, `.notes[0]`.',
+      },
+    ],
     outputs: {
       okExample: { categories: [{ name: 'flow', description: 'Top-level flow.json envelope.' }] },
-      errorKinds: ['notFound'],
+      errorKinds: ['notFound', 'badJq'],
     },
     requiresStudio: false,
     examples: [
@@ -640,12 +870,15 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       'seeflow schema node',
       'seeflow schema connector',
       'seeflow schema componentSpec',
+      'seeflow schema node --jq .schemas.rectangle',
+      "seeflow schema node --jq '.schemas.image.properties.data.properties.path'",
+      "seeflow schema node --jq '.schemas[]'",
     ],
   },
   // ---- live --------------------------------------------------------------
   {
     name: 'e2e',
-    synopsis: 'seeflow e2e <flowId> [--skip-nodes a,b] [--no-start]',
+    synopsis: 'seeflow e2e --project <p> --flow <f> [--skip-nodes a,b] [--no-start]',
     description:
       'End-to-end validate a registered flow. Walks every node with a playAction ' +
       "in flow.json order, POSTs each play, then drains the flow's SSE stream " +
@@ -653,8 +886,15 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       'when finished; exits non-zero if any play failed, any statusAction failed ' +
       'to report, or the 120s ceiling was exceeded. Requires a running studio.',
     category: 'live',
-    args: [{ name: 'flowId', required: true, description: 'Flow id or slug' }],
+    args: [],
     flags: [
+      { name: 'project', valuePlaceholder: '<p>', description: 'Project slug', required: true },
+      {
+        name: 'flow',
+        valuePlaceholder: '<f>',
+        description: 'Flow id within the project',
+        required: true,
+      },
       {
         name: 'skip-nodes',
         valuePlaceholder: '<a,b>',
@@ -671,7 +911,10 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       },
     },
     requiresStudio: true,
-    examples: ['seeflow e2e abc12345', 'seeflow e2e abc12345 --skip-nodes flaky-1,flaky-2'],
+    examples: [
+      'seeflow e2e --project order-pipeline --flow main',
+      'seeflow e2e --project order-pipeline --flow main --skip-nodes flaky-1,flaky-2',
+    ],
   },
   {
     name: 'emit',