@mytegroupinc/myte-core 0.0.45 → 0.0.47

package/cli.js

@@ -26,9 +26,9 @@ const DEFAULT_DIFF_LIMIT_CHARS = 500_000;
 const REMOVED_COMMAND_MESSAGES = {
   ask: "The `ask` alias has been removed. Use `myte query \"...\"`.",
   chat: "The `chat` command has been removed. Use repeated `myte query` calls instead.",
-  "create-prds": "The `create-prds` alias has been removed. Use `myte create-prd <file.md> [more.md ...]`.",
-  "add-prd": "The `add-prd` alias has been removed. Use `myte create-prd <file.md> [more.md ...]`.",
-  prd: "The `prd` alias has been removed. Use `myte create-prd <file.md> [more.md ...]`.",
+  "create-prds": "The `create-prds` alias has been removed. Use `myte create-prd <file.md> [more.md ...] --confirm-write --approval-artifact <path>`.",
+  "add-prd": "The `add-prd` alias has been removed. Use `myte create-prd <file.md> [more.md ...] --confirm-write --approval-artifact <path>`.",
+  prd: "The `prd` alias has been removed. Use `myte create-prd <file.md> [more.md ...] --confirm-write --approval-artifact <path>`.",
   "qaqc-status-update": "The `qaqc-status-update` command has been removed. Use `myte mission status --mission-ids \"M001,M002\" --status todo|in_progress|done`.",
   "mission-restore": "The project-key `myte mission restore` command has been removed. Restore archived missions from the Myte web archived missions board.",
 };
