@tuongaz/seeflow 0.1.57 → 0.1.63

package/src/merge.ts

@@ -76,7 +76,6 @@ const CONNECTOR_FLOW_KEYS = new Set([
   'id',
   'source',
   'target',
-  'kind',
   'label',
   'method',
   'url',

package/src/node-files.ts

@@ -3,9 +3,9 @@ import { dirname, join } from 'node:path';
 import { writeFileAtomic } from './atomic-write.ts';
 
 // Spec for fields that the studio externalizes to disk under
-// `<project>/.seeflow/nodes/<id>/<fileName>`. `nodeTypes` (when present)
-// scopes the spec entry to specific node types; absent means "applies to
-// every node type". Adding a future text field is one line.
+// `<project>/nodes/<id>/<fileName>`. `nodeTypes` (when present) scopes the
+// spec entry to specific node types; absent means "applies to every node
+// type". Adding a future text field is one line.
 export interface ExternalizedFieldSpec {
   field: string;
   fileName: string;
@@ -36,7 +36,7 @@ export const nodeFileRelPath = (nodeId: string, fileName: string): string =>
 export const nodeFileRef = (_nodeId: string, fileName: string): string => `file://${fileName}`;
 
 export const nodeFileAbsPath = (repoPath: string, nodeId: string, fileName: string): string =>
-  join(repoPath, '.seeflow', nodeFileRelPath(nodeId, fileName));
+  join(repoPath, nodeFileRelPath(nodeId, fileName));
 
 export function writeNodeFile(absPath: string, content: string): void {
   mkdirSync(dirname(absPath), { recursive: true });
@@ -44,5 +44,5 @@ export function writeNodeFile(absPath: string, content: string): void {
 }
 
 export function removeNodeDir(repoPath: string, nodeId: string): void {
-  rmSync(join(repoPath, '.seeflow', 'nodes', nodeId), { recursive: true, force: true });
+  rmSync(join(repoPath, 'nodes', nodeId), { recursive: true, force: true });
 }

package/src/operations.ts

@@ -21,8 +21,7 @@ import {
   removeNodeDir,
   writeNodeFile,
 } from './node-files.ts';
-import { seeflowHome } from './paths.ts';
-import { type Registry, slugify } from './registry.ts';
+import type { Registry } from './registry.ts';
 import {
   ColorTokenSchema,
   EdgePinSchema,
@@ -38,11 +37,13 @@ import {
   StyleSchema,
   TargetHandleIdSchema,
 } from './schema.ts';
-import { writeSdkEmitIfNeeded } from './sdk-writer.ts';
 import { shortId } from './short-id.ts';
 import { type FlowSnapshot, type FlowWatcher, readMergedFlow } from './watcher.ts';
 
-const DEFAULT_FLOW_RELATIVE_PATH = '.seeflow/flow.json';
+// Both projects:create and flows:register write/read flow.json at the project
+// root. The studio never assumes a `.seeflow/` subdirectory — whatever path
+// the caller supplies is treated as the seeflow project root.
+const PROJECT_FLOW_RELATIVE_PATH = 'flow.json';
 
 export const RegisterBodySchema = z.object({
   name: z.string().min(1).optional(),
@@ -52,7 +53,9 @@ export const RegisterBodySchema = z.object({
 export type RegisterBody = z.infer<typeof RegisterBodySchema>;
 
 export const CreateProjectBodySchema = z.object({
+  path: z.string().min(1),
   name: z.string().min(1),
+  description: z.string().min(1).optional(),
 });
 export type CreateProjectBody = z.infer<typeof CreateProjectBodySchema>;
 
@@ -96,8 +99,8 @@ export const NodePatchBodySchema = z
     // preserved, and the post-merge ResolvedFlowSchema reparse enforces the
     // new type's required fields (e.g. stateNode → playNode without a
     // playAction in the same body surfaces as `badSchema`). The per-node
-    // folder under `.seeflow/nodes/<id>/` is keyed by id, so retype keeps
-    // scripts, detail.md, and view.html attached.
+    // folder under `nodes/<id>/` is keyed by id, so retype keeps scripts,
+    // detail.md, and view.html attached.
     type: NodeTypeSchema.optional(),
     position: PositionBodySchema.optional(),
     name: z.string().optional(),
@@ -136,8 +139,8 @@ export const NodePatchBodySchema = z
     description: z.string().optional(),
     detail: z.string().optional(),
     // htmlNode-only: inline HTML content. Externalized to
-    // `<project>/.seeflow/nodes/<id>/view.html` by patchNodeImpl; the file://
-    // ref on the node persists. Empty string empties the file but keeps the ref.
+    // `<project>/nodes/<id>/view.html` by patchNodeImpl; the file:// ref on
+    // the node persists. Empty string empties the file but keeps the ref.
     html: z.string().optional(),
     // P5 overlay attach: lets the skill (or any consumer) wire executable
     // behaviour onto a previously-created node without re-issuing it. Final
@@ -283,10 +286,10 @@ export const mergeNodeUpdates = (node: Record<string, unknown>, updates: NodePat
   // (they route to style.json on write); any semantic data key not allowed
   // by the new type's FlowDataSchema is stripped so the post-merge reparse
   // doesn't reject lingering fields. The per-node folder under
-  // `.seeflow/nodes/<id>/` is keyed by id (unchanged), so scripts and
-  // externalized files stay attached. Missing required fields on the new
-  // type (e.g. stateNode → playNode without a playAction in the same patch)
-  // surface as `badSchema` from the ResolvedFlowSchema reparse.
+  // `nodes/<id>/` is keyed by id (unchanged), so scripts and externalized
+  // files stay attached. Missing required fields on the new type (e.g.
+  // stateNode → playNode without a playAction in the same patch) surface as
+  // `badSchema` from the ResolvedFlowSchema reparse.
   if (updates.type !== undefined && updates.type !== node.type) {
     node.type = updates.type;
     const allowedSemantic = SEMANTIC_KEYS_BY_TYPE[updates.type];
@@ -335,12 +338,6 @@ export const mergeNodeUpdates = (node: Record<string, unknown>, updates: NodePat
 export interface OperationsDeps {
   registry: Registry;
   watcher?: FlowWatcher;
-  /**
-   * Override the base directory for new projects. Defaults to seeflowHome()
-   * — `${SEEFLOW_WORKSPACE}/.seeflow` inside Docker, `~/.seeflow` locally.
-   * Tests inject a tmp dir.
-   */
-  projectBaseDir?: string;
 }
 
 export interface FlowListItem {
@@ -365,13 +362,11 @@ export interface FlowGetResponse {
 export interface RegisterFlowSuccess {
   id: string;
   slug: string;
-  sdk: { outcome: 'written' | 'present' | 'skipped'; filePath: string | null };
 }
 
 export interface CreateProjectSuccess {
   id: string;
   slug: string;
-  scaffolded: boolean;
 }
 
 export type ListFlowsOutcome = { kind: 'ok'; data: FlowListItem[] };
@@ -432,17 +427,14 @@ export type RegisterFlowOutcome =
   | { kind: 'ok'; data: RegisterFlowSuccess }
   | { kind: 'fileNotFound'; path: string }
   | { kind: 'badJson'; detail: string }
-  | { kind: 'badSchema'; issues: ZodIssue[] }
-  | { kind: 'sdkWriteFailed'; id: string; slug: string; message: string };
+  | { kind: 'badSchema'; issues: ZodIssue[] };
 
 export type DeleteFlowOutcome = { kind: 'ok' } | { kind: 'notFound' };
 
 export type CreateProjectOutcome =
   | { kind: 'ok'; data: CreateProjectSuccess }
-  | { kind: 'badJson'; detail: string }
-  | { kind: 'badSchema'; issues: ZodIssue[] }
-  | { kind: 'scaffoldFailed'; message: string }
-  | { kind: 'sdkWriteFailed'; message: string };
+  | { kind: 'alreadyExists'; path: string }
+  | { kind: 'scaffoldFailed'; message: string };
 
 // Outcomes for the four node-lifecycle helpers. Every variant lines up with
 // an existing REST error response so api.ts can translate them back to the
@@ -517,9 +509,8 @@ export type PatchNodeOutcome =
   | { kind: 'writeFailed'; message: string };
 
 // Partial connector update body. Strict at the top level so client typos
-// surface as 400. Per-kind invariants (e.g. kind='event' requires eventName)
-// are enforced post-merge by re-parsing the whole demo through ResolvedFlowSchema.
-const ConnectorKindSchema = z.enum(['http', 'event', 'queue', 'default']);
+// surface as 400. Field shape invariants are enforced post-merge by
+// re-parsing the whole demo through ResolvedFlowSchema.
 export const ConnectorPatchBodySchema = z
   .object({
     label: z.string().optional(),
@@ -530,7 +521,6 @@ export const ConnectorPatchBodySchema = z
     path: z.enum(['curve', 'step']).optional(),
     // US-018: per-connector label font size (mirrors NodeVisualBaseShape.fontSize).
     fontSize: z.number().positive().optional(),
-    kind: ConnectorKindSchema.optional(),
     eventName: z.string().optional(),
     queueName: z.string().optional(),
     method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).optional(),
@@ -567,21 +557,10 @@ export const ConnectorPatchBodySchema = z
   .strict();
 export type ConnectorPatchBody = z.infer<typeof ConnectorPatchBodySchema>;
 
-// Kind-specific connector fields. When `kind` changes via PATCH, these are
-// dropped first so the resulting connector doesn't carry phantom payloads
-// from the previous kind (e.g. an event→default change leaving eventName
-// behind, which ResolvedFlowSchema would silently strip on parse but leave on disk).
-const CONNECTOR_KIND_FIELDS = ['method', 'url', 'eventName', 'queueName'] as const;
-
 export const mergeConnectorUpdates = (
   conn: Record<string, unknown>,
   updates: ConnectorPatchBody,
 ): void => {
-  if (updates.kind !== undefined && updates.kind !== conn.kind) {
-    for (const key of CONNECTOR_KIND_FIELDS) {
-      delete conn[key];
-    }
-  }
   for (const [key, value] of Object.entries(updates)) {
     if (value === undefined) continue;
     // US-025: explicit null in the patch body means "clear this field on
@@ -1119,20 +1098,11 @@ export async function registerFlowImpl(
 
   watcher?.watch(entry.id);
 
-  let sdkResult: { outcome: 'written' | 'present' | 'skipped'; filePath: string | null };
-  try {
-    sdkResult = writeSdkEmitIfNeeded(repoPath, merged.flow);
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { kind: 'sdkWriteFailed', id: entry.id, slug: entry.slug, message };
-  }
-
   return {
     kind: 'ok',
     data: {
       id: entry.id,
       slug: entry.slug,
-      sdk: { outcome: sdkResult.outcome, filePath: sdkResult.filePath },
     },
   };
 }
@@ -1151,63 +1121,41 @@ export async function createProjectImpl(
   body: CreateProjectBody,
 ): Promise<CreateProjectOutcome> {
   const { registry, watcher } = deps;
-  const { name } = body;
-  const baseDir = deps.projectBaseDir ?? seeflowHome();
-  const folderPath = join(baseDir, slugify(name));
+  const { path: folderPath, name, description } = body;
 
-  const demoFullPath = join(folderPath, DEFAULT_FLOW_RELATIVE_PATH);
+  const demoFullPath = join(folderPath, PROJECT_FLOW_RELATIVE_PATH);
 
   if (existsSync(demoFullPath)) {
-    let raw: unknown;
-    try {
-      raw = await Bun.file(demoFullPath).json();
-    } catch (err) {
-      return { kind: 'badJson', detail: err instanceof Error ? err.message : String(err) };
-    }
-    const flowParse = FlowSchema.safeParse(raw);
-    if (!flowParse.success) return { kind: 'badSchema', issues: flowParse.error.issues };
-
-    const lastModified = statSync(demoFullPath).mtimeMs;
-    const entry = registry.upsert({
-      name,
-      repoPath: folderPath,
-      flowPath: DEFAULT_FLOW_RELATIVE_PATH,
-      valid: true,
-      lastModified,
-    });
-    watcher?.watch(entry.id);
-    return { kind: 'ok', data: { id: entry.id, slug: entry.slug, scaffolded: false } };
+    return { kind: 'alreadyExists', path: folderPath };
   }
 
   // Flow-only scaffold: empty nodes/connectors, no style.json needed.
-  const scaffold: Flow = { version: 2, name, nodes: [], connectors: [] };
+  const scaffold: Flow = {
+    version: 2,
+    name,
+    ...(description !== undefined ? { description } : {}),
+    nodes: [],
+    connectors: [],
+  };
 
   try {
-    mkdirSync(join(folderPath, '.seeflow'), { recursive: true });
+    mkdirSync(folderPath, { recursive: true });
     writeFileSync(demoFullPath, `${JSON.stringify(scaffold, null, 2)}\n`);
   } catch (err) {
     return { kind: 'scaffoldFailed', message: err instanceof Error ? err.message : String(err) };
   }
 
-  // Same SDK-emit path as the CLI register flow. For a fresh scaffold with no
-  // event-bound state nodes this returns 'skipped' and writes nothing —
-  // retained for parity with `seeflow register`.
-  try {
-    writeSdkEmitIfNeeded(folderPath, scaffold);
-  } catch (err) {
-    return { kind: 'sdkWriteFailed', message: err instanceof Error ? err.message : String(err) };
-  }
-
   const lastModified = statSync(demoFullPath).mtimeMs;
   const entry = registry.upsert({
     name,
+    description,
     repoPath: folderPath,
-    flowPath: DEFAULT_FLOW_RELATIVE_PATH,
+    flowPath: PROJECT_FLOW_RELATIVE_PATH,
     valid: true,
     lastModified,
   });
   watcher?.watch(entry.id);
-  return { kind: 'ok', data: { id: entry.id, slug: entry.slug, scaffolded: true } };
+  return { kind: 'ok', data: { id: entry.id, slug: entry.slug } };
 }
 
 // Append a new node to the demo. Auto-generates an id when absent; ResolvedFlowSchema
@@ -1346,9 +1294,6 @@ export async function addFlowBulkImpl(
     if (typeof newConn.id !== 'string' || newConn.id.length === 0) {
       newConn.id = `conn-${shortId()}`;
     }
-    if (typeof newConn.kind !== 'string' || newConn.kind.length === 0) {
-      newConn.kind = 'default';
-    }
     const newId = newConn.id as string;
     if (connIdsInBatch.has(newId)) {
       return { kind: 'duplicateIdInBatch', collection: 'connectors', id: newId };
@@ -1432,8 +1377,8 @@ export async function addFlowBulkImpl(
 // atomic write. Final ResolvedFlowSchema parse stays in place so a pre-existing
 // schema violation surfaces honestly instead of being silently papered over.
 // After the flow.json write, `removeNodeDir` cascades the node's whole
-// `<project>/.seeflow/nodes/<id>/` folder — covering detail.md, view.html,
-// and any imageNode upload that lived there.
+// `<project>/nodes/<id>/` folder — covering detail.md, view.html, and any
+// imageNode upload that lived there.
 export async function deleteNodeImpl(
   deps: OperationsDeps,
   flowId: string,
@@ -1617,9 +1562,6 @@ export async function addConnectorImpl(
   if (typeof newConn.id !== 'string' || newConn.id.length === 0) {
     newConn.id = `conn-${shortId()}`;
   }
-  if (typeof newConn.kind !== 'string' || newConn.kind.length === 0) {
-    newConn.kind = 'default';
-  }
   const newId = newConn.id as string;
 
   const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
@@ -1636,13 +1578,10 @@ export async function addConnectorImpl(
 
 // Apply a partial PATCH body to a single connector. Mutation runs against
 // the raw parsed JSON (so unknown forward-compat fields survive a round-trip).
-// When `kind` changes, the previous kind's payload fields are dropped first
-// so the connector doesn't carry phantom data; explicit `null` in the patch
-// clears the field on disk (used by reconnect-to-body to drop a pinned
-// handle id). The whole demo is re-validated through ResolvedFlowSchema before
-// commit so the discriminated union catches missing-required-fields
-// (e.g. kind='event' without eventName) and the superRefine gates
-// source/target referential integrity + handle role invariants.
+// Explicit `null` in the patch clears the field on disk (used by
+// reconnect-to-body to drop a pinned handle id). The whole demo is
+// re-validated through ResolvedFlowSchema before commit so the superRefine
+// gates source/target referential integrity + handle role invariants.
 export async function patchConnectorImpl(
   deps: OperationsDeps,
   flowId: string,

package/src/paths.ts

@@ -11,3 +11,19 @@ export function seeflowHome(): string {
   if (workspace && workspace.length > 0) return join(workspace, '.seeflow');
   return join(homedir(), '.seeflow');
 }
+
+// Per-project layout: everything lives at the project root. The studio never
+// assumes a `.seeflow/` subdirectory — whatever path the CLI / API was handed
+// is treated as the seeflow project root. The `/seeflow` skill creates a
+// `<host>/.seeflow/<flow-name>/` container per flow and passes that as the
+// project path, but that's a skill convention, not a studio rule.
+export const PROJECT_FLOW_FILENAME = 'flow.json';
+
+export const projectFlowPath = (repoPath: string): string => join(repoPath, PROJECT_FLOW_FILENAME);
+
+export const projectNodesRoot = (repoPath: string): string => join(repoPath, 'nodes');
+
+export const projectNodeDir = (repoPath: string, nodeId: string): string =>
+  join(repoPath, 'nodes', nodeId);
+
+export const projectSdkDir = (repoPath: string): string => join(repoPath, 'sdk');

package/src/proxy.ts

@@ -8,7 +8,7 @@
  *
  * Defense-in-depth on scriptPath: schema.ts already rejects absolute paths
  * and `..` traversal textually. Here we additionally realpath-resolve the
- * script under `<cwd>/.seeflow/` and reject anything that escapes that root —
+ * script under the project root and reject anything that escapes that root —
  * symlink-escape defense in line with `resolveProjectFile` in api.ts.
  */
 
@@ -34,7 +34,7 @@ export interface RunPlayOptions {
   events: EventBus;
   flowId: string;
   nodeId: string;
-  /** Project root (`<repoPath>`). Script resolves under `<cwd>/.seeflow/`. */
+  /** Project root (`<repoPath>`). Script resolves under `<cwd>/nodes/<nodeId>/`. */
   cwd: string;
   action: PlayAction;
   /** Injectable for tests; defaults to `defaultProcessSpawner`. */
@@ -48,11 +48,11 @@ const SCRIPT_PATH_ESCAPE = 'scriptPath escapes project root';
 
 type Resolved = { ok: true; absPath: string } | { ok: false };
 
-// Resolve `<cwd>/.seeflow/nodes/<nodeId>/<scriptPath>` and verify via realpath
-// it stays inside the node folder. The per-node anchor means scriptPath is
+// Resolve `<cwd>/nodes/<nodeId>/<scriptPath>` and verify via realpath it
+// stays inside the node folder. The per-node anchor means scriptPath is
 // "scripts/play.ts" — no node id leaks into its own path.
 function resolveScript(cwd: string, nodeId: string, scriptPath: string): Resolved {
-  const nodeRoot = join(cwd, '.seeflow', 'nodes', nodeId);
+  const nodeRoot = join(cwd, 'nodes', nodeId);
   let realRoot: string;
   try {
     realRoot = realpathSync(nodeRoot);
@@ -74,17 +74,17 @@ function resolveScript(cwd: string, nodeId: string, scriptPath: string): Resolve
 }
 
 // Legacy anchor for resetAction (kept until resetAction gets its own design
-// round). Same realpath escape check as resolveScript, but rooted at
-// <cwd>/.seeflow/ rather than a per-node folder.
+// round). Same realpath escape check as resolveScript, but rooted at the
+// project root rather than a per-node folder.
 function resolveResetScript(cwd: string, scriptPath: string): Resolved {
-  const seeflowRoot = join(cwd, '.seeflow');
+  const projectRoot = cwd;
   let realRoot: string;
   try {
-    realRoot = realpathSync(seeflowRoot);
+    realRoot = realpathSync(projectRoot);
   } catch {
     return { ok: false };
   }
-  const target = resolve(seeflowRoot, scriptPath);
+  const target = resolve(projectRoot, scriptPath);
   let realTarget: string;
   try {
     realTarget = realpathSync(target);
@@ -307,7 +307,7 @@ export async function runPlay(options: RunPlayOptions): Promise<PlayResult> {
 export interface RunResetOptions {
   events: EventBus;
   flowId: string;
-  /** Project root (`<repoPath>`). Script resolves under `<cwd>/.seeflow/`. */
+  /** Project root (`<repoPath>`). Script resolves under `<cwd>/`. */
   cwd: string;
   action: ResetAction;
   /** Injectable for tests; defaults to `defaultProcessSpawner`. */
@@ -330,8 +330,8 @@ export async function runReset(options: RunResetOptions): Promise<ResetResult> {
   const { events, flowId, cwd, action } = options;
   const spawner = options.spawner ?? defaultProcessSpawner;
 
-  // resetAction stays anchored at .seeflow/ for now — design defers per-node
-  // resetAction to a later round (decision #7). Mirrors the previous behaviour.
+  // resetAction is anchored at the project root — design defers per-node
+  // resetAction to a later round (decision #7).
   const resolved = resolveResetScript(cwd, action.scriptPath);
   if (!resolved.ok) {
     events.broadcast({

package/src/schema-catalog.ts

@@ -0,0 +1,114 @@
+// Single source of truth for runtime schema introspection. The CLI
+// (`seeflow schema`), the MCP tool (`seeflow_schema`), and the REST routes
+// (`GET /api/schema[/:name]`) all delegate here so the agent-facing surface
+// stays in lockstep with the on-disk Zod schemas in schema.ts. Built once at
+// module load — each call returns a fresh shallow copy so callers can't
+// mutate the cached payload.
+
+import type { ZodTypeAny } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import {
+  FlowConnectorSchema,
+  FlowEnvelopeSchema,
+  FlowHtmlNodeSchema,
+  FlowIconNodeSchema,
+  FlowImageNodeSchema,
+  FlowPlayNodeSchema,
+  FlowShapeNodeSchema,
+  FlowStateNodeSchema,
+  PlayActionSchema,
+  ResetActionSchema,
+  StatusActionSchema,
+  StatusReportSchema,
+  StyleSchema,
+} from './schema.ts';
+
+export interface SchemaCategory {
+  name: string;
+  description: string;
+}
+
+export interface SchemaPayload {
+  schemas: Record<string, unknown>;
+  notes: string[];
+}
+
+// Draft-07 pin matches the widest tool support; the same target string is
+// used by the MCP `tools/list` JSON Schemas (default in zod-to-json-schema)
+// so consumers see one consistent dialect across the whole surface.
+const toJsonSchema = (schema: ZodTypeAny): unknown =>
+  zodToJsonSchema(schema, { $refStrategy: 'none', target: 'jsonSchema7' });
+
+const CATEGORIES: SchemaCategory[] = [
+  { name: 'flow', description: 'Top-level flow.json envelope.' },
+  {
+    name: 'node',
+    description:
+      'All six node variants (playNode, stateNode, shapeNode, imageNode, iconNode, htmlNode).',
+  },
+  {
+    name: 'connector',
+    description: 'Edge between two nodes (id/source/target + optional label/style/metadata).',
+  },
+  {
+    name: 'action',
+    description: 'playAction, statusAction, resetAction, statusReport.',
+  },
+  { name: 'style', description: 'style.json (studio-owned).' },
+];
+
+const PAYLOADS: Record<string, SchemaPayload> = {
+  flow: {
+    schemas: { flow: toJsonSchema(FlowEnvelopeSchema) },
+    notes: ['connectors[].source and connectors[].target must reference an existing nodes[].id.'],
+  },
+  node: {
+    schemas: {
+      playNode: toJsonSchema(FlowPlayNodeSchema),
+      stateNode: toJsonSchema(FlowStateNodeSchema),
+      shapeNode: toJsonSchema(FlowShapeNodeSchema),
+      imageNode: toJsonSchema(FlowImageNodeSchema),
+      iconNode: toJsonSchema(FlowIconNodeSchema),
+      htmlNode: toJsonSchema(FlowHtmlNodeSchema),
+    },
+    notes: [
+      "imageNode.data.path must start with 'nodes/<id>/'.",
+      "scriptPath in playAction/statusAction is relative to nodes/<nodeId>/ and may not contain '..' or absolute paths.",
+    ],
+  },
+  connector: {
+    schemas: {
+      connector: toJsonSchema(FlowConnectorSchema),
+    },
+    notes: [],
+  },
+  action: {
+    schemas: {
+      playAction: toJsonSchema(PlayActionSchema),
+      statusAction: toJsonSchema(StatusActionSchema),
+      resetAction: toJsonSchema(ResetActionSchema),
+      statusReport: toJsonSchema(StatusReportSchema),
+    },
+    notes: [
+      "scriptPath in playAction/statusAction is relative to nodes/<nodeId>/ and may not contain '..' or absolute paths.",
+    ],
+  },
+  style: {
+    schemas: { style: toJsonSchema(StyleSchema) },
+    notes: [],
+  },
+};
+
+export function listSchemaCategories(): SchemaCategory[] {
+  return CATEGORIES.map((c) => ({ ...c }));
+}
+
+export function getSchemaCategory(name: string): SchemaPayload | null {
+  const payload = PAYLOADS[name];
+  if (!payload) return null;
+  return { schemas: { ...payload.schemas }, notes: [...payload.notes] };
+}
+
+export function schemaCategoryNames(): string[] {
+  return CATEGORIES.map((c) => c.name);
+}