@mytegroupinc/myte-core 0.0.46 → 0.0.49

package/cli.js

@@ -7,9 +7,12 @@
  * - Deterministic diffs: fetch project config, resolve local project repos, then collect scoped git context
  */
 
-const fs = require("fs");
-const path = require("path");
-const { createHash } = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const dns = require("dns");
+const net = require("net");
+const tls = require("tls");
+const { createHash, randomUUID } = require("crypto");
 const { spawnSync } = require("child_process");
 const {
   DEFAULT_MYTEAI_BASE,
@@ -21,14 +24,16 @@ const {
   normalizeMyteAiBase,
 } = require("./lib/ai-gateway");
 
-const DEFAULT_API_BASE = "https://api.myte.dev";
-const DEFAULT_DIFF_LIMIT_CHARS = 500_000;
+const DEFAULT_API_BASE = "https://api.myte.dev";
+const DEFAULT_DIFF_LIMIT_CHARS = 500_000;
+const DEFAULT_FEEDBACK_SYNC_PAGE_SIZE = 50;
+const MAX_PRD_DOCUMENT_MARKDOWN_CHARS = 250_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.",
 };
@@ -45,11 +50,11 @@ function findEnvPath(startDir) {
   return null;
 }
 
-function loadEnv() {
-  const envPath = findEnvPath(process.cwd());
-  if (!envPath || !fs.existsSync(envPath)) return;
+function loadEnv() {
+  const envPath = findEnvPath(process.cwd());
+  if (!envPath || !fs.existsSync(envPath)) return null;
   const content = fs.readFileSync(envPath, "utf8");
-  content.split(/\r?\n/).forEach((line) => {
+  content.split(/\r?\n/).forEach((line) => {
     const trimmed = String(line || "").trim();
     if (!trimmed || trimmed.startsWith("#")) return;
     const idx = trimmed.indexOf("=");
@@ -63,10 +68,11 @@ function loadEnv() {
       val = val.slice(1, -1);
     }
     if (key && !(key in process.env)) {
-      process.env[key] = val;
-    }
-  });
-}
+      process.env[key] = val;
+    }
+  });
+  return envPath;
+}
 
 function splitCommand(argv) {
   if (argv[0] === "mission") {
@@ -89,8 +95,13 @@ function splitCommand(argv) {
     "query",
     "ai",
     "ask",
-    "chat",
-    "config",
+    "chat",
+    "config",
+    "doctor",
+    "info",
+    "version",
+    "--version",
+    "-v",
     "bootstrap",
     "suggestions",
     "run-qaqc",
@@ -112,8 +123,13 @@ function splitCommand(argv) {
     "-h",
   ]);
   const first = argv[0];
-  if (first && known.has(first)) {
-    const cmd = first === "--help" || first === "-h" ? "help" : first;
+  if (first && known.has(first)) {
+    const cmd =
+      first === "--help" || first === "-h"
+        ? "help"
+        : first === "--version" || first === "-v"
+          ? "version"
+          : first;
     return { command: cmd, rest: argv.slice(1) };
   }
   return { command: "query", rest: argv };
@@ -181,45 +197,48 @@ function printHelp() {
     "myte - Myte CLI",
     "",
     "Usage:",
-    "  myte query \"<text>\" [--with-diff] [--context \"...\"]",
+    "  myte query \"<text>\" [--with-diff] [--context \"...\"] [--request-id <id>] [--verbose] [--json]",
     "  myte ai \"<text>\" [--json-response] [--max-output-tokens 500]",
-    "  myte config [--json]",
+    "  myte config [--json]",
+    "  myte doctor [--json] [--timeout-ms <ms>] [--base-url <url>]",
+    "  myte info [--json]",
+    "  myte --version [--verbose] [--json]",
     "  myte bootstrap [--output-dir ./MyteCommandCenter] [--json]",
     "  myte run-qaqc --mission-ids \"M001[,M002...]\" [--wait] [--sync] [--force] [--json]",
     "  myte mission status --mission-ids \"M001[,M002...]\" --status todo|in_progress|done [--no-sync] [--json]",
     "  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]",
     "  myte feedback status --feedback-id <id> --status frozen|todo|in_progress|in_review|completed|deployed|rejected|archived --reason \"...\"",
-    "  myte feedback edit --feedback-id <id> [--title \"...\"] [--feedback-text \"...\"] [--priority High] [--reason \"...\"]",
+    "  myte feedback edit --feedback-id <id> [--title \"...\"] [--feedback-text \"...\"] [--prd-file ./document.md] [--document-id <id>] [--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 review --request-id <id> --action approve|reject|request_changes|cancel [--reason \"...\"] [--verification-evidence \"...\"] [--deployment-evidence \"...\"] [--json]",
+    "  myte feedback review --request-ids \"<id1,id2>\" --action approve|reject|request_changes|cancel [--reason \"...\"] [--verification-evidence \"...\"] [--deployment-evidence \"...\"] [--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 prd-diff --feedback-id <id> --version-id <id> [--compare-to <id>] [--document-id <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 ...] [--document-set] --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",
@@ -282,7 +301,9 @@ function printHelp() {
     "",
     "create-prd contract:",
     "  - Required: valid MYTE_API_KEY, PRD markdown body, title",
-    "  - Accepts one file or many files per command; multi-file uploads are sent in one deterministic batch request",
+    "  - Accepts one file or many files per command; multi-file uploads create separate feedback items by default",
+    "  - Add --document-set to create one feedback item containing up to three ordered markdown documents",
+    "  - Document-set source markdown is preserved exactly; canonical markdown is generated server-side for reading and DOCX rendering",
     "  - Title source: myte-kanban.title, first # heading, or --title",
     "  - Description source: myte-kanban.description or --description; this is a short feedback/card summary only",
     "  - Never put the full PRD in description. The complete PRD must live in the markdown file body",
@@ -327,12 +348,25 @@ function printHelp() {
     "  - comment creates text-only feedback-specific comments; attachments remain web UI only for this endpoint",
     "  - 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:",
+    "  - prd-versions/prd-diff expose retained PRD versions and backend-generated per-document text diffs",
+    "  - edit/refine with --prd-file updates a review artifact only; --document-id targets one document in a PRD document set",
+    "  - 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",
@@ -352,7 +386,9 @@ function printHelp() {
     "Options:",
     "  --with-diff           Include deterministic git diffs (project-scoped; fails fast if no project repos are configured or resolved)",
     "  --diff-limit <chars>  Truncate diff context to N chars (default: 500000)",
-    "  --timeout-ms <ms>     Request timeout (default: 300000)",
+    "  --timeout-ms <ms>     Request timeout (default: 300000)",
+    "  --verbose             Print sanitized transport and retry diagnostics",
+    "  --request-id <id>     Stable, non-secret query request/idempotency identifier",
     "  --base-url <url>      API base (default: https://api.myte.dev)",
     "  --payload-file <path> Raw OpenAI-style chat-completions payload for `myte ai`",
     "  --json-response       Ask the Myte AI gateway to return clean JSON only and send OpenAI-compatible response_format",
@@ -361,8 +397,9 @@ function printHelp() {
     "  --output-dir <path>   Command Center output directory (default: <current-workspace>/MyteCommandCenter)",
     "  --file <path>         YAML/JSON payload file for suggestions create/revise/review",
     "  --stdin               Read supported command content from stdin instead of inline text or a file path",
-    "  --title <text>        Override PRD title for raw markdown uploads",
-    "  --description <text>  Set feedback description/card summary for raw markdown uploads",
+    "  --title <text>        Override PRD title for raw markdown uploads",
+    "  --description <text>  Set feedback description/card summary for raw markdown uploads",
+    "  --document-set        Create one PRD feedback item containing one to three ordered markdown files",
     "  --content <text>      Team update content for update-team",
     "  --body <text>         Feedback comment body for feedback comment",
     "  --subject <text>      Subject for update-owner or update-client",
@@ -375,8 +412,10 @@ function printHelp() {
     "  --request-id <id>     Feedback review request ObjectId for submit/revise/review flows",
     "  --request-ids <ids>   Comma-separated Feedback review request ObjectIds for batch review",
     "  --event-id <id>       Feedback board event ObjectId for undo",
-    "  --version-id <id>     Feedback PRD version ObjectId for prd-diff",
-    "  --compare-to <id>     Optional base PRD version ObjectId for prd-diff",
+    "  --version-id <id>     Feedback PRD version ObjectId for prd-diff",
+    "  --compare-to <id>     Optional base PRD version ObjectId for prd-diff",
+    "  --document-id <id>    Stable PRD document id for document refinement or version diff",
+    "  --prd-file <path>     Read proposed PRD document Markdown into a local feedback review artifact",
     "  --action <value>      Feedback review action: approve, reject, request_changes, or cancel",
     "  --to-state <value>    Target canonical feedback board state for feedback move",
     "  --from-state <value>  Optional current-state guard for feedback move",
@@ -392,8 +431,10 @@ 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",
     "  --no-sync             Skip automatic post-mutation sync for suggestions, missions, and feedback mutations",
@@ -401,38 +442,42 @@ function printHelp() {
     "  --no-fetch            Don't git fetch origin main/master before diff",
     "",
     "Examples:",
-    "  myte query \"What changed in logging?\" --with-diff",
+    "  myte query \"What changed in logging?\" --with-diff",
+    "  myte doctor --json",
+    "  myte info --json",
+    "  myte --version --verbose",
     "  myte ai \"Explain what this repository does\"",
     "  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",
+    "  myte create-prd ./drafts/overview.md ./drafts/api.md ./drafts/web.md --document-set --title \"Platform PRD\" --confirm-write --approval-artifact ./drafts/platform-prd-approval.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);
@@ -655,14 +700,280 @@ function parseFeedbackRequestIdsArg(args) {
   );
 }
 
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-async function getFetch() {
-  if (typeof fetch !== "undefined") return fetch;
-  throw new Error("Global fetch is unavailable. myte requires Node 18+.");
-}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function proxyEnvironmentValue(env, lowerName, upperName) {
+  const lowerValue = String(env?.[lowerName] || "").trim();
+  if (lowerValue) return lowerValue;
+  return String(env?.[upperName] || "").trim();
+}
+
+function proxyEnvironmentSummary(env = process.env) {
+  const httpProxy = proxyEnvironmentValue(env, "http_proxy", "HTTP_PROXY");
+  const httpsProxy = proxyEnvironmentValue(env, "https_proxy", "HTTPS_PROXY");
+  const noProxy = proxyEnvironmentValue(env, "no_proxy", "NO_PROXY");
+  return {
+    configured: Boolean(httpProxy || httpsProxy),
+    http_proxy_present: Boolean(httpProxy),
+    https_proxy_present: Boolean(httpsProxy),
+    no_proxy_present: Boolean(noProxy),
+  };
+}
+
+function buildFetchRuntime({
+  env = process.env,
+  nativeFetch = globalThis.fetch,
+  undiciModule,
+} = {}) {
+  const proxySummary = proxyEnvironmentSummary(env);
+  if (!proxySummary.configured) {
+    if (typeof nativeFetch !== "function") {
+      const error = new Error("Global fetch is unavailable. myte requires Node 18.17+.");
+      error.code = "MYTE_FETCH_UNAVAILABLE";
+      throw error;
+    }
+    return {
+      fetch: nativeFetch,
+      transport: "node_fetch",
+      proxy: proxySummary,
+    };
+  }
+
+  let undici = undiciModule;
+  if (!undici) {
+    try {
+      undici = require("undici");
+    } catch (cause) {
+      const error = new Error(
+        "Proxy variables are configured, but the Myte HTTP transport is unavailable. Reinstall the myte package.",
+      );
+      error.code = "MYTE_PROXY_TRANSPORT_UNAVAILABLE";
+      error.cause = cause;
+      throw error;
+    }
+  }
+  if (typeof undici.fetch !== "function" || typeof undici.EnvHttpProxyAgent !== "function") {
+    const error = new Error(
+      "The installed Myte HTTP transport does not support HTTP_PROXY, HTTPS_PROXY, and NO_PROXY.",
+    );
+    error.code = "MYTE_PROXY_TRANSPORT_INCOMPATIBLE";
+    throw error;
+  }
+
+  const dispatcher = new undici.EnvHttpProxyAgent({
+    httpProxy: proxyEnvironmentValue(env, "http_proxy", "HTTP_PROXY") || undefined,
+    httpsProxy: proxyEnvironmentValue(env, "https_proxy", "HTTPS_PROXY") || undefined,
+    noProxy: proxyEnvironmentValue(env, "no_proxy", "NO_PROXY") || undefined,
+  });
+  return {
+    fetch: (url, options = {}) => undici.fetch(url, { ...options, dispatcher }),
+    transport: "undici_env_proxy",
+    proxy: proxySummary,
+  };
+}
+
+let fetchRuntimePromise = null;
+
+async function getFetchRuntime() {
+  if (!fetchRuntimePromise) {
+    fetchRuntimePromise = Promise.resolve().then(() => buildFetchRuntime());
+  }
+  return fetchRuntimePromise;
+}
+
+async function getFetch() {
+  return (await getFetchRuntime()).fetch;
+}
+
+function requestErrorChain(error) {
+  const chain = [];
+  const seen = new Set();
+  let current = error;
+  while (current && typeof current === "object" && !seen.has(current) && chain.length < 8) {
+    seen.add(current);
+    chain.push(current);
+    current = current.cause;
+  }
+  return chain;
+}
+
+function requestErrorCode(error) {
+  for (const item of requestErrorChain(error)) {
+    const code = String(item?.code || item?.errno || "").trim();
+    if (code) return code;
+  }
+  return "";
+}
+
+function requestErrorMessage(error) {
+  return requestErrorChain(error)
+    .map((item) => String(item?.message || "").trim())
+    .filter(Boolean)
+    .join(" ");
+}
+
+function safeEndpointHost(url) {
+  try {
+    return new URL(String(url || "")).host || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function classifyNetworkFailure(error, { timedOut = false } = {}) {
+  const code = timedOut ? "ETIMEDOUT" : requestErrorCode(error) || "NETWORK_ERROR";
+  const message = requestErrorMessage(error).toLowerCase();
+  const certificateFailure =
+    /^(CERT_|ERR_TLS_CERT_|DEPTH_ZERO_SELF_SIGNED_CERT|SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_VERIFY_LEAF_SIGNATURE)/.test(code) ||
+    /certificate|self[- ]signed|unable to verify|hostname\/ip does not match/.test(message);
+
+  if (timedOut || code === "ABORT_ERR" || code === "UND_ERR_CONNECT_TIMEOUT" || code === "ETIMEDOUT") {
+    return {
+      kind: "timeout",
+      layer: "network",
+      code,
+      detail: "The request exceeded its configured timeout before a complete HTTP response was received.",
+      guidance: "Retry on a stable network or increase --timeout-ms when the API is known to be reachable.",
+      transient: true,
+    };
+  }
+  if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
+    return {
+      kind: "dns",
+      layer: "dns",
+      code,
+      detail: "The API hostname could not be resolved.",
+      guidance: "Check DNS connectivity, captive-portal login, VPN, or local resolver settings.",
+      transient: true,
+    };
+  }
+  if (code === "ECONNREFUSED") {
+    return {
+      kind: "connection_refused",
+      layer: "tcp",
+      code,
+      detail: "The remote host refused the TCP connection.",
+      guidance: "Check the API base, proxy/VPN path, firewall policy, and service availability.",
+      transient: true,
+    };
+  }
+  if (certificateFailure) {
+    return {
+      kind: "tls_certificate",
+      layer: "tls",
+      code,
+      detail: "TLS certificate validation failed.",
+      guidance: "Check system time, trusted corporate certificates, proxy interception, and the requested hostname. Do not disable TLS verification.",
+      transient: false,
+    };
+  }
+  if (
+    code === "ECONNRESET" ||
+    code === "UND_ERR_SOCKET" ||
+    /secure tls connection|tls connection|socket disconnected|connection reset|other side closed/.test(message)
+  ) {
+    return {
+      kind: "connection_reset",
+      layer: "tls",
+      code,
+      detail: /before secure tls|secure tls connection/.test(message)
+        ? "The TLS connection was reset before the secure connection was established."
+        : "The network connection was reset before a complete HTTP response was received.",
+      guidance: "The API key was loaded, but the request did not reach the Myte API. Check captive-portal login, restricted Wi-Fi, proxy/VPN settings, or retry on another network.",
+      transient: true,
+    };
+  }
+  if (/ssl|tls|handshake/.test(message) || code.startsWith("ERR_SSL")) {
+    return {
+      kind: "tls",
+      layer: "tls",
+      code,
+      detail: "The TLS handshake failed before an HTTP response was received.",
+      guidance: "Check captive-portal login, proxy/VPN interception, system trust, or retry on another network.",
+      transient: true,
+    };
+  }
+  return {
+    kind: "network",
+    layer: "network",
+    code,
+    detail: "The transport failed before a complete HTTP response was received.",
+    guidance: "Run `myte doctor --json`, then check network, proxy/VPN, captive-portal, and API base settings.",
+    transient: true,
+  };
+}
+
+function createNetworkRequestError(error, url, { timedOut = false } = {}) {
+  if (error?.isMyteRequestError) return error;
+  const classified = classifyNetworkFailure(error, { timedOut });
+  const endpoint = safeEndpointHost(url);
+  const wrapped = new Error(
+    [
+      "Network request failed before receiving an HTTP response.",
+      `Endpoint: ${endpoint}`,
+      `Cause: ${classified.code}`,
+      `Detail: ${classified.detail}`,
+      classified.guidance,
+    ].join("\n"),
+  );
+  wrapped.name = "MyteNetworkError";
+  wrapped.code = classified.code;
+  wrapped.failureKind = classified.kind;
+  wrapped.failureLayer = classified.layer;
+  wrapped.endpoint = endpoint;
+  wrapped.detail = classified.detail;
+  wrapped.guidance = classified.guidance;
+  wrapped.transient = classified.transient;
+  wrapped.isMyteRequestError = true;
+  wrapped.cause = error;
+  return wrapped;
+}
+
+function createNonJsonResponseError(resp, url) {
+  const status = Number(resp?.status || 0);
+  const contentType = String(resp?.headers?.get?.("content-type") || "").toLowerCase();
+  const endpoint = safeEndpointHost(url);
+  const likelyPortal = status >= 200 && status < 400 && contentType.includes("text/html");
+  const detail = likelyPortal
+    ? "The endpoint returned HTML instead of JSON, which commonly indicates a captive portal or intercepting proxy."
+    : "The endpoint returned a non-JSON response, so the CLI could not validate the API contract.";
+  const error = new Error(
+    [
+      `Invalid HTTP response (${status || "unknown status"}).`,
+      `Endpoint: ${endpoint}`,
+      `Cause: ${likelyPortal ? "CAPTIVE_PORTAL_OR_PROXY" : "NON_JSON_RESPONSE"}`,
+      `Detail: ${detail}`,
+    ].join("\n"),
+  );
+  error.name = "MyteHttpError";
+  error.code = likelyPortal ? "CAPTIVE_PORTAL_OR_PROXY" : "NON_JSON_RESPONSE";
+  error.failureKind = likelyPortal ? "captive_portal" : "non_json_response";
+  error.failureLayer = "http";
+  error.endpoint = endpoint;
+  error.status = status;
+  error.transient = likelyPortal || [408, 429, 500, 502, 503, 504].includes(status);
+  error.isMyteRequestError = true;
+  const retryAfter = resp?.headers?.get?.("retry-after");
+  const requestId = resp?.headers?.get?.("x-request-id");
+  if (retryAfter) error.retryAfter = retryAfter;
+  if (requestId) error.requestId = String(requestId);
+  return error;
+}
+
+function publicRequestFailure(error) {
+  return {
+    layer: error?.failureLayer || (error?.status ? "http" : "unknown"),
+    kind: error?.failureKind || "unknown",
+    code: String(error?.code || error?.status || "UNKNOWN"),
+    status: Number(error?.status || 0) || null,
+    endpoint: error?.endpoint || null,
+    detail: error?.detail || String(error?.message || "Request failed.").split("\n")[0],
+    transient: Boolean(error?.transient),
+    request_id: error?.requestId || null,
+  };
+}
 
 function normalizeApiBase(baseRaw) {
   const baseTrim = String(baseRaw || "").trim().replace(/\/+$/, "");
@@ -670,24 +981,31 @@ function normalizeApiBase(baseRaw) {
   return base.endsWith("/api") ? base : `${base}/api`;
 }
 
-async function fetchJsonWithTimeout(fetchFn, url, options, timeoutMs) {
-  const controller = typeof AbortController !== "undefined" ? new AbortController() : undefined;
-  const timeoutId =
-    controller && timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
-  try {
-    const resp = await fetchFn(url, { ...options, signal: controller?.signal });
-    const text = await resp.text();
-    let body;
-    try {
-      body = JSON.parse(text);
-    } catch {
-      const err = new Error(`Non-JSON response (${resp.status}): ${text.slice(0, 500)}`);
-      err.status = resp.status;
-      const retryAfter = resp.headers?.get?.("retry-after");
-      if (retryAfter) err.retryAfter = retryAfter;
-      throw err;
-    }
-    return { resp, body };
+async function fetchJsonWithTimeout(fetchFn, url, options, timeoutMs) {
+  const controller = typeof AbortController !== "undefined" ? new AbortController() : undefined;
+  let timedOut = false;
+  const timeoutId =
+    controller && timeoutMs > 0
+      ? setTimeout(() => {
+          timedOut = true;
+          controller.abort();
+        }, timeoutMs)
+      : undefined;
+  try {
+    let resp;
+    try {
+      resp = await fetchFn(url, { ...options, signal: controller?.signal });
+    } catch (error) {
+      throw createNetworkRequestError(error, url, { timedOut });
+    }
+    const text = await resp.text();
+    let body;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      throw createNonJsonResponseError(resp, url);
+    }
+    return { resp, body };
   } finally {
     if (timeoutId) clearTimeout(timeoutId);
   }
@@ -1621,14 +1939,11 @@ async function fetchProjectConfig({ apiBase, key, timeoutMs }) {
       headers: { Authorization: `Bearer ${key}` },
     },
     timeoutMs
-  );
-
-  if (!resp.ok || body.status !== "success") {
-    const msg = body?.message || `Config request failed (${resp.status})`;
-    const err = new Error(msg);
-    err.status = resp.status;
-    throw err;
-  }
+  );
+
+  if (!resp.ok || body.status !== "success") {
+    throw createHttpResponseError(resp, body, url, "Project configuration could not be loaded.");
+  }
   return body.data || {};
 }
 
@@ -1682,7 +1997,7 @@ async function fetchQaqcSyncSnapshot({ apiBase, key, timeoutMs }) {
   return body.data || {};
 }
 
-async function fetchFeedbackSyncSnapshot({ apiBase, key, timeoutMs, filters = {} }) {
+async function fetchFeedbackSyncSnapshot({ apiBase, key, timeoutMs, filters = {} }) {
   const fetchFn = await getFetch();
   const url = new URL(`${apiBase}/project-assistant/feedback-sync`);
   if (filters.status) url.searchParams.set("status", String(filters.status));
@@ -1690,9 +2005,21 @@ async function fetchFeedbackSyncSnapshot({ apiBase, key, timeoutMs, filters = {}
   if (filters.includePrdText !== undefined) {
     url.searchParams.set("include_prd_text", filters.includePrdText ? "true" : "false");
   }
-  if (filters.includeCommentTurns !== undefined) {
-    url.searchParams.set("include_comment_turns", filters.includeCommentTurns ? "true" : "false");
-  }
+  if (filters.includeCommentTurns !== undefined) {
+    url.searchParams.set("include_comment_turns", filters.includeCommentTurns ? "true" : "false");
+  }
+  if (filters.limit !== undefined && filters.limit !== null && filters.limit !== "") {
+    url.searchParams.set("limit", String(filters.limit));
+  }
+  if (filters.offset !== undefined && filters.offset !== null && Number(filters.offset) > 0) {
+    url.searchParams.set("offset", String(filters.offset));
+  }
+  if (filters.paginationMode) {
+    url.searchParams.set("pagination_mode", String(filters.paginationMode));
+  }
+  if (filters.cursor) {
+    url.searchParams.set("cursor", String(filters.cursor));
+  }
   const { resp, body } = await fetchJsonWithTimeout(
     fetchFn,
     url.toString(),
@@ -1709,8 +2036,191 @@ async function fetchFeedbackSyncSnapshot({ apiBase, key, timeoutMs, filters = {}
     err.status = resp.status;
     throw err;
   }
-  return body.data || {};
-}
+  return body.data || {};
+}
+
+function resolveBoundedInteger(value, { fallback, min, max, label }) {
+  if (value === undefined || value === null || value === "") return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+    throw new Error(`${label} must be an integer between ${min} and ${max}.`);
+  }
+  return parsed;
+}
+
+function aggregateFeedbackSyncCounts(items, availableTotal) {
+  const byStatus = {};
+  const bySource = {};
+  let withPrdText = 0;
+  let withConversationTurns = 0;
+  for (const item of items) {
+    const status = String(item?.status || "Pending");
+    const source = String(item?.source || "User");
+    byStatus[status] = (byStatus[status] || 0) + 1;
+    bySource[source] = (bySource[source] || 0) + 1;
+    if (String(item?.prd_text || "").trim()) withPrdText += 1;
+    if (Array.isArray(item?.conversation_turns) && item.conversation_turns.length > 0) {
+      withConversationTurns += 1;
+    }
+  }
+  return {
+    total_feedback: items.length,
+    available_feedback: Number.isFinite(Number(availableTotal)) ? Number(availableTotal) : items.length,
+    with_prd_text: withPrdText,
+    with_conversation_turns: withConversationTurns,
+    by_status: byStatus,
+    by_source: bySource,
+  };
+}
+
+async function fetchCompleteFeedbackSyncSnapshot({
+  apiBase,
+  key,
+  timeoutMs,
+  filters = {},
+  pageSize = DEFAULT_FEEDBACK_SYNC_PAGE_SIZE,
+  maxItems = 0,
+  onPage,
+}) {
+  const items = [];
+  const pageHashes = [];
+  const stageTotals = {};
+  let firstSnapshot = null;
+  let offset = 0;
+  let availableTotal = null;
+  let pageCount = 0;
+  let sawPagination = false;
+  let cursor = null;
+  let useCursorPagination = true;
+  let serverHasMore = false;
+  const seenFeedbackIds = new Set();
+
+  while (true) {
+    const remaining = maxItems > 0 ? maxItems - items.length : pageSize;
+    if (maxItems > 0 && remaining <= 0) break;
+    const requestedLimit = Math.min(pageSize, maxItems > 0 ? remaining : pageSize);
+    const page = await fetchFeedbackSyncSnapshot({
+      apiBase,
+      key,
+      timeoutMs,
+      filters: {
+        ...filters,
+        limit: requestedLimit,
+        ...(useCursorPagination
+          ? {
+              paginationMode: "cursor",
+              ...(cursor ? { cursor } : {}),
+            }
+          : { offset }),
+      },
+    });
+    pageCount += 1;
+    if (!firstSnapshot) firstSnapshot = page;
+
+    const pageItems = Array.isArray(page.items) ? page.items : [];
+    const pagination = page.pagination && typeof page.pagination === "object" ? page.pagination : null;
+    sawPagination = sawPagination || Boolean(pagination);
+    if (
+      availableTotal === null &&
+      pagination &&
+      Number.isFinite(Number(pagination.total))
+    ) {
+      availableTotal = Number(pagination.total);
+    }
+    if (page.snapshot_hash) pageHashes.push(String(page.snapshot_hash));
+    const stages = page?.diagnostics?.stages_ms;
+    if (stages && typeof stages === "object") {
+      for (const [name, value] of Object.entries(stages)) {
+        const duration = Number(value);
+        if (Number.isFinite(duration)) stageTotals[name] = (stageTotals[name] || 0) + duration;
+      }
+    }
+
+    for (const item of pageItems) {
+      const feedbackId = firstNonEmptyString(item?.feedback_id, item?._id);
+      if (feedbackId && seenFeedbackIds.has(feedbackId)) {
+        throw new Error(
+          `Feedback sync snapshot changed while paging; duplicate feedback ${feedbackId} was returned. Retry the sync.`,
+        );
+      }
+      if (feedbackId) seenFeedbackIds.add(feedbackId);
+      items.push(item);
+    }
+    if (typeof onPage === "function") {
+      onPage({
+        page: pageCount,
+        received: pageItems.length,
+        synced: items.length,
+        total: availableTotal,
+      });
+    }
+
+    if (!pagination) break;
+    const responseUsesCursor = String(pagination.mode || "").toLowerCase() === "cursor";
+    if (!responseUsesCursor) useCursorPagination = false;
+    const hasMore = Boolean(pagination.has_more);
+    serverHasMore = hasMore;
+    if (!hasMore) break;
+    if (pageItems.length === 0) {
+      throw new Error(`Feedback sync page ${pageCount} reported more results but returned no items.`);
+    }
+    if (responseUsesCursor) {
+      const nextCursor = firstNonEmptyString(pagination.next_cursor);
+      if (!nextCursor || nextCursor === cursor) {
+        throw new Error(
+          `Feedback sync page ${pageCount} did not return a new cursor while more results remain.`,
+        );
+      }
+      cursor = nextCursor;
+      useCursorPagination = true;
+    } else {
+      useCursorPagination = false;
+      offset += pageItems.length;
+    }
+  }
+
+  const base = firstSnapshot || {};
+  if (!sawPagination && pageCount === 1) {
+    return {
+      ...base,
+      diagnostics: {
+        ...(base.diagnostics && typeof base.diagnostics === "object" ? base.diagnostics : {}),
+        page_count: 1,
+      },
+    };
+  }
+  const aggregateHash = createHash("sha256")
+    .update(JSON.stringify({
+      project_id: base?.project?.id || null,
+      item_hashes: items.map((item) => item?.snapshot_hash || item?.feedback_id || null),
+      page_hashes: pageHashes,
+    }))
+    .digest("hex");
+
+  return {
+    ...base,
+    items,
+    counts: aggregateFeedbackSyncCounts(items, availableTotal),
+    pagination: {
+      mode: useCursorPagination && sawPagination ? "cursor" : "offset",
+      total: availableTotal ?? items.length,
+      limit: pageSize,
+      offset: 0,
+      has_more:
+        maxItems > 0
+          ? serverHasMore || (availableTotal !== null && items.length < availableTotal)
+          : false,
+      page_count: pageCount,
+      synced_count: items.length,
+      next_cursor: maxItems > 0 && serverHasMore ? cursor : null,
+    },
+    snapshot_hash: aggregateHash,
+    diagnostics: {
+      page_count: pageCount,
+      stages_ms: stageTotals,
+    },
+  };
+}
 
 async function fetchFeedbackReview({ apiBase, key, timeoutMs, feedbackId }) {
   const fetchFn = await getFetch();
@@ -2055,10 +2565,19 @@ async function fetchFeedbackPrdVersions({ apiBase, key, timeoutMs, feedbackId })
   return body.data || {};
 }
 
-async function fetchFeedbackPrdVersionDiff({ apiBase, key, timeoutMs, feedbackId, versionId, compareTo }) {
+async function fetchFeedbackPrdVersionDiff({
+  apiBase,
+  key,
+  timeoutMs,
+  feedbackId,
+  versionId,
+  compareTo,
+  documentId,
+}) {
   const fetchFn = await getFetch();
-  const url = new URL(`${apiBase}/project-assistant/feedback/${encodeURIComponent(String(feedbackId || ""))}/prd/versions/${encodeURIComponent(String(versionId || ""))}/diff`);
-  if (compareTo) url.searchParams.set("compare_to", String(compareTo));
+  const url = new URL(`${apiBase}/project-assistant/feedback/${encodeURIComponent(String(feedbackId || ""))}/prd/versions/${encodeURIComponent(String(versionId || ""))}/diff`);
+  if (compareTo) url.searchParams.set("compare_to", String(compareTo));
+  if (documentId) url.searchParams.set("document_id", String(documentId));
   const { resp, body } = await fetchJsonWithTimeout(
     fetchFn,
     url.toString(),
@@ -2270,48 +2789,162 @@ async function fetchRunQaqcBatchStatus({ apiBase, key, timeoutMs, batchId }) {
   return body.data || {};
 }
 
-function resolveRetryAfterMs(err, fallbackMs = 5_000) {
-  const retryAfterRaw = firstNonEmptyString(err?.retryAfter);
-  const retryAfterSeconds = Number.parseInt(String(retryAfterRaw || ""), 10);
-  if (Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0) {
-    return Math.min(retryAfterSeconds * 1_000, 60_000);
-  }
-  return fallbackMs;
-}
-
-function isTransientQueryStatusError(err) {
-  return [408, 429, 500, 502, 503, 504].includes(Number(err?.status));
-}
-
-async function createAssistantQueryJob({ apiBase, key, payload, timeoutMs, endpoint = "/project-assistant/query" }) {
-  const fetchFn = await getFetch();
-  const url = `${apiBase}${endpoint}`;
-  const { resp, body } = await fetchJsonWithTimeout(
+function resolveRetryAfterMs(err, fallbackMs = 5_000) {
+  const retryAfterRaw = firstNonEmptyString(err?.retryAfter);
+  const retryAfterSeconds = Number.parseInt(String(retryAfterRaw || ""), 10);
+  if (Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0) {
+    return Math.min(retryAfterSeconds * 1_000, 60_000);
+  }
+  const retryAfterDate = Date.parse(String(retryAfterRaw || ""));
+  if (Number.isFinite(retryAfterDate)) {
+    return Math.min(Math.max(0, retryAfterDate - Date.now()), 60_000);
+  }
+  return fallbackMs;
+}
+
+function isTransientQueryStatusError(err) {
+  return Boolean(
+    err?.transient ||
+      ["dns", "tcp", "tls", "network"].includes(String(err?.failureLayer || "")) ||
+      [408, 429, 500, 502, 503, 504].includes(Number(err?.status)),
+  );
+}
+
+function createHttpResponseError(resp, body, url, fallbackMessage) {
+  const status = Number(resp?.status || 0);
+  const endpoint = safeEndpointHost(url);
+  let kind = "http";
+  let detail = fallbackMessage || `HTTP request failed (${status || "unknown status"}).`;
+  let transient = false;
+  if (status === 401) {
+    kind = "authentication";
+    detail = "The API rejected the project key.";
+  } else if (status === 403) {
+    kind = "authorization";
+    detail = "The authenticated project identity is not allowed to perform this action.";
+  } else if (status === 429) {
+    kind = "rate_limit";
+    detail = "The API rate limit is temporarily exhausted.";
+    transient = true;
+  } else if ([408, 500, 502, 503, 504].includes(status)) {
+    kind = "server";
+    detail = "The API or an upstream gateway returned a transient error.";
+    transient = true;
+  }
+  const requestId =
+    resp?.headers?.get?.("x-request-id") ||
+    (body && typeof body === "object" ? body.request_id || body?.data?.request_id : null);
+  const error = new Error(
+    [
+      `HTTP request failed (${status || "unknown status"}).`,
+      `Endpoint: ${endpoint}`,
+      `Cause: ${kind.toUpperCase()}`,
+      `Detail: ${detail}`,
+      requestId ? `Request ID: ${requestId}` : "",
+    ]
+      .filter(Boolean)
+      .join("\n"),
+  );
+  error.name = "MyteHttpError";
+  error.code = `HTTP_${status || "ERROR"}`;
+  error.status = status;
+  error.failureKind = kind;
+  error.failureLayer = "http";
+  error.endpoint = endpoint;
+  error.detail = detail;
+  error.transient = transient;
+  error.isMyteRequestError = true;
+  if (requestId) error.requestId = String(requestId);
+  const retryAfter = resp?.headers?.get?.("retry-after");
+  if (retryAfter) error.retryAfter = retryAfter;
+  return error;
+}
+
+function queryRequestId(args) {
+  const explicit = firstNonEmptyString(
+    args["request-id"],
+    args.requestId,
+    args.request_id,
+    args["idempotency-key"],
+    args.idempotencyKey,
+    args.idempotency_key,
+  );
+  const value = explicit || `myte-query-${randomUUID()}`;
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value)) {
+    throw new Error("request-id must contain 1-128 safe letters, numbers, dots, underscores, colons, or hyphens.");
+  }
+  return value;
+}
+
+function transientRetryDelayMs(error, attempt, initialDelayMs = 750) {
+  const exponential = Math.min(15_000, initialDelayMs * 2 ** Math.max(0, attempt - 1));
+  const fallback = resolveRetryAfterMs(error, exponential);
+  const jitterLimit = Math.max(0, Number(process.env.MYTE_RETRY_JITTER_MS ?? 250) || 0);
+  const jitter = jitterLimit ? Math.floor(Math.random() * (jitterLimit + 1)) : 0;
+  return Math.min(60_000, fallback + jitter);
+}
+
+async function withTransientQueryRetries(
+  operation,
+  {
+    maxAttempts = 3,
+    verbose = false,
+    label = "request",
+    initialDelayMs = 750,
+  } = {},
+) {
+  let lastError;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      return await operation(attempt);
+    } catch (error) {
+      lastError = error;
+      if (!isTransientQueryStatusError(error) || attempt >= maxAttempts) throw error;
+      const waitMs = transientRetryDelayMs(error, attempt, initialDelayMs);
+      if (verbose) {
+        console.error(
+          `[myte] ${label} transient failure (${error?.code || error?.status || "unknown"}); retry ${attempt + 1}/${maxAttempts} in ${waitMs}ms.`,
+        );
+      }
+      await sleep(waitMs);
+    }
+  }
+  throw lastError;
+}
+
+async function createAssistantQueryJob({
+  apiBase,
+  key,
+  payload,
+  timeoutMs,
+  requestId,
+  endpoint = "/project-assistant/query",
+}) {
+  const fetchFn = await getFetch();
+  const url = `${apiBase}${endpoint}`;
+  const { resp, body } = await fetchJsonWithTimeout(
     fetchFn,
     url,
     {
       method: "POST",
       headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${key}`,
-      },
-      body: JSON.stringify(payload),
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${key}`,
+        "X-Idempotency-Key": requestId,
+        "X-Request-ID": requestId,
+      },
+      body: JSON.stringify({ ...payload, client_request_id: requestId }),
     },
     timeoutMs
   );
 
-  if (!resp.ok || body.status !== "success") {
-    const retryAfter = resp.headers?.get?.("retry-after");
-    const msg = body?.message || `Query failed (${resp.status})`;
-    const err = new Error(retryAfter ? `${msg} Retry after ${retryAfter}s.` : msg);
-    err.status = resp.status;
-    if (retryAfter) err.retryAfter = retryAfter;
-    throw err;
-  }
-  return body.data || {};
-}
-
-async function fetchAssistantQueryJobStatus({ apiBase, key, timeoutMs, jobId }) {
+  if (!resp.ok || body.status !== "success") {
+    throw createHttpResponseError(resp, body, url, "The query job could not be created.");
+  }
+  return body.data || {};
+}
+
+async function fetchAssistantQueryJobStatus({ apiBase, key, timeoutMs, jobId, requestId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}/project-assistant/query/${encodeURIComponent(String(jobId || ""))}`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2319,19 +2952,17 @@ async function fetchAssistantQueryJobStatus({ apiBase, key, timeoutMs, jobId })
     url,
     {
       method: "GET",
-      headers: { Authorization: `Bearer ${key}` },
+      headers: {
+        Authorization: `Bearer ${key}`,
+        ...(requestId ? { "X-Request-ID": requestId } : {}),
+      },
     },
     timeoutMs
   );
 
-  if (!resp.ok || body.status !== "success") {
-    const retryAfter = resp.headers?.get?.("retry-after");
-    const msg = body?.message || `Query status request failed (${resp.status})`;
-    const err = new Error(retryAfter ? `${msg} Retry after ${retryAfter}s.` : msg);
-    err.status = resp.status;
-    if (retryAfter) err.retryAfter = retryAfter;
-    throw err;
-  }
+  if (!resp.ok || body.status !== "success") {
+    throw createHttpResponseError(resp, body, url, "The query status could not be loaded.");
+  }
   return body.data || {};
 }
 
@@ -2355,11 +2986,6 @@ async function runRunQaqc(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: "yaml",
-    targets: missionIds,
-    batchCount: missionIds.length > 1 ? missionIds.length : null,
-  });
   const idempotencyKey = resolveProjectMutationIdempotencyKey({
     args,
     operation: "run-qaqc",
@@ -2515,11 +3141,6 @@ async function runMissionStatus(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: "yaml",
-    targets: missionIds,
-    batchCount: missionIds.length > 1 ? missionIds.length : null,
-  });
   const idempotencyKey = resolveProjectMutationIdempotencyKey({
     args,
     operation: "mission-status-update",
@@ -2624,15 +3245,9 @@ async function runMissionArchiveCommand(args) {
   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;
-  payload = withWriteApproval(args, payload, {
-    artifactKind: "yaml",
-    targets: missionIds,
-    batchCount: missionIds.length > 1 ? missionIds.length : null,
-  });
-
-  const operation = "mission-archive";
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
-    args,
+  const operation = "mission-archive";
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
     operation,
     payload,
   });
@@ -3099,7 +3714,7 @@ function resolveWriteApprovalArtifact(args) {
   }
   const ext = path.extname(absPath).toLowerCase();
   if (![".md", ".markdown", ".yml", ".yaml", ".json"].includes(ext)) {
-    console.error("Approval artifact must be a local .md, .yml, .yaml, or .json file.");
+    console.error("Approval artifact must be a local .md, .markdown, .yml, .yaml, or .json file.");
     process.exit(1);
   }
   return { displayPath: String(artifactPath), absPath };
@@ -3109,8 +3724,20 @@ function approvalTargets(values) {
   return uniqueNormalizedStrings(Array.isArray(values) ? values : [values]);
 }
 
-function withWriteApproval(args, payload, { artifactKind = "yaml", targets = [], batchCount = null } = {}) {
+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 || {}) };
@@ -3268,12 +3895,50 @@ function writeJsonFile(filePath, value) {
   fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 }
 
-function writeTextFile(filePath, value) {
-  ensureDir(path.dirname(filePath));
-  fs.writeFileSync(filePath, String(value || ""), "utf8");
-}
-
-function sanitizeFileSegment(value, fallback = "item") {
+function writeTextFile(filePath, value) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, String(value || ""), "utf8");
+}
+
+function replacePathsTransaction(entries, token) {
+  const prepared = [];
+  try {
+    for (const entry of entries) {
+      if (!entry?.staged || !entry?.target || !fs.existsSync(entry.staged)) {
+        throw new Error(`Missing staged sync artifact for ${entry?.target || "unknown target"}.`);
+      }
+      ensureDir(path.dirname(entry.target));
+      const backup = `${entry.target}.myte-backup-${token}`;
+      if (fs.existsSync(backup)) removePathIfExists(backup);
+      if (fs.existsSync(entry.target)) fs.renameSync(entry.target, backup);
+      prepared.push({ ...entry, backup, installed: false });
+    }
+
+    for (const entry of prepared) {
+      fs.renameSync(entry.staged, entry.target);
+      entry.installed = true;
+    }
+  } catch (error) {
+    for (const entry of [...prepared].reverse()) {
+      if (entry.installed && fs.existsSync(entry.target)) removePathIfExists(entry.target);
+      if (fs.existsSync(entry.backup)) fs.renameSync(entry.backup, entry.target);
+    }
+    throw error;
+  }
+
+  for (const entry of prepared) {
+    if (!fs.existsSync(entry.backup)) continue;
+    try {
+      removePathIfExists(entry.backup);
+    } catch (error) {
+      console.warn(
+        `[myte] Sync committed, but an old backup could not be removed: ${path.basename(entry.backup)}`,
+      );
+    }
+  }
+}
+
+function sanitizeFileSegment(value, fallback = "item") {
   const cleaned = String(value || "")
     .trim()
     .replace(/[<>:"/\\|?*\x00-\x1F]/g, "-")
@@ -3416,19 +4081,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,
@@ -3506,11 +4275,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,
@@ -3523,12 +4293,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);
@@ -3562,37 +4333,87 @@ function writeQaqcSnapshot({ snapshot, wrapperRoot, outputDir }) {
   };
 }
 
-function writeFeedbackSnapshot({ snapshot, wrapperRoot, outputDir }) {
-  const { targetRoot, dataRoot } = resolveCommandCenterRoots(wrapperRoot, outputDir);
-  const prdSyncDir = path.join(targetRoot, "PRD", "feedback-sync");
-
-  ensureDir(dataRoot);
-  ensureDir(prdSyncDir);
-  clearFileDirectory(prdSyncDir, [".md", ".markdown", ".txt"]);
-  pruneLegacyCommandCenterArtifacts(dataRoot, { bootstrap: true, feedback: true });
-
-  if (snapshot.project && typeof snapshot.project === "object") {
-    writeYamlFile(path.join(dataRoot, "project.yml"), scrubBootstrapValue(snapshot.project));
-  }
-
-  const items = Array.isArray(snapshot.items) ? snapshot.items : [];
-  let prdFileCount = 0;
-  const materializedItems = items.map((rawItem, index) => {
-    const item = isPlainObject(rawItem) ? { ...rawItem } : {};
-    const feedbackId = stableItemId(item, ["feedback_id", "id"], `F${String(index + 1).padStart(3, "0")}`);
-    const conversationTurns = normalizeFeedbackConversationTurns(item.conversation_turns);
-    const prdText = String(item.prd_text || "").trim();
-    const attachmentDocuments = Array.isArray(item.attachment_documents) ? item.attachment_documents : [];
-
-    let contextSource = "description_only";
-    let contextNote = "No separate PRD. Use feedback_text as the context for this feedback item.";
-    let prdFile = null;
-
-    if (prdText) {
-      const prdFilename = `${sanitizeFileSegment(feedbackId, `feedback-${index + 1}`)}.md`;
-      const prdPath = path.join(prdSyncDir, prdFilename);
-      writeTextFile(prdPath, ensureTrailingNewline(prdText));
-      prdFile = toPosixRelativePath(targetRoot, prdPath);
+function writeFeedbackSnapshot({ snapshot, wrapperRoot, outputDir }) {
+  const { targetRoot, dataRoot } = resolveCommandCenterRoots(wrapperRoot, outputDir);
+  const prdSyncDir = path.join(targetRoot, "PRD", "feedback-sync");
+  const transactionToken = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  const stagingRoot = path.join(targetRoot, `.myte-feedback-sync-${transactionToken}`);
+  const stagedDataRoot = path.join(stagingRoot, "data");
+  const stagedPrdRoot = path.join(stagingRoot, "PRD", "feedback-sync");
+  ensureDir(stagedDataRoot);
+  ensureDir(stagedPrdRoot);
+
+  const items = Array.isArray(snapshot.items) ? snapshot.items : [];
+  let prdFileCount = 0;
+  let prdDocumentSetCount = 0;
+  const materializedItems = items.map((rawItem, index) => {
+    const item = isPlainObject(rawItem) ? { ...rawItem } : {};
+    const feedbackId = stableItemId(item, ["feedback_id", "id"], `F${String(index + 1).padStart(3, "0")}`);
+    const conversationTurns = normalizeFeedbackConversationTurns(item.conversation_turns);
+    const prdText = String(item.prd_text || "").trim();
+    const rawPrdDocuments = Array.isArray(item.prd_documents) ? item.prd_documents : [];
+    const attachmentDocuments = Array.isArray(item.attachment_documents) ? item.attachment_documents : [];
+
+    let contextSource = "description_only";
+    let contextNote = "No separate PRD. Use feedback_text as the context for this feedback item.";
+    let prdFile = null;
+    let materializedPrdDocuments = rawPrdDocuments.map((document) =>
+      isPlainObject(document) ? { ...document } : {}
+    );
+
+    if (rawPrdDocuments.length > 0) {
+      prdDocumentSetCount += 1;
+      const feedbackFolderName = sanitizeFileSegment(feedbackId, `feedback-${index + 1}`);
+      materializedPrdDocuments = rawPrdDocuments.map((rawDocument, documentIndex) => {
+        const document = isPlainObject(rawDocument) ? { ...rawDocument } : {};
+        const markdown = String(
+          document.canonical_markdown || document.source_markdown || ""
+        );
+        let localFile = null;
+        if (markdown.trim()) {
+          const rawFilename = sanitizeFileSegment(
+            document.filename || document.title,
+            `document-${documentIndex + 1}.md`
+          );
+          const filename = /\.(md|markdown)$/i.test(rawFilename)
+            ? rawFilename
+            : `${rawFilename}.md`;
+          const position = Number.isInteger(Number(document.position))
+            ? Number(document.position) + 1
+            : documentIndex + 1;
+          const orderedFilename = `${String(position).padStart(2, "0")}-${filename}`;
+          const stagedPath = path.join(stagedPrdRoot, feedbackFolderName, orderedFilename);
+          ensureDir(path.dirname(stagedPath));
+          writeTextFile(stagedPath, ensureTrailingNewline(markdown));
+          localFile = toPosixRelativePath(
+            targetRoot,
+            path.join(prdSyncDir, feedbackFolderName, orderedFilename)
+          );
+          prdFileCount += 1;
+        }
+        return {
+          ...document,
+          local_file: localFile,
+        };
+      });
+      const primaryDocumentId = String(item.primary_prd_document_id || "");
+      const primaryDocument =
+        materializedPrdDocuments.find(
+          (document) => String(document.document_id || "") === primaryDocumentId
+        ) || materializedPrdDocuments[0];
+      prdFile = primaryDocument?.local_file || null;
+      if (prdFile) {
+        contextSource = "prd_document_set";
+        contextNote = "Readable PRD documents are stored in the linked document files.";
+      } else {
+        contextSource = "prd_declared_but_unavailable";
+        contextNote = "A PRD document set exists, but readable document text was not included in this sync snapshot.";
+      }
+    } else if (prdText) {
+      const prdFilename = `${sanitizeFileSegment(feedbackId, `feedback-${index + 1}`)}.md`;
+      const prdPath = path.join(stagedPrdRoot, prdFilename);
+      writeTextFile(prdPath, ensureTrailingNewline(prdText));
+      prdFile = toPosixRelativePath(targetRoot, path.join(prdSyncDir, prdFilename));
       contextSource = attachmentDocuments.length > 0 ? "attachment_file" : "prd_file";
       contextNote = attachmentDocuments.length > 0
         ? "Readable feedback attachment documents are stored in the linked file."
@@ -3604,31 +4425,34 @@ function writeFeedbackSnapshot({ snapshot, wrapperRoot, outputDir }) {
     }
 
     return {
-      ...item,
-      feedback_id: feedbackId,
-      conversation_turns: conversationTurns,
-      context_source: contextSource,
-      context_note: contextNote,
-      prd_file: prdFile,
+      ...item,
+      feedback_id: feedbackId,
+      conversation_turns: conversationTurns,
+      prd_documents: materializedPrdDocuments,
+      context_source: contextSource,
+      context_note: contextNote,
+      prd_file: prdFile,
     };
   });
   const snapshotCounts = snapshot.counts && typeof snapshot.counts === "object"
     ? { ...snapshot.counts }
     : { total_feedback: materializedItems.length };
-  snapshotCounts.with_prd_files = prdFileCount;
+  snapshotCounts.with_prd_files = prdFileCount;
+  snapshotCounts.with_prd_document_sets = prdDocumentSetCount;
   if (snapshotCounts.with_conversation_turns === undefined) {
     snapshotCounts.with_conversation_turns = materializedItems.filter((item) => Array.isArray(item?.conversation_turns) && item.conversation_turns.length > 0).length;
   }
 
-  const payload = scrubBootstrapValue({
+  const payload = scrubBootstrapValue({
     schema_version: snapshot.schema_version || 2,
     project: snapshot.project || null,
     repo_names: Array.isArray(snapshot.repo_names) ? snapshot.repo_names : [],
     filters: snapshot.filters && typeof snapshot.filters === "object" ? snapshot.filters : {},
     counts: snapshotCounts,
-    artifacts: {
-      feedback_prd_root: "PRD/feedback-sync",
-      with_prd_files: prdFileCount,
+    artifacts: {
+      feedback_prd_root: "PRD/feedback-sync",
+      with_prd_files: prdFileCount,
+      with_prd_document_sets: prdDocumentSetCount,
     },
     queue: materializedItems
       .filter((item) => String(item?.status || "").trim().toLowerCase() !== "resolved")
@@ -3638,24 +4462,55 @@ function writeFeedbackSnapshot({ snapshot, wrapperRoot, outputDir }) {
         priority: item?.priority || null,
         title: item?.title || null,
       })),
-    items: materializedItems.map((item) => {
-      const nextItem = { ...item };
-      delete nextItem.prd_text;
-      return nextItem;
-    }),
+    items: materializedItems.map((item) => {
+      const nextItem = { ...item };
+      delete nextItem.prd_text;
+      nextItem.prd_documents = (nextItem.prd_documents || []).map((rawDocument) => {
+        const document = isPlainObject(rawDocument) ? { ...rawDocument } : {};
+        delete document.source_markdown;
+        delete document.canonical_markdown;
+        return document;
+      });
+      return nextItem;
+    }),
     pagination: snapshot.pagination && typeof snapshot.pagination === "object" ? snapshot.pagination : undefined,
     generated_at: snapshot.generated_at || null,
-    snapshot_hash: snapshot.snapshot_hash || null,
-  });
-  writeYamlFile(path.join(dataRoot, "feedback.yml"), payload);
-
-  return {
-    targetRoot,
-    dataRoot,
-    prdSyncDir,
-    manifest: payload,
-  };
-}
+    snapshot_hash: snapshot.snapshot_hash || null,
+  });
+  try {
+    const replacements = [];
+    if (snapshot.project && typeof snapshot.project === "object") {
+      const stagedProjectPath = path.join(stagedDataRoot, "project.yml");
+      writeYamlFile(stagedProjectPath, scrubBootstrapValue(snapshot.project));
+      replacements.push({
+        staged: stagedProjectPath,
+        target: path.join(dataRoot, "project.yml"),
+      });
+    }
+    const stagedFeedbackPath = path.join(stagedDataRoot, "feedback.yml");
+    writeYamlFile(stagedFeedbackPath, payload);
+    replacements.push(
+      {
+        staged: stagedPrdRoot,
+        target: prdSyncDir,
+      },
+      {
+        staged: stagedFeedbackPath,
+        target: path.join(dataRoot, "feedback.yml"),
+      }
+    );
+    replacePathsTransaction(replacements, transactionToken);
+    pruneLegacyCommandCenterArtifacts(dataRoot, { bootstrap: true, feedback: true });
+    return {
+      targetRoot,
+      dataRoot,
+      prdSyncDir,
+      manifest: payload,
+    };
+  } finally {
+    if (fs.existsSync(stagingRoot)) removePathIfExists(stagingRoot);
+  }
+}
 
 function resolveFeedbackReviewPaths(args, { requireFeedback = false } = {}) {
   const outputDir = args["output-dir"] || args.outputDir || args.output_dir;
@@ -3731,9 +4586,14 @@ function feedbackChange(from, to) {
   return { from: from === undefined ? null : from, to: to === undefined ? null : to };
 }
 
-function buildFeedbackRefinementArtifact({ manifest, item, feedbackId, action, changes, reason, args }) {
-  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
-  const artifact = {
+function buildFeedbackRefinementArtifact({ manifest, item, feedbackId, action, changes, reason, args }) {
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  const documentId = firstNonEmptyString(
+    args["document-id"],
+    args.documentId,
+    args.document_id
+  );
+  const artifact = {
     schema_version: 1,
     kind: "feedback_refinement",
     project_id: firstNonEmptyString(manifest?.project?.id, item?.project_id),
@@ -3741,9 +4601,10 @@ function buildFeedbackRefinementArtifact({ manifest, item, feedbackId, action, c
     title_snapshot: firstNonEmptyString(item?.title),
     base_snapshot_hash: firstNonEmptyString(item?.snapshot_hash),
     base_updated_at: firstNonEmptyString(item?.updated_at),
-    review_action: action,
-    reason: reason || null,
-    changes,
+    review_action: action,
+    reason: reason || null,
+    document_id: documentId || undefined,
+    changes,
     force: Boolean(args.force) || undefined,
     client_session_id: clientSessionId || undefined,
     created_at: new Date().toISOString(),
@@ -4447,7 +5308,7 @@ async function reviewProjectSuggestions({ apiBase, key, timeoutMs, payload, idem
   });
 }
 
-async function runCreatePrd(args) {
+async function runCreatePrd(args) {
   const key = (process.env.MYTE_API_KEY || process.env.MYTE_PROJECT_API_KEY || "").trim();
   if (!key) {
     console.error("Missing MYTE_API_KEY (project key) in environment/.env");
@@ -4469,13 +5330,24 @@ async function runCreatePrd(args) {
     .flatMap((value) => toStringArray(value))
     .map((item) => item.trim())
     .filter(Boolean);
-  const providedPaths = explicitPaths.length ? explicitPaths.concat(positionalPaths) : positionalPaths;
-  const useStdin = Boolean(args.stdin || (!process.stdin.isTTY && providedPaths.length === 0));
-
-  if (useStdin && providedPaths.length) {
-    console.error("Use either file paths or --stdin for create-prd, not both.");
-    process.exit(1);
-  }
+  const providedPaths = explicitPaths.length ? explicitPaths.concat(positionalPaths) : positionalPaths;
+  const useStdin = Boolean(args.stdin || (!process.stdin.isTTY && providedPaths.length === 0));
+  const documentSetMode = Boolean(
+    args["document-set"] || args.documentSet || args.document_set
+  );
+
+  if (useStdin && providedPaths.length) {
+    console.error("Use either file paths or --stdin for create-prd, not both.");
+    process.exit(1);
+  }
+  if (documentSetMode && useStdin) {
+    console.error("--document-set requires one to three markdown file paths; --stdin is not supported.");
+    process.exit(1);
+  }
+  if (documentSetMode && (providedPaths.length < 1 || providedPaths.length > 3)) {
+    console.error("--document-set requires between one and three markdown file paths.");
+    process.exit(1);
+  }
 
   const buildCreatePrdPayload = ({ sourceText, filePath, includeClientRef = false }) => {
     const trimmedSource = String(sourceText || "").trim();
@@ -4507,8 +5379,8 @@ async function runCreatePrd(args) {
     return payload;
   };
 
-  let payloads = [];
-  if (useStdin) {
+  let payloads = [];
+  if (useStdin) {
     try {
       payloads = [
         buildCreatePrdPayload({
@@ -4527,21 +5399,72 @@ async function runCreatePrd(args) {
       printHelp();
       process.exit(1);
     }
-    try {
-      payloads = providedPaths.map((providedPath) => {
-        const absPath = path.resolve(providedPath);
-        if (!fs.existsSync(absPath) || !fs.statSync(absPath).isFile()) {
-          throw new Error(`PRD file not found: ${absPath}`);
-        }
-        return buildCreatePrdPayload({
-          sourceText: fs.readFileSync(absPath, "utf8"),
-          filePath: absPath,
-          includeClientRef: providedPaths.length > 1,
-        });
-      });
-    } catch (err) {
-      console.error(err?.message || err);
-      process.exit(1);
+    try {
+      const resolvedFiles = providedPaths.map((providedPath) => {
+        const absPath = path.resolve(providedPath);
+        if (!fs.existsSync(absPath) || !fs.statSync(absPath).isFile()) {
+          throw new Error(`PRD file not found: ${absPath}`);
+        }
+        return {
+          absPath,
+          sourceText: fs.readFileSync(absPath, "utf8"),
+        };
+      });
+      if (documentSetMode) {
+        const documents = resolvedFiles.map(({ absPath, sourceText }, index) => {
+          const extension = path.extname(absPath).toLowerCase();
+          if (![".md", ".markdown"].includes(extension)) {
+            throw new Error(`PRD document-set files must use .md or .markdown: ${absPath}`);
+          }
+          if (!String(sourceText || "").trim()) {
+            throw new Error(`PRD content is empty: ${absPath}`);
+          }
+          if (Array.from(sourceText).length > MAX_PRD_DOCUMENT_MARKDOWN_CHARS) {
+            throw new Error(
+              `PRD document-set files must contain at most ${MAX_PRD_DOCUMENT_MARKDOWN_CHARS} characters: ${absPath}`,
+            );
+          }
+          const clientRef = path.relative(process.cwd(), absPath) || path.basename(absPath);
+          return {
+            client_ref: clientRef,
+            filename: path.basename(absPath),
+            title: String(
+              extractMarkdownTitle(sourceText) || path.parse(absPath).name || `Document ${index + 1}`
+            ).trim(),
+            source_markdown: sourceText,
+          };
+        });
+        const parentTitle = String(args.title || documents[0]?.title || "").trim();
+        if (!parentTitle) {
+          throw new Error("A title is required for a PRD document set.");
+        }
+        const documentSetPayload = {
+          title: parentTitle,
+          documents,
+        };
+        const description = String(
+          args.description || args["feedback-text"] || args.feedbackText || ""
+        ).trim();
+        if (description) documentSetPayload.description = description;
+        const priority = firstNonEmptyString(args.priority);
+        const status = firstNonEmptyString(args.status);
+        const tags = parseFeedbackTags(args);
+        if (priority) documentSetPayload.priority = priority;
+        if (status) documentSetPayload.status = status;
+        if (tags) documentSetPayload.tags = tags;
+        payloads = [documentSetPayload];
+      } else {
+        payloads = resolvedFiles.map(({ absPath, sourceText }) =>
+          buildCreatePrdPayload({
+            sourceText,
+            filePath: absPath,
+            includeClientRef: providedPaths.length > 1,
+          })
+        );
+      }
+    } catch (err) {
+      console.error(err?.message || err);
+      process.exit(1);
     }
   }
 
@@ -4558,7 +5481,10 @@ async function runCreatePrd(args) {
     if (clientSessionId) payload.client_session_id = clientSessionId;
     payload = withWriteApproval(args, payload, {
       artifactKind: "markdown",
-      targets: [firstNonEmptyString(payload.client_ref, payload.title, "create-prd")],
+      targets: documentSetMode
+        ? payload.documents.map((document) => document.client_ref)
+        : [firstNonEmptyString(payload.client_ref, payload.title, "create-prd")],
+      batchCount: documentSetMode ? 1 : null,
     });
     const idempotencyKey = resolveProjectMutationIdempotencyKey({
       args,
@@ -4591,9 +5517,12 @@ async function runCreatePrd(args) {
             feedback_id: data.feedback_id || null,
             project_id: data.project_id || null,
             title: data.title || null,
-            status: data.status || null,
-            deterministic: data.deterministic === true,
-          },
+            status: data.status || null,
+            deterministic: data.deterministic === true,
+            document_count: data.document_count || null,
+            primary_document_id: data.primary_document_id || null,
+            documents: Array.isArray(data.documents) ? data.documents : [],
+          },
           null,
           2
         )
@@ -4671,10 +5600,386 @@ async function runCreatePrd(args) {
     if (message && status !== "created") line.push(`- ${message}`);
     console.log(line.join(" "));
   }
-  if (aggregated.failed_count > 0) process.exitCode = 1;
-}
-
-async function runConfig(args) {
+  if (aggregated.failed_count > 0) process.exitCode = 1;
+}
+
+function readJsonFileQuiet(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function packageRuntimeInfo() {
+  const corePackage = readJsonFileQuiet(path.join(__dirname, "package.json")) || {};
+  let wrapperPackage = null;
+  const localWrapperPath = path.resolve(__dirname, "..", "myte", "package.json");
+  if (fs.existsSync(localWrapperPath)) {
+    wrapperPackage = readJsonFileQuiet(localWrapperPath);
+  }
+  if (!wrapperPackage) {
+    try {
+      wrapperPackage = require("myte/package.json");
+    } catch {
+      wrapperPackage = null;
+    }
+  }
+  const expectedCoreVersion =
+    wrapperPackage?.dependencies?.["@mytegroupinc/myte-core"] || null;
+  const runtimeDependencies = Object.entries(corePackage.dependencies || {})
+    .map(([name, version]) => ({
+      name,
+      version: String(version),
+    }))
+    .sort((left, right) => left.name.localeCompare(right.name));
+  return {
+    wrapper: {
+      name: wrapperPackage?.name || "myte",
+      version: wrapperPackage?.version || null,
+    },
+    core: {
+      name: corePackage?.name || "@mytegroupinc/myte-core",
+      version: corePackage?.version || null,
+    },
+    compatible:
+      !wrapperPackage ||
+      !expectedCoreVersion ||
+      expectedCoreVersion === corePackage?.version,
+    expected_core_version: expectedCoreVersion,
+    runtime_dependencies: runtimeDependencies,
+    install_graph: {
+      package_count: (wrapperPackage ? 2 : 1) + runtimeDependencies.length,
+      explanation: wrapperPackage
+        ? "public wrapper + CLI core + core runtime dependencies"
+        : "CLI core + core runtime dependencies",
+    },
+  };
+}
+
+function projectKeySummary(key = getProjectApiKey()) {
+  const normalized = String(key || "").trim();
+  return {
+    present: Boolean(normalized),
+    source: process.env.MYTE_API_KEY
+      ? "MYTE_API_KEY"
+      : process.env.MYTE_PROJECT_API_KEY
+        ? "MYTE_PROJECT_API_KEY"
+        : null,
+    fingerprint: normalized
+      ? createHash("sha256").update(normalized).digest("hex").slice(0, 12)
+      : null,
+  };
+}
+
+function probeDns(
+  hostname,
+  timeoutMs,
+  {
+    lookup = dns.promises.lookup.bind(dns.promises),
+    setTimeoutFn = setTimeout,
+    clearTimeoutFn = clearTimeout,
+  } = {},
+) {
+  if (net.isIP(hostname)) {
+    return Promise.resolve({
+      ok: true,
+      hostname,
+      addresses: [{ address: hostname, family: net.isIP(hostname) }],
+    });
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer;
+    const finish = (payload) => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeoutFn(timer);
+      resolve(payload);
+    };
+    timer = setTimeoutFn(() => {
+      const error = new Error("DNS probe timed out.");
+      error.code = "ETIMEDOUT";
+      finish({
+        ok: false,
+        hostname,
+        failure: publicRequestFailure(
+          createNetworkRequestError(error, `https://${hostname}`, { timedOut: true }),
+        ),
+      });
+    }, timeoutMs);
+    Promise.resolve()
+      .then(() => lookup(hostname, { all: true }))
+      .then(
+        (addresses) => {
+          finish({
+            ok: true,
+            hostname,
+            addresses: addresses.map((entry) => ({
+              address: entry.address,
+              family: entry.family,
+            })),
+          });
+        },
+        (error) => {
+          finish({
+            ok: false,
+            hostname,
+            failure: publicRequestFailure(
+              createNetworkRequestError(error, `https://${hostname}`),
+            ),
+          });
+        },
+      );
+  });
+}
+
+function probeDirectTransport(apiBase, timeoutMs) {
+  const parsed = new URL(apiBase);
+  const secure = parsed.protocol === "https:";
+  const port = Number(parsed.port || (secure ? 443 : 80));
+  const startedAt = Date.now();
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (payload) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        socket.destroy();
+      } catch {}
+      resolve({
+        ...payload,
+        protocol: secure ? "tls" : "tcp",
+        host: parsed.hostname,
+        port,
+        duration_ms: Date.now() - startedAt,
+      });
+    };
+    const options = {
+      host: parsed.hostname,
+      port,
+      ...(secure && !net.isIP(parsed.hostname) ? { servername: parsed.hostname } : {}),
+    };
+    const socket = secure ? tls.connect(options) : net.connect(options);
+    const timer = setTimeout(() => {
+      const error = new Error("Transport probe timed out.");
+      error.code = "ETIMEDOUT";
+      finish({
+        ok: false,
+        failure: publicRequestFailure(
+          createNetworkRequestError(error, apiBase, { timedOut: true }),
+        ),
+      });
+    }, timeoutMs);
+    socket.once(secure ? "secureConnect" : "connect", () => {
+      finish({
+        ok: true,
+        authorized: secure ? socket.authorized === true : null,
+        tls_protocol: secure ? socket.getProtocol?.() || null : null,
+      });
+    });
+    socket.once("error", (error) => {
+      finish({
+        ok: false,
+        failure: publicRequestFailure(createNetworkRequestError(error, apiBase)),
+      });
+    });
+  });
+}
+
+async function runInfo(args, envPath) {
+  const packages = packageRuntimeInfo();
+  const payload = {
+    command: "myte",
+    packages,
+    node_version: process.version,
+    platform: `${process.platform}-${process.arch}`,
+    api_base: resolveApiBase(args),
+    project_key: projectKeySummary(),
+    proxy: proxyEnvironmentSummary(),
+    workspace: {
+      cwd: process.cwd(),
+      env_file: envPath,
+    },
+  };
+  if (args.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(`myte ${packages.wrapper.version || packages.core.version || "unknown"}`);
+  console.log(`core: ${packages.core.version || "unknown"}`);
+  console.log(`wrapper/core compatible: ${packages.compatible ? "yes" : "no"}`);
+  console.log(
+    `runtime dependencies: ${
+      packages.runtime_dependencies.length
+        ? packages.runtime_dependencies
+            .map((dependency) => `${dependency.name}@${dependency.version}`)
+            .join(", ")
+        : "none"
+    }`,
+  );
+  console.log(`npm install graph: ${packages.install_graph.package_count} packages`);
+  console.log(`node: ${payload.node_version}`);
+  console.log(`api: ${payload.api_base}`);
+  console.log(`project key: ${payload.project_key.present ? "present" : "missing"}`);
+  console.log(`proxy: ${payload.proxy.configured ? "configured" : "direct"}`);
+  console.log(`workspace: ${payload.workspace.cwd}`);
+}
+
+async function runVersion(args) {
+  const packages = packageRuntimeInfo();
+  const version = packages.wrapper.version || packages.core.version || "unknown";
+  if (args.verbose || args.json) {
+    const payload = {
+      version,
+      ...packages,
+      node_version: process.version,
+      compatible: packages.compatible,
+    };
+    if (args.json) {
+      console.log(JSON.stringify(payload, null, 2));
+    } else {
+      console.log(`myte ${version}`);
+      console.log(`core ${packages.core.version || "unknown"}`);
+      console.log(
+        `runtime dependencies: ${
+          packages.runtime_dependencies.length
+            ? packages.runtime_dependencies
+                .map((dependency) => `${dependency.name}@${dependency.version}`)
+                .join(", ")
+            : "none"
+        }`,
+      );
+      console.log(`npm install graph: ${packages.install_graph.package_count} packages`);
+      console.log(`node ${process.version}`);
+      console.log(`wrapper/core compatible: ${packages.compatible ? "yes" : "no"}`);
+    }
+    return;
+  }
+  console.log(version);
+}
+
+async function runDoctor(args, envPath) {
+  const timeoutMs = Math.max(
+    1_000,
+    Math.min(30_000, Number(args["timeout-ms"] || args.timeoutMs || 10_000) || 10_000),
+  );
+  const apiBase = resolveApiBase(args);
+  const parsedBase = new URL(apiBase);
+  const key = getProjectApiKey();
+  const proxy = proxyEnvironmentSummary();
+  const packages = packageRuntimeInfo();
+  const payload = {
+    schema_version: 1,
+    command: "myte doctor",
+    generated_at: new Date().toISOString(),
+    packages,
+    runtime: {
+      node_version: process.version,
+      platform: `${process.platform}-${process.arch}`,
+      transport: null,
+    },
+    api: {
+      base: apiBase,
+      endpoint: parsedBase.host,
+    },
+    project_key: projectKeySummary(key),
+    proxy,
+    dns: null,
+    direct_transport: null,
+    config_probe: null,
+    workspace: {
+      cwd: process.cwd(),
+      env_file: envPath,
+      mode: "unknown",
+      root: process.cwd(),
+      configured_repos: [],
+      found_repos: [],
+      missing_repos: [],
+    },
+    ok: false,
+    failure_layer: null,
+  };
+
+  try {
+    payload.runtime.transport = (await getFetchRuntime()).transport;
+  } catch (error) {
+    payload.runtime.transport = "unavailable";
+    payload.config_probe = {
+      ok: false,
+      failure: publicRequestFailure(error),
+    };
+  }
+  payload.dns = await probeDns(parsedBase.hostname, timeoutMs);
+  payload.direct_transport = await probeDirectTransport(apiBase, timeoutMs);
+
+  if (!payload.config_probe && key) {
+    try {
+      const config = await fetchProjectConfig({ apiBase, key, timeoutMs });
+      const repoNames = Array.isArray(config.repo_names) ? config.repo_names : [];
+      const repoBindings = Array.isArray(config.repo_bindings) ? config.repo_bindings : [];
+      const resolved = repoBindings.length
+        ? resolveConfiguredRepoBindings(repoBindings)
+        : resolvePortableWorkspace(repoNames);
+      payload.config_probe = {
+        ok: true,
+        project_id: config.project_id || null,
+        repo_count: repoNames.length,
+      };
+      payload.workspace = {
+        ...payload.workspace,
+        mode: resolved.mode || "unknown",
+        root: resolved.root || process.cwd(),
+        configured_repos: repoNames,
+        found_repos: (resolved.repos || []).map((repo) => repo.name),
+        missing_repos: resolved.missing || [],
+      };
+    } catch (error) {
+      payload.config_probe = {
+        ok: false,
+        failure: publicRequestFailure(error),
+      };
+    }
+  } else if (!payload.config_probe) {
+    payload.config_probe = {
+      ok: false,
+      skipped: true,
+      reason: "project_key_missing",
+    };
+  }
+
+  payload.ok = payload.config_probe.ok === true;
+  const firstFailure =
+    payload.config_probe.failure ||
+    (!payload.direct_transport.ok ? payload.direct_transport.failure : null) ||
+    (!payload.dns.ok ? payload.dns.failure : null);
+  payload.failure_layer = firstFailure?.layer || null;
+
+  if (args.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(`Myte doctor: ${payload.ok ? "reachable" : "not ready"}`);
+    console.log(`API: ${payload.api.base}`);
+    console.log(`Key: ${payload.project_key.present ? "present" : "missing"}`);
+    console.log(`Proxy: ${payload.proxy.configured ? "configured" : "direct"}`);
+    console.log(`DNS: ${payload.dns.ok ? "ok" : "failed"}`);
+    console.log(
+      `Direct ${payload.direct_transport.protocol || "transport"}: ${
+        payload.direct_transport.ok ? "ok" : "failed"
+      }`,
+    );
+    console.log(`Authenticated config: ${payload.config_probe.ok ? "ok" : "failed"}`);
+    if (firstFailure) {
+      console.log(`Failure layer: ${firstFailure.layer || "unknown"}`);
+      console.log(`Cause: ${firstFailure.code || "unknown"}`);
+      console.log(`Detail: ${firstFailure.detail || "Request failed."}`);
+    }
+  }
+  if (!payload.ok) process.exitCode = 1;
+}
+
+async function runConfig(args) {
   const key = (process.env.MYTE_API_KEY || process.env.MYTE_PROJECT_API_KEY || "").trim();
   if (!key) {
     console.error("Missing MYTE_API_KEY (project key) in environment/.env");
@@ -4821,10 +6126,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 });
@@ -4855,9 +6161,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.");
@@ -4956,7 +6263,7 @@ async function runSyncQaqc(args) {
   console.log(`Snapshot: ${summary.snapshot_hash || "n/a"}`);
 }
 
-async function runFeedbackSync(args) {
+async function runFeedbackSync(args) {
   const key = getProjectApiKey();
   if (!key) {
     console.error("Missing MYTE_API_KEY (project key) in environment/.env");
@@ -4965,17 +6272,45 @@ async function runFeedbackSync(args) {
 
   const timeoutMs = resolveTimeoutMs(args);
   const apiBase = resolveApiBase(args);
-  const includePrdText = resolveBooleanFlag(args, "with-prd-text", true);
-  const filters = {
+  const includePrdText = resolveBooleanFlag(args, "with-prd-text", true);
+  let pageSize;
+  let maxItems;
+  try {
+    pageSize = resolveBoundedInteger(
+      args["page-size"] || args.pageSize || args.page_size,
+      { fallback: DEFAULT_FEEDBACK_SYNC_PAGE_SIZE, min: 1, max: 500, label: "page-size" }
+    );
+    maxItems = resolveBoundedInteger(
+      args.limit,
+      { fallback: 0, min: 0, max: 100_000, label: "limit" }
+    );
+  } catch (err) {
+    console.error(err?.message || err);
+    process.exit(1);
+  }
+  const filters = {
     status: firstNonEmptyString(args.status) || "",
     source: firstNonEmptyString(args.source) || "",
     includePrdText,
     includeCommentTurns: true,
   };
 
-  let snapshot;
-  try {
-    snapshot = await fetchFeedbackSyncSnapshot({ apiBase, key, timeoutMs, filters });
+  let snapshot;
+  try {
+    snapshot = await fetchCompleteFeedbackSyncSnapshot({
+      apiBase,
+      key,
+      timeoutMs,
+      filters,
+      pageSize,
+      maxItems,
+      onPage: args.json
+        ? undefined
+        : ({ page, received, synced, total }) => {
+            const totalText = Number.isFinite(Number(total)) ? `/${total}` : "";
+            console.error(`Feedback sync page ${page}: +${received} (${synced}${totalText})`);
+          },
+    });
   } catch (err) {
     console.error("Failed to fetch feedback sync snapshot:", err?.message || err);
     process.exit(1);
@@ -5012,8 +6347,10 @@ async function runFeedbackSync(args) {
     filters: snapshot.filters && typeof snapshot.filters === "object" ? snapshot.filters : filters,
     counts,
     snapshot_hash: snapshot.snapshot_hash || null,
-    generated_at: snapshot.generated_at || null,
-    dry_run: dryRun,
+    generated_at: snapshot.generated_at || null,
+    pagination: snapshot.pagination || null,
+    diagnostics: snapshot.diagnostics || null,
+    dry_run: dryRun,
   };
 
   if (dryRun) {
@@ -5054,22 +6391,23 @@ async function runFeedbackSync(args) {
   console.log(`Snapshot: ${summary.snapshot_hash || "n/a"}`);
 }
 
-async function refreshFeedbackSnapshotAfterMutation(args, { apiBase, key, timeoutMs }) {
+async function refreshFeedbackSnapshotAfterMutation(args, { apiBase, key, timeoutMs }) {
   if (args.sync === false || args["no-sync"] || args.noSync || args.no_sync) {
     return { skipped: true };
   }
   try {
-    const snapshot = await fetchFeedbackSyncSnapshot({
-      apiBase,
-      key,
-      timeoutMs,
-      filters: {
+    const snapshot = await fetchCompleteFeedbackSyncSnapshot({
+      apiBase,
+      key,
+      timeoutMs,
+      filters: {
         status: "",
         source: "",
         includePrdText: true,
-        includeCommentTurns: true,
-      },
-    });
+        includeCommentTurns: true,
+      },
+      pageSize: DEFAULT_FEEDBACK_SYNC_PAGE_SIZE,
+    });
     const resolved = resolvePortableWorkspace(snapshot.repo_names || []);
     const writeResult = writeFeedbackSnapshot({
       snapshot,
@@ -5152,9 +6490,62 @@ async function buildFeedbackDraftForCommand(args, subcommand) {
     const tags = parseFeedbackTags(args);
     if (tags) changes.tags = feedbackChange(Array.isArray(item.tags) ? item.tags : [], tags);
 
-    const reviewNote = firstNonEmptyString(args["review-note"], args.reviewNote, args.review_note);
-    if (reviewNote) changes.review_note = feedbackChange(null, reviewNote);
-  } else {
+    const reviewNote = firstNonEmptyString(args["review-note"], args.reviewNote, args.review_note);
+    if (reviewNote) changes.review_note = feedbackChange(null, reviewNote);
+
+    const prdFile = firstNonEmptyString(args["prd-file"], args.prdFile, args.prd_file);
+    if (prdFile) {
+      const proposedPath = resolveInputFile(prdFile, "PRD document");
+      const proposedMarkdown = fs.readFileSync(proposedPath, "utf8");
+      if (!proposedMarkdown.trim()) {
+        console.error("PRD document markdown cannot be empty.");
+        process.exit(1);
+      }
+      if (proposedMarkdown.length > 250000) {
+        console.error("PRD document markdown must be at most 250000 characters.");
+        process.exit(1);
+      }
+
+      const documents = Array.isArray(item.prd_documents) ? item.prd_documents : [];
+      const explicitDocumentId = firstNonEmptyString(
+        args["document-id"],
+        args.documentId,
+        args.document_id
+      );
+      const targetDocumentId = explicitDocumentId
+        || firstNonEmptyString(item.primary_prd_document_id)
+        || firstNonEmptyString(documents[0]?.document_id);
+      const targetDocument = targetDocumentId
+        ? documents.find((document) => String(document?.document_id || "") === targetDocumentId)
+        : null;
+      if (explicitDocumentId && !targetDocument) {
+        console.error(`PRD document not found in feedback.yml: ${explicitDocumentId}. Run \`myte feedback-sync\` first.`);
+        process.exit(1);
+      }
+      if (documents.length > 0 && !targetDocument) {
+        console.error("Unable to resolve the primary PRD document. Run `myte feedback-sync` first.");
+        process.exit(1);
+      }
+
+      let currentMarkdown = "";
+      const localFile = firstNonEmptyString(targetDocument?.local_file, item.prd_file);
+      if (localFile) {
+        const currentPath = path.resolve(paths.targetRoot, localFile);
+        const relativePath = path.relative(paths.targetRoot, currentPath);
+        if (!relativePath.startsWith("..") && !path.isAbsolute(relativePath) && fs.existsSync(currentPath)) {
+          currentMarkdown = fs.readFileSync(currentPath, "utf8");
+        }
+      }
+      changes.prd_markdown = feedbackChange(currentMarkdown, proposedMarkdown);
+      changes.prd_format = feedbackChange(
+        firstNonEmptyString(item.prd_format, "markdown"),
+        "markdown"
+      );
+      if (targetDocumentId) {
+        args["document-id"] = targetDocumentId;
+      }
+    }
+  } else {
     console.error("Unknown feedback draft command. Use status, edit, assign, archive, or refine.");
     process.exit(1);
   }
@@ -5210,15 +6601,9 @@ async function runFeedbackValidateOrApply(args, mode) {
     args.client_session_id,
     payload.client_session_id
   );
-  if (mode === "apply") {
-    payload = withWriteApproval(args, payload, {
-      artifactKind: "yaml",
-      targets: [feedbackId],
-    });
-  }
   const idempotencyKey = mode === "apply"
-    ? resolveProjectMutationIdempotencyKey({
-        args,
+    ? resolveProjectMutationIdempotencyKey({
+        args,
         operation: `feedback_refinement_apply:${feedbackId}`,
         payload,
       })
@@ -5515,7 +6900,7 @@ async function runFeedbackReviews(args) {
   }
 }
 
-function buildFeedbackReviewDecisionPayload(args, action) {
+function buildFeedbackReviewDecisionPayload(args, action) {
   const filePath = firstNonEmptyString(args.file);
   let payload = {};
   if (filePath) {
@@ -5527,9 +6912,25 @@ function buildFeedbackReviewDecisionPayload(args, action) {
   }
   const nextPayload = { ...payload };
   const reason = firstNonEmptyString(args.reason, args["review-note"], args.reviewNote, args.review_note);
-  if (reason && !nextPayload.reason && !nextPayload.review_reason) {
-    nextPayload.reason = reason;
-  }
+  if (reason && !nextPayload.reason && !nextPayload.review_reason) {
+    nextPayload.reason = reason;
+  }
+  const verificationEvidence = firstNonEmptyString(
+    args["verification-evidence"],
+    args.verificationEvidence,
+    args.verification_evidence,
+  );
+  if (verificationEvidence && !nextPayload.verification_evidence) {
+    nextPayload.verification_evidence = verificationEvidence;
+  }
+  const deploymentEvidence = firstNonEmptyString(
+    args["deployment-evidence"],
+    args.deploymentEvidence,
+    args.deployment_evidence,
+  );
+  if (deploymentEvidence && !nextPayload.deployment_evidence) {
+    nextPayload.deployment_evidence = deploymentEvidence;
+  }
   const finalFile = firstNonEmptyString(args["final-file"], args.finalFile, args.final_file);
   if (finalFile) {
     nextPayload.final_change_set = readStructuredPayloadFile(finalFile, "Feedback final change set");
@@ -5569,20 +6970,27 @@ async function runFeedbackReviewDecision(args) {
       console.error("Missing --request-ids for batch feedback review.");
       process.exit(1);
     }
-    const reason = firstNonEmptyString(args.reason, args["review-note"], args.reviewNote, args.review_note);
+    const reason = firstNonEmptyString(args.reason, args["review-note"], args.reviewNote, args.review_note);
+    const verificationEvidence = firstNonEmptyString(
+      args["verification-evidence"],
+      args.verificationEvidence,
+      args.verification_evidence,
+    );
+    const deploymentEvidence = firstNonEmptyString(
+      args["deployment-evidence"],
+      args.deploymentEvidence,
+      args.deployment_evidence,
+    );
     let payload = {
       ...(isPlainObject(filePayload) && !Array.isArray(filePayload) ? filePayload : {}),
       items,
       action,
       reason: reason || undefined,
+      verification_evidence: verificationEvidence || undefined,
+      deployment_evidence: deploymentEvidence || undefined,
     };
-    payload = withWriteApproval(args, payload, {
-      artifactKind: "yaml",
-      targets: items.map((item) => item.request_id || item.id).filter(Boolean),
-      batchCount: items.length,
-    });
     const timeoutMs = resolveTimeoutMs(args);
-    const apiBase = resolveApiBase(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,
@@ -5639,12 +7047,8 @@ async function runFeedbackReviewDecision(args) {
     process.exit(1);
   }
   const endpointAction = action === "request_changes" ? "request-changes" : action === "cancel" ? "cancel" : "review";
-  payload = withWriteApproval(args, payload, {
-    artifactKind: "yaml",
-    targets: [requestId],
-  });
   const timeoutMs = resolveTimeoutMs(args);
-  const apiBase = resolveApiBase(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({
@@ -5717,14 +7121,9 @@ async function runFeedbackMove(args) {
     }
     const batchId = firstNonEmptyString(args["batch-id"], args.batchId, args.batch_id);
     if (batchId) payload.batch_id = batchId;
-    payload = withWriteApproval(args, payload, {
-      artifactKind: "yaml",
-      targets: feedbackIds,
-      batchCount: feedbackIds.length,
-    });
     const idempotencyKey = resolveProjectMutationIdempotencyKey({
-      args,
-      operation: `feedback_board_batch_move:${toState}:${feedbackIds.join(",")}`,
+      args,
+      operation: `feedback_board_batch_move:${toState}:${feedbackIds.join(",")}`,
       payload,
     });
     let data;
@@ -5758,13 +7157,9 @@ async function runFeedbackMove(args) {
   }
 
   payload.from_state = fromState;
-  payload = withWriteApproval(args, payload, {
-    artifactKind: "yaml",
-    targets: [feedbackId],
-  });
   const idempotencyKey = resolveProjectMutationIdempotencyKey({
-    args,
-    operation: `feedback_board_move:${feedbackId}`,
+    args,
+    operation: `feedback_board_move:${feedbackId}`,
     payload,
   });
 
@@ -5901,13 +7296,9 @@ async function runFeedbackUndo(args) {
   const timeoutMs = resolveTimeoutMs(args);
   const apiBase = resolveApiBase(args);
   const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
-  payload = withWriteApproval(args, payload, {
-    artifactKind: "yaml",
-    targets: [feedbackId, eventId],
-  });
   const idempotencyKey = resolveProjectMutationIdempotencyKey({
-    args,
-    operation: `feedback_event_undo:${feedbackId}:${eventId}`,
+    args,
+    operation: `feedback_event_undo:${feedbackId}:${eventId}`,
     payload,
   });
 
@@ -5989,12 +7380,21 @@ async function runFeedbackPrdDiff(args) {
     console.error("Missing --version-id.");
     process.exit(1);
   }
-  const timeoutMs = resolveTimeoutMs(args);
-  const apiBase = resolveApiBase(args);
-  const compareTo = firstNonEmptyString(args["compare-to"], args.compareTo, args.compare_to);
-  let data;
-  try {
-    data = await fetchFeedbackPrdVersionDiff({ apiBase, key, timeoutMs, feedbackId, versionId, compareTo });
+  const timeoutMs = resolveTimeoutMs(args);
+  const apiBase = resolveApiBase(args);
+  const compareTo = firstNonEmptyString(args["compare-to"], args.compareTo, args.compare_to);
+  const documentId = firstNonEmptyString(args["document-id"], args.documentId, args.document_id);
+  let data;
+  try {
+    data = await fetchFeedbackPrdVersionDiff({
+      apiBase,
+      key,
+      timeoutMs,
+      feedbackId,
+      versionId,
+      compareTo,
+      documentId,
+    });
   } catch (err) {
     console.error("Feedback PRD diff failed:", err?.message || err);
     process.exit(1);
@@ -6213,11 +7613,13 @@ async function buildSuggestionsMutationContext(args, mode) {
     validateSuggestionsRevisePayload(payload);
   }
   const items = Array.isArray(payload?.items) ? payload.items : [];
-  payload = withWriteApproval(args, payload, {
-    artifactKind: "yaml",
-    targets: suggestionWriteTargets(items),
-    batchCount: items.length > 1 ? items.length : null,
-  });
+  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,
@@ -6706,8 +8108,9 @@ async function runQuery(args) {
     process.exit(1);
   }
 
-  const includeDiff = Boolean(args["with-diff"] || args.withDiff || args.diff || args.d);
-  const printContext = Boolean(args["print-context"] || args.printContext || args["dry-run"] || args.dryRun);
+  const includeDiff = Boolean(args["with-diff"] || args.withDiff || args.diff || args.d);
+  const printContext = Boolean(args["print-context"] || args.printContext || args["dry-run"] || args.dryRun);
+  const verbose = Boolean(args.verbose || args.v);
 
   const fetchRemote = args.fetch !== undefined ? Boolean(args.fetch) : true;
 
@@ -6779,11 +8182,32 @@ async function runQuery(args) {
     process.exit(0);
   }
 
-  let data;
-  try {
-    const queued = await createAssistantQueryJob({ apiBase, key, payload, timeoutMs });
-    if (queued.answer) {
-      data = queued;
+  let data;
+  const requestId = queryRequestId(args);
+  try {
+    if (verbose) {
+      const runtime = await getFetchRuntime();
+      console.error(
+        `[myte] query request_id=${requestId} endpoint=${safeEndpointHost(apiBase)} transport=${runtime.transport}`,
+      );
+    }
+    const queued = await withTransientQueryRetries(
+      () =>
+        createAssistantQueryJob({
+          apiBase,
+          key,
+          payload,
+          timeoutMs,
+          requestId,
+        }),
+      {
+        maxAttempts: 3,
+        verbose,
+        label: "query creation",
+      },
+    );
+    if (queued.answer) {
+      data = queued;
     } else {
       const jobId = firstNonEmptyString(queued.job_id, queued.id);
       if (!jobId) {
@@ -6794,21 +8218,24 @@ async function runQuery(args) {
       let finalStatus = null;
       let pollDelayMs = 2_000;
       do {
-        await sleep(pollDelayMs);
-        try {
-          finalStatus = await fetchAssistantQueryJobStatus({ apiBase, key, timeoutMs, jobId });
-          pollDelayMs = Math.min(10_000, Math.ceil(pollDelayMs * 1.25));
-        } catch (err) {
-          if (isTransientQueryStatusError(err)) {
-            const fallbackMs =
-              Number(err?.status) === 429 ? 5_000 : Math.min(30_000, Math.max(5_000, pollDelayMs * 2));
-            const waitMs = resolveRetryAfterMs(err, fallbackMs);
-            await sleep(waitMs);
-            pollDelayMs = Math.min(30_000, Math.max(pollDelayMs, waitMs));
-            continue;
-          }
-          throw err;
-        }
+        await sleep(pollDelayMs);
+        finalStatus = await withTransientQueryRetries(
+          () =>
+            fetchAssistantQueryJobStatus({
+              apiBase,
+              key,
+              timeoutMs,
+              jobId,
+              requestId,
+            }),
+          {
+            maxAttempts: 4,
+            verbose,
+            label: "query status",
+            initialDelayMs: Math.min(2_000, pollDelayMs),
+          },
+        );
+        pollDelayMs = Math.min(10_000, Math.ceil(pollDelayMs * 1.25));
         if (["completed", "failed"].includes(String(finalStatus.status || "").trim())) {
           break;
         }
@@ -6821,22 +8248,37 @@ async function runQuery(args) {
         const detail = firstNonEmptyString(finalStatus?.error?.message, finalStatus?.error?.code);
         throw new Error(detail || `Query job ${jobId} failed`);
       }
-      data = {
-        answer: finalStatus.answer,
-        context_blocks: finalStatus.context_blocks,
-        telemetry: finalStatus.telemetry,
+      data = {
+        job_id: jobId,
+        answer: finalStatus.answer,
+        context_blocks: finalStatus.context_blocks,
+        telemetry: finalStatus.telemetry,
       };
     }
-  } catch (err) {
-    if (err?.name === "AbortError") {
-      console.error(`Request timed out after ${timeoutMs}ms`);
-    } else {
-      console.error("Assistant query failed:", err?.message || err);
-    }
-    process.exit(1);
-  }
-
-  console.log("Answer:\n", data.answer || "(no answer)");
+  } catch (err) {
+    console.error("Assistant query failed:", err?.message || err);
+    process.exit(1);
+  }
+
+  if (args.json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          request_id: requestId,
+          job_id: firstNonEmptyString(data.job_id, data.id) || null,
+          answer: data.answer || "",
+          context_blocks: Array.isArray(data.context_blocks) ? data.context_blocks : [],
+          telemetry: data.telemetry || null,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  console.log("Answer:\n", data.answer || "(no answer)");
   if (data.context_blocks?.length) console.log(`\nContext blocks: ${data.context_blocks.length}`);
   if (data.telemetry) {
     const t = data.telemetry;
@@ -6850,8 +8292,8 @@ async function runChat(args) {
   process.exit(1);
 }
 
-async function main() {
-  loadEnv();
+async function main() {
+  const envPath = loadEnv();
 
   const { command, rest } = splitCommand(process.argv.slice(2));
   if (REMOVED_COMMAND_MESSAGES[command]) {
@@ -6863,12 +8305,27 @@ async function main() {
     process.exit(1);
   }
   const args = parseArgs(rest);
-  if (args.help || command === "help") {
+  if (args.help || command === "help") {
     printHelp();
     return;
-  }
-
-  if (command === "config") {
+  }
+
+  if (command === "version") {
+    await runVersion(args);
+    return;
+  }
+
+  if (command === "info") {
+    await runInfo(args, envPath);
+    return;
+  }
+
+  if (command === "doctor") {
+    await runDoctor(args, envPath);
+    return;
+  }
+
+  if (command === "config") {
     await runConfig(args);
     return;
   }
@@ -6948,12 +8405,19 @@ if (require.main === module) {
     process.exit(1);
   });
 } else {
-  module.exports = {
-    buildMissionOpsPayload,
-    collectCreateDraftPayload,
+  module.exports = {
+    buildFetchRuntime,
+    buildMissionOpsPayload,
+    classifyNetworkFailure,
+    createHttpResponseError,
+    createNetworkRequestError,
+    collectCreateDraftPayload,
     collectReviewPayload,
     collectRevisionPayload,
-    normalizeItemsPayload,
+    normalizeItemsPayload,
+    proxyEnvironmentSummary,
+    probeDns,
+    publicRequestFailure,
     preserveMissionOpsWorkspace,
     pruneLegacyCommandCenterArtifacts,
     readYamlFile,
@@ -6965,6 +8429,8 @@ if (require.main === module) {
     writeFeedbackSnapshot,
     writeApprovedMissionCards,
     writeMissionOpsSnapshot,
-    writeQaqcSnapshot,
-  };
-}
+    writeQaqcSnapshot,
+    fetchJsonWithTimeout,
+    withTransientQueryRetries,
+  };
+}