@mytegroupinc/myte-core 0.0.47 → 0.0.50

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,8 +24,10 @@ 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.",
@@ -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,15 +123,20 @@ 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 };
 }
 
-function parseArgs(argv) {
-  const parsed = { _: [], fetch: true };
+function parseArgs(argv) {
+  const parsed = { _: [] };
   const aliases = { q: "query", d: "with-diff", c: "context", h: "help" };
   const setValue = (key, value) => {
     const finalKey = aliases[key] || key;
@@ -181,9 +197,12 @@ 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]",
@@ -200,23 +219,23 @@ function printHelp() {
     "  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 --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] --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 ...] --confirm-write --approval-artifact <path> [--json] [--title \"...\"] [--description \"...\"]",
+    "  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",
@@ -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",
@@ -307,12 +328,14 @@ function printHelp() {
     "  - Optional: --target-contact-id <id> (repeatable) or --target-contact-ids <id1,id2>",
     "  - If the project has no linked client contacts, the backend falls back to the project owner for internal projects",
     "",
-    "feedback-sync contract:",
+    "feedback-sync contract:",
     "  - Runs from any workspace where you want local MyteCommandCenter data written",
     "  - Syncs non-archived feedback by default so local Command Center data stays focused on active visible work",
     "  - Archived feedback is intentionally excluded from normal sync; returning it to active work is web UI only",
-    "  - Writes project feedback metadata and conversation turns into MyteCommandCenter/data/feedback.yml",
-    "  - Stores full PRD context in MyteCommandCenter/PRD/feedback-sync/*.md and points to those files from feedback.yml",
+    "  - Writes project feedback metadata and comment turns, stable comment ids, and nested attachment metadata into MyteCommandCenter/data/feedback.yml",
+    "  - Stores full PRD context in MyteCommandCenter/PRD/feedback-sync/*.md and points to those files from feedback.yml",
+    "  - Stores readable text/Markdown/DOCX comment attachment context under MyteCommandCenter/feedback-sync/comment-attachments and never writes raw storage URLs",
+    "  - Non-readable comment attachments remain nested under the correct comment as metadata_only context",
     "  - Reads existing feedback comments and can create text-only feedback-specific comments through the project-key API",
     "",
     "feedback review contract:",
@@ -327,7 +350,8 @@ 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",
+    "  - 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",
@@ -364,7 +388,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",
@@ -373,8 +399,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",
@@ -387,8 +414,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",
@@ -401,7 +430,8 @@ function printHelp() {
     "  --due-date <date>     Feedback due date target for edit artifacts",
     "  --review-note <text>  Review note stored in feedback refinement history",
     "  --with-prd-text       Include extracted PRD text so local PRD files are materialized during feedback-sync (default: on)",
-    "  --no-with-prd-text    Skip PRD text download and write only feedback metadata/comment turns",
+    "  --no-with-prd-text    Skip PRD and readable comment-attachment extraction; keep feedback/comment/attachment metadata",
+    "  --comment-attachment-limit <n>  Cap readable comment-attachment extraction per sync page (0-100; default: 20)",
     "  --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)",
@@ -409,13 +439,16 @@ function printHelp() {
     "  --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",
+    "  --force               Allow QAQC retry or owner/elevated stale Feedback apply; Feedback force requires a reason",
     "  --no-sync             Skip automatic post-mutation sync for suggestions, missions, and feedback mutations",
     "  --print-context       Print JSON payload and exit (no query call)",
     "  --no-fetch            Don't git fetch origin main/master before diff",
     "",
     "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",
@@ -446,6 +479,7 @@ function printHelp() {
     "  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");
@@ -669,14 +703,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(/\/+$/, "");
@@ -684,24 +984,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);
   }
@@ -1575,18 +1882,18 @@ function collectGitDiffWithDiagnostics({
 
       const headingParts = [`${name} (${dir || "."})`];
       if (repo.role) headingParts.push(`role=${repo.role}`);
-      let section = `### ${headingParts.join(" | ")}\n\n`;
-      section += `# ?? Base vs HEAD (${repoSummary.base_ref_label}...HEAD | head=${headBranch})\n`;
-      if (repoSummary.matched_by?.length) {
-        section += `# ?? Matched by ${repoSummary.matched_by.join(", ")}\n`;
-      }
-      if (repoSummary.compare_remote_url) {
-        section += `# ?? Compare remote ${repoSummary.compare_remote_url}\n`;
-      }
-      if (baseDiff) section += `${baseDiff}\n\n`;
-      if (staged) section += `# ?? Staged changes\n${staged}\n\n`;
-      if (unstaged) section += `# ?? Unstaged changes\n${unstaged}\n\n`;
-      if (untrackedDiffs) section += `# ?? Untracked files (full contents below)\n${untrackedDiffs}\n`;
+      let section = `### ${headingParts.join(" | ")}\n\n`;
+      if (repoSummary.matched_by?.length) {
+        section += `# ?? Matched by ${repoSummary.matched_by.join(", ")}\n`;
+      }
+      if (repoSummary.compare_remote_url) {
+        section += `# ?? Compare remote ${repoSummary.compare_remote_url}\n`;
+      }
+      if (staged) section += `# ?? Staged changes\n${staged}\n\n`;
+      if (unstaged) section += `# ?? Unstaged changes\n${unstaged}\n\n`;
+      if (untrackedDiffs) section += `# ?? Untracked files (full contents below)\n${untrackedDiffs}\n`;
+      section += `# ?? Base vs HEAD (${repoSummary.base_ref_label}...HEAD | head=${headBranch})\n`;
+      if (baseDiff) section += `${baseDiff}\n\n`;
 
       if (!repoSummary.has_changes) {
         section += "_No local changes - working tree clean_\n\n";
@@ -1635,14 +1942,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 || {};
 }
 
@@ -1696,7 +2000,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));
@@ -1704,9 +2008,36 @@ 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.includeCommentAttachmentText !== undefined) {
+    url.searchParams.set(
+      "include_comment_attachment_text",
+      filters.includeCommentAttachmentText ? "true" : "false"
+    );
+  }
+  if (
+    filters.commentAttachmentTextLimit !== undefined
+    && filters.commentAttachmentTextLimit !== null
+  ) {
+    url.searchParams.set(
+      "comment_attachment_text_limit",
+      String(filters.commentAttachmentTextLimit)
+    );
+  }
+  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(),
@@ -1723,8 +2054,212 @@ 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;
+  let withCommentAttachments = 0;
+  let commentAttachments = 0;
+  const commentAttachmentContext = {};
+  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;
+    }
+    const itemCommentAttachments = (item?.conversation_turns || []).reduce(
+      (total, turn) => total + (Array.isArray(turn?.attachments) ? turn.attachments.length : 0),
+      0
+    );
+    if (itemCommentAttachments > 0) {
+      withCommentAttachments += 1;
+      commentAttachments += itemCommentAttachments;
+      for (const turn of item?.conversation_turns || []) {
+        for (const attachment of turn?.attachments || []) {
+          const contextStatus = String(attachment?.context_status || "metadata_only");
+          commentAttachmentContext[contextStatus] =
+            (commentAttachmentContext[contextStatus] || 0) + 1;
+        }
+      }
+    }
+  }
+  return {
+    total_feedback: items.length,
+    available_feedback: Number.isFinite(Number(availableTotal)) ? Number(availableTotal) : items.length,
+    with_prd_text: withPrdText,
+    with_conversation_turns: withConversationTurns,
+    with_comment_attachments: withCommentAttachments,
+    comment_attachments: commentAttachments,
+    comment_attachment_context: commentAttachmentContext,
+    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();
@@ -2069,10 +2604,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(),
@@ -2284,48 +2828,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(
@@ -2333,19 +2991,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 || {};
 }
 
@@ -3278,12 +3934,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, "-")
@@ -3304,22 +3998,47 @@ function ensureTrailingNewline(value) {
   return text.endsWith("\n") ? text : `${text}\n`;
 }
 
-function normalizeFeedbackConversationTurns(turns) {
-  if (!Array.isArray(turns)) return [];
-  return turns
-    .map((turn) => {
-      const content = String(turn?.content || "").trim();
-      if (!content) return null;
-      const normalized = {
-        sender_name: firstNonEmptyString(turn?.sender_name, turn?.user_name, turn?.author_name) || "Unknown",
-        content,
-      };
-      const createdAt = firstNonEmptyString(turn?.created_at, turn?.timestamp);
-      if (createdAt) normalized.created_at = createdAt;
-      return normalized;
-    })
-    .filter(Boolean);
-}
+function normalizeFeedbackConversationTurns(turns) {
+  if (!Array.isArray(turns)) return [];
+  return turns
+    .map((turn) => {
+      const content = String(turn?.content || "").trim();
+      const attachments = (Array.isArray(turn?.attachments) ? turn.attachments : [])
+        .map((attachment) => {
+          if (!isPlainObject(attachment)) return null;
+          const normalizedAttachment = {
+            name: firstNonEmptyString(attachment.name) || "attachment",
+            context_status: firstNonEmptyString(attachment.context_status) || "metadata_only",
+          };
+          for (const field of ["type", "asset_kind", "download_name", "format"]) {
+            const value = firstNonEmptyString(attachment[field]);
+            if (value) normalizedAttachment[field] = value;
+          }
+          const size = Number(attachment.size);
+          if (Number.isFinite(size) && size >= 0) normalizedAttachment.size = size;
+          const attachmentContent = String(attachment.content || "");
+          if (attachmentContent.trim()) normalizedAttachment.content = attachmentContent;
+          if (attachment.truncated !== undefined) {
+            normalizedAttachment.truncated = Boolean(attachment.truncated);
+          }
+          return normalizedAttachment;
+        })
+        .filter(Boolean);
+      if (!content && attachments.length === 0) return null;
+      const normalized = {
+        comment_id: firstNonEmptyString(turn?.comment_id, turn?.id),
+        sender_name: firstNonEmptyString(turn?.sender_name, turn?.user_name, turn?.author_name) || "Unknown",
+        content,
+        attachments,
+      };
+      const createdAt = firstNonEmptyString(turn?.created_at, turn?.timestamp);
+      if (createdAt) normalized.created_at = createdAt;
+      const updatedAt = firstNonEmptyString(turn?.updated_at);
+      if (updatedAt) normalized.updated_at = updatedAt;
+      return normalized;
+    })
+    .filter(Boolean);
+}
 
 function readJsonFile(filePath) {
   if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) return null;
@@ -3678,37 +4397,149 @@ 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 commentAttachmentsDir = path.join(targetRoot, "feedback-sync", "comment-attachments");
+  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");
+  const stagedCommentAttachmentsRoot = path.join(stagingRoot, "feedback-sync", "comment-attachments");
+  ensureDir(stagedDataRoot);
+  ensureDir(stagedPrdRoot);
+  ensureDir(stagedCommentAttachmentsRoot);
+
+  const items = Array.isArray(snapshot.items) ? snapshot.items : [];
+  let prdFileCount = 0;
+  let prdDocumentSetCount = 0;
+  let commentAttachmentCount = 0;
+  let commentAttachmentFileCount = 0;
+  const commentAttachmentContextCounts = {};
+  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 feedbackFolderName = sanitizeFileSegment(feedbackId, `feedback-${index + 1}`);
+    const conversationTurns = normalizeFeedbackConversationTurns(item.conversation_turns)
+      .map((turn, turnIndex) => {
+        const commentId = stableItemId(
+          turn,
+          ["comment_id", "id"],
+          `comment-${String(turnIndex + 1).padStart(3, "0")}`
+        );
+        const commentFolderName = sanitizeFileSegment(commentId, `comment-${turnIndex + 1}`);
+        const attachments = (turn.attachments || []).map((rawAttachment, attachmentIndex) => {
+          const attachment = isPlainObject(rawAttachment) ? { ...rawAttachment } : {};
+          const content = String(attachment.content || "");
+          let localFile = null;
+          commentAttachmentCount += 1;
+          const contextStatus = String(attachment.context_status || "metadata_only");
+          commentAttachmentContextCounts[contextStatus] =
+            (commentAttachmentContextCounts[contextStatus] || 0) + 1;
+          if (content.trim()) {
+            const sourceName = sanitizeFileSegment(
+              attachment.name,
+              `attachment-${attachmentIndex + 1}`
+            );
+            const sourceBase = path.parse(sourceName).name || `attachment-${attachmentIndex + 1}`;
+            const extension = String(attachment.format || "").toLowerCase() === "markdown"
+              ? "md"
+              : "txt";
+            const filename = `${String(attachmentIndex + 1).padStart(2, "0")}-${sourceBase}.${extension}`;
+            const stagedPath = path.join(
+              stagedCommentAttachmentsRoot,
+              feedbackFolderName,
+              commentFolderName,
+              filename
+            );
+            ensureDir(path.dirname(stagedPath));
+            writeTextFile(stagedPath, ensureTrailingNewline(content));
+            localFile = toPosixRelativePath(
+              targetRoot,
+              path.join(
+                commentAttachmentsDir,
+                feedbackFolderName,
+                commentFolderName,
+                filename
+              )
+            );
+            commentAttachmentFileCount += 1;
+          }
+          delete attachment.content;
+          return {
+            ...attachment,
+            local_file: localFile,
+          };
+        });
+        return {
+          ...turn,
+          comment_id: commentId,
+          attachments,
+        };
+      });
+    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;
+      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."
@@ -3720,31 +4551,45 @@ 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;
-  if (snapshotCounts.with_conversation_turns === undefined) {
-    snapshotCounts.with_conversation_turns = materializedItems.filter((item) => Array.isArray(item?.conversation_turns) && item.conversation_turns.length > 0).length;
-  }
+  snapshotCounts.with_prd_files = prdFileCount;
+  snapshotCounts.with_prd_document_sets = prdDocumentSetCount;
+  snapshotCounts.comment_attachments = commentAttachmentCount;
+  snapshotCounts.comment_attachment_context = commentAttachmentContextCounts;
+  snapshotCounts.readable_comment_attachment_files = commentAttachmentFileCount;
+  if (snapshotCounts.with_conversation_turns === undefined) {
+    snapshotCounts.with_conversation_turns = materializedItems.filter((item) => Array.isArray(item?.conversation_turns) && item.conversation_turns.length > 0).length;
+  }
+  snapshotCounts.with_comment_attachments = materializedItems.filter(
+    (item) => (item?.conversation_turns || []).some(
+      (turn) => Array.isArray(turn?.attachments) && turn.attachments.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",
+      feedback_comment_attachment_root: "feedback-sync/comment-attachments",
+      with_prd_files: prdFileCount,
+      with_prd_document_sets: prdDocumentSetCount,
+      comment_attachments: commentAttachmentCount,
+      readable_comment_attachment_files: commentAttachmentFileCount,
     },
     queue: materializedItems
       .filter((item) => String(item?.status || "").trim().toLowerCase() !== "resolved")
@@ -3754,24 +4599,60 @@ 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: stagedCommentAttachmentsRoot,
+        target: commentAttachmentsDir,
+      },
+      {
+        staged: stagedFeedbackPath,
+        target: path.join(dataRoot, "feedback.yml"),
+      }
+    );
+    replacePathsTransaction(replacements, transactionToken);
+    pruneLegacyCommandCenterArtifacts(dataRoot, { bootstrap: true, feedback: true });
+    return {
+      targetRoot,
+      dataRoot,
+      prdSyncDir,
+      commentAttachmentsDir,
+      manifest: payload,
+    };
+  } finally {
+    if (fs.existsSync(stagingRoot)) removePathIfExists(stagingRoot);
+  }
+}
 
 function resolveFeedbackReviewPaths(args, { requireFeedback = false } = {}) {
   const outputDir = args["output-dir"] || args.outputDir || args.output_dir;
@@ -3847,9 +4728,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),
@@ -3857,9 +4743,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(),
@@ -3911,11 +4798,13 @@ function summarizeFeedbackRefinementResult(data) {
     new_snapshot_hash: data?.new_snapshot_hash || data?.feedback?.snapshot_hash || null,
     diff_count: Array.isArray(data?.diffs) ? data.diffs.length : 0,
     diffs: data?.diffs || [],
-    warnings: data?.warnings || [],
-    errors: data?.errors || [],
-    history_id: data?.history?.history_id || null,
-  };
-}
+    warnings: data?.warnings || [],
+    errors: data?.errors || [],
+    history_id: data?.history?.history_id || null,
+    feedback: data?.feedback || null,
+    history: data?.history || null,
+  };
+}
 
 function missionOpsThreads(payload) {
   if (Array.isArray(payload?.threads)) return payload.threads;
@@ -4563,7 +5452,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");
@@ -4585,13 +5474,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();
@@ -4623,8 +5523,8 @@ async function runCreatePrd(args) {
     return payload;
   };
 
-  let payloads = [];
-  if (useStdin) {
+  let payloads = [];
+  if (useStdin) {
     try {
       payloads = [
         buildCreatePrdPayload({
@@ -4643,21 +5543,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);
     }
   }
 
@@ -4674,7 +5625,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,
@@ -4707,9 +5661,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
         )
@@ -4787,10 +5744,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");
@@ -5074,7 +6407,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");
@@ -5083,17 +6416,59 @@ async function runFeedbackSync(args) {
 
   const timeoutMs = resolveTimeoutMs(args);
   const apiBase = resolveApiBase(args);
-  const includePrdText = resolveBooleanFlag(args, "with-prd-text", true);
-  const filters = {
-    status: firstNonEmptyString(args.status) || "",
-    source: firstNonEmptyString(args.source) || "",
-    includePrdText,
-    includeCommentTurns: true,
-  };
+  const includePrdText = resolveBooleanFlag(args, "with-prd-text", true);
+  let pageSize;
+  let maxItems;
+  let commentAttachmentTextLimit;
+  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" }
+    );
+    commentAttachmentTextLimit = resolveBoundedInteger(
+      args["comment-attachment-limit"]
+        || args.commentAttachmentLimit
+        || args.comment_attachment_limit,
+      {
+        fallback: 20,
+        min: 0,
+        max: 100,
+        label: "comment-attachment-limit",
+      }
+    );
+  } catch (err) {
+    console.error(err?.message || err);
+    process.exit(1);
+  }
+  const filters = {
+    status: firstNonEmptyString(args.status) || "",
+    source: firstNonEmptyString(args.source) || "",
+    includePrdText,
+    includeCommentTurns: true,
+    includeCommentAttachmentText: includePrdText,
+    commentAttachmentTextLimit,
+  };
 
-  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);
@@ -5130,8 +6505,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) {
@@ -5172,22 +6549,25 @@ 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,
-      },
-    });
+        includePrdText: true,
+        includeCommentTurns: true,
+        includeCommentAttachmentText: true,
+        commentAttachmentTextLimit: 20,
+      },
+      pageSize: DEFAULT_FEEDBACK_SYNC_PAGE_SIZE,
+    });
     const resolved = resolvePortableWorkspace(snapshot.repo_names || []);
     const writeResult = writeFeedbackSnapshot({
       snapshot,
@@ -5270,9 +6650,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);
   }
@@ -5627,7 +7060,7 @@ async function runFeedbackReviews(args) {
   }
 }
 
-function buildFeedbackReviewDecisionPayload(args, action) {
+function buildFeedbackReviewDecisionPayload(args, action) {
   const filePath = firstNonEmptyString(args.file);
   let payload = {};
   if (filePath) {
@@ -5639,9 +7072,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");
@@ -5681,12 +7130,24 @@ 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,
     };
     const timeoutMs = resolveTimeoutMs(args);
     const apiBase = resolveApiBase(args);
@@ -6079,12 +7540,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);
@@ -6798,8 +8268,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;
 
@@ -6871,11 +8342,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) {
@@ -6886,21 +8378,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;
         }
@@ -6913,22 +8408,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;
@@ -6942,8 +8452,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]) {
@@ -6955,12 +8465,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;
   }
@@ -7040,12 +8565,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,
@@ -7057,6 +8589,8 @@ if (require.main === module) {
     writeFeedbackSnapshot,
     writeApprovedMissionCards,
     writeMissionOpsSnapshot,
-    writeQaqcSnapshot,
-  };
-}
+    writeQaqcSnapshot,
+    fetchJsonWithTimeout,
+    withTransientQueryRetries,
+  };
+}