@chalksurf/cli 0.3.3 → 0.3.4

package/dist/bin/chalksurf.js

@@ -20,6 +20,27 @@ var ApiClientError = class extends Error {
 var normalizeBaseUrl = (baseUrl) => {
   return baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
 };
+var getSafeBaseUrlForError = (baseUrl) => {
+  const url = new URL(baseUrl);
+  url.username = "";
+  url.password = "";
+  url.search = "";
+  url.hash = "";
+  const safeBaseUrl = url.toString();
+  return safeBaseUrl.endsWith("/") ? safeBaseUrl : `${safeBaseUrl}/`;
+};
+var getSafeNetworkCause = ({ error, token }) => {
+  if (!(error instanceof Error)) {
+    return void 0;
+  }
+  const causeCode = typeof error.cause === "object" && error.cause !== null && "code" in error.cause && typeof error.cause.code === "string" && /^[A-Z0-9_]+$/.test(error.cause.code) ? error.cause.code : void 0;
+  const errorMessage = error.message.trim();
+  const combinedCause = [causeCode, errorMessage].filter(Boolean).join(": ");
+  if (combinedCause.length === 0 || combinedCause.length > 200 || /authorization|bearer|password|secret|token/iu.test(combinedCause) || token && combinedCause.includes(token)) {
+    return void 0;
+  }
+  return combinedCause;
+};
 var getErrorMessage = (payload, status) => {
   return payload?.error?.message ?? `API request failed with status ${status}`;
 };
@@ -51,6 +72,7 @@ var createApiClient = ({
   organizationId
 }) => {
   const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
+  const safeBaseUrlForError = getSafeBaseUrlForError(normalizedBaseUrl);
   const createHeaders = ({ includeJsonContentType }) => {
     const headers = new Headers();
     if (token) {
@@ -64,11 +86,21 @@ var createApiClient = ({
     }
     return headers;
   };
+  const fetchApi = async (url, init) => {
+    try {
+      return await fetch(url, init);
+    } catch (error) {
+      const safeCause = getSafeNetworkCause({ error, token });
+      throw new ApiClientError(
+        `Could not reach ChalkSurf API at ${safeBaseUrlForError}.${safeCause ? ` Cause: ${safeCause}` : ""}`
+      );
+    }
+  };
   const query = async (procedureName, input) => {
     const url = new URL(`trpc/${procedureName}`, normalizedBaseUrl);
     url.searchParams.set("batch", "1");
     url.searchParams.set("input", JSON.stringify({ 0: input ?? null }));
-    const response = await fetch(url.toString(), {
+    const response = await fetchApi(url.toString(), {
       method: "GET",
       headers: createHeaders({ includeJsonContentType: false })
     });
@@ -76,7 +108,7 @@ var createApiClient = ({
   };
   const mutation = async (procedureName, input) => {
     const isFormDataInput = input instanceof FormData;
-    const response = await fetch(new URL(`trpc/${procedureName}`, normalizedBaseUrl).toString(), {
+    const response = await fetchApi(new URL(`trpc/${procedureName}`, normalizedBaseUrl).toString(), {
       method: "POST",
       headers: createHeaders({ includeJsonContentType: !isFormDataInput }),
       body: isFormDataInput ? input : JSON.stringify(input ?? {})
@@ -140,9 +172,6 @@ var createApiClient = ({
     agentUploadExerciseFigure: async (input) => {
       return await mutation("agentUploadExerciseFigure", input);
     },
-    agentAttachExerciseFigures: async (input) => {
-      return await mutation("agentAttachExerciseFigures", input);
-    },
     agentUpdateExercise: async (input) => {
       return await mutation("agentUpdateExercise", input);
     },
@@ -182,8 +211,11 @@ var createApiClient = ({
     agentBulkUpdateSheets: async (input) => {
       return await mutation("agentBulkUpdateSheets", input);
     },
-    agentListSheetSeries: async () => {
-      return await query("agentListSheetSeries", {});
+    agentListSheets: async (input) => {
+      return await query("agentListSheets", input);
+    },
+    agentListSheetSeries: async (input = {}) => {
+      return await query("agentListSheetSeries", input);
     },
     agentSetSheetVisibility: async (input) => {
       return await mutation("agentSetSheetVisibility", input);
@@ -931,7 +963,6 @@ import { z as z2 } from "zod";
 var exerciseStatusOptions = Constants.public.Enums.exercise_status;
 var exerciseQualityIssueSeverities = Constants.public.Enums.exercise_quality_issue_severity;
 var exerciseQualityIssueStatuses = Constants.public.Enums.exercise_quality_issue_status;
-var figureAssetSourceKinds = Constants.public.Enums.figure_asset_source_kind;
 var exerciseFigureRowSourceKinds = Constants.public.Enums.exercise_figure_source_kind;
 var exerciseFigureRenditionPurposes = Constants.public.Enums.exercise_figure_rendition_purpose;
 var exerciseVersionTypes = Constants.public.Enums.exercise_version_type;
@@ -1440,12 +1471,6 @@ var agentWriteOperationRegistry = {
   upload_exercise_figure: {
     agentToolName: "upload_exercise_figure",
     receiptOperation: "upload_exercise_figure",
-    resourceType: "figure_asset",
-    sync: true
-  },
-  attach_exercise_figures: {
-    agentToolName: "attach_exercise_figures",
-    receiptOperation: "attach_exercise_figures",
     resourceType: "exercise",
     sync: true
   },
@@ -1596,15 +1621,17 @@ var exerciseTranslationSchema = strictObject({
   status: z3.enum(exerciseStatusOptions)
 });
 var exerciseFigureWidthSchema = z3.number().finite().min(minExerciseFigureWidthInCm).max(maxExerciseFigureWidthInCm);
-var agentLegacyExerciseFigureSchema = strictObject({
+var agentExerciseFigureInputSchema = strictObject({
   type: z3.enum(exerciseFigureTypes),
   url: z3.url(),
   widthInCm: exerciseFigureWidthSchema,
   exerciseFigureId: uuidSchema.optional(),
-  figureAssetId: uuidSchema.optional(),
+  orderIndex: z3.number().int().min(0).optional(),
+  rotationClockwiseDegrees: exerciseFigureRotationSchema.optional(),
   provenance: exerciseFigureProvenanceSchema.optional()
 });
-var agentExerciseFigureSchema = agentLegacyExerciseFigureSchema.extend({
+var agentExerciseFigureSchema = agentExerciseFigureInputSchema.extend({
+  exerciseFigureId: uuidSchema,
   orderIndex: z3.number().int().min(0),
   rotationClockwiseDegrees: exerciseFigureRotationSchema
 });
@@ -1703,6 +1730,34 @@ var folderSchema = strictObject({
   parentId: uuidSchema.nullable(),
   updatedAt: dateStringSchema
 });
+var folderPathSegmentSchema = strictObject({
+  id: uuidSchema,
+  name: z3.string().trim().min(1)
+});
+var listSheetsAgentInputSchema = strictObject({
+  folderId: uuidSchema.optional(),
+  includeDescendants: z3.boolean().optional().default(false),
+  limit: z3.number().int().min(1).max(100).optional().default(50),
+  offset: z3.number().int().min(0).optional().default(0)
+}).refine(({ folderId, includeDescendants }) => folderId !== void 0 || !includeDescendants, {
+  message: "folderId is required when includeDescendants is true",
+  path: ["folderId"]
+});
+var listSheetsAgentOutputSchema = strictObject({
+  sheets: z3.array(
+    strictObject({
+      id: uuidSchema,
+      name: z3.string().trim().min(1),
+      subject: z3.enum(exerciseSubjects),
+      isPublic: z3.boolean(),
+      folderId: uuidSchema.nullable(),
+      folderPath: z3.array(folderPathSegmentSchema),
+      updatedAt: dateStringSchema,
+      seriesAssignments: sheetSeriesAssignmentsSchema
+    })
+  ),
+  totalCount: z3.number().int().min(0)
+});
 var exerciseLabelSchema = strictObject({
   id: z3.string().trim().min(1),
   subject: z3.enum(exerciseSubjects),
@@ -1955,7 +2010,7 @@ var getExerciseUsageAgentOutputSchema = strictObject({
 });
 var agentWriteReceiptSchema = strictObject({
   resource: strictObject({
-    type: z3.enum(["exercise", "sheet", "folder", "figure_asset"]),
+    type: z3.enum(["exercise", "sheet", "folder"]),
     id: uuidSchema
   }),
   operation: agentWriteReceiptOperationSchema,
@@ -2031,14 +2086,6 @@ var exerciseCreateFigureSchema = strictObject({
   widthInCm: z3.number().positive().finite().optional(),
   provenance: exerciseFigureProvenanceSchema.optional()
 });
-var agentExerciseFigureInputSchema = strictObject({
-  type: z3.enum(exerciseFigureTypes),
-  url: z3.url(),
-  widthInCm: exerciseFigureWidthSchema.optional(),
-  exerciseFigureId: uuidSchema.optional(),
-  figureAssetId: uuidSchema.optional(),
-  provenance: exerciseFigureProvenanceSchema.optional()
-});
 var figureReviewWarningSchema = strictObject({
   code: z3.string().trim().min(1),
   message: z3.string().trim().min(1),
@@ -2066,7 +2113,7 @@ var uploadExerciseFigureSourceSchema = z3.discriminatedUnion("kind", [
   })
 ]);
 var uploadExerciseFigureAgentInputSchema = strictObject({
-  exerciseId: uuidSchema.optional(),
+  exerciseId: uuidSchema,
   figureType: z3.enum(exerciseFigureTypes),
   source: uploadExerciseFigureSourceSchema,
   widthInCm: exerciseFigureWidthSchema.optional().default(defaultExerciseFigureWidthInCm),
@@ -2083,53 +2130,10 @@ var figureUploadReviewSchema = strictObject({
   nextActions: z3.array(z3.string().trim().min(1))
 });
 var uploadExerciseFigureAgentOutputSchema = strictObject({
-  figure: z3.union([agentExerciseFigureSchema, agentLegacyExerciseFigureSchema]),
+  figure: agentExerciseFigureSchema,
   review: figureUploadReviewSchema,
   receipt: agentWriteReceiptSchema
 });
-var attachExerciseFiguresAgentInputSchema = strictObject({
-  exerciseId: uuidSchema,
-  expectedUpdatedAt: expectedUpdatedAtSchema,
-  targetSheetId: uuidSchema.nullable().optional(),
-  allowSharedExerciseUpdate: z3.boolean().optional().default(false),
-  mode: z3.enum(["append", "replace_type", "replace_all"]),
-  figureType: z3.enum(exerciseFigureTypes).optional(),
-  figures: z3.array(agentExerciseFigureInputSchema)
-}).superRefine((input, ctx) => {
-  if (input.mode === "append" && input.figures.length === 0) {
-    ctx.addIssue({
-      code: z3.ZodIssueCode.custom,
-      message: "append mode requires at least one figure.",
-      path: ["figures"]
-    });
-  }
-  if (input.mode === "replace_type" && !input.figureType) {
-    ctx.addIssue({
-      code: z3.ZodIssueCode.custom,
-      message: "replace_type mode requires figureType.",
-      path: ["figureType"]
-    });
-  }
-  if (input.mode !== "replace_type" && input.figureType) {
-    ctx.addIssue({
-      code: z3.ZodIssueCode.custom,
-      message: "figureType is only supported for replace_type mode.",
-      path: ["figureType"]
-    });
-  }
-  if (input.mode === "replace_type" && input.figureType) {
-    input.figures.forEach((figure, index) => {
-      if (figure.type !== input.figureType) {
-        ctx.addIssue({
-          code: z3.ZodIssueCode.custom,
-          message: "Replacement figures must match figureType.",
-          path: ["figures", index, "type"]
-        });
-      }
-    });
-  }
-});
-var attachExerciseFiguresAgentOutputSchema = agentWriteReceiptOutputSchema;
 var exercisePatchMetadataSchema = strictObject({
   sourceUrl: patchNullableStringSchema,
   solutionUrl: patchNullableStringSchema
@@ -2363,12 +2367,15 @@ var mcpPublicErrorCodes = [
   "storage_upload_failed",
   "unsupported_image",
   "validation_failed",
+  "organization_selection_required",
+  "organization_access_denied",
   "internal_error"
 ];
+var mcpPublicErrorCodeSchema = z5.enum(mcpPublicErrorCodes);
 var mcpToolErrorOutputSchema = strictObject2({
   isError: z5.literal(true),
   error: strictObject2({
-    code: z5.enum(mcpPublicErrorCodes),
+    code: mcpPublicErrorCodeSchema,
     message: z5.string().trim().min(1),
     agentErrorDetails: agentErrorDetailsSchema.optional()
   })
@@ -2416,7 +2423,7 @@ var userSchema = strictObject2({
   email: z5.string().email().nullable(),
   name: z5.string().nullable()
 });
-var organizationSchema = strictObject2({
+var mcpOrganizationSchema = strictObject2({
   id: z5.uuid(),
   name: z5.string(),
   mcpPermission: z5.enum(mcpOAuthGrantPermissions).nullable().optional(),
@@ -2549,14 +2556,31 @@ var chalksurfMcpScopes = {
 var getAuthStatusInputSchema = strictObject2({});
 var getAuthStatusOutputSchema = strictObject2({
   authenticated: z5.literal(true),
+  organizations: z5.array(mcpOrganizationSchema),
   selectedOrganizationId: z5.uuid().nullable(),
   user: userSchema
 });
 var listOrganizationsInputSchema = strictObject2({});
 var listOrganizationsOutputSchema = strictObject2({
-  organizations: z5.array(organizationSchema),
+  organizations: z5.array(mcpOrganizationSchema),
   selectedOrganizationId: z5.uuid().nullable()
 });
+var mcpOrganizationRecoveryOutputSchema = strictObject2({
+  isError: z5.literal(true),
+  error: strictObject2({
+    code: z5.enum(["organization_selection_required", "organization_access_denied"]),
+    message: z5.string().trim().min(1)
+  }),
+  organizations: z5.array(
+    strictObject2({
+      id: z5.uuid(),
+      name: z5.string(),
+      permission: z5.enum(mcpOAuthGrantPermissions),
+      role: z5.enum(["owner", "editor", "viewer"]),
+      type: z5.enum(["personal", "team"])
+    })
+  )
+});
 var searchExercisesInputSchema = strictObject2({
   organizationId: organizationIdSchema,
   age: z5.number().int().nullish(),
@@ -2587,9 +2611,7 @@ var getExerciseUsageInputSchema = getExerciseUsageAgentInputSchema.extend({
   organizationId: organizationIdSchema
 });
 var getExerciseUsageOutputSchema = getExerciseUsageAgentOutputSchema;
-var listExerciseLabelsInputSchema = listExerciseLabelsAgentInputSchema.extend({
-  organizationId: organizationIdSchema
-});
+var listExerciseLabelsInputSchema = listExerciseLabelsAgentInputSchema;
 var listExerciseLabelsOutputSchema = listExerciseLabelsAgentOutputSchema;
 var copyExerciseInputSchema = copyExerciseAgentInputSchema.extend({
   organizationId: organizationIdSchema
@@ -2662,13 +2684,15 @@ var searchSheetsOutputSchema = strictObject2({
   ),
   totalCount: z5.number().int().min(0)
 });
-var getSheetInputSchema = getSheetAgentInputSchema.extend({
+var listSheetsInputSchema = listSheetsAgentInputSchema.extend({
   organizationId: organizationIdSchema
 });
-var getSheetOutputSchema = getSheetAgentOutputSchema;
-var listSheetSeriesInputSchema = listSheetSeriesAgentInputSchema.extend({
+var listSheetsOutputSchema = listSheetsAgentOutputSchema;
+var getSheetInputSchema = getSheetAgentInputSchema.extend({
   organizationId: organizationIdSchema
 });
+var getSheetOutputSchema = getSheetAgentOutputSchema;
+var listSheetSeriesInputSchema = listSheetSeriesAgentInputSchema;
 var listSheetSeriesOutputSchema = listSheetSeriesAgentOutputSchema;
 var listSheetVersionsInputSchema = listSheetVersionsAgentInputSchema.extend({
   organizationId: organizationIdSchema
@@ -2738,9 +2762,7 @@ var renameFolderInputSchema = renameFolderAgentInputSchema.extend({
   organizationId: organizationIdSchema
 });
 var renameFolderOutputSchema = renameFolderAgentOutputSchema;
-var validateLatexSnippetsInputSchema = validateLatexSnippetsAgentInputSchema.extend({
-  organizationId: organizationIdSchema
-});
+var validateLatexSnippetsInputSchema = validateLatexSnippetsAgentInputSchema;
 var validateLatexSnippetsOutputSchema = validateLatexSnippetsAgentOutputSchema;
 var importSheetInputSchema = strictObject2({
   organizationId: organizationIdSchema,
@@ -3497,6 +3519,7 @@ var uploadExerciseFigureInputSchema = uploadExerciseFigureAgentInputSchema.exten
 });
 var uploadExerciseFigureMcpToolInputSchema = strictObject2({
   organizationId: organizationIdSchema,
+  exerciseId: z5.uuid(),
   figureType: z5.enum(exerciseFigureTypes),
   ...chatGptFigureUploadFileParamInputShape,
   source: strictObject2({
@@ -3513,10 +3536,6 @@ var uploadExerciseFigureMcpToolInputSchema = strictObject2({
   allowNeedsRevision: z5.boolean().optional()
 }).passthrough();
 var uploadExerciseFigureOutputSchema = uploadExerciseFigureAgentOutputSchema;
-var attachExerciseFiguresInputSchema = attachExerciseFiguresAgentInputSchema.extend({
-  organizationId: organizationIdSchema
-});
-var attachExerciseFiguresOutputSchema = attachExerciseFiguresAgentOutputSchema;
 var chalksurfMcpToolCapabilities = {
   get_auth_status: {
     name: "get_auth_status",
@@ -3672,6 +3691,16 @@ var chalksurfMcpToolCapabilities = {
     requiredPermission: "read",
     security: { type: "oauth2", scopes: [chalksurfMcpScopes.read] }
   },
+  list_sheets: {
+    name: "list_sheets",
+    title: "List sheets",
+    description: "Use this to list exercise sheets owned by a ChalkSurf organization and inspect their folder paths and series assignments.",
+    inputSchema: listSheetsInputSchema,
+    outputSchema: listSheetsOutputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    requiredPermission: "read",
+    security: { type: "oauth2", scopes: [chalksurfMcpScopes.read] }
+  },
   get_sheet: {
     name: "get_sheet",
     title: "Get sheet",
@@ -3950,7 +3979,7 @@ var chalksurfMcpToolCapabilities = {
   upload_exercise_figure: {
     name: "upload_exercise_figure",
     title: "Upload exercise figure",
-    description: "Use this to attach one reviewed image, MCP file, HTTPS image, base64 image, or rendered figure to an exercise by providing exerciseId, figureType, source, and width. Uploading without exerciseId is a temporary compatibility path only.",
+    description: "Use this to attach one reviewed image, MCP file, HTTPS image, base64 image, or rendered figure to an exercise by providing exerciseId, figureType, source, and width.",
     inputSchema: uploadExerciseFigureInputSchema,
     mcpInputSchema: uploadExerciseFigureMcpToolInputSchema,
     outputSchema: uploadExerciseFigureOutputSchema,
@@ -3958,16 +3987,6 @@ var chalksurfMcpToolCapabilities = {
     requiredPermission: "write",
     security: { type: "oauth2", scopes: [chalksurfMcpScopes.write] },
     fileParams: chatGptFigureUploadFileParamNames
-  },
-  attach_exercise_figures: {
-    name: "attach_exercise_figures",
-    title: "Attach exercise figures",
-    description: "Deprecated compatibility tool. Use upload_exercise_figure with exerciseId for new figures; use this only to attach already-uploaded compatibility URLs or replace existing figure lists.",
-    inputSchema: attachExerciseFiguresInputSchema,
-    outputSchema: attachExerciseFiguresOutputSchema,
-    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    requiredPermission: "write",
-    security: { type: "oauth2", scopes: [chalksurfMcpScopes.write] }
   }
 };
 
@@ -8719,29 +8738,106 @@ ${formatOrganizationSummary(result.organization)}`,
 };
 
 // src/commands/exercise.ts
-import { readFile as readFile3 } from "node:fs/promises";
-import { basename as basename2, extname as extname2, isAbsolute as isAbsolute2, resolve as resolve4 } from "node:path";
+import { readFile as readFile4 } from "node:fs/promises";
+import { basename as basename2, extname as extname2, isAbsolute as isAbsolute2, resolve as resolve5 } from "node:path";
 import { z as z13 } from "zod";
 
-// src/lib/agent-patch.ts
-var formatZodIssues = (issues) => {
-  return issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; ");
+// src/lib/json-input.ts
+import { readFile as readFile2, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+var isInteractiveStdin2 = (stdin) => {
+  return stdin.isTTY === true;
 };
-var parseJsonObjectFlag = ({ label, value }) => {
-  if (value === void 0) {
-    throw new CliCommandError(`${label} is required.`, 2);
+var readTextFromStdin = async (stdin) => {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
   }
+  return Buffer.concat(chunks).toString("utf8");
+};
+var parseJsonObjectText = ({
+  invalidJsonMessage,
+  nonObjectMessage,
+  text
+}) => {
   let parsedValue;
   try {
-    parsedValue = JSON.parse(value);
+    parsedValue = JSON.parse(text);
   } catch {
-    throw new CliCommandError(`${label} must be valid JSON.`, 2);
+    throw new CliCommandError(invalidJsonMessage, 2);
   }
   if (typeof parsedValue !== "object" || parsedValue === null || Array.isArray(parsedValue)) {
-    throw new CliCommandError(`${label} must be a JSON object.`, 2);
+    throw new CliCommandError(nonObjectMessage, 2);
   }
   return parsedValue;
 };
+var loadJsonObjectInput = async ({
+  cwd,
+  inputJson,
+  inputPath,
+  stdin
+}) => {
+  if (inputPath !== void 0 && inputJson !== void 0) {
+    throw new CliCommandError("Pass --input or --input-json, not both.", 2);
+  }
+  if (inputPath === void 0 && inputJson === void 0) {
+    throw new CliCommandError("One of --input or --input-json is required.", 2);
+  }
+  if (inputJson !== void 0) {
+    return parseJsonObjectText({
+      invalidJsonMessage: "--input-json must be valid JSON.",
+      nonObjectMessage: "--input-json must be a JSON object.",
+      text: inputJson
+    });
+  }
+  if (inputPath === "-") {
+    if (isInteractiveStdin2(stdin)) {
+      throw new CliCommandError('No JSON was piped on stdin. Pipe JSON into "--input -".', 2);
+    }
+    const inputText = await readTextFromStdin(stdin);
+    if (inputText.trim().length === 0) {
+      throw new CliCommandError('No JSON was piped on stdin. Pipe JSON into "--input -".', 2);
+    }
+    return parseJsonObjectText({
+      invalidJsonMessage: "Standard input must contain valid JSON.",
+      nonObjectMessage: "Standard input must contain a JSON object.",
+      text: inputText
+    });
+  }
+  const resolvedInputPath = resolve(cwd, inputPath);
+  let inputStats;
+  try {
+    inputStats = await stat(resolvedInputPath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new CliCommandError(`Input file "${inputPath}" does not exist.`, 2);
+    }
+    throw error;
+  }
+  if (!inputStats.isFile()) {
+    throw new CliCommandError(`Input path "${inputPath}" is not a file.`, 2);
+  }
+  return parseJsonObjectText({
+    invalidJsonMessage: `Input file "${inputPath}" must contain valid JSON.`,
+    nonObjectMessage: `Input file "${inputPath}" must contain a JSON object.`,
+    text: await readFile2(resolvedInputPath, "utf8")
+  });
+};
+
+// src/lib/agent-patch.ts
+var formatZodIssues = (issues) => {
+  return issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; ");
+};
+var parseJsonObjectFlag = ({ label, value }) => {
+  if (value === void 0) {
+    throw new CliCommandError(`${label} is required.`, 2);
+  }
+  return parseJsonObjectText({
+    invalidJsonMessage: `${label} must be valid JSON.`,
+    nonObjectMessage: `${label} must be a JSON object.`,
+    text: value
+  });
+};
 var parseUpdateExerciseAgentInput = (input) => {
   const parsedInput = updateExerciseAgentInputSchema.safeParse(input);
   if (!parsedInput.success) {
@@ -8865,8 +8961,8 @@ var toApiOwnership = (ownership) => {
 
 // src/lib/import-files.ts
 import { openAsBlob } from "node:fs";
-import { stat } from "node:fs/promises";
-import { extname, resolve } from "node:path";
+import { stat as stat2 } from "node:fs/promises";
+import { extname, resolve as resolve2 } from "node:path";
 var guessMimeType = (fileName) => {
   return mimeTypesByExtension[extname(fileName).toLowerCase()] ?? "application/octet-stream";
 };
@@ -8937,7 +9033,7 @@ var buildFileImportCommandSources = async ({
       continue;
     }
     try {
-      const pathStats = await stat(resolve(cwd, rawSource));
+      const pathStats = await stat2(resolve2(cwd, rawSource));
       if (pathStats.isDirectory()) {
         if (relativePath) {
           throw new CliCommandError("--relative-path cannot be used with directory sources.", 2);
@@ -9065,8 +9161,8 @@ var formatCliImportTranslationJobs = (translationJobs) => {
 };
 
 // src/lib/manifest.ts
-import { readFile as readFile2, stat as stat2 } from "node:fs/promises";
-import { resolve as resolve2 } from "node:path";
+import { readFile as readFile3, stat as stat3 } from "node:fs/promises";
+import { resolve as resolve3 } from "node:path";
 import { z as z12 } from "zod";
 
 // src/lib/translation-languages.ts
@@ -9230,10 +9326,10 @@ var assertUniqueSourceIds = (sources) => {
     seenSourceIds.add(source.sourceId);
   }
 };
-var isInteractiveStdin2 = (stdin) => {
+var isInteractiveStdin3 = (stdin) => {
   return stdin.isTTY === true;
 };
-var readTextFromStdin = async (stdin) => {
+var readTextFromStdin2 = async (stdin) => {
   let text = "";
   for await (const chunk of stdin) {
     text += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
@@ -9400,15 +9496,15 @@ var loadManifest = async ({
   stdin
 }) => {
   if (manifestPath === "-") {
-    if (isInteractiveStdin2(stdin)) {
+    if (isInteractiveStdin3(stdin)) {
       throw new CliCommandError('No manifest was piped on stdin. Pipe JSON into "--manifest -".', 2);
     }
-    return parseManifest(await readTextFromStdin(stdin));
+    return parseManifest(await readTextFromStdin2(stdin));
   }
-  const resolvedManifestPath = resolve2(cwd, manifestPath);
+  const resolvedManifestPath = resolve3(cwd, manifestPath);
   let fileStats;
   try {
-    fileStats = await stat2(resolvedManifestPath);
+    fileStats = await stat3(resolvedManifestPath);
   } catch (error) {
     if (error.code === "ENOENT") {
       throw new CliCommandError(`Manifest file "${manifestPath}" does not exist.`, 2);
@@ -9418,7 +9514,7 @@ var loadManifest = async ({
   if (!fileStats.isFile()) {
     throw new CliCommandError(`Manifest path "${manifestPath}" is not a file.`, 2);
   }
-  return parseManifest(await readFile2(resolvedManifestPath, "utf8"));
+  return parseManifest(await readFile3(resolvedManifestPath, "utf8"));
 };
 var loadExerciseImportManifest = async ({
   cwd,
@@ -9471,9 +9567,9 @@ var loadSheetImportManifest = async ({
 
 // src/lib/source-resolver.ts
 import { createWriteStream } from "node:fs";
-import { mkdtemp, open, readdir, rm as rm2, stat as stat3 } from "node:fs/promises";
+import { mkdtemp, open, readdir, rm as rm2, stat as stat4 } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { basename, isAbsolute, relative, resolve as resolve3 } from "node:path";
+import { basename, isAbsolute, relative, resolve as resolve4 } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import pLimit from "p-limit";
@@ -9498,7 +9594,7 @@ var normalizeRelativePath = (relativePath) => {
 var ensureExistingFile = async (filePath, label) => {
   let fileStats;
   try {
-    fileStats = await stat3(filePath);
+    fileStats = await stat4(filePath);
   } catch (error) {
     if (error.code === "ENOENT") {
       throw createSourceResolutionError(`${label} "${filePath}" does not exist.`);
@@ -9512,7 +9608,7 @@ var ensureExistingFile = async (filePath, label) => {
 var ensureExistingDirectory = async (directoryPath, label) => {
   let directoryStats;
   try {
-    directoryStats = await stat3(directoryPath);
+    directoryStats = await stat4(directoryPath);
   } catch (error) {
     if (error.code === "ENOENT") {
       throw createSourceResolutionError(`${label} "${directoryPath}" does not exist.`);
@@ -9535,7 +9631,7 @@ var collectFilesRecursively = async (directoryPath) => {
   const sortedEntries = directoryEntries.sort((leftEntry, rightEntry) => leftEntry.name.localeCompare(rightEntry.name));
   const filePaths = [];
   for (const directoryEntry of sortedEntries) {
-    const entryPath = resolve3(directoryPath, directoryEntry.name);
+    const entryPath = resolve4(directoryPath, directoryEntry.name);
     if (directoryEntry.isDirectory()) {
       filePaths.push(...await collectFilesRecursively(entryPath));
       continue;
@@ -9596,7 +9692,7 @@ var resolveLocalFileSource = async ({
   cwd,
   sourceInputIndex
 }) => {
-  const resolvedPath = resolve3(cwd, source.path);
+  const resolvedPath = resolve4(cwd, source.path);
   await ensureExistingFile(resolvedPath, "Local source");
   const relativePath = normalizeRelativePath(source.relativePath ?? basename(resolvedPath));
   return [
@@ -9616,8 +9712,8 @@ var resolveDirectorySource = async ({
   cwd,
   sourceInputIndex
 }) => {
-  const resolvedDirectoryPath = resolve3(cwd, source.path);
-  const resolvedRelativeRoot = resolve3(cwd, source.relativeRoot ?? source.path);
+  const resolvedDirectoryPath = resolve4(cwd, source.path);
+  const resolvedRelativeRoot = resolve4(cwd, source.relativeRoot ?? source.path);
   await ensureExistingDirectory(resolvedDirectoryPath, "Directory source");
   await ensureExistingDirectory(resolvedRelativeRoot, "Directory relativeRoot");
   if (!isContainedWithin({ childPath: resolvedDirectoryPath, parentPath: resolvedRelativeRoot })) {
@@ -9656,8 +9752,8 @@ var resolveUrlSource = async ({
     throw createSourceResolutionError(`URL source "${source.url}" must use http or https.`);
   }
   const relativePath = normalizeRelativePath(source.relativePath ?? deriveRelativePathFromUrl(parsedUrl));
-  const downloadDirectoryPath = await mkdtemp(resolve3(tmpdir(), "chalksurf-cli-source-"));
-  const downloadedFilePath = resolve3(downloadDirectoryPath, basename(relativePath));
+  const downloadDirectoryPath = await mkdtemp(resolve4(tmpdir(), "chalksurf-cli-source-"));
+  const downloadedFilePath = resolve4(downloadDirectoryPath, basename(relativePath));
   try {
     const response = await fetch(source.url);
     if (!response.ok) {
@@ -9979,9 +10075,6 @@ var formatUploadExerciseFigureOutput = ({ figure, receipt, review }) => [
   `figure: ${figure.type} ${figure.url}`,
   `image: ${review.pixelWidth ?? "?"}x${review.pixelHeight ?? "?"} ${review.byteLength} bytes`
 ].join("\n");
-var formatAttachExerciseFiguresOutput = ({ receipt }) => {
-  return formatAgentWriteReceiptOutput({ receipt });
-};
 var getExerciseTranslationJobIds = ({ jobs }) => jobs.map((job) => job.jobId);
 var formatExerciseTranslationOutput = ({ jobs }) => {
   if (jobs.length === 0) {
@@ -9998,16 +10091,6 @@ var resolveVisibilityFlag = ({ privateFlag, publicFlag }) => {
   }
   return Boolean(publicFlag);
 };
-var parseJsonFlagValue = ({ label, value }) => {
-  if (value === void 0) {
-    throw new CliCommandError(`${label} is required.`, 2);
-  }
-  try {
-    return JSON.parse(value);
-  } catch {
-    throw new CliCommandError(`${label} must be valid JSON.`, 2);
-  }
-};
 var resolveExerciseFigureType = ({
   label,
   required,
@@ -10024,13 +10107,6 @@ var resolveExerciseFigureType = ({
   }
   return value;
 };
-var resolveAttachFigureMode = (value) => {
-  const mode = value ?? "append";
-  if (mode !== "append" && mode !== "replace_type" && mode !== "replace_all") {
-    throw new CliCommandError("--mode must be one of: append, replace_type, replace_all.", 2);
-  }
-  return mode;
-};
 var parseUploadExerciseFigureInput = (input) => {
   const parsedInput = uploadExerciseFigureAgentInputSchema.safeParse(input);
   if (!parsedInput.success) {
@@ -10038,22 +10114,7 @@ var parseUploadExerciseFigureInput = (input) => {
   }
   return parsedInput.data;
 };
-var parseAttachExerciseFiguresInput = (input) => {
-  const parsedInput = attachExerciseFiguresAgentInputSchema.safeParse(input);
-  if (!parsedInput.success) {
-    throw new CliCommandError(`Invalid figure attach input: ${formatZodIssues(parsedInput.error.issues)}`, 2);
-  }
-  return parsedInput.data;
-};
-var parseFigureJsonList = (value) => {
-  const parsedValue = parseJsonFlagValue({ label: "--figure-json", value });
-  const figures = Array.isArray(parsedValue) ? parsedValue : [parsedValue];
-  if (!figures.every((figure) => typeof figure === "object" && figure !== null && !Array.isArray(figure))) {
-    throw new CliCommandError("--figure-json must be a figure object or an array of figure objects.", 2);
-  }
-  return figures;
-};
-var resolveLocalPath = ({ cwd, path }) => isAbsolute2(path) ? path : resolve4(cwd, path);
+var resolveLocalPath = ({ cwd, path }) => isAbsolute2(path) ? path : resolve5(cwd, path);
 var getMimeTypeFromFileName = (fileName) => mimeTypesByExtension[extname2(fileName).toLowerCase()] ?? "";
 var buildLocalFigureUploadFormData = async ({
   context,
@@ -10062,7 +10123,7 @@ var buildLocalFigureUploadFormData = async ({
 }) => {
   const resolvedSourcePath = resolveLocalPath({ cwd: context.cwd, path: source });
   const fileName = input.originalFileName ?? basename2(resolvedSourcePath);
-  const fileBuffer = await readFile3(resolvedSourcePath);
+  const fileBuffer = await readFile4(resolvedSourcePath);
   const file = new File([new Uint8Array(fileBuffer)], fileName, { type: getMimeTypeFromFileName(fileName) });
   const formData = new FormData();
   formData.set("payload", JSON.stringify(input));
@@ -10442,11 +10503,14 @@ var registerExerciseCommands = (exerciseYargs, context) => {
     }
   ).command(
     "figure <subcommand>",
-    "Exercise figure upload and attachment commands",
+    "Exercise figure upload commands",
     (figureYargs) => figureYargs.command(
-      "upload [source]",
-      "Upload a reviewed figure image to exercise-image storage",
-      (uploadYargs) => uploadYargs.positional("source", {
+      "upload <exerciseId> [source]",
+      "Upload and attach a reviewed figure image to an exercise",
+      (uploadYargs) => uploadYargs.positional("exerciseId", {
+        type: "string",
+        describe: "Exercise ID to attach the figure to"
+      }).positional("source", {
         type: "string",
         describe: "Local image file path. Omit when using --input-json for HTTPS/base64/rendered sources."
       }).option("input-json", {
@@ -10467,15 +10531,21 @@ var registerExerciseCommands = (exerciseYargs, context) => {
         default: false,
         describe: "Allow uploading a rendered figure whose quality status is needs_revision"
       }).example(
-        "chalksurf exercise figure upload ./triangle.png --figure-type text --json",
+        "chalksurf exercise figure upload 00000000-0000-4000-8000-000000000001 ./triangle.png --figure-type text --json",
         "Upload a local figure image"
       ).example(
-        `chalksurf exercise figure upload --input-json '{"figureType":"text","source":{"kind":"https_url","url":"https://example.com/figure.png"}}' --json`,
+        `chalksurf exercise figure upload 00000000-0000-4000-8000-000000000001 --input-json '{"exerciseId":"00000000-0000-4000-8000-000000000001","figureType":"text","source":{"kind":"https_url","url":"https://example.com/figure.png"}}' --json`,
         "Upload a figure from an HTTPS image URL"
       ),
       async (argv) => {
         const source = argv.source;
+        const exerciseId = resolveRequestedUuid({
+          fallbackValue: argv.exerciseId,
+          label: "exerciseId",
+          required: true
+        });
         const input = argv.inputJson === void 0 ? parseUploadExerciseFigureInput({
+          exerciseId,
           figureType: resolveExerciseFigureType({
             label: "--figure-type",
             required: true,
@@ -10485,9 +10555,10 @@ var registerExerciseCommands = (exerciseYargs, context) => {
           ...argv.widthCm === void 0 ? {} : { widthInCm: argv.widthCm },
           ...argv.originalFileName === void 0 ? {} : { originalFileName: argv.originalFileName },
           allowNeedsRevision: argv.allowNeedsRevision ?? false
-        }) : parseUploadExerciseFigureInput(
-          parseJsonObjectFlag({ label: "--input-json", value: argv.inputJson })
-        );
+        }) : parseUploadExerciseFigureInput({
+          ...parseJsonObjectFlag({ label: "--input-json", value: argv.inputJson }),
+          exerciseId
+        });
         if (argv.inputJson === void 0 && !source) {
           throw new CliCommandError("source is required unless --input-json is provided.", 2);
         }
@@ -10527,91 +10598,6 @@ var registerExerciseCommands = (exerciseYargs, context) => {
           }
         );
       }
-    ).command(
-      "attach [exerciseId]",
-      "Attach one or more uploaded figures to an exercise",
-      (attachYargs) => attachYargs.positional("exerciseId", {
-        type: "string",
-        describe: "Exercise ID to update"
-      }).option("expected-updated-at", {
-        type: "string",
-        demandOption: true,
-        describe: "Expected current exercise updated_at ISO timestamp"
-      }).option("figure-json", {
-        type: "string",
-        demandOption: true,
-        describe: "Figure object or array of figure objects, usually from exercise figure upload output"
-      }).option("mode", {
-        type: "string",
-        default: "append",
-        choices: ["append", "replace_type", "replace_all"],
-        describe: "How to merge figures into the exercise figure collection"
-      }).option("figure-type", {
-        type: "string",
-        choices: [...exerciseFigureTypes],
-        describe: "Required for --mode replace_type"
-      }).option("target-sheet-id", {
-        type: "string",
-        describe: "Sheet ID whose variant workflow this update targets"
-      }).option("allow-shared-exercise-update", {
-        type: "boolean",
-        default: false,
-        describe: "Acknowledge updating an exercise used outside --target-sheet-id"
-      }).example(
-        `chalksurf exercise figure attach 00000000-0000-4000-8000-000000000001 --expected-updated-at 2026-01-01T00:00:00.000Z --figure-json '{"type":"text","url":"https://...","widthInCm":6}' --json`,
-        "Append one uploaded figure to an exercise"
-      ),
-      async (argv) => {
-        const exerciseId = resolveRequestedUuid({
-          fallbackValue: argv.exerciseId,
-          label: "exerciseId",
-          required: true
-        });
-        const targetSheetId = resolveRequestedUuid({
-          flagValue: argv.targetSheetId,
-          label: "--target-sheet-id"
-        });
-        const mode = resolveAttachFigureMode(argv.mode);
-        const figureType = resolveExerciseFigureType({
-          label: "--figure-type",
-          required: mode === "replace_type",
-          value: argv.figureType
-        });
-        const input = parseAttachExerciseFiguresInput({
-          exerciseId,
-          expectedUpdatedAt: argv.expectedUpdatedAt,
-          ...targetSheetId === void 0 ? {} : { targetSheetId },
-          allowSharedExerciseUpdate: argv.allowSharedExerciseUpdate ?? false,
-          mode,
-          ...figureType === void 0 ? {} : { figureType },
-          figures: parseFigureJsonList(argv.figureJson)
-        });
-        const { apiClient, organizationId } = await createResolvedApiClient({
-          context,
-          baseUrlFlagValue: argv.baseUrl,
-          organizationFlagValue: argv.organization,
-          profileName: argv.profile
-        });
-        let result;
-        try {
-          result = await apiClient.agentAttachExerciseFigures(input);
-        } catch (error) {
-          throw mapApiErrorToCliError(error);
-        }
-        context.output.print(
-          {
-            request: {
-              ...input,
-              organizationId: organizationId ?? null
-            },
-            receipt: result.receipt
-          },
-          (output) => formatAttachExerciseFiguresOutput({ receipt: output.receipt }),
-          {
-            command: "exercise figure attach"
-          }
-        );
-      }
     ).demandCommand(1).strict(),
     () => {
     }
@@ -11511,7 +11497,7 @@ var registerFeedbackCommands = (feedbackYargs, context) => {
 
 // src/commands/figure.ts
 import { writeFile as writeFile2 } from "node:fs/promises";
-import { isAbsolute as isAbsolute3, resolve as resolve5 } from "node:path";
+import { isAbsolute as isAbsolute3, resolve as resolve6 } from "node:path";
 var parseFigureRenderDraftInput = (value) => {
   const parsedInput = figureRenderDraftInputSchema.safeParse(parseJsonObjectFlag({ label: "--input-json", value }));
   if (!parsedInput.success) {
@@ -11519,7 +11505,7 @@ var parseFigureRenderDraftInput = (value) => {
   }
   return parsedInput.data;
 };
-var resolveOutputPath = ({ cwd, outputPath }) => isAbsolute3(outputPath) ? outputPath : resolve5(cwd, outputPath);
+var resolveOutputPath = ({ cwd, outputPath }) => isAbsolute3(outputPath) ? outputPath : resolve6(cwd, outputPath);
 var writeFigurePng = async ({
   cwd,
   outputPath,
@@ -12074,6 +12060,33 @@ var normalizeReadinessFilters = ({
     }) ?? []
   };
 };
+var normalizeSheetSeriesPath = (value) => {
+  const normalizedValue = normalizeOptionalText(value);
+  if (normalizedValue === null) {
+    return null;
+  }
+  const parsedValue = sheetSeriesPathSchema.safeParse(normalizedValue);
+  if (!parsedValue.success) {
+    throw new CliCommandError(
+      '--series-path is unknown. Run "chalksurf sheet series list --json" to inspect valid paths.',
+      2
+    );
+  }
+  return parsedValue.data;
+};
+var normalizeSheetSeriesYearFilter = ({ fromYear, toYear }) => {
+  if (fromYear === void 0 && toYear === void 0) {
+    return null;
+  }
+  if (fromYear !== void 0 && toYear !== void 0 && fromYear > toYear) {
+    throw new CliCommandError("--from-year must be less than or equal to --to-year.", 2);
+  }
+  const parsedFilter = sheetSeriesYearFilterSchema.safeParse({ fromYear, toYear });
+  if (!parsedFilter.success) {
+    throw new CliCommandError("--from-year and --to-year must be four-digit years.", 2);
+  }
+  return parsedFilter.data;
+};
 var hasUniqueItems2 = (values) => new Set(values).size === values.length;
 var sheetImportComponentIdPattern3 = /^[a-zA-Z0-9_-]{1,80}$/;
 var isValidTargetFolderPath2 = (value) => {
@@ -12501,6 +12514,19 @@ var formatSheetSearchOutput = ({
     )
   ].join("\n");
 };
+var formatSheetListOutput = ({ sheets, totalCount }) => {
+  if (sheets.length === 0) {
+    return "No sheets found.";
+  }
+  return [
+    `${sheets.length} of ${totalCount} sheet${totalCount === 1 ? "" : "s"} returned.`,
+    ...sheets.map((sheet) => {
+      const folderPath = sheet.folderPath.map(({ name }) => name).join(" / ") || "(root)";
+      const assignments = sheet.seriesAssignments.map(({ editionYear, seriesPath }) => `${seriesPath}@${editionYear}`).join(", ") || "unassigned";
+      return `${sheet.id}  ${sheet.name}  ${folderPath}  ${assignments}`;
+    })
+  ].join("\n");
+};
 var formatSheetReadinessSummary = (readinessSummary) => {
   if (!readinessSummary.hasIssues) {
     return "OK";
@@ -12649,6 +12675,73 @@ var resolveVisibilityFlag2 = ({ privateFlag, publicFlag }) => {
 };
 var registerSheetCommands = (sheetYargs, context) => {
   return sheetYargs.command(
+    "list",
+    "List exercise sheets owned by the selected organization",
+    (listYargs) => listYargs.option("folder-id", {
+      type: "string",
+      describe: "Only include sheets placed directly in this folder"
+    }).option("include-descendants", {
+      type: "boolean",
+      default: false,
+      describe: "Include sheets in descendant folders; requires --folder-id"
+    }).option("limit", {
+      type: "number",
+      default: 50,
+      describe: "Maximum number of sheets to return"
+    }).option("offset", {
+      type: "number",
+      default: 0,
+      describe: "Number of organization-owned sheets to skip"
+    }).example("chalksurf --profile prod-codex sheet list --json", "List sheets owned by the selected organization").example(
+      "chalksurf --profile prod-codex sheet list --folder-id 00000000-0000-4000-8000-000000000001 --include-descendants --json",
+      "List a folder subtree"
+    ),
+    async (argv) => {
+      const folderId = resolveRequestedUuid2({
+        flagValue: argv.folderId,
+        label: "--folder-id"
+      });
+      const includeDescendants = Boolean(argv.includeDescendants);
+      if (includeDescendants && !folderId) {
+        throw new CliCommandError("--folder-id is required with --include-descendants.", 2);
+      }
+      const limit = normalizeLimit(argv.limit);
+      const offset = normalizeOffset(argv.offset);
+      const { apiClient, organizationId } = await createResolvedApiClient({
+        context,
+        baseUrlFlagValue: argv.baseUrl,
+        organizationFlagValue: argv.organization,
+        profileName: argv.profile
+      });
+      let result;
+      try {
+        result = await apiClient.agentListSheets({
+          folderId,
+          includeDescendants,
+          limit,
+          offset
+        });
+      } catch (error) {
+        throw mapApiErrorToCliError(error);
+      }
+      context.output.print(
+        {
+          request: {
+            folderId: folderId ?? null,
+            includeDescendants,
+            limit,
+            offset,
+            organizationId: organizationId ?? null
+          },
+          ...result
+        },
+        (output) => formatSheetListOutput(output),
+        {
+          command: "sheet list"
+        }
+      );
+    }
+  ).command(
     "search",
     "Search exercise sheets visible to the selected organization",
     (searchYargs) => searchYargs.option("text", {
@@ -12661,6 +12754,15 @@ var registerSheetCommands = (sheetYargs, context) => {
     }).option("subject", {
       type: "string",
       describe: `Only include sheets in this subject (${exerciseSubjects.join(", ")})`
+    }).option("series-path", {
+      type: "string",
+      describe: "Only include sheets with an assignment at or below this authoritative series path"
+    }).option("from-year", {
+      type: "number",
+      describe: "Only include matching series assignments from this edition year"
+    }).option("to-year", {
+      type: "number",
+      describe: "Only include matching series assignments through this edition year"
     }).option("limit", {
       type: "number",
       default: 20,
@@ -12696,6 +12798,11 @@ var registerSheetCommands = (sheetYargs, context) => {
         label: "--subject",
         value: argv.subject
       });
+      const seriesPath = normalizeSheetSeriesPath(argv.seriesPath);
+      const yearFilter = normalizeSheetSeriesYearFilter({
+        fromYear: argv.fromYear,
+        toYear: argv.toYear
+      });
       const limit = normalizeLimit(argv.limit);
       const offset = normalizeOffset(argv.offset);
       const readinessFilters = normalizeReadinessFilters({
@@ -12716,6 +12823,8 @@ var registerSheetCommands = (sheetYargs, context) => {
           issueTypes: readinessFilters.issueTypes,
           text,
           subject,
+          seriesPath,
+          yearFilter,
           ownership: toApiOwnership(ownership),
           limit,
           offset
@@ -12728,6 +12837,8 @@ var registerSheetCommands = (sheetYargs, context) => {
           request: {
             text,
             subject,
+            seriesPath,
+            yearFilter,
             ownership,
             hasIssues: readinessFilters.hasIssues,
             issueTypes: readinessFilters.issueTypes,
@@ -12934,8 +13045,16 @@ var registerSheetCommands = (sheetYargs, context) => {
     (seriesYargs) => seriesYargs.command(
       "list",
       "List valid sheet-series paths",
-      (listYargs) => listYargs.example("chalksurf sheet series list --json", "Inspect valid paths before assigning sheets"),
+      (listYargs) => listYargs.option("subject", {
+        type: "string",
+        describe: `Only include series paths valid for this subject (${exerciseSubjects.join(", ")})`
+      }).example("chalksurf sheet series list --json", "Inspect valid paths before assigning sheets").example("chalksurf sheet series list --subject math --json", "Inspect mathematics series paths"),
       async (argv) => {
+        const subject = normalizeChoiceValue({
+          allowedValues: exerciseSubjects,
+          label: "--subject",
+          value: argv.subject
+        });
         const { apiClient, organizationId } = await createResolvedApiClient({
           context,
           baseUrlFlagValue: argv.baseUrl,
@@ -12944,13 +13063,15 @@ var registerSheetCommands = (sheetYargs, context) => {
         });
         let result;
         try {
-          result = await apiClient.agentListSheetSeries();
+          result = await apiClient.agentListSheetSeries({
+            subject: subject ?? void 0
+          });
         } catch (error) {
           throw mapApiErrorToCliError(error);
         }
         context.output.print(
           {
-            request: { organizationId: organizationId ?? null },
+            request: { organizationId: organizationId ?? null, subject },
             series: result.series
           },
           (output) => formatSheetSeriesOutput({ series: output.series }),
@@ -13612,17 +13733,32 @@ var registerSheetCommands = (sheetYargs, context) => {
   ).command(
     "bulk-update",
     "Dry-run or apply up to 100 sheet patches",
-    (bulkUpdateYargs) => bulkUpdateYargs.option("input-json", {
+    (bulkUpdateYargs) => bulkUpdateYargs.option("input", {
       type: "string",
-      demandOption: true,
-      describe: "JSON matching the bulk update contract: mode, updates, and confirmationDigest for apply mode"
+      nargs: 1,
+      describe: 'Read the bulk update JSON object from a UTF-8 file, or "-" for stdin'
+    }).option("input-json", {
+      type: "string",
+      nargs: 1,
+      describe: "Inline JSON matching the bulk update contract: mode, updates, and confirmationDigest for apply mode"
     }).example(
+      "chalksurf sheet bulk-update --input batch-001.json --json",
+      "Validate a reviewed bulk-update batch from a file"
+    ).example(
+      "cat batch-001.json | chalksurf sheet bulk-update --input - --json",
+      "Validate a reviewed bulk-update batch from stdin"
+    ).example(
       `chalksurf sheet bulk-update --input-json '{"mode":"dry_run","updates":[{"id":"00000000-0000-4000-8000-000000000001","expectedUpdatedAt":"2026-01-01T00:00:00.000Z","patch":{"seriesAssignments":[{"seriesPath":"international.imo","editionYear":2025}]}}]}' --json`,
       "Validate sheet-series assignments and obtain a confirmation digest"
     ),
     async (argv) => {
       const input = parseBulkUpdateSheetsAgentInput(
-        parseJsonObjectFlag({ label: "--input-json", value: argv.inputJson })
+        await loadJsonObjectInput({
+          cwd: context.cwd,
+          inputJson: argv.inputJson,
+          inputPath: argv.input,
+          stdin: context.stdin
+        })
       );
       const { apiClient, organizationId } = await createResolvedApiClient({
         context,
@@ -14255,7 +14391,7 @@ var parseCliWithCapturedOutput = async ({
   argv,
   stdout
 }) => {
-  await new Promise((resolve6, reject) => {
+  await new Promise((resolve7, reject) => {
     cli.parse(argv, (error, _parsedArgv, output) => {
       if (output) {
         stdout.write(output);
@@ -14264,7 +14400,7 @@ var parseCliWithCapturedOutput = async ({
         reject(error);
         return;
       }
-      resolve6();
+      resolve7();
     });
   });
 };
@@ -14295,7 +14431,7 @@ var runCli = async ({
   configPath,
   env = process.env,
   nowImpl = Date.now,
-  sleepImpl = (milliseconds) => new Promise((resolve6) => setTimeout(resolve6, milliseconds)),
+  sleepImpl = (milliseconds) => new Promise((resolve7) => setTimeout(resolve7, milliseconds)),
   stdin = process.stdin,
   stdout = process.stdout,
   stderr = process.stderr