@@ -190,12 +190,12 @@ function printHelp() {
     "  myte mission archive --mission-ids \"M001[,M002...]\" [--reason \"...\"] [--no-sync] [--json]",
     "  myte sync-qaqc [--output-dir ./MyteCommandCenter] [--json]",
     "  myte suggestions sync [--output-dir ./MyteCommandCenter] [--json]",
-    "  myte suggestions create [--file ./payload.yml] [--no-sync] [--json]",
-    "  myte suggestions revise [--file ./payload.yml] [--no-sync] [--json]",
-    "  myte suggestions review [--file ./payload.yml] [--no-sync] [--json]",
-    "  myte update-team \"<content>\" [--json]",
-    "  myte update-owner --subject \"<text>\" [--body-markdown \"...\"] [--body-file ./update.md] [--json]",
-    "  myte update-client --subject \"<text>\" [--body-markdown \"...\"] [--body-file ./update.md] [--target-contact-ids <id1,id2>] [--json]",
+    "  myte suggestions create [--file ./payload.yml] --confirm-write --approval-artifact <path> [--no-sync] [--json]",
+    "  myte suggestions revise [--file ./payload.yml] --confirm-write --approval-artifact <path> [--no-sync] [--json]",
+    "  myte suggestions review [--file ./payload.yml] [--no-sync] [--json]",
+    "  myte update-team \"<content>\" --confirm-write --approval-artifact <path> [--json]",
+    "  myte update-owner --subject \"<text>\" [--body-markdown \"...\"] [--body-file ./update.md] --confirm-write --approval-artifact <path> [--json]",
+    "  myte update-client --subject \"<text>\" [--body-markdown \"...\"] [--body-file ./update.md] [--target-contact-ids <id1,id2>] --confirm-write --approval-artifact <path> [--json]",
     "  myte feedback-sync [--status <value>] [--source <value>] [--with-prd-text|--no-with-prd-text] [--output-dir ./MyteCommandCenter] [--json]",
     "  myte feedback get --feedback-id <id> [--json]",
     "  myte feedback history --feedback-id <id> [--limit 50] [--json]",
@@ -203,23 +203,23 @@ function printHelp() {
     "  myte feedback edit --feedback-id <id> [--title \"...\"] [--feedback-text \"...\"] [--priority High] [--reason \"...\"]",
     "  myte feedback assign --feedback-id <id> --user-id <id> [--reason \"...\"]",
     "  myte feedback archive --feedback-id <id> --reason \"...\"",
-    "  myte feedback submit --file ./MyteCommandCenter/reviews/feedback/<id>-edit.yml [--json]",
-    "  myte feedback revise --request-id <id> --file ./MyteCommandCenter/reviews/feedback/<id>-edit.yml [--json]",
+    "  myte feedback submit --file ./MyteCommandCenter/reviews/feedback/<id>-edit.yml --confirm-write --approval-artifact <path> [--json]",
+    "  myte feedback revise --request-id <id> --file ./MyteCommandCenter/reviews/feedback/<id>-edit.yml --confirm-write --approval-artifact <path> [--json]",
     "  myte feedback reviews [--status open|terminal|all] [--request-id <id>] [--json]",
     "  myte feedback review --request-id <id> --action approve|reject|request_changes|cancel [--reason \"...\"] [--json]",
     "  myte feedback review --request-ids \"<id1,id2>\" --action approve|reject|request_changes|cancel [--reason \"...\"] [--json]",
     "  myte feedback move --feedback-id <id> --to-state in_progress --from-state todo --reason \"...\" [--json]",
     "  myte feedback move --feedback-ids \"<id1,id2>\" --to-state in_progress --reason \"...\" [--json]",
-    "  myte feedback comment --feedback-id <id> --body \"...\" [--body-file ./comment.md] [--json]",
+    "  myte feedback comment --feedback-id <id> --body \"...\" [--body-file ./comment.md] --confirm-write --approval-artifact <path> [--json]",
     "  myte feedback undo --feedback-id <id> --event-id <id> --reason \"...\" [--json]",
     "  myte feedback prd-versions --feedback-id <id> [--json]",
     "  myte feedback prd-diff --feedback-id <id> --version-id <id> [--compare-to <id>] [--json]",
     "  myte feedback validate --file ./MyteCommandCenter/reviews/feedback/<id>-status.yml [--json]",
     "  myte feedback apply --file ./MyteCommandCenter/reviews/feedback/<id>-status.yml [--json]",
-    "  myte create-prd <file.md> [more.md ...] [--json] [--title \"...\"] [--description \"...\"]",
-    "  cat file.md | myte create-prd --stdin [--title \"...\"] [--description \"...\"]",
-    "  cat update.md | myte update-owner --stdin --subject \"Owner update\"",
-    "  cat update.md | myte update-client --stdin --subject \"Weekly client update\"",
+    "  myte create-prd <file.md> [more.md ...] --confirm-write --approval-artifact <path> [--json] [--title \"...\"] [--description \"...\"]",
+    "  cat file.md | myte create-prd --stdin --confirm-write --approval-artifact <path> [--title \"...\"] [--description \"...\"]",
+    "  cat update.md | myte update-owner --stdin --subject \"Owner update\" --confirm-write --approval-artifact ./update.md",
+    "  cat update.md | myte update-client --stdin --subject \"Weekly client update\" --confirm-write --approval-artifact ./update.md",
     "",
     "Run forms:",
     "  npm install myte   then npx myte query \"...\" --with-diff",
@@ -235,12 +235,6 @@ function printHelp() {
     "  - Set MYTE_API_KEY in a workspace .env (or env var)",
     "  - Set MYTEAI_API_KEY in a workspace .env (or env var) for `myte ai`",
     "",
-    "Live write approval:",
-    "  - Live project-key mutations require --confirm-write --approval-artifact <path>",
-    "  - The artifact must be a local .md, .yml/.yaml, or .json file shown to and approved by the user before the command is rerun",
-    "  - Batch artifacts must enumerate every feedback id, mission id, suggestion id, request id, or PRD item",
-    "  - Read/sync/query/validate, --print-context, and --dry-run commands do not require write approval",
-    "",
     "bootstrap contract:",
     "  - Run from any workspace where you want local MyteCommandCenter data written",
     "  - Writes MyteCommandCenter/data/project.yml plus phases, epics, stories, and missions locally",
@@ -334,11 +328,23 @@ function printHelp() {
     "  - project-key API/CLI cannot unarchive archived Feedback; use the web archived Feedback view",
     "  - get/history read current feedback snapshots and audited event history through the project-key API",
     "  - prd-versions/prd-diff expose retained PRD versions and backend-generated text diffs",
-    "  - validate/apply send artifacts to /api/project-assistant/feedback/<id>/refinement/* for validation or owner-direct apply",
-    "  - The backend owns authorization, stale snapshot checks, allowed field/transition rules, and history",
-    "  - apply is idempotent and does not rewrite local feedback.yml; run feedback-sync after apply to refresh local state",
-    "",
-    "feedback action map:",
+    "  - validate/apply send artifacts to /api/project-assistant/feedback/<id>/refinement/* for validation or owner-direct apply",
+    "  - The backend owns authorization, stale snapshot checks, allowed field/transition rules, and history",
+    "  - apply is idempotent and does not rewrite local feedback.yml; run feedback-sync after apply to refresh local state",
+    "",
+    "approval artifact requirements:",
+    "  - Required: create-prd, update-team, update-owner, update-client, feedback submit/revise/comment, suggestions create/revise",
+    "  - Not required: run-qaqc, mission status/archive, suggestions review, feedback review/move/undo/apply",
+    "  - Never required: read/sync/query/validate commands, --print-context, --dry-run, and feedback local draft commands",
+    "  - For required actions, prepare a .md/.markdown/.yml/.yaml/.json artifact, show it to the user, then rerun with --confirm-write --approval-artifact <path>",
+    "  - In plain language, the artifact is the human-reviewed record of the exact write the agent is about to send; it is not a permission grant and does not bypass owner/delegate checks, idempotency, stale-state guards, validation, or audit",
+    "  - Minimum artifact contents: exact command; every target id or PRD item; complete proposed-change summary; reason/approval note; batch_count when one command sends multiple items",
+    "  - Mission edit/create batches use suggestions create/revise and must enumerate each item: update items include change_type: update, mission_id, and changed fields; create items include change_type: create, title, description, and acceptance details; revisions include suggestion_id and expected_revision",
+    "  - PRD batches use one create-prd fileA.md fileB.md ...; list each PRD file/title/client_ref and make batch_count match the number of PRDs",
+    "  - Feedback submit/revise/comment artifacts are usually the same YAML/markdown file being submitted; for inline text or stdin, use an approval memo with feedback_id/request_id and exact content",
+    "  - Team, owner, and client update artifacts should name the audience and include the exact message body or complete summary; client updates should include target contact ids when used",
+    "",
+    "feedback action map:",
     "  - feedback-sync: pull board/PRD context into MyteCommandCenter for IDE work",
     "  - get: read one feedback item's current server snapshot and snapshot_hash",
     "  - status/edit/assign/archive/refine: create reviewable local YAML artifacts; no live mutation",
@@ -398,12 +404,12 @@ function printHelp() {
     "  --no-with-prd-text    Skip PRD text download and write only feedback metadata/comment turns",
     "  --mission-ids <ids>   Comma-separated mission business ids for run-qaqc, mission status, or mission archive (quote multi-id values on PowerShell)",
     "  --reason <text>       Optional reason for governed mission archive or feedback changes",
-    "  --actor-scope <id>    Actor workspace key inside mission-ops.yml (defaults to machine-cwd slug)",
-    "  --wait                Poll batch status until terminal completion for run-qaqc",
+    "  --actor-scope <id>    Actor workspace key inside mission-ops.yml (defaults to machine-cwd slug)",
+    "  --confirm-write       Attach approval metadata for commands that require an approval artifact",
+    "  --approval-artifact   Local .md/.markdown/.yml/.yaml/.json approval artifact for gated write commands",
+    "  --wait                Poll batch status until terminal completion for run-qaqc",
     "  --sync                After run-qaqc completes, refresh local QAQC file",
     "  --force               Allow run-qaqc to bypass stale-state protection when supported",
-    "  --confirm-write       Confirm the user explicitly approved a live Myte project-key mutation",
-    "  --approval-artifact   Local .md/.yml/.json approval artifact shown to and approved by the user",
     "  --no-sync             Skip automatic post-mutation sync for suggestions, missions, and feedback mutations",
     "  --print-context       Print JSON payload and exit (no query call)",
     "  --no-fetch            Don't git fetch origin main/master before diff",
@@ -414,33 +420,33 @@ function printHelp() {
     "  myte ai \"Return a JSON object with risks and next_steps\" --json-response",
     "  myte bootstrap",
     "  myte suggestions sync",
-    "  myte suggestions create",
-    "  myte suggestions revise --no-sync",
+    "  myte suggestions create --file ./suggestions/create.yml --confirm-write --approval-artifact ./suggestions/create.yml",
+    "  myte suggestions revise --file ./suggestions/revise.yml --confirm-write --approval-artifact ./suggestions/revise.yml --no-sync",
     "  myte suggestions review --file ./review.yml",
     "  myte run-qaqc --mission-ids \"M001,M002\" --wait --sync",
     "  myte mission status --mission-ids \"M001,M002\" --status done",
     "  myte mission archive --mission-ids \"M001\" --reason \"Duplicate disposable test mission\"",
     "  myte bootstrap --output-dir ./MyteCommandCenter",
     "  myte sync-qaqc",
-    "  myte update-team \"Backend deploy completed; QAQC rerun queued.\"",
-    "  myte update-owner --subject \"QAQC progress\" --body-file ./updates/owner.md",
-    "  myte update-client --subject \"Weekly client update\" --body-file ./updates/week-12.md",
+    "  myte update-team \"Backend deploy completed; QAQC rerun queued.\" --confirm-write --approval-artifact ./updates/team.md",
+    "  myte update-owner --subject \"QAQC progress\" --body-file ./updates/owner.md --confirm-write --approval-artifact ./updates/owner.md",
+    "  myte update-client --subject \"Weekly client update\" --body-file ./updates/week-12.md --confirm-write --approval-artifact ./updates/week-12.md",
     "  myte feedback-sync --json",
     "  myte feedback status --feedback-id 507f1f77bcf86cd799439011 --status in_review --reason \"Ready for owner review\"",
-    "  myte feedback submit --file ./MyteCommandCenter/reviews/feedback/507f1f77bcf86cd799439011-edit.yml --json",
+    "  myte feedback submit --file ./MyteCommandCenter/reviews/feedback/507f1f77bcf86cd799439011-edit.yml --confirm-write --approval-artifact ./MyteCommandCenter/reviews/feedback/507f1f77bcf86cd799439011-edit.yml --json",
     "  myte feedback reviews --status open --json",
     "  myte feedback review --request-id 507f1f77bcf86cd799439022 --action approve --reason \"Looks correct\" --json",
     "  myte feedback move --feedback-id 507f1f77bcf86cd799439011 --to-state in_progress --reason \"Started\" --json",
-    "  myte feedback comment --feedback-id 507f1f77bcf86cd799439011 --body \"Implementation notes are ready for review.\" --json",
+    "  myte feedback comment --feedback-id 507f1f77bcf86cd799439011 --body-file ./comments/implementation.md --confirm-write --approval-artifact ./comments/implementation.md --json",
     "  myte feedback validate --file ./MyteCommandCenter/reviews/feedback/507f1f77bcf86cd799439011-status.yml --json",
     "  myte feedback apply --file ./MyteCommandCenter/reviews/feedback/507f1f77bcf86cd799439011-status.yml --json",
-    "  myte suggestions create --file ./suggestions/create.yml",
-    "  myte suggestions revise",
+    "  myte suggestions create --file ./suggestions/create.yml --confirm-write --approval-artifact ./suggestions/create.yml",
+    "  myte suggestions revise --file ./suggestions/revise.yml --confirm-write --approval-artifact ./suggestions/revise.yml",
     "  myte suggestions review",
-    "  myte update-client --subject \"Weekly client update\" --body-markdown \"## Progress\\n- Login complete\" --target-contact-ids 507f1f77bcf86cd799439011,507f1f77bcf86cd799439012",
-    "  myte create-prd ./drafts/auth-prd.md --description \"Short card summary\"",
-    "  myte create-prd ./drafts/auth-prd.md ./drafts/billing-prd.md",
-    "  cat ./drafts/auth-prd.md | myte create-prd --stdin",
+    "  myte update-client --subject \"Weekly client update\" --body-markdown \"## Progress\\n- Login complete\" --target-contact-ids 507f1f77bcf86cd799439011,507f1f77bcf86cd799439012 --confirm-write --approval-artifact ./updates/week-12.md",
+    "  myte create-prd ./drafts/auth-prd.md --description \"Short card summary\" --confirm-write --approval-artifact ./drafts/auth-prd.md",
+    "  myte create-prd ./drafts/auth-prd.md ./drafts/billing-prd.md --confirm-write --approval-artifact ./drafts/prd-batch.md",
+    "  cat ./drafts/auth-prd.md | myte create-prd --stdin --confirm-write --approval-artifact ./drafts/auth-prd.md",
     "  myte config",
   ].join("\n");
   console.log(text);
@@ -701,164 +707,6 @@ async function fetchJsonWithTimeout(fetchFn, url, options, timeoutMs) {
   }
 }
 
-const WRITE_APPROVAL_TRANSPORT_KEYS = new Set(["write_approval", "client_session_id"]);
-
-function canonicalizeWritePayload(value) {
-  if (Array.isArray(value)) {
-    return value.map((item) => canonicalizeWritePayload(item));
-  }
-  if (value && typeof value === "object") {
-    return Object.fromEntries(
-      Object.keys(value)
-        .filter((key) => !WRITE_APPROVAL_TRANSPORT_KEYS.has(String(key)))
-        .sort()
-        .map((key) => [key, canonicalizeWritePayload(value[key])])
-    );
-  }
-  return value;
-}
-
-function projectApiWritePayloadHash(payload) {
-  return createHash("sha256")
-    .update(pythonJsonDumpsCompatible(canonicalizeWritePayload(payload || {})))
-    .digest("hex");
-}
-
-function isConfirmWrite(args) {
-  return Boolean(args["confirm-write"] || args.confirmWrite || args.confirm_write);
-}
-
-function resolveWriteApprovalArtifactPath(args) {
-  const explicit = firstNonEmptyString(args["approval-artifact"], args.approvalArtifact, args.approval_artifact);
-  if (!explicit) return "";
-  const resolved = path.resolve(process.cwd(), explicit);
-  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
-    console.error(`Approval artifact not found: ${resolved}`);
-    process.exit(1);
-  }
-  return resolved;
-}
-
-function inferApprovalArtifactKind(filePath, fallbackKind) {
-  const ext = path.extname(String(filePath || "")).toLowerCase();
-  if (ext === ".md" || ext === ".markdown") return "markdown";
-  if (ext === ".yml" || ext === ".yaml") return "yaml";
-  if (ext === ".json") return "json";
-  return fallbackKind || "artifact";
-}
-
-function normalizeApprovalTargets(targets) {
-  return toStringArray(targets).map((item) => item.trim()).filter(Boolean);
-}
-
-function writePayloadItems(payload) {
-  if (Array.isArray(payload?.items)) return payload.items;
-  if (Array.isArray(payload)) return payload;
-  return payload && typeof payload === "object" ? [payload] : [];
-}
-
-function suggestionApprovalTargets(payload) {
-  return writePayloadItems(payload).map((item, index) => {
-    if (!item || typeof item !== "object") return `index:${index}`;
-    return firstNonEmptyString(
-      item.suggestion_id,
-      item.id,
-      item._id,
-      item.mission_id,
-      item.target_mission_id,
-      item.title ? `${item.change_type || "suggestion"}:${item.title}` : ""
-    ) || `index:${index}`;
-  });
-}
-
-function prdApprovalTargets(payload) {
-  return writePayloadItems(payload).map((item, index) => {
-    if (!item || typeof item !== "object") return `index:${index}`;
-    return firstNonEmptyString(item.client_ref, item.title) || `index:${index}`;
-  });
-}
-
-function requireWriteApproval(args, payload, { operation, artifactKind, targets = [], batchCount = null } = {}) {
-  const payloadSha256 = projectApiWritePayloadHash(payload || {});
-  const targetValues = normalizeApprovalTargets(targets);
-  const expectedBatchCount = batchCount !== null && batchCount !== undefined
-    ? Number(batchCount)
-    : targetValues.length > 1
-      ? targetValues.length
-      : null;
-
-  if (!isConfirmWrite(args)) {
-    console.error("Refusing live Myte write without explicit human approval.");
-    console.error(`Operation: ${operation || "unknown"}`);
-    console.error(`Payload SHA256: ${payloadSha256}`);
-    if (targetValues.length) console.error(`Targets: ${targetValues.join(", ")}`);
-    if (expectedBatchCount !== null) console.error(`Batch count: ${expectedBatchCount}`);
-    console.error("Create a local .md/.yml/.json approval artifact that lists the exact operation, payload summary, and every target.");
-    console.error("Show that artifact to the user and ask for explicit approval.");
-    console.error("Then rerun with --confirm-write --approval-artifact <path>.");
-    process.exit(1);
-  }
-
-  const artifactPath = resolveWriteApprovalArtifactPath(args);
-  if (!artifactPath) {
-    console.error("Missing --approval-artifact <path> for approved Myte write.");
-    console.error(`Payload SHA256: ${payloadSha256}`);
-    console.error("The artifact must be a local .md/.yml/.json file shown to and explicitly approved by the user.");
-    process.exit(1);
-  }
-
-  return {
-    approved: true,
-    source: "explicit_user_approval",
-    artifact_path: artifactPath,
-    artifact_kind: inferApprovalArtifactKind(artifactPath, artifactKind),
-    payload_sha256: payloadSha256,
-    targets: targetValues,
-    batch_count: expectedBatchCount,
-  };
-}
-
-function writeApprovalHeaders(writeApproval) {
-  if (!writeApproval) return {};
-  const headers = {
-    "X-Myte-Write-Approval": "explicit_user_approval",
-    "X-Myte-Approval-Artifact": String(writeApproval.artifact_path || ""),
-    "X-Myte-Approval-Artifact-Kind": String(writeApproval.artifact_kind || ""),
-    "X-Myte-Approval-Payload-SHA256": String(writeApproval.payload_sha256 || ""),
-  };
-  if (writeApproval.batch_count !== null && writeApproval.batch_count !== undefined) {
-    headers["X-Myte-Approval-Batch-Count"] = String(writeApproval.batch_count);
-  }
-  if (Array.isArray(writeApproval.targets) && writeApproval.targets.length) {
-    headers["X-Myte-Approval-Targets"] = writeApproval.targets.join(",");
-  }
-  return headers;
-}
-
-function formatProjectApiErrorMessage(body, fallback) {
-  const message = body?.message || fallback;
-  const data = body?.data || {};
-  const code = String(data?.code || "");
-  if (!code.startsWith("myte_write_approval")) {
-    return message;
-  }
-  const lines = [
-    message,
-    `Approval error: ${code}`,
-  ];
-  if (data.operation) lines.push(`Operation: ${data.operation}`);
-  if (data.payload_sha256) lines.push(`Payload SHA256: ${data.payload_sha256}`);
-  if (Array.isArray(data.targets) && data.targets.length) lines.push(`Targets: ${data.targets.join(", ")}`);
-  if (data.batch_count !== undefined && data.batch_count !== null) lines.push(`Batch count: ${data.batch_count}`);
-  if (Array.isArray(data.required_agent_steps) && data.required_agent_steps.length) {
-    lines.push("Required agent steps:");
-    for (const step of data.required_agent_steps) {
-      lines.push(`- ${step}`);
-    }
-  }
-  return lines.join("\n");
-}
-
 function summarizeDiffDiagnosticsForContext(diagnostics) {
   if (!diagnostics) return null;
   const repos = Array.isArray(diagnostics.repo_summaries)
@@ -1922,7 +1770,7 @@ async function fetchFeedbackHistory({ apiBase, key, timeoutMs, feedbackId }) {
   return body.data || {};
 }
 
-async function postFeedbackRefinement({ apiBase, key, timeoutMs, feedbackId, mode, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function postFeedbackRefinement({ apiBase, key, timeoutMs, feedbackId, mode, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const action = String(mode || "").trim();
   const url = `${apiBase}/project-assistant/feedback/${encodeURIComponent(String(feedbackId || ""))}/refinement/${action}`;
@@ -1930,7 +1778,6 @@ async function postFeedbackRefinement({ apiBase, key, timeoutMs, feedbackId, mod
     "Content-Type": "application/json",
     Authorization: `Bearer ${key}`,
     ...(String(clientSessionId || "").trim() ? { "X-Client-Session-Id": String(clientSessionId).trim() } : {}),
-    ...writeApprovalHeaders(writeApproval),
   };
   if (idempotencyKey) {
     headers["X-Idempotency-Key"] = String(idempotencyKey).trim();
@@ -1947,7 +1794,7 @@ async function postFeedbackRefinement({ apiBase, key, timeoutMs, feedbackId, mod
   );
 
   if (!resp.ok || body.status !== "success") {
-    const msg = formatProjectApiErrorMessage(body, `Feedback refinement ${action} failed (${resp.status})`);
+    const msg = body?.message || `Feedback refinement ${action} failed (${resp.status})`;
     const err = new Error(msg);
     err.status = resp.status;
     err.data = body?.data;
@@ -2026,7 +1873,7 @@ async function fetchFeedbackEvents({ apiBase, key, timeoutMs, feedbackId, limit
   return body.data || {};
 }
 
-async function postFeedbackReviewSubmission({ apiBase, key, timeoutMs, feedbackId, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function postFeedbackReviewSubmission({ apiBase, key, timeoutMs, feedbackId, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}/project-assistant/feedback/${encodeURIComponent(String(feedbackId || ""))}/refinement/requests`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2039,7 +1886,6 @@ async function postFeedbackReviewSubmission({ apiBase, key, timeoutMs, feedbackI
         Authorization: `Bearer ${key}`,
         "X-Idempotency-Key": String(idempotencyKey || "").trim(),
         ...(String(clientSessionId || "").trim() ? { "X-Client-Session-Id": String(clientSessionId).trim() } : {}),
-        ...writeApprovalHeaders(writeApproval),
       },
       body: JSON.stringify(payload || {}),
     },
@@ -2047,7 +1893,7 @@ async function postFeedbackReviewSubmission({ apiBase, key, timeoutMs, feedbackI
   );
 
   if (!resp.ok || body.status !== "success") {
-    const msg = formatProjectApiErrorMessage(body, `Feedback review submission failed (${resp.status})`);
+    const msg = body?.message || `Feedback review submission failed (${resp.status})`;
     const err = new Error(msg);
     err.status = resp.status;
     err.data = body?.data;
@@ -2056,7 +1902,7 @@ async function postFeedbackReviewSubmission({ apiBase, key, timeoutMs, feedbackI
   return body.data || {};
 }
 
-async function postFeedbackReviewRequestMutation({ apiBase, key, timeoutMs, requestId, endpointAction, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function postFeedbackReviewRequestMutation({ apiBase, key, timeoutMs, requestId, endpointAction, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}/project-assistant/feedback-review-requests/${encodeURIComponent(String(requestId || ""))}/${endpointAction}`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2069,7 +1915,6 @@ async function postFeedbackReviewRequestMutation({ apiBase, key, timeoutMs, requ
         Authorization: `Bearer ${key}`,
         "X-Idempotency-Key": String(idempotencyKey || "").trim(),
         ...(String(clientSessionId || "").trim() ? { "X-Client-Session-Id": String(clientSessionId).trim() } : {}),
-        ...writeApprovalHeaders(writeApproval),
       },
       body: JSON.stringify(payload || {}),
     },
@@ -2077,7 +1922,7 @@ async function postFeedbackReviewRequestMutation({ apiBase, key, timeoutMs, requ
   );
 
   if (!resp.ok || body.status !== "success") {
-    const msg = formatProjectApiErrorMessage(body, `Feedback review ${endpointAction} failed (${resp.status})`);
+    const msg = body?.message || `Feedback review ${endpointAction} failed (${resp.status})`;
     const err = new Error(msg);
     err.status = resp.status;
     err.data = body?.data;
@@ -2086,7 +1931,7 @@ async function postFeedbackReviewRequestMutation({ apiBase, key, timeoutMs, requ
   return body.data || {};
 }
 
-async function postFeedbackBatchReviewMutation({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function postFeedbackBatchReviewMutation({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}/project-assistant/feedback-review-requests/batch-review`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2099,7 +1944,6 @@ async function postFeedbackBatchReviewMutation({ apiBase, key, timeoutMs, payloa
         Authorization: `Bearer ${key}`,
         "X-Idempotency-Key": String(idempotencyKey || "").trim(),
         ...(String(clientSessionId || "").trim() ? { "X-Client-Session-Id": String(clientSessionId).trim() } : {}),
-        ...writeApprovalHeaders(writeApproval),
       },
       body: JSON.stringify(payload || {}),
     },
@@ -2107,7 +1951,7 @@ async function postFeedbackBatchReviewMutation({ apiBase, key, timeoutMs, payloa
   );
 
   if (!resp.ok || body.status !== "success") {
-    const msg = formatProjectApiErrorMessage(body, `Feedback batch review failed (${resp.status})`);
+    const msg = body?.message || `Feedback batch review failed (${resp.status})`;
     const err = new Error(msg);
     err.status = resp.status;
     err.data = body?.data;
@@ -2116,7 +1960,7 @@ async function postFeedbackBatchReviewMutation({ apiBase, key, timeoutMs, payloa
   return body.data || {};
 }
 
-async function postFeedbackBoardMutation({ apiBase, key, timeoutMs, feedbackId, endpoint, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function postFeedbackBoardMutation({ apiBase, key, timeoutMs, feedbackId, endpoint, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}/project-assistant/feedback/${encodeURIComponent(String(feedbackId || ""))}/${endpoint}`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2129,7 +1973,6 @@ async function postFeedbackBoardMutation({ apiBase, key, timeoutMs, feedbackId,
         Authorization: `Bearer ${key}`,
         "X-Idempotency-Key": String(idempotencyKey || "").trim(),
         ...(String(clientSessionId || "").trim() ? { "X-Client-Session-Id": String(clientSessionId).trim() } : {}),
-        ...writeApprovalHeaders(writeApproval),
       },
       body: JSON.stringify(payload || {}),
     },
@@ -2137,7 +1980,7 @@ async function postFeedbackBoardMutation({ apiBase, key, timeoutMs, feedbackId,
   );
 
   if (!resp.ok || body.status !== "success") {
-    const msg = formatProjectApiErrorMessage(body, `Feedback board mutation failed (${resp.status})`);
+    const msg = body?.message || `Feedback board mutation failed (${resp.status})`;
     const err = new Error(msg);
     err.status = resp.status;
     err.data = body?.data;
@@ -2146,7 +1989,7 @@ async function postFeedbackBoardMutation({ apiBase, key, timeoutMs, feedbackId,
   return body.data || {};
 }
 
-async function postFeedbackBatchBoardMutation({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function postFeedbackBatchBoardMutation({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}/project-assistant/feedback/batch-board-move`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2159,7 +2002,6 @@ async function postFeedbackBatchBoardMutation({ apiBase, key, timeoutMs, payload
         Authorization: `Bearer ${key}`,
         "X-Idempotency-Key": String(idempotencyKey || "").trim(),
         ...(String(clientSessionId || "").trim() ? { "X-Client-Session-Id": String(clientSessionId).trim() } : {}),
-        ...writeApprovalHeaders(writeApproval),
       },
       body: JSON.stringify(payload || {}),
     },
@@ -2167,7 +2009,7 @@ async function postFeedbackBatchBoardMutation({ apiBase, key, timeoutMs, payload
   );
 
   if (!resp.ok || body.status !== "success") {
-    const msg = formatProjectApiErrorMessage(body, `Feedback batch board mutation failed (${resp.status})`);
+    const msg = body?.message || `Feedback batch board mutation failed (${resp.status})`;
     const err = new Error(msg);
     err.status = resp.status;
     err.data = body?.data;
@@ -2176,7 +2018,7 @@ async function postFeedbackBatchBoardMutation({ apiBase, key, timeoutMs, payload
   return body.data || {};
 }
 
-async function postFeedbackComment({ apiBase, key, timeoutMs, feedbackId, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function postFeedbackComment({ apiBase, key, timeoutMs, feedbackId, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}/project-assistant/feedback/${encodeURIComponent(String(feedbackId || ""))}/comments`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2189,7 +2031,6 @@ async function postFeedbackComment({ apiBase, key, timeoutMs, feedbackId, payloa
         Authorization: `Bearer ${key}`,
         "X-Idempotency-Key": String(idempotencyKey || "").trim(),
         ...(String(clientSessionId || "").trim() ? { "X-Client-Session-Id": String(clientSessionId).trim() } : {}),
-        ...writeApprovalHeaders(writeApproval),
       },
       body: JSON.stringify(payload || {}),
     },
@@ -2197,7 +2038,7 @@ async function postFeedbackComment({ apiBase, key, timeoutMs, feedbackId, payloa
   );
 
   if (!resp.ok || body.status !== "success") {
-    const msg = formatProjectApiErrorMessage(body, `Feedback comment failed (${resp.status})`);
+    const msg = body?.message || `Feedback comment failed (${resp.status})`;
     const err = new Error(msg);
     err.status = resp.status;
     err.data = body?.data;
@@ -2303,7 +2144,7 @@ function resolveProjectMutationIdempotencyKey({ args, operation, payload }) {
   return createHash("sha256").update(fingerprint).digest("hex");
 }
 
-async function postSuggestionsMutation({ apiBase, key, timeoutMs, endpoint, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function postSuggestionsMutation({ apiBase, key, timeoutMs, endpoint, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}${endpoint}`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2316,7 +2157,6 @@ async function postSuggestionsMutation({ apiBase, key, timeoutMs, endpoint, payl
         Authorization: `Bearer ${key}`,
         "X-Idempotency-Key": String(idempotencyKey || "").trim(),
         ...(String(clientSessionId || "").trim() ? { "X-Client-Session-Id": String(clientSessionId).trim() } : {}),
-        ...writeApprovalHeaders(writeApproval),
       },
       body: JSON.stringify(payload),
     },
@@ -2324,16 +2164,15 @@ async function postSuggestionsMutation({ apiBase, key, timeoutMs, endpoint, payl
   );
 
   if (!resp.ok || body.status !== "success") {
-    const msg = formatProjectApiErrorMessage(body, `Mission suggestions request failed (${resp.status})`);
+    const msg = body?.message || `Mission suggestions request failed (${resp.status})`;
     const err = new Error(msg);
     err.status = resp.status;
-    err.data = body?.data;
     throw err;
   }
   return body.data || {};
 }
 
-async function createRunQaqcBatch({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function createRunQaqcBatch({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}/project-assistant/run-qaqc`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2346,7 +2185,6 @@ async function createRunQaqcBatch({ apiBase, key, timeoutMs, payload, idempotenc
         Authorization: `Bearer ${key}`,
         "X-Idempotency-Key": String(idempotencyKey || "").trim(),
         ...(String(clientSessionId || "").trim() ? { "X-Client-Session-Id": String(clientSessionId).trim() } : {}),
-        ...writeApprovalHeaders(writeApproval),
       },
       body: JSON.stringify(payload),
     },
@@ -2354,16 +2192,15 @@ async function createRunQaqcBatch({ apiBase, key, timeoutMs, payload, idempotenc
   );
 
   if (!resp.ok || body.status !== "success") {
-    const msg = formatProjectApiErrorMessage(body, `Run QAQC request failed (${resp.status})`);
+    const msg = body?.message || `Run QAQC request failed (${resp.status})`;
     const err = new Error(msg);
     err.status = resp.status;
-    err.data = body?.data;
     throw err;
   }
   return body.data || {};
 }
 
-async function createMissionStatusUpdate({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function createMissionStatusUpdate({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}/project-assistant/mission-status-update`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2376,7 +2213,6 @@ async function createMissionStatusUpdate({ apiBase, key, timeoutMs, payload, ide
         Authorization: `Bearer ${key}`,
         "X-Idempotency-Key": String(idempotencyKey || "").trim(),
         ...(String(clientSessionId || "").trim() ? { "X-Client-Session-Id": String(clientSessionId).trim() } : {}),
-        ...writeApprovalHeaders(writeApproval),
       },
       body: JSON.stringify(payload),
     },
@@ -2384,16 +2220,15 @@ async function createMissionStatusUpdate({ apiBase, key, timeoutMs, payload, ide
   );
 
   if (!resp.ok || body.status !== "success") {
-    const msg = formatProjectApiErrorMessage(body, `Mission status update request failed (${resp.status})`);
+    const msg = body?.message || `Mission status update request failed (${resp.status})`;
     const err = new Error(msg);
     err.status = resp.status;
-    err.data = body?.data;
     throw err;
   }
   return body.data || {};
 }
 
-async function createMissionArchiveUpdate({ apiBase, key, timeoutMs, endpoint, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function createMissionArchiveUpdate({ apiBase, key, timeoutMs, endpoint, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}${endpoint}`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2406,7 +2241,6 @@ async function createMissionArchiveUpdate({ apiBase, key, timeoutMs, endpoint, p
         Authorization: `Bearer ${key}`,
         "X-Idempotency-Key": String(idempotencyKey || "").trim(),
         ...(String(clientSessionId || "").trim() ? { "X-Client-Session-Id": String(clientSessionId).trim() } : {}),
-        ...writeApprovalHeaders(writeApproval),
       },
       body: JSON.stringify(payload),
     },
@@ -2414,10 +2248,9 @@ async function createMissionArchiveUpdate({ apiBase, key, timeoutMs, endpoint, p
   );
 
   if (!resp.ok || body.status !== "success") {
-    const msg = formatProjectApiErrorMessage(body, `Mission archive request failed (${resp.status})`);
+    const msg = body?.message || `Mission archive request failed (${resp.status})`;
     const err = new Error(msg);
     err.status = resp.status;
-    err.data = body?.data;
     throw err;
   }
   return body.data || {};
@@ -2530,15 +2363,15 @@ async function runRunQaqc(args) {
     process.exit(1);
   }
 
-  const payload = {
-    mission_ids: missionIds,
-    force: Boolean(args.force),
-  };
-  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
-  if (clientSessionId) payload.client_session_id = clientSessionId;
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
-    args,
-    operation: "run-qaqc",
+  let payload = {
+    mission_ids: missionIds,
+    force: Boolean(args.force),
+  };
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  if (clientSessionId) payload.client_session_id = clientSessionId;
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
+    operation: "run-qaqc",
     payload,
   });
 
@@ -2551,12 +2384,6 @@ async function runRunQaqc(args) {
   const apiBase = resolveApiBase(args);
   const shouldWait = Boolean(args.wait || args.sync);
   const shouldSync = Boolean(args.sync);
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: "run-qaqc",
-    artifactKind: "yaml",
-    targets: missionIds,
-    batchCount: missionIds.length,
-  });
 
   let data;
   try {
@@ -2567,7 +2394,6 @@ async function runRunQaqc(args) {
       payload,
       idempotencyKey,
       clientSessionId,
-      writeApproval,
     });
   } catch (err) {
     if (err?.name === "AbortError") {
@@ -2692,15 +2518,15 @@ async function runMissionStatus(args) {
     process.exit(1);
   }
 
-  const payload = {
-    mission_ids: missionIds,
-    new_status: newStatus,
-  };
-  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
-  if (clientSessionId) payload.client_session_id = clientSessionId;
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
-    args,
-    operation: "mission-status-update",
+  let payload = {
+    mission_ids: missionIds,
+    new_status: newStatus,
+  };
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  if (clientSessionId) payload.client_session_id = clientSessionId;
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
+    operation: "mission-status-update",
     payload,
   });
 
@@ -2711,12 +2537,6 @@ async function runMissionStatus(args) {
 
   const timeoutMs = resolveTimeoutMs(args);
   const apiBase = resolveApiBase(args);
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: "mission-status-update",
-    artifactKind: "yaml",
-    targets: missionIds,
-    batchCount: missionIds.length,
-  });
 
   let data;
   try {
@@ -2727,7 +2547,6 @@ async function runMissionStatus(args) {
       payload,
       idempotencyKey,
       clientSessionId,
-      writeApproval,
     });
   } catch (err) {
     if (err?.name === "AbortError") {
@@ -2802,17 +2621,16 @@ async function runMissionArchiveCommand(args) {
     process.exit(1);
   }
 
-  const payload = {
-    mission_ids: missionIds,
-  };
-  const reason = firstNonEmptyString(args.reason);
-  if (reason) payload.reason = reason;
-  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
-  if (clientSessionId) payload.client_session_id = clientSessionId;
-
-  const operation = "mission-archive";
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
-    args,
+  let payload = {
+    mission_ids: missionIds,
+  };
+  const reason = firstNonEmptyString(args.reason);
+  if (reason) payload.reason = reason;
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  if (clientSessionId) payload.client_session_id = clientSessionId;
+  const operation = "mission-archive";
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
     operation,
     payload,
   });
@@ -2825,12 +2643,6 @@ async function runMissionArchiveCommand(args) {
   const timeoutMs = resolveTimeoutMs(args);
   const apiBase = resolveApiBase(args);
   const endpoint = "/project-assistant/mission-archive";
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: "mission-archive",
-    artifactKind: "yaml",
-    targets: missionIds,
-    batchCount: missionIds.length,
-  });
 
   let data;
   try {
@@ -2842,7 +2654,6 @@ async function runMissionArchiveCommand(args) {
       payload,
       idempotencyKey,
       clientSessionId,
-      writeApproval,
     });
   } catch (err) {
     if (err?.name === "AbortError") {
@@ -2924,9 +2735,9 @@ async function runUpdateTeam(args) {
     process.exit(1);
   }
 
-  const payload = {
-    content: await resolveTeamUpdateContent(args),
-  };
+  let payload = {
+    content: await resolveTeamUpdateContent(args),
+  };
 
   if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
     console.log(JSON.stringify(payload, null, 2));
@@ -2934,18 +2745,18 @@ async function runUpdateTeam(args) {
   }
 
   const timeoutMs = resolveTimeoutMs(args);
-  const apiBase = resolveApiBase(args);
-  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
-  if (clientSessionId) payload.client_session_id = clientSessionId;
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+  const apiBase = resolveApiBase(args);
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  if (clientSessionId) payload.client_session_id = clientSessionId;
+  payload = withWriteApproval(args, payload, {
+    artifactKind: "markdown",
+    targets: ["project"],
+  });
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
     args,
     operation: "update_team",
     payload,
   });
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: "update_team",
-    artifactKind: "markdown",
-  });
 
   let data;
   try {
@@ -2957,7 +2768,6 @@ async function runUpdateTeam(args) {
       endpoint: "/project-assistant/project-comment",
       idempotencyKey,
       clientSessionId,
-      writeApproval,
     });
   } catch (err) {
     if (err?.name === "AbortError") {
@@ -2997,10 +2807,10 @@ async function runUpdateOwner(args) {
     process.exit(1);
   }
 
-  const payload = {
-    subject,
-    body_markdown: await resolveOwnerUpdateBody(args),
-  };
+  let payload = {
+    subject,
+    body_markdown: await resolveOwnerUpdateBody(args),
+  };
 
   if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
     console.log(JSON.stringify(payload, null, 2));
@@ -3008,18 +2818,18 @@ async function runUpdateOwner(args) {
   }
 
   const timeoutMs = resolveTimeoutMs(args);
-  const apiBase = resolveApiBase(args);
-  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
-  if (clientSessionId) payload.client_session_id = clientSessionId;
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+  const apiBase = resolveApiBase(args);
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  if (clientSessionId) payload.client_session_id = clientSessionId;
+  payload = withWriteApproval(args, payload, {
+    artifactKind: "markdown",
+    targets: ["project"],
+  });
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
     args,
     operation: "update_owner",
     payload,
   });
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: "update_owner",
-    artifactKind: "markdown",
-  });
 
   let data;
   try {
@@ -3031,7 +2841,6 @@ async function runUpdateOwner(args) {
       endpoint: "/project-assistant/update-owner",
       idempotencyKey,
       clientSessionId,
-      writeApproval,
     });
   } catch (err) {
     if (err?.name === "AbortError") {
@@ -3079,11 +2888,11 @@ async function runUpdateClient(args) {
     process.exit(1);
   }
 
-  const payload = {
-    subject,
-    body_markdown: await resolveClientUpdateBody(args),
-    target_contact_ids: resolveTargetContactIds(args),
-  };
+  let payload = {
+    subject,
+    body_markdown: await resolveClientUpdateBody(args),
+    target_contact_ids: resolveTargetContactIds(args),
+  };
 
   if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
     console.log(JSON.stringify(payload, null, 2));
@@ -3091,18 +2900,18 @@ async function runUpdateClient(args) {
   }
 
   const timeoutMs = resolveTimeoutMs(args);
-  const apiBase = resolveApiBase(args);
-  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
-  if (clientSessionId) payload.client_session_id = clientSessionId;
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+  const apiBase = resolveApiBase(args);
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  if (clientSessionId) payload.client_session_id = clientSessionId;
+  payload = withWriteApproval(args, payload, {
+    artifactKind: "markdown",
+    targets: ["project"],
+  });
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
     args,
     operation: "update_client",
     payload,
   });
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: "update_client",
-    artifactKind: "markdown",
-  });
 
   let data;
   try {
@@ -3114,7 +2923,6 @@ async function runUpdateClient(args) {
       endpoint: "/project-assistant/client-update-drafts",
       idempotencyKey,
       clientSessionId,
-      writeApproval,
     });
   } catch (err) {
     if (err?.name === "AbortError") {
@@ -3210,7 +3018,7 @@ function stringifyYaml(value) {
 function stableJsonStringify(value) {
   if (Array.isArray(value)) {
     return `[${value.map((item) => stableJsonStringify(item)).join(",")}]`;
-  }
+  }
   if (value && typeof value === "object") {
     const entries = Object.keys(value)
       .sort()
@@ -3220,38 +3028,137 @@ function stableJsonStringify(value) {
   return JSON.stringify(value);
 }
 
-function jsonStringifyEnsureAscii(value) {
+function pythonJsonStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => pythonJsonStringify(item)).join(", ")}]`;
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.keys(value)
+      .filter((key) => value[key] !== undefined)
+      .sort()
+      .map((key) => `${jsonStringEnsureAscii(key)}: ${pythonJsonStringify(value[key])}`);
+    return `{${entries.join(", ")}}`;
+  }
+  if (typeof value === "string") return jsonStringEnsureAscii(value);
+  if (value === undefined) return "null";
+  return JSON.stringify(value);
+}
+
+function jsonStringEnsureAscii(value) {
   return JSON.stringify(String(value)).replace(/[^\x00-\x7F]/g, (char) => {
     const code = char.charCodeAt(0);
     return `\\u${code.toString(16).padStart(4, "0")}`;
   });
 }
 
-function pythonJsonDumpsCompatible(value) {
+function canonicalizeWritePayload(value) {
   if (Array.isArray(value)) {
-    return `[${value.map((item) => pythonJsonDumpsCompatible(item)).join(", ")}]`;
+    return value.map((item) => canonicalizeWritePayload(item));
   }
   if (value && typeof value === "object") {
-    const entries = Object.keys(value)
-      .sort()
-      .map((key) => `${jsonStringifyEnsureAscii(key)}: ${pythonJsonDumpsCompatible(value[key])}`);
-    return `{${entries.join(", ")}}`;
+    const next = {};
+    for (const key of Object.keys(value)) {
+      if (key === "write_approval" || key === "client_session_id") continue;
+      if (value[key] === undefined) continue;
+      next[key] = canonicalizeWritePayload(value[key]);
+    }
+    return next;
+  }
+  return value;
+}
+
+function projectWritePayloadHash(payload) {
+  const canonical = canonicalizeWritePayload(payload || {});
+  return createHash("sha256").update(pythonJsonStringify(canonical)).digest("hex");
+}
+
+function approvalArtifactKind(artifactPath, fallback = "yaml") {
+  const ext = path.extname(String(artifactPath || "")).toLowerCase();
+  if (ext === ".md" || ext === ".markdown") return "markdown";
+  if (ext === ".json") return "json";
+  if (ext === ".yml" || ext === ".yaml") return "yaml";
+  return fallback || "yaml";
+}
+
+function resolveWriteApprovalArtifact(args) {
+  const artifactPath = firstNonEmptyString(
+    args["approval-artifact"],
+    args.approvalArtifact,
+    args.approval_artifact
+  );
+  if (!artifactPath) {
+    console.error("Missing --approval-artifact for confirmed live Myte write.");
+    process.exit(1);
   }
-  if (value === null) return "null";
-  if (typeof value === "boolean") return value ? "true" : "false";
-  if (typeof value === "number") {
-    if (Number.isNaN(value)) return "NaN";
-    if (value === Infinity) return "Infinity";
-    if (value === -Infinity) return "-Infinity";
-    return JSON.stringify(value);
+  const absPath = path.resolve(String(artifactPath));
+  if (!fs.existsSync(absPath) || !fs.statSync(absPath).isFile()) {
+    console.error(`Approval artifact not found: ${absPath}`);
+    process.exit(1);
   }
-  return jsonStringifyEnsureAscii(value);
+  const ext = path.extname(absPath).toLowerCase();
+  if (![".md", ".markdown", ".yml", ".yaml", ".json"].includes(ext)) {
+    console.error("Approval artifact must be a local .md, .markdown, .yml, .yaml, or .json file.");
+    process.exit(1);
+  }
+  return { displayPath: String(artifactPath), absPath };
+}
+
+function approvalTargets(values) {
+  return uniqueNormalizedStrings(Array.isArray(values) ? values : [values]);
+}
+
+function hasWriteApprovalArtifactArg(args) {
+  return Boolean(firstNonEmptyString(
+    args["approval-artifact"],
+    args.approvalArtifact,
+    args.approval_artifact
+  ));
+}
+
+function withWriteApproval(args, payload, { artifactKind = "yaml", targets = [], batchCount = null, required = true } = {}) {
+  const confirmed = Boolean(args["confirm-write"] || args.confirmWrite || args.confirm_write);
+  if (required && (!confirmed || !hasWriteApprovalArtifactArg(args))) {
+    console.error("Missing --confirm-write --approval-artifact <path> for this live Myte write.");
+    process.exit(1);
+  }
+  if (!confirmed) return payload;
+  const { displayPath } = resolveWriteApprovalArtifact(args);
+  const nextPayload = { ...(payload || {}) };
+  const normalizedTargets = approvalTargets(targets);
+  const approval = {
+    approved: true,
+    source: "explicit_user_approval",
+    artifact_path: displayPath,
+    artifact_kind: approvalArtifactKind(displayPath, artifactKind),
+    payload_sha256: projectWritePayloadHash(nextPayload),
+  };
+  if (normalizedTargets.length) approval.targets = normalizedTargets;
+  if (batchCount !== undefined && batchCount !== null) approval.batch_count = Number(batchCount);
+  nextPayload.write_approval = approval;
+  return nextPayload;
+}
+
+function suggestionWriteTargets(items) {
+  return (Array.isArray(items) ? items : [])
+    .map((item, index) => {
+      if (!item || typeof item !== "object") return `index:${index}`;
+      const changeType = String(item.change_type || item.action || "suggestion").trim().toLowerCase() || "suggestion";
+      const changeSet = item.change_set && typeof item.change_set === "object" ? item.change_set : item;
+      return firstNonEmptyString(
+        item.suggestion_id,
+        item.mission_id,
+        item.client_ref,
+        changeSet.title ? `${changeType}:${String(changeSet.title).slice(0, 80)}` : "",
+        `index:${index}`
+      );
+    })
+    .filter(Boolean);
 }
 
 function parseYaml(text) {
-  const raw = String(text || "").trim();
-  if (!raw) return null;
-  if (raw.startsWith("{") || raw.startsWith("[")) {
+  const raw = String(text || "").trim();
+  if (!raw) return null;
+  if (raw.startsWith("{") || raw.startsWith("[")) {
     return JSON.parse(raw);
   }
   return parseSimpleYaml(raw);
@@ -3519,19 +3426,123 @@ function resolvePortableWorkspace(repoNames) {
   };
 }
 
-function resolveCommandCenterRoots(wrapperRoot, outputDir) {
-  const targetRoot = outputDir
-    ? path.resolve(process.cwd(), String(outputDir))
-    : path.join(wrapperRoot, "MyteCommandCenter");
-  return {
-    targetRoot,
-    dataRoot: path.join(targetRoot, "data"),
-  };
-}
-
-function pruneLegacyCommandCenterArtifacts(dataRoot, options = {}) {
-  const {
-    bootstrap = false,
+function resolveCommandCenterRoots(wrapperRoot, outputDir) {
+  const targetRoot = outputDir
+    ? path.resolve(process.cwd(), String(outputDir))
+    : path.join(wrapperRoot, "MyteCommandCenter");
+  return {
+    targetRoot,
+    dataRoot: path.join(targetRoot, "data"),
+  };
+}
+
+function buildAgentsMyteApiMarkdown() {
+  return ensureTrailingNewline([
+    "# AgentsMyteAPI",
+    "",
+    "This file is generated by `myte bootstrap` as contextual guidance for coding agents using a project-scoped Myte API key.",
+    "It does not grant permission, approve a write, or replace project authorization. Prefer the `myte` CLI over direct HTTP.",
+    "",
+    "## Auth And Discovery",
+    "",
+    "- Use `MYTE_API_KEY` or `MYTE_PROJECT_API_KEY` for `/api/project-assistant/*`.",
+    "- Default API base: `https://api.myte.dev/api`.",
+    "- Start with `myte config --json`, then `myte bootstrap --json`.",
+    "- Use local IDs from `MyteCommandCenter/data/missions/*.yml`, `data/mission-ops.yml`, and `data/feedback.yml`.",
+    "- `myte ai` is intentionally outside this project-scoped table. It uses `MYTEAI_API_KEY` and the Myte AI gateway, not `/api/project-assistant/*`.",
+    "",
+    "## Approval Artifact Rule",
+    "",
+    "Only the commands marked `required` below need `--confirm-write --approval-artifact <path>`.",
+    "Approval artifacts are local `.md`, `.markdown`, `.yml`, `.yaml`, or `.json` files that list the operation, exact target IDs, proposed change, and batch count when relevant.",
+    "The artifact is the human-reviewed record of the intended mutation. It does not grant permission, bypass owner/delegate checks, or replace idempotency; it gives the API enough evidence that a human approved this exact write payload.",
+    "",
+    "Minimum artifact contents for required actions:",
+    "",
+    "- `command`: the exact CLI command you plan to run.",
+    "- `targets`: every affected project, feedback, request, suggestion, mission, PRD file, client ref, or contact id.",
+    "- `proposed_change`: a complete summary of the text/status/content being sent.",
+    "- `batch_count`: required when the command sends more than one item in one API call.",
+    "- `reason` or `approval_note`: why the write is being sent now.",
+    "",
+    "Batch guidance:",
+    "",
+    "- Mission edit/create batches use `myte suggestions create` or `myte suggestions revise`; the artifact must list each item. For mission edits include `change_type: update`, the existing `mission_id`, and the changed fields. For new missions include `change_type: create`, the proposed title, description, and acceptance details. For revisions include each `suggestion_id` and expected revision.",
+    "- PRD batches use one `myte create-prd fileA.md fileB.md ...`; the artifact must list each PRD file/title/client ref. `batch_count` must match the number of PRD items.",
+    "- Feedback submit/revise/comment artifacts are usually the same YAML or markdown file being submitted. If the command uses inline text or stdin, create a separate approval memo that includes the feedback id or request id and the exact content.",
+    "- Team, owner, and client update artifacts should name the audience and include the exact message body or a complete summary; client updates should include target contact ids when used.",
+    "- `feedback review --request-ids`, `feedback move --feedback-ids`, `mission status --mission-ids`, `mission archive --mission-ids`, and `run-qaqc --mission-ids` are batched governed writes, but they are marked `no` below and should not receive approval artifact flags.",
+    "",
+    "Example approval artifact:",
+    "",
+    "```yaml",
+    "command: myte suggestions create --file ./mission-suggestions.yml --confirm-write --approval-artifact ./mission-suggestions-approval.yml",
+    "reason: Human approved this mission review batch after inspecting the proposed changes.",
+    "batch_count: 2",
+    "targets:",
+    "  - mission_id: M093",
+    "    change_type: update",
+    "    proposed_change: Mark acceptance criteria complete and clarify final QA note.",
+    "  - new_mission: Add deployment verification",
+    "    change_type: create",
+    "    proposed_change: Create a mission to verify deploy logs, smoke test, and rollback note.",
+    "```",
+    "",
+    "| Action | CLI shape | API route | Class | Artifact approval |",
+    "|---|---|---|---|---|",
+    "| Config | `myte config --json` | `GET /project-assistant/config` | read | no |",
+    "| Query | `myte query \"...\" --with-diff` | `POST /project-assistant/query`; polls `GET /project-assistant/query/<job_id>` when queued; `--with-diff` also reads `GET /project-assistant/config` | query job | no |",
+    "| Bootstrap | `myte bootstrap --json` | `GET /project-assistant/bootstrap` and `GET /project-assistant/suggestions` | local sync | no |",
+    "| QAQC sync | `myte sync-qaqc --json` | `GET /project-assistant/qaqc-sync` | local sync | no |",
+    "| Run QAQC | `myte run-qaqc --mission-ids \"M001,M002\" --wait --sync --json` | `POST /project-assistant/run-qaqc`; `--wait` polls `GET /project-assistant/run-qaqc/<batch_id>`; `--sync` reads `GET /project-assistant/qaqc-sync` | governed write | no |",
+    "| Mission status | `myte mission status --mission-ids \"M001\" --status done --json` | `POST /project-assistant/mission-status-update` | governed write | no |",
+    "| Mission archive | `myte mission archive --mission-ids \"M001\" --reason \"...\" --json` | `POST /project-assistant/mission-archive` | governed write | no |",
+    "| Suggestions sync | `myte suggestions sync --json` | `GET /project-assistant/suggestions` | local sync | no |",
+    "| Suggestions create | `myte suggestions create --file ./create.yml --confirm-write --approval-artifact ./create.yml --json` | `POST /project-assistant/suggestions` | review-thread write | required |",
+    "| Suggestions revise | `myte suggestions revise --file ./revise.yml --confirm-write --approval-artifact ./revise.yml --json` | `POST /project-assistant/suggestions/revise` | review-thread write | required |",
+    "| Suggestions review | `myte suggestions review --file ./review.yml --json` | `POST /project-assistant/suggestions/review` | governed review write | no |",
+    "| Feedback sync | `myte feedback-sync --json` | `GET /project-assistant/feedback-sync` | local sync | no |",
+    "| Feedback get | `myte feedback get --feedback-id <id> --json` | `GET /project-assistant/feedback/<id>` | read | no |",
+    "| Feedback history | `myte feedback history --feedback-id <id> --json` | `GET /project-assistant/feedback/<id>/events` | read | no |",
+    "| Feedback local drafts | `myte feedback status/edit/assign/archive/refine ...` | none | local artifact only | no |",
+    "| Feedback validate | `myte feedback validate --file ./review.yml --json` | `POST /project-assistant/feedback/<id>/refinement/validate` | validation | no |",
+    "| Feedback submit | `myte feedback submit --file ./review.yml --confirm-write --approval-artifact ./review.yml --json` | `POST /project-assistant/feedback/<id>/refinement/requests` | review-request write | required |",
+    "| Feedback revise | `myte feedback revise --request-id <id> --file ./review.yml --confirm-write --approval-artifact ./review.yml --json` | `POST /project-assistant/feedback-review-requests/<id>/revise` | review-request write | required |",
+    "| Feedback reviews | `myte feedback reviews [--status open/terminal/all] [--request-id <id>] --json` (`requests` alias) | `GET /project-assistant/feedback-review-requests` or `GET /project-assistant/feedback-review-requests/<id>` | read | no |",
+    "| Feedback review | `myte feedback review --request-id <id> --action approve/reject/request_changes/cancel [--reason \"...\"] --json` | `POST /project-assistant/feedback-review-requests/<id>/review`, `/request-changes`, or `/cancel` | governed review write | no |",
+    "| Feedback batch review | `myte feedback review --request-ids \"<id1,id2>\" --action approve/reject/request_changes/cancel --json` | `POST /project-assistant/feedback-review-requests/batch-review` | governed review write | no |",
+    "| Feedback move | `myte feedback move --feedback-id <id> --to-state in_progress --reason \"...\" --json` | `POST /project-assistant/feedback/<id>/board-move` | governed write | no |",
+    "| Feedback batch move | `myte feedback move --feedback-ids \"<id1,id2>\" --to-state in_progress --json` | `POST /project-assistant/feedback/batch-board-move` | governed write | no |",
+    "| Feedback comment | `myte feedback comment --feedback-id <id> --body-file ./comment.md --confirm-write --approval-artifact ./comment.md --json` | `POST /project-assistant/feedback/<id>/comments` | comment write | required |",
+    "| Feedback undo | `myte feedback undo --feedback-id <id> --event-id <id> --reason \"...\" --json` | `POST /project-assistant/feedback/<id>/events/<event_id>/undo` | governed write | no |",
+    "| Feedback PRD versions | `myte feedback prd-versions --feedback-id <id> --json` | `GET /project-assistant/feedback/<id>/prd/versions` | read | no |",
+    "| Feedback PRD diff | `myte feedback prd-diff --feedback-id <id> --version-id <id>` | `GET /project-assistant/feedback/<id>/prd/versions/<version_id>/diff` | read | no |",
+    "| Feedback apply | `myte feedback apply --file ./review.yml --json` | `POST /project-assistant/feedback/<id>/refinement/apply` | governed write | no |",
+    "| Create PRD | `myte create-prd ./prd.md --confirm-write --approval-artifact ./prd.md --json` | `POST /project-assistant/create-prd` | PRD write | required |",
+    "| Batch create PRDs | `myte create-prd ./a.md ./b.md --confirm-write --approval-artifact ./approval.md --json` | `POST /project-assistant/create-prds` | PRD write | required |",
+    "| Team update | `myte update-team \"...\" --confirm-write --approval-artifact ./team.md --json` | `POST /project-assistant/project-comment` | project comment | required |",
+    "| Owner update | `myte update-owner --subject \"...\" --body-file ./owner.md --confirm-write --approval-artifact ./owner.md --json` | `POST /project-assistant/update-owner` | owner email | required |",
+    "| Client update | `myte update-client --subject \"...\" --body-file ./client.md --confirm-write --approval-artifact ./client.md --json` | `POST /project-assistant/client-update-drafts` | client draft | required |",
+    "",
+    "## Agent Rules",
+    "",
+    "- For `required` actions, draft the artifact, show it to the user, get explicit approval, then rerun with the approval flags.",
+    "- For `no` actions, do not add approval flags. The API still enforces key binding, project permissions, idempotency, stale-state checks, and route validation.",
+    "- For local draft actions, inspect the generated YAML before submitting or applying it.",
+    "- Use `--print-context` or `--dry-run` where available to inspect payloads without sending a write.",
+  ].join("\n"));
+}
+
+function writeAgentsMyteApiGuide({ wrapperRoot, outputDir }) {
+  const { targetRoot } = resolveCommandCenterRoots(wrapperRoot, outputDir);
+  const guidePath = path.join(targetRoot, "AgentsMyteAPI.md");
+  writeTextFile(guidePath, buildAgentsMyteApiMarkdown());
+  return guidePath;
+}
+
+function pruneLegacyCommandCenterArtifacts(dataRoot, options = {}) {
+  const {
+    bootstrap = false,
     qaqc = false,
     feedback = false,
     missionOps = false,
@@ -3609,11 +3620,12 @@ function writeBootstrapSnapshot({ snapshot, wrapperRoot, outputDir }) {
     writeYamlFile(path.join(missionsDir, `${missionPathId}.yml`), mission);
   });
 
-  if (snapshot.project && typeof snapshot.project === "object") {
-    writeYamlFile(path.join(dataRoot, "project.yml"), scrubBootstrapValue(snapshot.project));
-  }
-
-  const manifest = {
+  if (snapshot.project && typeof snapshot.project === "object") {
+    writeYamlFile(path.join(dataRoot, "project.yml"), scrubBootstrapValue(snapshot.project));
+  }
+  const agentsMyteApiPath = writeAgentsMyteApiGuide({ wrapperRoot, outputDir });
+
+  const manifest = {
     schema_version: snapshot.schema_version || 1,
     generated_at: snapshot.generated_at || null,
     snapshot_hash: snapshot.snapshot_hash || null,
@@ -3626,12 +3638,13 @@ function writeBootstrapSnapshot({ snapshot, wrapperRoot, outputDir }) {
       missions: missions.length,
     },
   };
-  return {
-    targetRoot,
-    dataRoot,
-    manifest,
-  };
-}
+  return {
+    targetRoot,
+    dataRoot,
+    agentsMyteApiPath,
+    manifest,
+  };
+}
 
 function writeQaqcSnapshot({ snapshot, wrapperRoot, outputDir }) {
   const { targetRoot, dataRoot } = resolveCommandCenterRoots(wrapperRoot, outputDir);
@@ -4514,7 +4527,7 @@ async function fetchSuggestionsSyncSnapshot({ apiBase, key, timeoutMs, actorScop
   return body.data || {};
 }
 
-async function createProjectSuggestions({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function createProjectSuggestions({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId }) {
   return postSuggestionsMutation({
     apiBase,
     key,
@@ -4523,11 +4536,10 @@ async function createProjectSuggestions({ apiBase, key, timeoutMs, payload, idem
     payload,
     idempotencyKey,
     clientSessionId,
-    writeApproval,
   });
 }
 
-async function reviseProjectSuggestions({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function reviseProjectSuggestions({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId }) {
   return postSuggestionsMutation({
     apiBase,
     key,
@@ -4536,11 +4548,10 @@ async function reviseProjectSuggestions({ apiBase, key, timeoutMs, payload, idem
     payload,
     idempotencyKey,
     clientSessionId,
-    writeApproval,
   });
 }
 
-async function reviewProjectSuggestions({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function reviewProjectSuggestions({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId }) {
   return postSuggestionsMutation({
     apiBase,
     key,
@@ -4549,7 +4560,6 @@ async function reviewProjectSuggestions({ apiBase, key, timeoutMs, payload, idem
     payload,
     idempotencyKey,
     clientSessionId,
-    writeApproval,
   });
 }
 
@@ -4658,20 +4668,19 @@ async function runCreatePrd(args) {
 
   const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
 
-  if (payloads.length === 1) {
-    let data;
-    const payload = payloads[0];
-    if (clientSessionId) payload.client_session_id = clientSessionId;
-    const idempotencyKey = resolveProjectMutationIdempotencyKey({
-      args,
-      operation: "create_prd",
+  if (payloads.length === 1) {
+    let data;
+    let payload = payloads[0];
+    if (clientSessionId) payload.client_session_id = clientSessionId;
+    payload = withWriteApproval(args, payload, {
+      artifactKind: "markdown",
+      targets: [firstNonEmptyString(payload.client_ref, payload.title, "create-prd")],
+    });
+    const idempotencyKey = resolveProjectMutationIdempotencyKey({
+      args,
+      operation: "create_prd",
       payload,
     });
-    const writeApproval = requireWriteApproval(args, payload, {
-      operation: "create_prd",
-      artifactKind: "markdown",
-      targets: prdApprovalTargets(payload),
-    });
     try {
       data = await postSuggestionsMutation({
         apiBase,
@@ -4681,7 +4690,6 @@ async function runCreatePrd(args) {
         endpoint: "/project-assistant/create-prd",
         idempotencyKey,
         clientSessionId,
-        writeApproval,
       });
     } catch (err) {
       if (err?.name === "AbortError") {
@@ -4723,22 +4731,20 @@ async function runCreatePrd(args) {
     failed_count: 0,
     items: [],
   };
-
-  try {
-    const payload = { items: payloads };
-    if (clientSessionId) payload.client_session_id = clientSessionId;
-    const idempotencyKey = resolveProjectMutationIdempotencyKey({
-      args,
-      operation: "create_prds",
+
+  try {
+    let payload = { items: payloads };
+    if (clientSessionId) payload.client_session_id = clientSessionId;
+    payload = withWriteApproval(args, payload, {
+      artifactKind: "markdown",
+      targets: payloads.map((item, index) => firstNonEmptyString(item.client_ref, item.title, `index:${index}`)),
+      batchCount: payloads.length,
+    });
+    const idempotencyKey = resolveProjectMutationIdempotencyKey({
+      args,
+      operation: "create_prds",
       payload,
     });
-    const prdTargets = prdApprovalTargets(payload);
-    const writeApproval = requireWriteApproval(args, payload, {
-      operation: "create_prds",
-      artifactKind: "markdown",
-      targets: prdTargets,
-      batchCount: prdTargets.length,
-    });
     const data = await postSuggestionsMutation({
       apiBase,
       key,
@@ -4747,7 +4753,6 @@ async function runCreatePrd(args) {
       endpoint: "/project-assistant/create-prds",
       idempotencyKey,
       clientSessionId,
-      writeApproval,
     });
     aggregated.project_id = data.project_id || null;
     aggregated.created_count = Number(data.created_count || 0);
@@ -4932,10 +4937,11 @@ async function runBootstrap(args) {
     return;
   }
 
-  const writeResult = writeBootstrapSnapshot({ snapshot, wrapperRoot, outputDir });
-  summary.data_root = writeResult.dataRoot;
-
-  if (includeSuggestions) {
+  const writeResult = writeBootstrapSnapshot({ snapshot, wrapperRoot, outputDir });
+  summary.data_root = writeResult.dataRoot;
+  summary.agents_myte_api_path = writeResult.agentsMyteApiPath;
+
+  if (includeSuggestions) {
     let missionOpsSnapshot;
     try {
       missionOpsSnapshot = await fetchSuggestionsSyncSnapshot({ apiBase, key, timeoutMs, actorScope });
@@ -4966,9 +4972,10 @@ async function runBootstrap(args) {
   console.log(`Output root: ${summary.output_root}`);
   console.log(`Configured repos: ${summary.repo_names.join(", ") || "(none)"}`);
   console.log(`Found locally: ${summary.local.found.join(", ") || "(none)"}`);
-  if (summary.local.missing.length) console.log(`Missing locally: ${summary.local.missing.join(", ")}`);
-  console.log(`Wrote: phases=${summary.counts.phases}, epics=${summary.counts.epics}, stories=${summary.counts.stories}, missions=${summary.counts.missions}`);
-  if (summary.mission_ops?.included) {
+  if (summary.local.missing.length) console.log(`Missing locally: ${summary.local.missing.join(", ")}`);
+  console.log(`Wrote: phases=${summary.counts.phases}, epics=${summary.counts.epics}, stories=${summary.counts.stories}, missions=${summary.counts.missions}`);
+  if (summary.agents_myte_api_path) console.log(`Wrote AgentsMyteAPI: ${summary.agents_myte_api_path}`);
+  if (summary.mission_ops?.included) {
     console.log(`Wrote mission ops: total_threads=${summary.mission_ops.total_threads}, actionable_threads=${summary.mission_ops.actionable_threads}`);
   } else {
     console.log("Skipped mission ops sync.");
@@ -5304,7 +5311,8 @@ async function runFeedbackValidateOrApply(args, mode) {
     console.error("Missing MYTE_API_KEY (project key) in environment/.env");
     process.exit(1);
   }
-  const { absPath, payload } = readFeedbackRefinementArtifact(args);
+  const { absPath, payload: artifactPayload } = readFeedbackRefinementArtifact(args);
+  let payload = artifactPayload;
   const feedbackId = firstNonEmptyString(args["feedback-id"], args.feedbackId, args.feedback_id, payload.feedback_id);
   if (!feedbackId) {
     console.error("Feedback refinement artifact is missing feedback_id.");
@@ -5314,26 +5322,19 @@ async function runFeedbackValidateOrApply(args, mode) {
 
   const timeoutMs = resolveTimeoutMs(args);
   const apiBase = resolveApiBase(args);
-  const clientSessionId = firstNonEmptyString(
+  const clientSessionId = firstNonEmptyString(
     args["client-session-id"],
     args.clientSessionId,
     args.client_session_id,
     payload.client_session_id
-  );
-  const idempotencyKey = mode === "apply"
-    ? resolveProjectMutationIdempotencyKey({
-        args,
+  );
+  const idempotencyKey = mode === "apply"
+    ? resolveProjectMutationIdempotencyKey({
+        args,
         operation: `feedback_refinement_apply:${feedbackId}`,
         payload,
       })
     : null;
-  const writeApproval = mode === "apply"
-    ? requireWriteApproval(args, payload, {
-        operation: `feedback_refinement_apply:${feedbackId}`,
-        artifactKind: "yaml",
-        targets: [feedbackId],
-      })
-    : null;
 
   let data;
   try {
@@ -5346,7 +5347,6 @@ async function runFeedbackValidateOrApply(args, mode) {
       payload,
       idempotencyKey,
       clientSessionId,
-      writeApproval,
     });
   } catch (err) {
     if (args.json) {
@@ -5458,7 +5458,8 @@ async function runFeedbackSubmit(args) {
     console.error("Missing MYTE_API_KEY (project key) in environment/.env");
     process.exit(1);
   }
-  const { absPath, payload } = readFeedbackRefinementArtifact(args);
+  const { absPath, payload: artifactPayload } = readFeedbackRefinementArtifact(args);
+  let payload = artifactPayload;
   const feedbackId = firstNonEmptyString(args["feedback-id"], args.feedbackId, args.feedback_id, payload.feedback_id);
   if (!feedbackId) {
     console.error("Feedback refinement artifact is missing feedback_id.");
@@ -5466,22 +5467,21 @@ async function runFeedbackSubmit(args) {
   }
   const timeoutMs = resolveTimeoutMs(args);
   const apiBase = resolveApiBase(args);
-  const clientSessionId = firstNonEmptyString(
+  const clientSessionId = firstNonEmptyString(
     args["client-session-id"],
     args.clientSessionId,
     args.client_session_id,
     payload.client_session_id
-  );
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+  );
+  payload = withWriteApproval(args, payload, {
+    artifactKind: "yaml",
+    targets: [feedbackId],
+  });
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
     args,
     operation: `feedback_refinement_request_submit:${feedbackId}`,
     payload,
   });
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: `feedback_refinement_request_submit:${feedbackId}`,
-    artifactKind: "yaml",
-    targets: [feedbackId],
-  });
 
   let data;
   try {
@@ -5493,7 +5493,6 @@ async function runFeedbackSubmit(args) {
       payload,
       idempotencyKey,
       clientSessionId,
-      writeApproval,
     });
   } catch (err) {
     if (args.json) {
@@ -5535,25 +5534,25 @@ async function runFeedbackRevise(args) {
     console.error("Missing --request-id.");
     process.exit(1);
   }
-  const { absPath, payload } = readFeedbackRefinementArtifact(args);
+  const { absPath, payload: artifactPayload } = readFeedbackRefinementArtifact(args);
+  let payload = artifactPayload;
   const timeoutMs = resolveTimeoutMs(args);
   const apiBase = resolveApiBase(args);
-  const clientSessionId = firstNonEmptyString(
+  const clientSessionId = firstNonEmptyString(
     args["client-session-id"],
     args.clientSessionId,
     args.client_session_id,
     payload.client_session_id
-  );
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+  );
+  payload = withWriteApproval(args, payload, {
+    artifactKind: "yaml",
+    targets: [requestId],
+  });
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
     args,
     operation: `feedback_refinement_request_revise:${requestId}`,
     payload,
   });
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: `feedback_refinement_request_revise:${requestId}`,
-    artifactKind: "yaml",
-    targets: [requestId],
-  });
 
   let data;
   try {
@@ -5566,7 +5565,6 @@ async function runFeedbackRevise(args) {
       payload,
       idempotencyKey,
       clientSessionId,
-      writeApproval,
     });
   } catch (err) {
     if (args.json) {
@@ -5684,29 +5682,20 @@ async function runFeedbackReviewDecision(args) {
       process.exit(1);
     }
     const reason = firstNonEmptyString(args.reason, args["review-note"], args.reviewNote, args.review_note);
-    const payload = {
-      ...(isPlainObject(filePayload) && !Array.isArray(filePayload) ? filePayload : {}),
-      items,
-      action,
-      reason: reason || undefined,
-    };
-    const timeoutMs = resolveTimeoutMs(args);
-    const apiBase = resolveApiBase(args);
+    let payload = {
+      ...(isPlainObject(filePayload) && !Array.isArray(filePayload) ? filePayload : {}),
+      items,
+      action,
+      reason: reason || undefined,
+    };
+    const timeoutMs = resolveTimeoutMs(args);
+    const apiBase = resolveApiBase(args);
     const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id, payload.client_session_id);
     const idempotencyKey = resolveProjectMutationIdempotencyKey({
       args,
       operation: `feedback_review_batch:${action}:${items.map((item) => item.request_id || item.id || "").join(",")}`,
       payload,
     });
-    const requestTargets = items
-      .map((item, index) => firstNonEmptyString(item.request_id, item.id, item._id) || `index:${index}`)
-      .filter(Boolean);
-    const writeApproval = requireWriteApproval(args, payload, {
-      operation: `feedback_review_batch:${action}`,
-      artifactKind: "yaml",
-      targets: requestTargets,
-      batchCount: items.length,
-    });
 
     let data;
     try {
@@ -5717,7 +5706,6 @@ async function runFeedbackReviewDecision(args) {
         payload,
         idempotencyKey,
         clientSessionId,
-        writeApproval,
       });
     } catch (err) {
       if (args.json) {
@@ -5745,8 +5733,8 @@ async function runFeedbackReviewDecision(args) {
     process.exit(1);
   }
 
-  let payload;
-  try {
+  let payload;
+  try {
     payload = filePayload && !Array.isArray(filePayload?.items)
       ? buildFeedbackReviewDecisionPayload({ ...args, file: "" }, action)
       : buildFeedbackReviewDecisionPayload(args, action);
@@ -5757,9 +5745,9 @@ async function runFeedbackReviewDecision(args) {
     console.error(err?.message || err);
     process.exit(1);
   }
-  const endpointAction = action === "request_changes" ? "request-changes" : action === "cancel" ? "cancel" : "review";
-  const timeoutMs = resolveTimeoutMs(args);
-  const apiBase = resolveApiBase(args);
+  const endpointAction = action === "request_changes" ? "request-changes" : action === "cancel" ? "cancel" : "review";
+  const timeoutMs = resolveTimeoutMs(args);
+  const apiBase = resolveApiBase(args);
   const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id, payload.client_session_id);
   const operationAction = action === "request_changes" ? "request_changes" : action;
   const idempotencyKey = resolveProjectMutationIdempotencyKey({
@@ -5767,11 +5755,6 @@ async function runFeedbackReviewDecision(args) {
     operation: `feedback_review_request_${operationAction}:${requestId}`,
     payload,
   });
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: `feedback_review_request_${operationAction}:${requestId}`,
-    artifactKind: "yaml",
-    targets: [requestId],
-  });
 
   let data;
   try {
@@ -5784,7 +5767,6 @@ async function runFeedbackReviewDecision(args) {
       payload,
       idempotencyKey,
       clientSessionId,
-      writeApproval,
     });
   } catch (err) {
     if (args.json) {
@@ -5823,32 +5805,26 @@ async function runFeedbackMove(args) {
     process.exit(1);
   }
   const fromState = firstNonEmptyString(args["from-state"], args.fromState, args.from_state) || undefined;
-  const payload = {
-    to_state: toState,
-    reason: firstNonEmptyString(args.reason) || undefined,
-  };
+  let payload = {
+    to_state: toState,
+    reason: firstNonEmptyString(args.reason) || undefined,
+  };
   const timeoutMs = resolveTimeoutMs(args);
   const apiBase = resolveApiBase(args);
   const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
   const isBatch = feedbackIds.length > 1 || Boolean(firstNonEmptyString(args["feedback-ids"], args.feedbackIds, args.feedback_ids));
-  if (isBatch) {
-    payload.feedback_ids = feedbackIds;
+  if (isBatch) {
+    payload.feedback_ids = feedbackIds;
     if (fromState) {
       payload.from_states = Object.fromEntries(feedbackIds.map((id) => [id, fromState]));
     }
     const batchId = firstNonEmptyString(args["batch-id"], args.batchId, args.batch_id);
-    if (batchId) payload.batch_id = batchId;
-    const idempotencyKey = resolveProjectMutationIdempotencyKey({
-      args,
-      operation: `feedback_board_batch_move:${toState}:${feedbackIds.join(",")}`,
+    if (batchId) payload.batch_id = batchId;
+    const idempotencyKey = resolveProjectMutationIdempotencyKey({
+      args,
+      operation: `feedback_board_batch_move:${toState}:${feedbackIds.join(",")}`,
       payload,
     });
-    const writeApproval = requireWriteApproval(args, payload, {
-      operation: `feedback_board_batch_move:${toState}`,
-      artifactKind: "yaml",
-      targets: feedbackIds,
-      batchCount: feedbackIds.length,
-    });
     let data;
     try {
       data = await postFeedbackBatchBoardMutation({
@@ -5858,7 +5834,6 @@ async function runFeedbackMove(args) {
         payload,
         idempotencyKey,
         clientSessionId,
-        writeApproval,
       });
     } catch (err) {
       if (args.json) {
@@ -5879,18 +5854,13 @@ async function runFeedbackMove(args) {
     if (postSync?.error) console.error(`Feedback sync warning: ${postSync.error}`);
     return;
   }
-
-  payload.from_state = fromState;
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
-    args,
-    operation: `feedback_board_move:${feedbackId}`,
+
+  payload.from_state = fromState;
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
+    operation: `feedback_board_move:${feedbackId}`,
     payload,
   });
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: `feedback_board_move:${feedbackId}`,
-    artifactKind: "yaml",
-    targets: [feedbackId],
-  });
 
   let data;
   try {
@@ -5903,7 +5873,6 @@ async function runFeedbackMove(args) {
       payload,
       idempotencyKey,
       clientSessionId,
-      writeApproval,
     });
   } catch (err) {
     if (args.json) {
@@ -5944,12 +5913,16 @@ async function runFeedbackComment(args) {
     process.exit(1);
   }
 
-  const payload = { content };
-  const timeoutMs = resolveTimeoutMs(args);
-  const apiBase = resolveApiBase(args);
-  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
-  if (clientSessionId) payload.client_session_id = clientSessionId;
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+  let payload = { content };
+  const timeoutMs = resolveTimeoutMs(args);
+  const apiBase = resolveApiBase(args);
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  if (clientSessionId) payload.client_session_id = clientSessionId;
+  payload = withWriteApproval(args, payload, {
+    artifactKind: "markdown",
+    targets: [feedbackId],
+  });
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
     args,
     operation: `feedback_comment_create:${feedbackId}`,
     payload,
@@ -5960,12 +5933,6 @@ async function runFeedbackComment(args) {
     return;
   }
 
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: `feedback_comment_create:${feedbackId}`,
-    artifactKind: "markdown",
-    targets: [feedbackId],
-  });
-
   let data;
   try {
     data = await postFeedbackComment({
@@ -5976,7 +5943,6 @@ async function runFeedbackComment(args) {
       payload,
       idempotencyKey,
       clientSessionId,
-      writeApproval,
     });
   } catch (err) {
     if (args.json) {
@@ -6025,27 +5991,16 @@ async function runFeedbackUndo(args) {
     console.error("Missing --event-id.");
     process.exit(1);
   }
-  const payload = { reason: firstNonEmptyString(args.reason) || undefined };
-  const timeoutMs = resolveTimeoutMs(args);
-  const apiBase = resolveApiBase(args);
-  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
-    args,
-    operation: `feedback_event_undo:${feedbackId}:${eventId}`,
+  let payload = { reason: firstNonEmptyString(args.reason) || undefined };
+  const timeoutMs = resolveTimeoutMs(args);
+  const apiBase = resolveApiBase(args);
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
+    operation: `feedback_event_undo:${feedbackId}:${eventId}`,
     payload,
   });
 
-  if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
-    console.log(JSON.stringify(payload, null, 2));
-    return;
-  }
-
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: `feedback_event_undo:${feedbackId}:${eventId}`,
-    artifactKind: "yaml",
-    targets: [feedbackId, eventId],
-  });
-
   let data;
   try {
     data = await postFeedbackBoardMutation({
@@ -6057,7 +6012,6 @@ async function runFeedbackUndo(args) {
       payload,
       idempotencyKey,
       clientSessionId,
-      writeApproval,
     });
   } catch (err) {
     if (args.json) {
@@ -6343,14 +6297,22 @@ async function buildSuggestionsMutationContext(args, mode) {
   if (clientSessionId && !payload.client_session_id) {
     payload.client_session_id = clientSessionId;
   }
-  if (mode === "create") {
-    validateSuggestionsCreatePayload(payload);
-  } else if (mode === "revise") {
-    validateSuggestionsRevisePayload(payload);
-  }
-  const idempotencyKey = resolveSuggestionsIdempotencyKey({
-    args,
-    mode,
+  if (mode === "create") {
+    validateSuggestionsCreatePayload(payload);
+  } else if (mode === "revise") {
+    validateSuggestionsRevisePayload(payload);
+  }
+  const items = Array.isArray(payload?.items) ? payload.items : [];
+  if (mode === "create" || mode === "revise") {
+    payload = withWriteApproval(args, payload, {
+      artifactKind: "yaml",
+      targets: suggestionWriteTargets(items),
+      batchCount: items.length > 1 ? items.length : null,
+    });
+  }
+  const idempotencyKey = resolveSuggestionsIdempotencyKey({
+    args,
+    mode,
     actorScope,
     payload,
   });
@@ -6436,14 +6398,6 @@ async function runSuggestionsCreate(args) {
     return;
   }
 
-  const createTargets = suggestionApprovalTargets(context.payload);
-  const writeApproval = requireWriteApproval(args, context.payload, {
-    operation: "suggestions.create",
-    artifactKind: "yaml",
-    targets: createTargets,
-    batchCount: createTargets.length > 1 ? createTargets.length : null,
-  });
-
   let data;
   try {
     data = await createProjectSuggestions({
@@ -6453,7 +6407,6 @@ async function runSuggestionsCreate(args) {
       payload: context.payload,
       idempotencyKey: context.idempotencyKey,
       clientSessionId: context.clientSessionId,
-      writeApproval,
     });
   } catch (err) {
     console.error("Suggestions create failed:", err?.message || err);
@@ -6530,14 +6483,6 @@ async function runSuggestionsRevise(args) {
     return;
   }
 
-  const reviseTargets = suggestionApprovalTargets(context.payload);
-  const writeApproval = requireWriteApproval(args, context.payload, {
-    operation: "suggestions.revise",
-    artifactKind: "yaml",
-    targets: reviseTargets,
-    batchCount: reviseTargets.length > 1 ? reviseTargets.length : null,
-  });
-
   let data;
   try {
     data = await reviseProjectSuggestions({
@@ -6547,7 +6492,6 @@ async function runSuggestionsRevise(args) {
       payload: context.payload,
       idempotencyKey: context.idempotencyKey,
       clientSessionId: context.clientSessionId,
-      writeApproval,
     });
   } catch (err) {
     console.error("Suggestions revise failed:", err?.message || err);
@@ -6622,14 +6566,6 @@ async function runSuggestionsReview(args) {
     return;
   }
 
-  const reviewTargets = suggestionApprovalTargets(context.payload);
-  const writeApproval = requireWriteApproval(args, context.payload, {
-    operation: "suggestions.review",
-    artifactKind: "yaml",
-    targets: reviewTargets,
-    batchCount: reviewTargets.length > 1 ? reviewTargets.length : null,
-  });
-
   let data;
   try {
     data = await reviewProjectSuggestions({
@@ -6639,7 +6575,6 @@ async function runSuggestionsReview(args) {
       payload: context.payload,
       idempotencyKey: context.idempotencyKey,
       clientSessionId: context.clientSessionId,
-      writeApproval,
     });
   } catch (err) {
     console.error("Suggestions review failed:", err?.message || err);