@chalksurf/cli 0.3.3 → 0.3.6

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 ?? {})
@@ -119,6 +151,15 @@ var createApiClient = ({
     agentGetExerciseUsage: async (id) => {
       return await query("agentGetExerciseUsage", { id });
     },
+    agentListQualityIssues: async (input) => {
+      return await query("agentListQualityIssues", input);
+    },
+    agentResolveQualityIssue: async (input) => {
+      return await mutation("agentResolveQualityIssue", input);
+    },
+    agentDismissQualityIssue: async (input) => {
+      return await mutation("agentDismissQualityIssue", input);
+    },
     agentListExerciseLabels: async () => {
       return await query("agentListExerciseLabels", {});
     },
@@ -140,9 +181,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 +220,14 @@ var createApiClient = ({
     agentBulkUpdateSheets: async (input) => {
       return await mutation("agentBulkUpdateSheets", input);
     },
-    agentListSheetSeries: async () => {
-      return await query("agentListSheetSeries", {});
+    agentVerifyBulkSheetUpdates: async (input) => {
+      return await mutation("agentVerifyBulkSheetUpdates", input);
+    },
+    agentListSheets: async (input) => {
+      return await query("agentListSheets", input);
+    },
+    agentListSheetSeries: async (input = {}) => {
+      return await query("agentListSheetSeries", input);
     },
     agentSetSheetVisibility: async (input) => {
       return await mutation("agentSetSheetVisibility", input);
@@ -855,7 +899,9 @@ var Constants = {
         "generate_sheet_translation_completed",
         "upload_exercise_figure",
         "attach_exercise_figures",
-        "bulk_update_sheets"
+        "bulk_update_sheets",
+        "resolve_quality_issue",
+        "dismiss_quality_issue"
       ],
       agent_audit_outcome: ["started", "success", "failed", "denied"],
       agent_audit_resource_type: ["exercise", "sheet", "folder", "job", "event", "figure_asset"],
@@ -896,7 +942,6 @@ var Constants = {
         "figure_update",
         "automatic_labeling"
       ],
-      figure_asset_source_kind: ["document_crop", "rendered_figure"],
       job_type: [
         "exercise_sheet_import",
         "exercise_import",
@@ -931,7 +976,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;
@@ -1377,6 +1421,18 @@ var agentWriteOperationRegistry = {
     resourceType: "exercise",
     sync: true
   },
+  resolve_quality_issue: {
+    agentToolName: "resolve_quality_issue",
+    receiptOperation: "resolve_quality_issue",
+    resourceType: "exercise",
+    sync: true
+  },
+  dismiss_quality_issue: {
+    agentToolName: "dismiss_quality_issue",
+    receiptOperation: "dismiss_quality_issue",
+    resourceType: "exercise",
+    sync: true
+  },
   update_sheet: {
     agentToolName: "update_sheet",
     receiptOperation: "update_sheet",
@@ -1440,12 +1496,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 +1646,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 +1755,39 @@ var folderSchema = strictObject({
   parentId: uuidSchema.nullable(),
   updatedAt: dateStringSchema
 });
+var folderPathSegmentSchema = strictObject({
+  id: uuidSchema,
+  name: z3.string().trim().min(1)
+});
+var listSheetsAgentInputSchema = strictObject({
+  afterId: uuidSchema.optional(),
+  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"]
+}).refine(({ afterId, offset }) => afterId === void 0 || offset === 0, {
+  message: "offset must be zero when afterId is provided",
+  path: ["offset"]
+});
+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
+    })
+  ),
+  inventoryToken: z3.string().trim().min(1),
+  totalCount: z3.number().int().min(0)
+});
 var exerciseLabelSchema = strictObject({
   id: z3.string().trim().min(1),
   subject: z3.enum(exerciseSubjects),
@@ -1953,9 +2038,44 @@ var getExerciseUsageAgentInputSchema = strictObject({
 var getExerciseUsageAgentOutputSchema = strictObject({
   usage: exerciseUsageSchema
 });
+var qualityIssueSelectorShape = {
+  exerciseIds: z3.array(uuidSchema).min(1).max(100).optional(),
+  issueIds: z3.array(uuidSchema).min(1).max(100).optional(),
+  severities: z3.array(z3.enum(exerciseQualityIssueSeverities)).min(1).optional(),
+  limit: z3.number().int().min(1).max(100).optional().default(50),
+  cursor: z3.string().trim().min(1).optional()
+};
+var listQualityIssuesAgentInputSchema = strictObject(qualityIssueSelectorShape).refine(
+  ({ exerciseIds, issueIds }) => exerciseIds === void 0 || issueIds === void 0,
+  { message: "exerciseIds and issueIds are mutually exclusive" }
+);
+var qualityIssueListItemSchema = strictObject({
+  id: uuidSchema,
+  severity: z3.enum(exerciseQualityIssueSeverities),
+  comment: z3.string(),
+  sourceLanguage: z3.enum(translationLanguages),
+  sourceInputHash: z3.string(),
+  createdAt: dateStringSchema,
+  exercise: strictObject({
+    id: uuidSchema,
+    updatedAt: dateStringSchema,
+    subject: z3.enum(exerciseSubjects),
+    source: z3.string().nullable(),
+    organizationId: uuidSchema
+  })
+});
+var listQualityIssuesAgentOutputSchema = strictObject({
+  issues: z3.array(qualityIssueListItemSchema),
+  nextCursor: z3.string().nullable()
+});
+var resolveQualityIssueAgentInputSchema = strictObject({
+  issueId: uuidSchema,
+  expectedExerciseUpdatedAt: expectedUpdatedAtSchema
+});
+var dismissQualityIssueAgentInputSchema = resolveQualityIssueAgentInputSchema;
 var agentWriteReceiptSchema = strictObject({
   resource: strictObject({
-    type: z3.enum(["exercise", "sheet", "folder", "figure_asset"]),
+    type: z3.enum(["exercise", "sheet", "folder"]),
     id: uuidSchema
   }),
   operation: agentWriteReceiptOperationSchema,
@@ -1978,6 +2098,8 @@ var agentWriteReceiptSchema = strictObject({
 var agentWriteReceiptOutputSchema = strictObject({
   receipt: agentWriteReceiptSchema
 });
+var resolveQualityIssueAgentOutputSchema = agentWriteReceiptOutputSchema;
+var dismissQualityIssueAgentOutputSchema = agentWriteReceiptOutputSchema;
 var copyExerciseAgentInputSchema = strictObject({
   id: uuidSchema
 });
@@ -2031,14 +2153,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 +2180,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 +2197,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
@@ -2214,6 +2285,34 @@ var bulkUpdateSheetsAgentOutputSchema = strictObject({
   results: z3.array(bulkUpdateSheetResultSchema),
   receipt: agentWriteReceiptSchema.nullable()
 });
+var verifyBulkSheetUpdateStatusSchema = z3.enum(["applied", "pending", "conflicting", "error"]);
+var verifyBulkSheetUpdateConflictSchema = strictObject({
+  field: z3.enum(["expectedUpdatedAt", "expectedSeriesAssignments"]),
+  code: z3.enum(["updated_at_changed", "series_assignments_changed"])
+});
+var verifyBulkSheetUpdateResultSchema = strictObject({
+  id: uuidSchema,
+  status: verifyBulkSheetUpdateStatusSchema,
+  matchedPaths: z3.array(z3.string()),
+  unmatchedPaths: z3.array(z3.string()),
+  conflicts: z3.array(verifyBulkSheetUpdateConflictSchema),
+  errorCode: z3.string().nullable(),
+  errorMessage: z3.string().nullable()
+});
+var verifyBulkSheetUpdatesAgentInputSchema = strictObject({
+  updates: z3.array(updateSheetAgentInputSchema).min(1).max(100)
+});
+var verifyBulkSheetUpdatesAgentOutputSchema = strictObject({
+  state: z3.enum(["applied", "pending", "conflicting", "mixed", "error"]),
+  counts: strictObject({
+    total: z3.number().int().min(0),
+    applied: z3.number().int().min(0),
+    pending: z3.number().int().min(0),
+    conflicting: z3.number().int().min(0),
+    error: z3.number().int().min(0)
+  }),
+  results: z3.array(verifyBulkSheetUpdateResultSchema)
+});
 var createSheetScoredExerciseSchema = strictObject({
   id: uuidSchema,
   scorePoints: z3.number().min(0).max(99999.9).refine((value) => Number.isInteger(value * 10), "Score can have at most 1 decimal place").nullable()
@@ -2363,12 +2462,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 +2518,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 +2651,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 +2706,19 @@ var getExerciseUsageInputSchema = getExerciseUsageAgentInputSchema.extend({
   organizationId: organizationIdSchema
 });
 var getExerciseUsageOutputSchema = getExerciseUsageAgentOutputSchema;
-var listExerciseLabelsInputSchema = listExerciseLabelsAgentInputSchema.extend({
+var listQualityIssuesInputSchema = listQualityIssuesAgentInputSchema.safeExtend({
+  organizationId: organizationIdSchema
+});
+var listQualityIssuesOutputSchema = listQualityIssuesAgentOutputSchema;
+var resolveQualityIssueInputSchema = resolveQualityIssueAgentInputSchema.extend({
+  organizationId: organizationIdSchema
+});
+var resolveQualityIssueOutputSchema = resolveQualityIssueAgentOutputSchema;
+var dismissQualityIssueInputSchema = dismissQualityIssueAgentInputSchema.extend({
   organizationId: organizationIdSchema
 });
+var dismissQualityIssueOutputSchema = dismissQualityIssueAgentOutputSchema;
+var listExerciseLabelsInputSchema = listExerciseLabelsAgentInputSchema;
 var listExerciseLabelsOutputSchema = listExerciseLabelsAgentOutputSchema;
 var copyExerciseInputSchema = copyExerciseAgentInputSchema.extend({
   organizationId: organizationIdSchema
@@ -2662,13 +2791,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.omit({ inventoryToken: true });
+var getSheetInputSchema = getSheetAgentInputSchema.extend({
   organizationId: organizationIdSchema
 });
+var getSheetOutputSchema = getSheetAgentOutputSchema;
+var listSheetSeriesInputSchema = listSheetSeriesAgentInputSchema;
 var listSheetSeriesOutputSchema = listSheetSeriesAgentOutputSchema;
 var listSheetVersionsInputSchema = listSheetVersionsAgentInputSchema.extend({
   organizationId: organizationIdSchema
@@ -2702,6 +2833,10 @@ var bulkUpdateSheetsInputSchema = bulkUpdateSheetsAgentInputSchema.extend({
   organizationId: organizationIdSchema
 });
 var bulkUpdateSheetsOutputSchema = bulkUpdateSheetsAgentOutputSchema;
+var verifyBulkSheetUpdatesInputSchema = verifyBulkSheetUpdatesAgentInputSchema.extend({
+  organizationId: organizationIdSchema
+});
+var verifyBulkSheetUpdatesOutputSchema = verifyBulkSheetUpdatesAgentOutputSchema;
 var setSheetVisibilityInputSchema = setSheetVisibilityAgentInputSchema.extend({
   organizationId: organizationIdSchema
 });
@@ -2738,9 +2873,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 +3630,7 @@ var uploadExerciseFigureInputSchema = uploadExerciseFigureAgentInputSchema.exten
 });
 var uploadExerciseFigureMcpToolInputSchema = strictObject2({
   organizationId: organizationIdSchema,
+  exerciseId: z5.uuid(),
   figureType: z5.enum(exerciseFigureTypes),
   ...chatGptFigureUploadFileParamInputShape,
   source: strictObject2({
@@ -3513,10 +3647,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",
@@ -3568,6 +3698,16 @@ var chalksurfMcpToolCapabilities = {
     requiredPermission: "read",
     security: { type: "oauth2", scopes: [chalksurfMcpScopes.read] }
   },
+  list_quality_issues: {
+    name: "list_quality_issues",
+    title: "List quality issues",
+    description: "List active quality issues for exercises owned by the selected ChalkSurf organization.",
+    inputSchema: listQualityIssuesInputSchema,
+    outputSchema: listQualityIssuesOutputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    requiredPermission: "read",
+    security: { type: "oauth2", scopes: [chalksurfMcpScopes.read] }
+  },
   list_exercise_labels: {
     name: "list_exercise_labels",
     title: "List exercise labels",
@@ -3618,6 +3758,26 @@ var chalksurfMcpToolCapabilities = {
     requiredPermission: "write",
     security: { type: "oauth2", scopes: [chalksurfMcpScopes.write] }
   },
+  resolve_quality_issue: {
+    name: "resolve_quality_issue",
+    title: "Resolve quality issue",
+    description: "Mark an active quality issue resolved after checking the exercise evidence timestamp.",
+    inputSchema: resolveQualityIssueInputSchema,
+    outputSchema: resolveQualityIssueOutputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    requiredPermission: "write",
+    security: { type: "oauth2", scopes: [chalksurfMcpScopes.write] }
+  },
+  dismiss_quality_issue: {
+    name: "dismiss_quality_issue",
+    title: "Dismiss quality issue",
+    description: "Dismiss an active quality issue after checking the exercise evidence timestamp.",
+    inputSchema: dismissQualityIssueInputSchema,
+    outputSchema: dismissQualityIssueOutputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    requiredPermission: "write",
+    security: { type: "oauth2", scopes: [chalksurfMcpScopes.write] }
+  },
   set_exercise_visibility: {
     name: "set_exercise_visibility",
     title: "Set exercise visibility",
@@ -3672,6 +3832,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",
@@ -3772,6 +3942,16 @@ var chalksurfMcpToolCapabilities = {
     requiredPermission: "write",
     security: { type: "oauth2", scopes: [chalksurfMcpScopes.write] }
   },
+  verify_bulk_sheet_updates: {
+    name: "verify_bulk_sheet_updates",
+    title: "Verify bulk sheet updates",
+    description: "Use this after an uncertain bulk apply response to classify each requested sheet target as applied, pending, conflicting, or error without writing.",
+    inputSchema: verifyBulkSheetUpdatesInputSchema,
+    outputSchema: verifyBulkSheetUpdatesOutputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    requiredPermission: "write",
+    security: { type: "oauth2", scopes: [chalksurfMcpScopes.write] }
+  },
   set_sheet_visibility: {
     name: "set_sheet_visibility",
     title: "Set sheet visibility",
@@ -3950,7 +4130,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 +4138,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 +8889,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) {
@@ -8777,10 +9024,46 @@ var parseBulkUpdateSheetsAgentInput = (input) => {
   }
   return parsedInput.data;
 };
+var parseVerifyBulkSheetUpdatesAgentInput = (input) => {
+  if (typeof input === "object" && input !== null && "schemaVersion" in input) {
+    throw new CliCommandError(
+      "CLI result envelopes are not verifier manifests. Pass the original bulk update manifest or an object with updates.",
+      2
+    );
+  }
+  if (typeof input === "object" && input !== null && "mode" in input) {
+    const parsedBulkInput = bulkUpdateSheetsAgentInputSchema.safeParse(input);
+    if (!parsedBulkInput.success) {
+      throw new CliCommandError(
+        `Invalid bulk sheet verification input: ${formatZodIssues(parsedBulkInput.error.issues)}`,
+        2
+      );
+    }
+    return { updates: parsedBulkInput.data.updates };
+  }
+  const parsedInput = verifyBulkSheetUpdatesAgentInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    throw new CliCommandError(`Invalid bulk sheet verification input: ${formatZodIssues(parsedInput.error.issues)}`, 2);
+  }
+  return parsedInput.data;
+};
 
 // src/lib/agent-receipt.ts
+var getBulkSheetCount = (details) => {
+  if (typeof details !== "object" || details === null || !("sheetIds" in details) || !Array.isArray(details.sheetIds)) {
+    return null;
+  }
+  return details.sheetIds.filter((sheetId) => typeof sheetId === "string").length;
+};
 var formatAgentWriteReceiptOutput = ({ receipt }) => {
-  return `${receipt.operation} -> ${receipt.resource.type} ${receipt.resource.id}`;
+  if (receipt.resource) {
+    return `${receipt.operation} -> ${receipt.resource.type} ${receipt.resource.id}`;
+  }
+  const bulkSheetCount = receipt.operation === "bulk_update_sheets" ? getBulkSheetCount(receipt.details) : null;
+  if (bulkSheetCount !== null) {
+    return `${receipt.operation} -> ${bulkSheetCount} sheet${bulkSheetCount === 1 ? "" : "s"}`;
+  }
+  return `${receipt.operation} completed`;
 };
 
 // src/lib/command-options.ts
@@ -8865,8 +9148,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 +9220,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 +9348,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 +9513,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 +9683,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 +9701,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 +9754,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 +9781,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 +9795,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 +9818,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 +9879,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 +9899,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 +9939,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 +10262,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 +10278,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 +10294,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 +10301,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 +10310,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 +10690,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 +10718,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 +10742,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 +10785,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 +11684,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 +11692,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,
@@ -12045,11 +12218,923 @@ var registerProfileCommands = (profileYargs, context) => {
         }
       );
     }
-  ).demandCommand(1).strict();
+  ).demandCommand(1).strict();
+};
+
+// src/commands/quality-issue/index.ts
+import { z as z15 } from "zod";
+
+// src/commands/quality-issue/artifact-integrity.ts
+import { createHash } from "node:crypto";
+import { readFile as readFile5 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+
+// src/commands/quality-issue/artifact-schemas.ts
+import { z as z14 } from "zod";
+var schemaVersion = z14.literal("v1");
+var uuid = z14.uuid();
+var commonShape = {
+  schemaVersion,
+  runId: z14.string().trim().min(1),
+  organizationId: uuid
+};
+var qualityIssueScopeSchema = z14.object({
+  ...commonShape,
+  request: z14.string().trim().min(1),
+  environment: z14.string().trim().min(1),
+  profile: z14.string().trim().min(1),
+  mode: z14.enum(["dry_run", "apply"]),
+  discovery: z14.object({}).catchall(z14.unknown())
+}).strict();
+var qualityIssueInventoryRowSchema = z14.object({
+  ...commonShape,
+  issueId: uuid,
+  exerciseId: uuid,
+  exerciseUpdatedAt: z14.string().trim().min(1),
+  severity: z14.enum(["warning", "error", "critical"]),
+  subject: z14.enum(["math", "physics", "chemistry"]),
+  evidence: z14.object({}).catchall(z14.unknown())
+}).strict();
+var qualityIssueDiscoveryRowSchema = z14.object({
+  ...commonShape,
+  tool: z14.string().trim().min(1),
+  evidence: z14.object({}).catchall(z14.unknown())
+}).strict();
+var qualityIssueCandidateExerciseRowSchema = z14.object({
+  ...commonShape,
+  exerciseId: uuid,
+  evidence: z14.object({}).catchall(z14.unknown())
+}).strict();
+var patchSchema = z14.object({
+  path: z14.string().trim().min(1),
+  before: z14.unknown(),
+  after: z14.unknown()
+}).strict().refine((patch) => Object.hasOwn(patch, "before") && Object.hasOwn(patch, "after"), {
+  message: "Patch before and after values are required; use null for an intentionally empty value."
+});
+var classificationBaseShape = {
+  ...commonShape,
+  issueId: uuid,
+  reasonCode: z14.string().trim().min(1),
+  rationale: z14.string().trim().min(1)
+};
+var qualityIssueClassificationRowSchema = z14.discriminatedUnion("disposition", [
+  z14.object({
+    ...classificationBaseShape,
+    disposition: z14.literal("proposed_fix"),
+    patches: z14.array(patchSchema).min(1)
+  }).strict(),
+  z14.object({ ...classificationBaseShape, disposition: z14.literal("proposed_dismissal") }).strict(),
+  z14.object({ ...classificationBaseShape, disposition: z14.literal("needs_human") }).strict(),
+  z14.object({ ...classificationBaseShape, disposition: z14.literal("stale") }).strict(),
+  z14.object({ ...classificationBaseShape, disposition: z14.literal("failed") }).strict(),
+  z14.object({ ...classificationBaseShape, disposition: z14.literal("skipped") }).strict()
+]);
+var actionIdentityShape = {
+  actionId: z14.string().trim().min(1),
+  exerciseId: uuid
+};
+var updateActionSchema = z14.object({
+  ...actionIdentityShape,
+  type: z14.literal("update_exercise"),
+  expectedExerciseUpdatedAt: z14.string().trim().min(1),
+  issueIds: z14.array(uuid).min(1),
+  patches: z14.array(patchSchema).min(1)
+}).strict();
+var resolveActionSchema = z14.object({
+  ...actionIdentityShape,
+  type: z14.literal("resolve_quality_issue"),
+  issueId: uuid,
+  expectedExerciseUpdatedAtFromActionId: z14.string().trim().min(1)
+}).strict();
+var dismissActionSchema = z14.object({
+  ...actionIdentityShape,
+  type: z14.literal("dismiss_quality_issue"),
+  issueId: uuid,
+  expectedExerciseUpdatedAt: z14.string().trim().min(1)
+}).strict();
+var qualityIssueActionPlanSchema = z14.object({
+  ...commonShape,
+  inventory: z14.array(
+    z14.object({
+      issueId: uuid,
+      exerciseId: uuid,
+      exerciseUpdatedAt: z14.string().trim().min(1)
+    }).strict()
+  ),
+  actions: z14.array(z14.discriminatedUnion("type", [updateActionSchema, resolveActionSchema, dismissActionSchema])),
+  exclusions: z14.array(
+    z14.object({
+      issueId: uuid,
+      disposition: z14.enum(["needs_human", "stale", "failed", "skipped"]),
+      reasonCode: z14.string().trim().min(1)
+    }).strict()
+  )
+}).strict();
+var resultBaseShape = {
+  ...commonShape,
+  actionId: z14.string().trim().min(1)
+};
+var terminalErrorSchema = z14.object({
+  code: z14.string().trim().min(1),
+  message: z14.string().trim().min(1),
+  recovery: z14.string().trim().min(1)
+}).strict();
+var terminalResultSchema = (outcome) => z14.object({
+  ...resultBaseShape,
+  outcome: z14.literal(outcome),
+  error: terminalErrorSchema
+}).strict();
+var qualityIssueApplicationResultRowSchema = z14.discriminatedUnion("outcome", [
+  z14.object({
+    ...resultBaseShape,
+    outcome: z14.literal("success"),
+    receipt: agentWriteReceiptSchema,
+    resultingExerciseUpdatedAt: z14.iso.datetime({ offset: true }).optional()
+  }).strict(),
+  terminalResultSchema("failed"),
+  terminalResultSchema("stale"),
+  terminalResultSchema("skipped")
+]);
+
+// src/commands/quality-issue/artifact-integrity.ts
+var readJson = async (path, schema) => {
+  try {
+    return schema.parse(JSON.parse(await readFile5(path, "utf8")));
+  } catch (error) {
+    throw new CliCommandError(`Artifact validation failed for ${path}: ${String(error)}`, 2, true, {
+      code: "artifact_validation_failed",
+      retryable: false
+    });
+  }
+};
+var readJsonLines = async (path, schema, optional = false) => {
+  let contents;
+  try {
+    contents = await readFile5(path, "utf8");
+  } catch (error) {
+    if (optional && typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+      return [];
+    }
+    throw new CliCommandError(`Artifact validation failed for ${path}: ${String(error)}`, 2, true, {
+      code: "artifact_validation_failed",
+      retryable: false
+    });
+  }
+  return contents.split(/\r?\n/u).filter((line) => line.trim().length > 0).map((line, index) => {
+    try {
+      return schema.parse(JSON.parse(line));
+    } catch (error) {
+      throw new CliCommandError(`Artifact validation failed for ${path}:${index + 1}: ${String(error)}`, 2, true, {
+        code: "artifact_validation_failed",
+        retryable: false
+      });
+    }
+  });
+};
+var assertUnique = (values, label) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    if (seen.has(value)) {
+      throw new CliCommandError(`Artifact validation failed: duplicate ${label} ${value}`, 2, true, {
+        code: "artifact_validation_failed",
+        retryable: false
+      });
+    }
+    seen.add(value);
+  }
+};
+var canonicalize = (value) => {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, nestedValue]) => [key, canonicalize(nestedValue)])
+    );
+  }
+  return value;
+};
+var canonicalJson = (value) => JSON.stringify(canonicalize(value));
+var assertPartitionIdentity = (scope, rows) => {
+  if (rows.some((row) => row.runId !== scope.runId || row.organizationId !== scope.organizationId)) {
+    throw new CliCommandError("Artifact validation failed: partition identity mismatch", 2, true, {
+      code: "artifact_validation_failed",
+      retryable: false
+    });
+  }
+};
+var validateQualityIssueRun = async (runDirectory) => {
+  const scope = await readJson(join2(runDirectory, "scope.json"), qualityIssueScopeSchema);
+  const discovery = await readJsonLines(join2(runDirectory, "discovery.jsonl"), qualityIssueDiscoveryRowSchema);
+  const candidates = await readJsonLines(
+    join2(runDirectory, "candidate-exercises.jsonl"),
+    qualityIssueCandidateExerciseRowSchema
+  );
+  const inventory = await readJsonLines(join2(runDirectory, "inventory.jsonl"), qualityIssueInventoryRowSchema);
+  const classifications = await readJsonLines(
+    join2(runDirectory, "classifications.jsonl"),
+    qualityIssueClassificationRowSchema
+  );
+  const actionPlan = await readJson(join2(runDirectory, "action-plan.json"), qualityIssueActionPlanSchema);
+  const results = await readJsonLines(
+    join2(runDirectory, "application-results.jsonl"),
+    qualityIssueApplicationResultRowSchema,
+    true
+  );
+  assertPartitionIdentity(scope, [
+    ...discovery,
+    ...candidates,
+    ...inventory,
+    ...classifications,
+    actionPlan,
+    ...results
+  ]);
+  assertUnique(
+    candidates.map((row) => row.exerciseId),
+    "candidate exerciseId"
+  );
+  assertUnique(
+    inventory.map((row) => row.issueId),
+    "inventory issueId"
+  );
+  assertUnique(
+    classifications.map((row) => row.issueId),
+    "classification issueId"
+  );
+  assertUnique(
+    actionPlan.actions.map((action) => action.actionId),
+    "actionId"
+  );
+  const inventoryIds = new Set(inventory.map((row) => row.issueId));
+  const classificationIds = new Set(classifications.map((row) => row.issueId));
+  if (inventoryIds.size !== classificationIds.size || [...inventoryIds].some((issueId) => !classificationIds.has(issueId))) {
+    throw new CliCommandError(
+      "Artifact validation failed: every inventory issue needs exactly one classification",
+      2,
+      true,
+      {
+        code: "artifact_validation_failed",
+        retryable: false
+      }
+    );
+  }
+  const planInventoryIds = new Set(actionPlan.inventory.map((row) => row.issueId));
+  assertUnique(
+    actionPlan.inventory.map((row) => row.issueId),
+    "action-plan inventory issueId"
+  );
+  if (inventoryIds.size !== planInventoryIds.size || [...inventoryIds].some((issueId) => !planInventoryIds.has(issueId))) {
+    throw new CliCommandError(
+      "Artifact validation failed: action-plan inventory does not match inventory.jsonl",
+      2,
+      true,
+      {
+        code: "artifact_validation_failed",
+        retryable: false
+      }
+    );
+  }
+  const candidateExerciseIds = new Set(candidates.map((row) => row.exerciseId));
+  if (inventory.some((row) => !candidateExerciseIds.has(row.exerciseId))) {
+    throw new CliCommandError("Artifact validation failed: inventory exercise is missing from candidates", 2, true, {
+      code: "artifact_validation_failed",
+      retryable: false
+    });
+  }
+  const inventoryByIssueId = new Map(inventory.map((row) => [row.issueId, row]));
+  const classificationByIssueId = new Map(classifications.map((row) => [row.issueId, row]));
+  const patchKeys = actionPlan.actions.flatMap(
+    (action) => action.type === "update_exercise" ? action.patches.map((patch) => `${action.exerciseId}\0${patch.path}`) : []
+  );
+  assertUnique(patchKeys, "exercise patch path");
+  assertUnique(
+    classifications.flatMap((classification) => {
+      if (classification.disposition !== "proposed_fix") return [];
+      const inventoryRow = inventoryByIssueId.get(classification.issueId);
+      return classification.patches.map((patch) => `${inventoryRow?.exerciseId ?? ""}\0${patch.path}`);
+    }),
+    "classified exercise patch path"
+  );
+  for (const plannedIssue of actionPlan.inventory) {
+    const source = inventoryByIssueId.get(plannedIssue.issueId);
+    if (!source || source.exerciseId !== plannedIssue.exerciseId || source.exerciseUpdatedAt !== plannedIssue.exerciseUpdatedAt) {
+      throw new CliCommandError("Artifact validation failed: action-plan evidence differs from inventory", 2, true, {
+        code: "artifact_validation_failed",
+        retryable: false
+      });
+    }
+  }
+  const updateActionsByExerciseId = /* @__PURE__ */ new Map();
+  const updateActionsByIssueId = /* @__PURE__ */ new Map();
+  const resolveActionsByIssueId = /* @__PURE__ */ new Map();
+  const dismissActionsByIssueId = /* @__PURE__ */ new Map();
+  const actionIndexById = new Map(actionPlan.actions.map((action, index) => [action.actionId, index]));
+  for (const action of actionPlan.actions) {
+    if (action.type === "update_exercise") {
+      assertUnique(action.issueIds, `update action ${action.actionId} issueId`);
+      if (updateActionsByExerciseId.has(action.exerciseId)) {
+        throw new CliCommandError(
+          `Artifact validation failed: exercise ${action.exerciseId} has more than one update action`,
+          2,
+          true,
+          { code: "artifact_validation_failed", retryable: false }
+        );
+      }
+      updateActionsByExerciseId.set(action.exerciseId, action);
+      const expectedPatches = action.issueIds.flatMap((actionIssueId) => {
+        const source2 = inventoryByIssueId.get(actionIssueId);
+        const classification = classificationByIssueId.get(actionIssueId);
+        if (!source2 || source2.exerciseId !== action.exerciseId || source2.exerciseUpdatedAt !== action.expectedExerciseUpdatedAt || classification?.disposition !== "proposed_fix") {
+          throw new CliCommandError(
+            "Artifact validation failed: update action evidence differs from inventory",
+            2,
+            true,
+            {
+              code: "artifact_validation_failed",
+              retryable: false
+            }
+          );
+        }
+        updateActionsByIssueId.set(actionIssueId, [...updateActionsByIssueId.get(actionIssueId) ?? [], action]);
+        return classification.patches;
+      });
+      const sortPatches = (patches) => [...patches].sort((left, right) => left.path.localeCompare(right.path));
+      if (canonicalJson(sortPatches(action.patches)) !== canonicalJson(sortPatches(expectedPatches))) {
+        throw new CliCommandError(
+          `Artifact validation failed: update action patches do not match classifications for ${action.exerciseId}`,
+          2,
+          true,
+          { code: "artifact_validation_failed", retryable: false }
+        );
+      }
+      continue;
+    }
+    const source = inventoryByIssueId.get(action.issueId);
+    if (!source || source.exerciseId !== action.exerciseId) {
+      throw new CliCommandError("Artifact validation failed: triage action evidence differs from inventory", 2, true, {
+        code: "artifact_validation_failed",
+        retryable: false
+      });
+    }
+    if (action.type === "resolve_quality_issue") {
+      resolveActionsByIssueId.set(action.issueId, [...resolveActionsByIssueId.get(action.issueId) ?? [], action]);
+    } else {
+      if (source.exerciseUpdatedAt !== action.expectedExerciseUpdatedAt) {
+        throw new CliCommandError("Artifact validation failed: dismissal evidence differs from inventory", 2, true, {
+          code: "artifact_validation_failed",
+          retryable: false
+        });
+      }
+      dismissActionsByIssueId.set(action.issueId, [...dismissActionsByIssueId.get(action.issueId) ?? [], action]);
+    }
+  }
+  const exclusionsByIssueId = new Map(actionPlan.exclusions.map((exclusion) => [exclusion.issueId, exclusion]));
+  assertUnique(
+    actionPlan.exclusions.map((exclusion) => exclusion.issueId),
+    "exclusion issueId"
+  );
+  for (const classification of classifications) {
+    const source = inventoryByIssueId.get(classification.issueId);
+    const updates = updateActionsByIssueId.get(classification.issueId) ?? [];
+    const resolves = resolveActionsByIssueId.get(classification.issueId) ?? [];
+    const dismissals = dismissActionsByIssueId.get(classification.issueId) ?? [];
+    const exclusion = exclusionsByIssueId.get(classification.issueId);
+    const exerciseUpdate = source ? updateActionsByExerciseId.get(source.exerciseId) : void 0;
+    if (classification.disposition === "proposed_dismissal" && dismissals.length === 1 && exerciseUpdate && (actionIndexById.get(dismissals[0].actionId) ?? Number.POSITIVE_INFINITY) > (actionIndexById.get(exerciseUpdate.actionId) ?? Number.NEGATIVE_INFINITY)) {
+      throw new CliCommandError(
+        `Artifact validation failed: dismissal ${dismissals[0].actionId} must precede update ${exerciseUpdate.actionId}`,
+        2,
+        true,
+        { code: "artifact_validation_failed", retryable: false }
+      );
+    }
+    const valid = classification.disposition === "proposed_fix" && !exclusion && updates.length === 1 && resolves.length === 1 && dismissals.length === 0 && resolves[0]?.exerciseId === source?.exerciseId && resolves[0]?.expectedExerciseUpdatedAtFromActionId === updates[0]?.actionId && (actionIndexById.get(updates[0]?.actionId ?? "") ?? Number.POSITIVE_INFINITY) < (actionIndexById.get(resolves[0]?.actionId ?? "") ?? Number.NEGATIVE_INFINITY) || classification.disposition === "proposed_dismissal" && !exclusion && updates.length === 0 && resolves.length === 0 && dismissals.length === 1 || ["needs_human", "stale", "failed", "skipped"].includes(classification.disposition) && updates.length === 0 && resolves.length === 0 && dismissals.length === 0 && exclusion?.disposition === classification.disposition && exclusion.reasonCode === classification.reasonCode;
+    if (!valid) {
+      throw new CliCommandError(
+        `Artifact validation failed: action plan does not exactly implement ${classification.disposition} for ${classification.issueId}`,
+        2,
+        true,
+        { code: "artifact_validation_failed", retryable: false }
+      );
+    }
+  }
+  if ([...exclusionsByIssueId].some(([excludedIssueId]) => !classificationByIssueId.has(excludedIssueId))) {
+    throw new CliCommandError("Artifact validation failed: action plan contains an unexpected exclusion", 2, true, {
+      code: "artifact_validation_failed",
+      retryable: false
+    });
+  }
+  return { scope, discovery, candidates, inventory, classifications, actionPlan, results };
+};
+var digestQualityIssueRun = (run) => createHash("sha256").update(
+  JSON.stringify(
+    canonicalize({
+      scope: run.scope,
+      discovery: run.discovery,
+      candidates: run.candidates,
+      inventory: run.inventory,
+      classifications: run.classifications,
+      actionPlan: run.actionPlan
+    })
+  )
+).digest("hex");
+var reconcileQualityIssueRun = ({
+  actionPlan,
+  results
+}) => {
+  const planned = new Set(actionPlan.actions.map((action) => action.actionId));
+  const counts = /* @__PURE__ */ new Map();
+  for (const result of results) counts.set(result.actionId, (counts.get(result.actionId) ?? 0) + 1);
+  const missingActionIds = [...planned].filter((actionId) => !counts.has(actionId));
+  const duplicateActionIds = [...counts].filter(([, count]) => count > 1).map(([actionId]) => actionId);
+  const unexpectedActionIds = [...counts].filter(([actionId]) => !planned.has(actionId)).map(([actionId]) => actionId);
+  const resultByActionId = new Map(
+    results.filter((result) => counts.get(result.actionId) === 1).map((result) => [result.actionId, result])
+  );
+  const resultIndexByActionId = new Map(results.map((result, index) => [result.actionId, index]));
+  const sameStrings = (left, right) => canonicalJson([...left].sort()) === canonicalJson([...right].sort());
+  const semanticInvalidActionIds = actionPlan.actions.flatMap((action) => {
+    const result = resultByActionId.get(action.actionId);
+    if (!result || result.outcome !== "success") return [];
+    const receipt = result.receipt;
+    if (receipt.resource.type !== "exercise" || receipt.resource.id !== action.exerciseId || receipt.operation !== action.type || receipt.precondition.status !== "matched") {
+      return [action.actionId];
+    }
+    if (action.type === "update_exercise") {
+      const valid2 = result.resultingExerciseUpdatedAt !== void 0 && receipt.precondition.expectedUpdatedAt === action.expectedExerciseUpdatedAt && receipt.precondition.actualUpdatedAt === action.expectedExerciseUpdatedAt && sameStrings(
+        receipt.changedPaths,
+        action.patches.map((patch) => patch.path)
+      );
+      return valid2 ? [] : [action.actionId];
+    }
+    const expectedChangedPaths = [`qualityIssues.${action.issueId}.status`];
+    const details = receipt.details;
+    const expectedStatus = action.type === "resolve_quality_issue" ? "resolved" : "dismissed";
+    if (!sameStrings(receipt.changedPaths, expectedChangedPaths) || typeof details !== "object" || details === null || !("issueId" in details) || details.issueId !== action.issueId || !("status" in details) || details.status !== expectedStatus) {
+      return [action.actionId];
+    }
+    if (action.type === "dismiss_quality_issue") {
+      const valid2 = receipt.precondition.expectedUpdatedAt === action.expectedExerciseUpdatedAt && receipt.precondition.actualUpdatedAt === action.expectedExerciseUpdatedAt;
+      return valid2 ? [] : [action.actionId];
+    }
+    const dependencyResult = resultByActionId.get(action.expectedExerciseUpdatedAtFromActionId);
+    const dependencyIndex = resultIndexByActionId.get(action.expectedExerciseUpdatedAtFromActionId);
+    const resultIndex = resultIndexByActionId.get(action.actionId);
+    const expectedUpdatedAt = dependencyResult?.outcome === "success" ? dependencyResult.resultingExerciseUpdatedAt : void 0;
+    const valid = dependencyResult?.outcome === "success" && expectedUpdatedAt !== void 0 && dependencyIndex !== void 0 && resultIndex !== void 0 && dependencyIndex < resultIndex && receipt.precondition.expectedUpdatedAt === expectedUpdatedAt && receipt.precondition.actualUpdatedAt === expectedUpdatedAt;
+    return valid ? [] : [action.actionId];
+  });
+  const orderInvalidActionIds = missingActionIds.length === 0 && duplicateActionIds.length === 0 && unexpectedActionIds.length === 0 ? actionPlan.actions.flatMap(
+    (action, index) => results[index]?.actionId === action.actionId ? [] : [action.actionId]
+  ) : [];
+  const invalidActionIds = [.../* @__PURE__ */ new Set([...semanticInvalidActionIds, ...orderInvalidActionIds])];
+  return {
+    complete: missingActionIds.length === 0 && duplicateActionIds.length === 0 && unexpectedActionIds.length === 0 && invalidActionIds.length === 0,
+    missingActionIds,
+    duplicateActionIds,
+    unexpectedActionIds,
+    invalidActionIds
+  };
+};
+var verifyQualityIssueRun = (run, approvedDigest) => {
+  const actualDigest = digestQualityIssueRun(run);
+  if (actualDigest !== approvedDigest) {
+    throw new CliCommandError("Approved digest does not match the current action plan", 2, true, {
+      code: "approval_digest_mismatch",
+      retryable: false
+    });
+  }
+  return actualDigest;
+};
+
+// src/commands/quality-issue/index.ts
+var parseUuid = (value, label) => {
+  const result = z15.uuid().safeParse(value);
+  if (!result.success) throw new CliCommandError(`${label} must be a UUID.`, 2);
+  return result.data;
+};
+var parseUuidArray = (values, label) => {
+  if (values === void 0) return void 0;
+  const result = z15.array(z15.uuid()).min(1).max(100).safeParse(values);
+  if (!result.success) throw new CliCommandError(`${label} must contain 1 to 100 UUIDs.`, 2);
+  return result.data;
+};
+var registerQualityIssueCommands = (yargs2, context) => yargs2.command(
+  "list",
+  "List active quality issues for organization-owned exercises",
+  (listYargs) => listYargs.option("exercise-id", { type: "string", array: true, describe: "Restrict to exercise IDs" }).option("issue-id", { type: "string", array: true, describe: "Restrict to quality issue IDs" }).option("severity", {
+    type: "string",
+    array: true,
+    choices: ["warning", "error", "critical"]
+  }).option("limit", { type: "number", default: 50 }).option("cursor", { type: "string" }),
+  async (argv) => {
+    const common = argv;
+    if (argv.exerciseId && argv.issueId) {
+      throw new CliCommandError("--exercise-id and --issue-id are mutually exclusive.", 2);
+    }
+    const input = {
+      exerciseIds: parseUuidArray(argv.exerciseId, "exercise-id"),
+      issueIds: parseUuidArray(argv.issueId, "issue-id"),
+      severities: argv.severity,
+      limit: normalizeLimit(argv.limit),
+      cursor: argv.cursor
+    };
+    const { apiClient, organizationId } = await createResolvedApiClient({
+      context,
+      baseUrlFlagValue: common.baseUrl,
+      organizationFlagValue: common.organization,
+      profileName: common.profile
+    });
+    try {
+      const result = await apiClient.agentListQualityIssues(input);
+      context.output.print(
+        { request: { organizationId, ...input }, ...result },
+        `${result.issues.length} active quality issue(s)${result.nextCursor ? "; more available" : ""}`,
+        { command: "quality-issue list" }
+      );
+    } catch (error) {
+      throw mapApiErrorToCliError(error);
+    }
+  }
+).command(
+  "resolve <issueId>",
+  "Resolve one quality issue using the approved exercise timestamp",
+  (commandYargs) => commandYargs.positional("issueId", { type: "string", demandOption: true }).option("expected-exercise-updated-at", { type: "string", demandOption: true }),
+  async (argv) => {
+    const common = argv;
+    const input = {
+      issueId: parseUuid(argv.issueId, "issueId"),
+      expectedExerciseUpdatedAt: argv.expectedExerciseUpdatedAt
+    };
+    const { apiClient } = await createResolvedApiClient({
+      context,
+      baseUrlFlagValue: common.baseUrl,
+      organizationFlagValue: common.organization,
+      profileName: common.profile
+    });
+    try {
+      const result = await apiClient.agentResolveQualityIssue(input);
+      context.output.print(result, formatAgentWriteReceiptOutput, { command: "quality-issue resolve" });
+    } catch (error) {
+      throw mapApiErrorToCliError(error);
+    }
+  }
+).command(
+  "dismiss <issueId>",
+  "Dismiss one quality issue using the approved exercise timestamp",
+  (commandYargs) => commandYargs.positional("issueId", { type: "string", demandOption: true }).option("expected-exercise-updated-at", { type: "string", demandOption: true }),
+  async (argv) => {
+    const common = argv;
+    const input = {
+      issueId: parseUuid(argv.issueId, "issueId"),
+      expectedExerciseUpdatedAt: argv.expectedExerciseUpdatedAt
+    };
+    const { apiClient } = await createResolvedApiClient({
+      context,
+      baseUrlFlagValue: common.baseUrl,
+      organizationFlagValue: common.organization,
+      profileName: common.profile
+    });
+    try {
+      const result = await apiClient.agentDismissQualityIssue(input);
+      context.output.print(result, formatAgentWriteReceiptOutput, { command: "quality-issue dismiss" });
+    } catch (error) {
+      throw mapApiErrorToCliError(error);
+    }
+  }
+).command(
+  "artifact <subcommand>",
+  "Validate and reconcile local quality-issue run artifacts",
+  (artifactYargs) => artifactYargs.command(
+    "validate",
+    "Validate a quality-issue run partition",
+    (commandYargs) => commandYargs.option("run-dir", { type: "string", demandOption: true }),
+    async (argv) => {
+      const run = await validateQualityIssueRun(argv.runDir);
+      context.output.print(
+        {
+          runId: run.scope.runId,
+          organizationId: run.scope.organizationId,
+          inventoryCount: run.inventory.length,
+          classificationCount: run.classifications.length,
+          actionCount: run.actionPlan.actions.length,
+          resultCount: run.results.length
+        },
+        "Quality-issue run artifacts are valid.",
+        { command: "quality-issue artifact validate" }
+      );
+    }
+  ).command(
+    "digest",
+    "Compute the canonical action-plan digest",
+    (commandYargs) => commandYargs.option("run-dir", { type: "string", demandOption: true }),
+    async (argv) => {
+      const run = await validateQualityIssueRun(argv.runDir);
+      const digest = digestQualityIssueRun(run);
+      context.output.print({ digest }, digest, { command: "quality-issue artifact digest" });
+    }
+  ).command(
+    "verify",
+    "Verify an approved action-plan digest before writes",
+    (commandYargs) => commandYargs.option("run-dir", { type: "string", demandOption: true }).option("approved-digest", { type: "string", demandOption: true }),
+    async (argv) => {
+      const run = await validateQualityIssueRun(argv.runDir);
+      const digest = verifyQualityIssueRun(run, argv.approvedDigest);
+      context.output.print({ digest, verified: true }, "Approved digest verified.", {
+        command: "quality-issue artifact verify"
+      });
+    }
+  ).command(
+    "reconcile",
+    "Reconcile planned actions with terminal result rows",
+    (commandYargs) => commandYargs.option("run-dir", { type: "string", demandOption: true }),
+    async (argv) => {
+      const run = await validateQualityIssueRun(argv.runDir);
+      const reconciliation = reconcileQualityIssueRun(run);
+      context.output.print(
+        reconciliation,
+        reconciliation.complete ? "Reconciliation complete." : "Reconciliation incomplete.",
+        {
+          command: "quality-issue artifact reconcile",
+          ok: reconciliation.complete
+        }
+      );
+      if (!reconciliation.complete) throwSilentExitCode(2);
+    }
+  ).demandCommand(1),
+  () => {
+  }
+).demandCommand(1);
+
+// src/commands/sheet.ts
+import { z as z16 } from "zod";
+
+// src/lib/result-artifact.ts
+import { randomUUID } from "node:crypto";
+import { link, open as open2, unlink } from "node:fs/promises";
+import { basename as basename3, dirname as dirname2, join as join3, resolve as resolve7 } from "node:path";
+
+// src/lib/output.ts
+var cliJsonSchemaVersion = "v1";
+var ensureTrailingNewline = (value) => {
+  return value.endsWith("\n") ? value : `${value}
+`;
+};
+var writeLine = (writer, value) => {
+  writer.write(ensureTrailingNewline(value));
+};
+var serializeCliOutputEnvelope = (envelope) => JSON.stringify(envelope, null, 2);
+var createCliOutputEnvelope = ({
+  command,
+  error,
+  ok,
+  result,
+  warnings
+}) => ({
+  schemaVersion: cliJsonSchemaVersion,
+  command,
+  ok,
+  ...result === void 0 ? {} : { result },
+  ...error ? { error } : {},
+  warnings
+});
+var createOutput = ({
+  json,
+  stdout,
+  stderr
+}) => {
+  let warnings = [];
+  const consumeWarnings = () => {
+    const nextWarnings = warnings;
+    warnings = [];
+    return nextWarnings;
+  };
+  return {
+    json,
+    print: (value, humanFormatter, options) => {
+      if (json) {
+        writeLine(
+          stdout,
+          serializeCliOutputEnvelope(
+            createCliOutputEnvelope({
+              command: options.command,
+              error: options.error,
+              ok: options.ok ?? true,
+              result: value,
+              warnings: consumeWarnings()
+            })
+          )
+        );
+        return;
+      }
+      const message = typeof humanFormatter === "function" ? humanFormatter(value) : humanFormatter;
+      writeLine(stdout, message);
+    },
+    printWithResultArtifact: async (value, compactValue, humanFormatter, options) => {
+      const currentWarnings = [...warnings];
+      await options.publishArtifact(
+        createCliOutputEnvelope({
+          command: options.command,
+          error: options.error,
+          ok: options.ok ?? true,
+          result: value,
+          warnings: currentWarnings
+        })
+      );
+      warnings = warnings.slice(currentWarnings.length);
+      if (json) {
+        writeLine(
+          stdout,
+          serializeCliOutputEnvelope(
+            createCliOutputEnvelope({
+              command: options.command,
+              error: options.error,
+              ok: options.ok ?? true,
+              result: compactValue,
+              warnings: currentWarnings
+            })
+          )
+        );
+        return;
+      }
+      const message = typeof humanFormatter === "function" ? humanFormatter(compactValue) : humanFormatter;
+      writeLine(stdout, message);
+    },
+    printError: ({ command, error, result }) => {
+      if (json) {
+        writeLine(
+          stdout,
+          serializeCliOutputEnvelope(
+            createCliOutputEnvelope({
+              command,
+              ok: false,
+              result,
+              error,
+              warnings: consumeWarnings()
+            })
+          )
+        );
+        return;
+      }
+      writeLine(stderr, formatSerializableCliErrorForHuman(error));
+    },
+    info: (message) => {
+      if (json) {
+        warnings.push(message);
+        return;
+      }
+      writeLine(stderr, message);
+    },
+    error: (message) => {
+      writeLine(stderr, message);
+    }
+  };
+};
+
+// src/lib/result-artifact.ts
+var resolveCliResultFilePath = ({ cwd, inputPath }) => resolve7(cwd, inputPath);
+var getFilesystemErrorCode = (error) => error.code;
+var publishCliResultArtifact = async ({
+  destinationPath,
+  envelope
+}) => {
+  const temporaryPath = join3(dirname2(destinationPath), `.${basename3(destinationPath)}.${randomUUID()}.tmp`);
+  let temporaryFile;
+  try {
+    temporaryFile = await open2(temporaryPath, "wx", 384);
+    await temporaryFile.writeFile(`${serializeCliOutputEnvelope(envelope)}
+`, "utf8");
+    await temporaryFile.sync();
+    await temporaryFile.close();
+    temporaryFile = void 0;
+    await link(temporaryPath, destinationPath);
+  } catch (error) {
+    if (getFilesystemErrorCode(error) === "EEXIST") {
+      throw new CliCommandError(`Result file "${destinationPath}" already exists; choose another path.`, 2);
+    }
+    const message = error instanceof Error ? error.message : "Unknown filesystem error";
+    throw new CliCommandError(`Could not write result file "${destinationPath}": ${message}`, 1);
+  } finally {
+    await temporaryFile?.close().catch(() => {
+    });
+    await unlink(temporaryPath).catch(() => {
+    });
+  }
+};
+
+// src/lib/sheet-list-all.ts
+var pageSize = 100;
+var collectAllSheets = async ({
+  fetchPage
+}) => {
+  const sheets = [];
+  const seenSheetIds = /* @__PURE__ */ new Set();
+  const duplicateSheetIds = /* @__PURE__ */ new Set();
+  const seenPageSignatures = /* @__PURE__ */ new Set();
+  const observedTotalCounts = [];
+  const observedInventoryTokens = [];
+  const issues = [];
+  const warnings = [];
+  let afterId;
+  let pagesFetched = 0;
+  let rowsFetched = 0;
+  const addIssue = (issue, warning) => {
+    if (issues.includes(issue)) {
+      return;
+    }
+    issues.push(issue);
+    warnings.push(warning);
+  };
+  while (true) {
+    const page = await fetchPage({ limit: pageSize, ...afterId ? { afterId } : {} });
+    pagesFetched += 1;
+    rowsFetched += page.sheets.length;
+    observedTotalCounts.push(page.totalCount);
+    observedInventoryTokens.push(page.inventoryToken);
+    const firstObservedTotal = observedTotalCounts[0];
+    if (page.totalCount !== firstObservedTotal) {
+      addIssue(
+        "total_count_changed",
+        `Sheet inventory total changed during collection (${firstObservedTotal} -> ${page.totalCount}).`
+      );
+    }
+    const firstInventoryToken = observedInventoryTokens[0];
+    if (page.inventoryToken !== firstInventoryToken) {
+      addIssue(
+        "inventory_changed",
+        `Sheet inventory membership changed during collection (${firstInventoryToken} -> ${page.inventoryToken}).`
+      );
+    }
+    if (page.sheets.length === 0) {
+      if (sheets.length < page.totalCount) {
+        addIssue(
+          "early_empty_page",
+          `Sheet inventory returned an empty page${afterId ? ` after cursor ${afterId}` : ""} before the observed total of ${page.totalCount}.`
+        );
+      }
+      break;
+    }
+    const pageSignature = page.sheets.map(({ id }) => id).join("\n");
+    if (seenPageSignatures.has(pageSignature)) {
+      addIssue(
+        "repeated_page",
+        `Sheet inventory page${afterId ? ` after cursor ${afterId}` : ""} repeated an earlier page; collection stopped.`
+      );
+      break;
+    }
+    seenPageSignatures.add(pageSignature);
+    for (const sheet of page.sheets) {
+      if (seenSheetIds.has(sheet.id)) {
+        duplicateSheetIds.add(sheet.id);
+        continue;
+      }
+      seenSheetIds.add(sheet.id);
+      sheets.push(sheet);
+    }
+    if (duplicateSheetIds.size > 0) {
+      addIssue(
+        "duplicate_sheet_ids",
+        `Sheet inventory pages repeated ${duplicateSheetIds.size} sheet ID${duplicateSheetIds.size === 1 ? "" : "s"}; the snapshot may be incomplete.`
+      );
+    }
+    if (rowsFetched >= page.totalCount) {
+      break;
+    }
+    if (page.sheets.length < pageSize) {
+      addIssue(
+        "early_short_page",
+        `Sheet inventory returned only ${page.sheets.length} sheets${afterId ? ` after cursor ${afterId}` : ""} before the observed total of ${page.totalCount}.`
+      );
+      break;
+    }
+    afterId = page.sheets.at(-1).id;
+  }
+  const totalCount = observedTotalCounts.at(-1) ?? 0;
+  if (sheets.length !== totalCount) {
+    addIssue(
+      "sheet_count_mismatch",
+      `Collected ${sheets.length} unique sheets but the final observed total was ${totalCount}.`
+    );
+  }
+  return {
+    sheets,
+    totalCount,
+    snapshot: {
+      complete: issues.length === 0,
+      pageSize,
+      pagesFetched,
+      observedTotalCounts,
+      observedInventoryTokens,
+      uniqueSheetCount: sheets.length,
+      duplicateSheetIds: [...duplicateSheetIds],
+      issues
+    },
+    warnings
+  };
 };
 
 // src/commands/sheet.ts
-import { z as z14 } from "zod";
 var readinessIssueTypeLabels = {
   missing_translation: "missing translations",
   missing_solution: "missing solutions",
@@ -12074,6 +13159,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) => {
@@ -12174,7 +13286,7 @@ var resolveRequestedUuid2 = ({
     }
     return void 0;
   }
-  const parsedValue = z14.uuid().safeParse(resolvedValue);
+  const parsedValue = z16.uuid().safeParse(resolvedValue);
   if (!parsedValue.success) {
     throw new CliCommandError(`${label} must be a valid UUID.`, 2);
   }
@@ -12185,7 +13297,7 @@ var resolveRequestedUuidList = ({ label, values }) => {
     throw new CliCommandError(`${label} is required at least once.`, 2);
   }
   return values.map((value, index) => {
-    const parsedValue = z14.uuid().safeParse(value.trim());
+    const parsedValue = z16.uuid().safeParse(value.trim());
     if (!parsedValue.success) {
       throw new CliCommandError(`${label}[${index}] must be a valid UUID.`, 2);
     }
@@ -12501,6 +13613,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";
@@ -12581,22 +13706,26 @@ var formatDeleteSheetOutput = ({ receipt }) => {
 var formatUpdateSheetOutput = ({ receipt }) => {
   return formatAgentWriteReceiptOutput({ receipt });
 };
-var formatBulkUpdateSheetsOutput = ({
-  confirmationDigest,
-  mode,
-  receipt,
-  results
-}) => {
-  const summary = results.reduce(
+var getBulkUpdateSheetsCounts = ({ results }) => {
+  const statusCounts = results.reduce(
     (counts, result) => ({
       ...counts,
       [result.status]: counts[result.status] + 1
     }),
     { ready: 0, unchanged: 0, updated: 0, error: 0 }
   );
+  return { total: results.length, ...statusCounts };
+};
+var formatBulkUpdateSheetsOutput = ({
+  confirmationDigest,
+  mode,
+  receipt,
+  results
+}) => {
+  const counts = getBulkUpdateSheetsCounts({ confirmationDigest, mode, receipt, results });
   const lines = [
-    `${mode === "dry_run" ? "Validated" : "Applied"} ${results.length} sheet update${results.length === 1 ? "" : "s"}.`,
-    `ready: ${summary.ready}  updated: ${summary.updated}  unchanged: ${summary.unchanged}  errors: ${summary.error}`,
+    `${mode === "dry_run" ? "Validated" : "Applied"} ${counts.total} sheet update${counts.total === 1 ? "" : "s"}.`,
+    `ready: ${counts.ready}  updated: ${counts.updated}  unchanged: ${counts.unchanged}  errors: ${counts.error}`,
     `confirmation digest: ${confirmationDigest}`
   ];
   if (receipt) {
@@ -12604,6 +13733,161 @@ var formatBulkUpdateSheetsOutput = ({
   }
   return lines.join("\n");
 };
+var formatVerifyBulkSheetUpdatesOutput = ({ counts, state }) => [
+  `Verification state: ${state}.`,
+  `total: ${counts.total}  applied: ${counts.applied}  pending: ${counts.pending}  conflicting: ${counts.conflicting}  errors: ${counts.error}`
+].join("\n");
+var printWithOptionalResultArtifact = async ({
+  command,
+  compactHumanFormatter,
+  compactValue,
+  context,
+  fullHumanFormatter,
+  fullValue,
+  resultFileInput
+}) => {
+  if (resultFileInput === void 0) {
+    context.output.print(fullValue, fullHumanFormatter, { command });
+    return;
+  }
+  if (!resultFileInput.trim()) {
+    throw new CliCommandError("--result-file must be a non-empty path.", 2);
+  }
+  const resultFile = resolveCliResultFilePath({ cwd: context.cwd, inputPath: resultFileInput });
+  await context.output.printWithResultArtifact(fullValue, { ...compactValue, resultFile }, compactHumanFormatter, {
+    command,
+    publishArtifact: async (envelope) => await publishCliResultArtifact({
+      destinationPath: resultFile,
+      envelope
+    })
+  });
+};
+var configureBulkJsonInputOptions = (commandYargs, description) => commandYargs.option("input", {
+  type: "string",
+  nargs: 1,
+  describe: 'Read the JSON object from a UTF-8 file, or "-" for stdin'
+}).option("input-json", {
+  type: "string",
+  nargs: 1,
+  describe: description
+}).option("result-file", {
+  type: "string",
+  nargs: 1,
+  describe: "Publish the complete JSON result envelope to a new private file"
+});
+var runBulkUpdateCommand = async (argv, context) => {
+  const args = argv;
+  if (args.resultFile !== void 0 && !args.resultFile.trim()) {
+    throw new CliCommandError("--result-file must be a non-empty path.", 2);
+  }
+  const input = parseBulkUpdateSheetsAgentInput(
+    await loadJsonObjectInput({
+      cwd: context.cwd,
+      inputJson: args.inputJson,
+      inputPath: args.input,
+      stdin: context.stdin
+    })
+  );
+  const { apiClient, organizationId } = await createResolvedApiClient({
+    context,
+    baseUrlFlagValue: args.baseUrl,
+    organizationFlagValue: args.organization,
+    profileName: args.profile
+  });
+  let result;
+  try {
+    result = await apiClient.agentBulkUpdateSheets(input);
+  } catch (error) {
+    throw mapApiErrorToCliError(error);
+  }
+  const fullValue = {
+    request: {
+      ...input,
+      organizationId: organizationId ?? null
+    },
+    ...result
+  };
+  const counts = getBulkUpdateSheetsCounts(result);
+  try {
+    await printWithOptionalResultArtifact({
+      command: "sheet bulk-update",
+      compactHumanFormatter: ({ confirmationDigest, counts: counts2, mode, receiptPresent, resultFile }) => [
+        `${mode === "dry_run" ? "Validated" : "Applied"} ${counts2.total} sheet update${counts2.total === 1 ? "" : "s"}.`,
+        `ready: ${counts2.ready}  updated: ${counts2.updated}  unchanged: ${counts2.unchanged}  errors: ${counts2.error}`,
+        `confirmation digest: ${confirmationDigest}`,
+        `receipt: ${receiptPresent ? "present" : "none"}`,
+        `full result: ${resultFile}`
+      ].join("\n"),
+      compactValue: {
+        mode: result.mode,
+        counts,
+        confirmationDigest: result.confirmationDigest,
+        receiptPresent: result.receipt !== null
+      },
+      context,
+      fullHumanFormatter: (output) => formatBulkUpdateSheetsOutput(output),
+      fullValue,
+      resultFileInput: args.resultFile
+    });
+  } catch (error) {
+    if (input.mode !== "apply") {
+      throw error;
+    }
+    const message = error instanceof Error ? error.message : "Unknown result artifact error";
+    context.output.info(
+      `The server confirmed the bulk apply, but the result artifact could not be published: ${message} Do not retry the apply; preserve this stdout response and use "sheet bulk-update verify" with the original manifest if independent recovery is needed.`
+    );
+    context.output.print(fullValue, (output) => formatBulkUpdateSheetsOutput(output), {
+      command: "sheet bulk-update"
+    });
+  }
+};
+var runVerifyBulkSheetUpdatesCommand = async (argv, context) => {
+  const args = argv;
+  const input = parseVerifyBulkSheetUpdatesAgentInput(
+    await loadJsonObjectInput({
+      cwd: context.cwd,
+      inputJson: args.inputJson,
+      inputPath: args.input,
+      stdin: context.stdin
+    })
+  );
+  const { apiClient, organizationId } = await createResolvedApiClient({
+    context,
+    baseUrlFlagValue: args.baseUrl,
+    organizationFlagValue: args.organization,
+    profileName: args.profile
+  });
+  let result;
+  try {
+    result = await apiClient.agentVerifyBulkSheetUpdates(input);
+  } catch (error) {
+    throw mapApiErrorToCliError(error);
+  }
+  const fullValue = {
+    request: {
+      ...input,
+      organizationId: organizationId ?? null
+    },
+    ...result
+  };
+  await printWithOptionalResultArtifact({
+    command: "sheet bulk-update verify",
+    compactHumanFormatter: ({ counts, resultFile, state }) => [
+      `Verification state: ${state}.`,
+      `total: ${counts.total}  applied: ${counts.applied}  pending: ${counts.pending}  conflicting: ${counts.conflicting}  errors: ${counts.error}`,
+      `full result: ${resultFile}`
+    ].join("\n"),
+    compactValue: {
+      state: result.state,
+      counts: result.counts
+    },
+    context,
+    fullHumanFormatter: (output) => formatVerifyBulkSheetUpdatesOutput(output),
+    fullValue,
+    resultFileInput: args.resultFile
+  });
+};
 var formatSheetSeriesOutput = ({ series }) => series.map(({ depth, names, path }) => `${"  ".repeat(depth)}${names.english}  ${path}`).join("\n");
 var formatSetSheetVisibilityOutput = ({ receipt }) => {
   return formatAgentWriteReceiptOutput({ receipt });
@@ -12649,6 +13933,128 @@ 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",
+      describe: "Maximum number of sheets to return"
+    }).option("offset", {
+      type: "number",
+      describe: "Number of organization-owned sheets to skip"
+    }).option("after-id", {
+      type: "string",
+      describe: "Return sheets with IDs after this keyset cursor; cannot be combined with --offset"
+    }).option("all", {
+      type: "boolean",
+      default: false,
+      describe: "Collect every organization-owned sheet in sequential pages of 100"
+    }).option("result-file", {
+      type: "string",
+      nargs: 1,
+      describe: "Publish the complete JSON result envelope to a new private file"
+    }).example("chalksurf --profile prod-codex sheet list --json", "List sheets owned by the selected organization").example(
+      "chalksurf --profile prod-codex sheet list --all --result-file inventory.json --json",
+      "Save a complete reviewed inventory"
+    ).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 collectAll = Boolean(argv.all);
+      const afterId = resolveRequestedUuid2({
+        flagValue: argv.afterId,
+        label: "--after-id"
+      });
+      const limitArgument = argv.limit;
+      const offsetArgument = argv.offset;
+      if (collectAll && (limitArgument !== void 0 || offsetArgument !== void 0 || afterId !== void 0)) {
+        throw new CliCommandError("--all cannot be combined with --limit, --offset, or --after-id.", 2);
+      }
+      if (afterId !== void 0 && offsetArgument !== void 0 && offsetArgument !== 0) {
+        throw new CliCommandError("--after-id cannot be combined with a non-zero --offset.", 2);
+      }
+      const limit = collectAll ? null : normalizeLimit(limitArgument ?? 50);
+      const offset = collectAll ? null : normalizeOffset(offsetArgument);
+      const { apiClient, organizationId } = await createResolvedApiClient({
+        context,
+        baseUrlFlagValue: argv.baseUrl,
+        organizationFlagValue: argv.organization,
+        profileName: argv.profile
+      });
+      let result;
+      try {
+        if (collectAll) {
+          const collected = await collectAllSheets({
+            fetchPage: async ({ afterId: pageAfterId, limit: pageLimit }) => await apiClient.agentListSheets({
+              afterId: pageAfterId,
+              folderId,
+              includeDescendants,
+              limit: pageLimit,
+              offset: 0
+            })
+          });
+          for (const warning of collected.warnings) {
+            context.output.info(warning);
+          }
+          result = {
+            sheets: collected.sheets,
+            totalCount: collected.totalCount,
+            snapshot: collected.snapshot
+          };
+        } else {
+          result = await apiClient.agentListSheets({
+            afterId,
+            folderId,
+            includeDescendants,
+            limit,
+            offset
+          });
+        }
+      } catch (error) {
+        throw mapApiErrorToCliError(error);
+      }
+      const fullValue = {
+        request: {
+          ...collectAll ? { all: true } : {},
+          ...afterId ? { afterId } : {},
+          folderId: folderId ?? null,
+          includeDescendants,
+          limit,
+          offset,
+          organizationId: organizationId ?? null
+        },
+        ...result
+      };
+      await printWithOptionalResultArtifact({
+        command: "sheet list",
+        compactHumanFormatter: ({ resultFile, sheetCount, snapshotComplete }) => `Saved ${sheetCount} sheet${sheetCount === 1 ? "" : "s"} to ${resultFile}.${snapshotComplete === false ? " Snapshot is incomplete." : ""}`,
+        compactValue: {
+          sheetCount: result.sheets.length,
+          totalCount: result.totalCount,
+          snapshotComplete: "snapshot" in result ? result.snapshot.complete : null
+        },
+        context,
+        fullHumanFormatter: (output) => formatSheetListOutput(output),
+        fullValue,
+        resultFileInput: argv.resultFile
+      });
+    }
+  ).command(
     "search",
     "Search exercise sheets visible to the selected organization",
     (searchYargs) => searchYargs.option("text", {
@@ -12661,6 +14067,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 +14111,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 +14136,8 @@ var registerSheetCommands = (sheetYargs, context) => {
           issueTypes: readinessFilters.issueTypes,
           text,
           subject,
+          seriesPath,
+          yearFilter,
           ownership: toApiOwnership(ownership),
           limit,
           offset
@@ -12728,6 +14150,8 @@ var registerSheetCommands = (sheetYargs, context) => {
           request: {
             text,
             subject,
+            seriesPath,
+            yearFilter,
             ownership,
             hasIssues: readinessFilters.hasIssues,
             issueTypes: readinessFilters.issueTypes,
@@ -12934,8 +14358,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 +14376,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 }),
@@ -13610,43 +15044,35 @@ var registerSheetCommands = (sheetYargs, context) => {
       );
     }
   ).command(
-    "bulk-update",
-    "Dry-run or apply up to 100 sheet patches",
-    (bulkUpdateYargs) => bulkUpdateYargs.option("input-json", {
-      type: "string",
-      demandOption: true,
-      describe: "JSON matching the bulk update contract: mode, updates, and confirmationDigest for apply mode"
-    }).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"
+    "bulk-update [subcommand]",
+    "Bulk sheet update and recovery commands",
+    (bulkUpdateYargs) => bulkUpdateYargs.command(
+      "$0",
+      "Dry-run or apply up to 100 sheet patches",
+      (runYargs) => configureBulkJsonInputOptions(
+        runYargs,
+        "Inline JSON with mode, updates, and confirmationDigest for apply mode"
+      ).example(
+        "chalksurf sheet bulk-update --input batch-001.json --result-file dry-run.json --json",
+        "Validate a reviewed batch and save the complete result"
+      ).example(
+        "cat batch-001.json | chalksurf sheet bulk-update --input - --json",
+        "Validate a reviewed batch from stdin"
+      ).example('chalksurf sheet bulk-update --input-json "$BATCH_JSON" --json', "Validate an inline batch"),
+      async (argv) => await runBulkUpdateCommand(argv, context)
+    ).command(
+      "verify",
+      "Verify current targets after an uncertain bulk apply response",
+      (verifyYargs) => configureBulkJsonInputOptions(
+        verifyYargs,
+        "Inline JSON containing updates, or a prior dry-run/apply manifest"
+      ).example(
+        "chalksurf sheet bulk-update verify --input batch-001.json --result-file verification.json --json",
+        "Classify the current state of every target in a batch"
+      ),
+      async (argv) => await runVerifyBulkSheetUpdatesCommand(argv, context)
     ),
-    async (argv) => {
-      const input = parseBulkUpdateSheetsAgentInput(
-        parseJsonObjectFlag({ label: "--input-json", value: argv.inputJson })
-      );
-      const { apiClient, organizationId } = await createResolvedApiClient({
-        context,
-        baseUrlFlagValue: argv.baseUrl,
-        organizationFlagValue: argv.organization,
-        profileName: argv.profile
-      });
-      let result;
-      try {
-        result = await apiClient.agentBulkUpdateSheets(input);
-      } catch (error) {
-        throw mapApiErrorToCliError(error);
-      }
-      context.output.print(
-        {
-          request: {
-            ...input,
-            organizationId: organizationId ?? null
-          },
-          ...result
-        },
-        (output) => formatBulkUpdateSheetsOutput(output),
-        { command: "sheet bulk-update" }
-      );
+    () => {
     }
   ).command(
     "import [sources..]",
@@ -14036,84 +15462,6 @@ var registerSheetCommands = (sheetYargs, context) => {
   ).demandCommand(1).strict();
 };
 
-// src/lib/output.ts
-var cliJsonSchemaVersion = "v1";
-var ensureTrailingNewline = (value) => {
-  return value.endsWith("\n") ? value : `${value}
-`;
-};
-var writeLine = (writer, value) => {
-  writer.write(ensureTrailingNewline(value));
-};
-var createOutput = ({
-  json,
-  stdout,
-  stderr
-}) => {
-  let warnings = [];
-  const consumeWarnings = () => {
-    const nextWarnings = warnings;
-    warnings = [];
-    return nextWarnings;
-  };
-  return {
-    json,
-    print: (value, humanFormatter, options) => {
-      if (json) {
-        writeLine(
-          stdout,
-          JSON.stringify(
-            {
-              schemaVersion: cliJsonSchemaVersion,
-              command: options.command,
-              ok: options.ok ?? true,
-              result: value,
-              ...options.error ? { error: options.error } : {},
-              warnings: consumeWarnings()
-            },
-            null,
-            2
-          )
-        );
-        return;
-      }
-      const message = typeof humanFormatter === "function" ? humanFormatter(value) : humanFormatter;
-      writeLine(stdout, message);
-    },
-    printError: ({ command, error, result }) => {
-      if (json) {
-        writeLine(
-          stdout,
-          JSON.stringify(
-            {
-              schemaVersion: cliJsonSchemaVersion,
-              command,
-              ok: false,
-              ...result === void 0 ? {} : { result },
-              error,
-              warnings: consumeWarnings()
-            },
-            null,
-            2
-          )
-        );
-        return;
-      }
-      writeLine(stderr, formatSerializableCliErrorForHuman(error));
-    },
-    info: (message) => {
-      if (json) {
-        warnings.push(message);
-        return;
-      }
-      writeLine(stderr, message);
-    },
-    error: (message) => {
-      writeLine(stderr, message);
-    }
-  };
-};
-
 // src/lib/prompt-secret.ts
 import { createInterface } from "node:readline/promises";
 import { Writable } from "node:stream";
@@ -14151,11 +15499,13 @@ var createPromptSecret = ({
 };
 
 // src/bin/chalksurf.ts
+var getHelpWidth = (stdout) => stdout.columns === void 0 ? null : Math.min(120, Math.max(80, stdout.columns));
 var packageJson = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
 var createCli = ({
   cwd,
   configPath,
   env,
+  helpWidth,
   now,
   output,
   sleep,
@@ -14172,7 +15522,7 @@ var createCli = ({
     sleep,
     stdin
   };
-  return yargs().scriptName("chalksurf").usage("$0 <command> [options]").version(false).option("json", {
+  return yargs().wrap(helpWidth).scriptName("chalksurf").usage("$0 <command> [options]").version(false).option("json", {
     type: "boolean",
     default: false,
     describe: "Write machine-readable JSON to stdout"
@@ -14216,6 +15566,12 @@ var createCli = ({
     (exerciseYargs) => registerExerciseCommands(exerciseYargs, commandContext),
     () => {
     }
+  ).command(
+    "quality-issue <subcommand>",
+    "Exercise quality issue review commands",
+    (qualityIssueYargs) => registerQualityIssueCommands(qualityIssueYargs, commandContext),
+    () => {
+    }
   ).command(
     "feedback <subcommand>",
     "Feedback commands",
@@ -14255,7 +15611,7 @@ var parseCliWithCapturedOutput = async ({
   argv,
   stdout
 }) => {
-  await new Promise((resolve6, reject) => {
+  await new Promise((resolve8, reject) => {
     cli.parse(argv, (error, _parsedArgv, output) => {
       if (output) {
         stdout.write(output);
@@ -14264,14 +15620,24 @@ var parseCliWithCapturedOutput = async ({
         reject(error);
         return;
       }
-      resolve6();
+      resolve8();
     });
   });
 };
 var hasFlag = (argv, flags) => {
   return argv.some((argument) => flags.includes(argument));
 };
-var topLevelCommands = /* @__PURE__ */ new Set(["auth", "org", "profile", "exercise", "feedback", "figure", "sheet", "job"]);
+var topLevelCommands = /* @__PURE__ */ new Set([
+  "auth",
+  "org",
+  "profile",
+  "exercise",
+  "quality-issue",
+  "feedback",
+  "figure",
+  "sheet",
+  "job"
+]);
 var hasTopLevelCommand = (argv) => {
   return argv.some((argument) => topLevelCommands.has(argument));
 };
@@ -14281,7 +15647,17 @@ var resolveCommandName = (argv) => {
     if (!topLevelCommands.has(argument)) {
       continue;
     }
-    const subcommand = argv.slice(index + 1).find((candidate) => candidate.length > 0 && !candidate.startsWith("-") && !candidate.startsWith("http"));
+    const commandArguments = argv.slice(index + 1);
+    const subcommandIndex = commandArguments.findIndex(
+      (candidate) => candidate.length > 0 && !candidate.startsWith("-") && !candidate.startsWith("http")
+    );
+    const subcommand = commandArguments[subcommandIndex];
+    if (argument === "sheet" && subcommand === "bulk-update") {
+      const nestedSubcommand = commandArguments.slice(subcommandIndex + 1).find((candidate) => candidate.length > 0 && !candidate.startsWith("-"));
+      if (nestedSubcommand === "verify") {
+        return "sheet bulk-update verify";
+      }
+    }
     return subcommand ? `${argument} ${subcommand}` : argument;
   }
   if (hasFlag(argv, ["--version", "-v"])) {
@@ -14295,7 +15671,7 @@ var runCli = async ({
   configPath,
   env = process.env,
   nowImpl = Date.now,
-  sleepImpl = (milliseconds) => new Promise((resolve6) => setTimeout(resolve6, milliseconds)),
+  sleepImpl = (milliseconds) => new Promise((resolve8) => setTimeout(resolve8, milliseconds)),
   stdin = process.stdin,
   stdout = process.stdout,
   stderr = process.stderr
@@ -14310,6 +15686,7 @@ var runCli = async ({
     cwd,
     configPath,
     env,
+    helpWidth: getHelpWidth(stdout),
     now: nowImpl,
     output,
     sleep: sleepImpl,