@mytegroupinc/myte-core 0.0.19 → 0.0.20

package/README.md

@@ -1,151 +1,23 @@
 # @mytegroupinc/myte-core
 
-Internal implementation package for the `myte` CLI.
+Implementation package for the `myte` CLI.
 
-Most users should install the unscoped wrapper instead:
-- `npm install myte` then `npx myte ai "Explain this repository"`
-- `npm install myte` then `npx myte ai "Return a JSON object with risks and next_steps" --json-response`
-- `npm install myte` then `npx myte bootstrap`
-- `npm install myte` then `npx myte run-qaqc --mission-ids M001 --wait --sync`
-- `npm install myte` then `npx myte mission status --mission-ids M001 --status done`
-- `npm install myte` then `npx myte sync-qaqc`
-- `npm install myte` then `npx myte feedback-sync`
-- `npm install myte` then `npx myte suggestions sync`
-- `npm install myte` then `npx myte suggestions create`
-- `npm install myte` then `npx myte suggestions revise`
-- `npm install myte` then `npx myte suggestions review`
-- `npm install myte` then `npx myte query "..." --with-diff`
-- `npm install myte` then `npm exec myte -- query "..." --with-diff`
-- `npm install myte` then `npx myte update-team "Backend deploy completed; QAQC rerun queued."`
-- `npm install myte` then `npx myte update-owner --subject "QAQC progress" --body-file ./updates/owner.md`
-- `npm install myte` then `npx myte update-client --subject "Weekly client update" --body-file ./updates/week-12.md`
-- `npm i -g myte` then `myte bootstrap`
-- `npm i -g myte` then `myte run-qaqc --mission-ids M001 --wait --sync`
-- `npm i -g myte` then `myte mission status --mission-ids M001 --status done`
-- `npm i -g myte` then `myte sync-qaqc`
-- `npm i -g myte` then `myte feedback-sync`
-- `npm i -g myte` then `myte suggestions sync`
-- `npm i -g myte` then `myte suggestions create`
-- `npm i -g myte` then `myte suggestions revise`
-- `npm i -g myte` then `myte suggestions review`
-- `npm i -g myte` then `myte query "..." --with-diff`
-- `npm i -g myte` then `myte update-team "Backend deploy completed; QAQC rerun queued."`
-- `npm i -g myte` then `myte update-owner --subject "QAQC progress" --body-file ./updates/owner.md`
-- `npm i -g myte` then `myte update-client --subject "Weekly client update" --body-file ./updates/week-12.md`
-- `npx myte@latest bootstrap`
-- `npx myte@latest run-qaqc --mission-ids M001 --wait --sync`
-- `npx myte@latest mission status --mission-ids M001 --status done`
-- `npx myte@latest sync-qaqc`
-- `npx myte@latest feedback-sync`
-- `npx myte@latest suggestions sync`
-- `npx myte@latest suggestions create`
-- `npx myte@latest suggestions revise`
-- `npx myte@latest suggestions review`
-- `npx myte@latest query "..." --with-diff`
-- `npx myte@latest update-team "Backend deploy completed; QAQC rerun queued."`
-- `npx myte@latest update-owner --subject "QAQC progress" --body-file ./updates/owner.md`
-- `npx myte@latest update-client --subject "Weekly client update" --body-file ./updates/week-12.md`
-- `npm install myte` then `npx myte create-prd ./drafts/auth-prd.md`
-- `npm install myte` then `npx myte create-prd ./drafts/auth-prd.md ./drafts/billing-prd.md`
-- `cat ./drafts/auth-prd.md | npx myte create-prd --stdin`
+Most users should install the public wrapper instead:
 
-Requirements:
-- Node `18+`
-- macOS, Linux, or Windows
-- `git` in `PATH` for `--with-diff`
-- `MYTEAI_API_KEY=<inference_api_key>` in env or `.env` for `myte ai`
-- `MYTE_API_KEY=<project_api_key>` in env or `.env`
-- repo folder names must match the project repo names configured in Myte, including casing on case-sensitive filesystems
+- `npm install myte`
+- run with `npx myte ...`
 
-Notes:
-- `npm install myte` installs the wrapper locally; use `npx myte` or `npm exec myte -- ...` to run it.
-- `npm install myte` means the CLI is available locally; bare `myte ...` still requires a global install.
-- `bootstrap` is a local file materialization path, not a hosted file download.
-- `bootstrap` expects to run from a wrapper root that contains the project's configured repo folders.
-- `bootstrap` writes `MyteCommandCenter/data/project.yml` plus itemized `phases`, `epics`, `stories`, and `missions`.
-- `bootstrap` materializes a public Command Center DTO, not raw backend documents.
-- `bootstrap` mission cards now include richer execution context like `complexity`, `estimated_hours`, `due_date`, `subtasks`, `technical_requirements`, `resources_needed`, `labels`, and normalized `test_cases`.
-- `bootstrap` excludes internal keys like `_id`, `org_id`, `project_id`, `created_by`, `assigned_to`, and raw `qa_qc_results`.
-- rerunning current commands on an older workspace automatically prunes legacy artifacts like `bootstrap-manifest.json`, `data/qaqc/`, and `data/feedback/` as the new files are written.
-- `run-qaqc` queues QAQC for up to 10 explicit mission ids through `/api/project-assistant/run-qaqc`.
-- On PowerShell, quote comma-separated multi-id values: `--mission-ids "M001,M002"`.
-- `run-qaqc --wait` polls `/api/project-assistant/run-qaqc/<batch_id>` until the batch is terminal.
-- `run-qaqc --sync` refreshes `MyteCommandCenter/data/qaqc.yml` after a completed batch.
-- `mission status` updates one or many mission business ids through `/api/project-assistant/mission-status-update`.
-- `mission status` normalizes status aliases like `todo`, `in_progress`, and `done`, then sends the canonical mission status values `Todo`, `In Progress`, or `Done`.
-- `mission status` updates only the mission `status` field used by the app. It does not run QAQC and it does not rewrite `MyteCommandCenter/data/qaqc.yml`.
-- project-key QAQC runs through the dedicated `project_api_qaqc` queue inside the existing Celery service, with a global budget of `20` dispatch starts/minute and `20` live jobs.
-- a saturated `run-qaqc --wait` batch can take roughly `5-10` minutes before `--sync` has final data to write.
-- `sync-qaqc` works without `bootstrap`; it creates `MyteCommandCenter/data/qaqc.yml` automatically if missing.
-- `sync-qaqc` writes the active mission QAQC working set to `MyteCommandCenter/data/qaqc.yml`.
-- `sync-qaqc` only exports active `Todo` / `In Progress` missions plus a public QAQC summary and sanitized latest batch metadata.
-- `sync-qaqc` keeps QAQC state in one deterministic file so the working set grows and shrinks with current active-mission reality.
-- `sync-qaqc` fully rewrites `MyteCommandCenter/data/qaqc.yml` on every sync and does not delete `MyteCommandCenter/data/missions/*.yml`.
-- `feedback-sync` writes one deterministic feedback snapshot under `MyteCommandCenter/data/feedback.yml`.
-- `feedback-sync` defaults to pending feedback unless `--status` is provided.
-- `feedback-sync` keeps feedback metadata plus comment turns in `MyteCommandCenter/data/feedback.yml`.
-- `feedback-sync` writes full PRD context into `MyteCommandCenter/PRD/feedback-sync/*.md` and points to those files from `feedback.yml`.
-- `feedback-sync` fully replaces the feedback-owned sync file to avoid stale local feedback noise.
-- `feedback-sync` fully rewrites `MyteCommandCenter/data/feedback.yml` on every sync and does not delete `MyteCommandCenter/data/missions/*.yml`.
-- `suggestions sync` writes one merge-safe workflow file at `MyteCommandCenter/data/mission-ops.yml`.
-- `suggestions sync` should be the first step before ideating locally so new submissions start from the latest aggregated thread state.
-- `suggestions sync` rewrites the canonical synced state into `threads[]` and preserves top-level `workspace.<actor_scope>` blocks plus per-thread `workspace.<actor_scope>` drafts from the existing file.
-- synced `threads[]` include aggregate diffs, conflict summaries, and archived decision lineage so local agents do not need to reconstruct review state.
-- `suggestions create` reads a structured file payload or local `workspace.<actor_scope>.draft_submissions[]` blocks from `mission-ops.yml`.
-- `suggestions revise` reads structured file payloads or local per-thread `workspace.<actor_scope>` drafts only when `draft_status` is `submit`, `ready`, or `pending_submit`.
-- `suggestions review` is owner-only, reads structured file payloads or local per-thread owner review intent, and refreshes `data/missions/*.yml` when approvals apply changes.
-- `suggestions review` requires an explicit `review_action` of `request_changes`, `approve`, or `reject`; there is no persisted save-draft review action.
-- suggestion notifications deep-link into the project Reviews workspace for the affected thread.
-- create/revise/review resync `mission-ops.yml` by default unless `--no-sync` is passed.
-- create/revise/review automatically send `X-Idempotency-Key` and a default `client_session_id` so retries stay deterministic and auditable.
-- `--print-context` prints the JSON payload that would be submitted for create/revise/review.
-- `mission-ops.yml` keeps synced thread lineage plus actor-local draft space in one file; terminal items fall out of `queue` after sync but remain in `threads[]`.
-- `create-prd` is the deterministic PRD upload path, not an LLM generation command.
-- `update-team` creates a project comment through `/api/project-assistant/project-comment`.
-- `update-owner` sends a direct owner email through `/api/project-assistant/update-owner`.
-- `update-owner` requires `--subject` plus body markdown from `--body-markdown`, `--body-file`, positional input, or `--stdin`.
-- `update-client` creates a client update draft through `/api/project-assistant/client-update-drafts`.
-- `update-client` requires `--subject` plus body markdown from `--body-markdown`, `--body-file`, positional input, or `--stdin`.
-- `update-client` accepts optional `--target-contact-id` repeats or `--target-contact-ids <id1,id2>`.
-- If no linked client contacts exist, the backend falls back to the project owner for internal projects.
-- `--with-diff` only searches repo folders whose names match the project repo names configured in Myte.
-- `--with-diff` includes per-repo diagnostics in `print-context` payload:
-  - missing repo directories
-  - per-repo errors (for example fetch or command failures)
-  - clean/no-change repo summaries
-- `--with-diff` query payload includes `diff_diagnostics` so backend/UI can report exactly why context may be missing.
+This package exists so the public wrapper can stay small and versioned cleanly. It is not the recommended public install target.
 
-Deterministic `create-prd` contract:
-- Required: `MYTE_API_KEY`, a PRD markdown body, and a title.
-- Accepts one file or many files per command. The CLI uses `/project-assistant/create-prd` for one item and automatically uses the batch upload path for multi-file requests.
-- Title source: `myte-kanban.title`, the first markdown `# Heading`, or `--title`.
-- Description source: `myte-kanban.description` or `--description`.
-- The markdown body (`prd_markdown`, or the body portion of `ticket_markdown`) is stored verbatim as PRD content and is what the backend uses to build the PRD DOCX.
-- Legacy `feedback_text` is still accepted for older payloads, but new callers should use `description`.
-- Optional structured fields: `priority`, `status`, `tags`, `assigned_user_email`, `assigned_user_id`, `due_date`, `repo_name`, `repo_id`, `preview_url`, `source`.
+## Requirements
 
-Examples:
-- `npx myte ai "Explain what this project does"`
-- `npx myte ai "Return a JSON object with risks and next_steps" --json-response`
-- `npx myte bootstrap`
-- `npx myte run-qaqc --mission-ids "M001,M002" --wait --sync`
-- `npx myte mission status --mission-ids "M001,M002" --status done`
-- `npx myte sync-qaqc`
-- `npx myte feedback-sync`
-- `npx myte suggestions sync`
-- `npx myte suggestions create --file ./changes/create.yml`
-- `npx myte suggestions create`
-- `npx myte suggestions revise`
-- `npx myte suggestions review`
-- `npx myte bootstrap --dry-run --json`
-- `npx myte sync-qaqc --dry-run --json`
-- `npx myte create-prd ./drafts/auth-prd.md --description "Short card summary"`
-- `npx myte create-prd ./drafts/auth-prd.md ./drafts/billing-prd.md`
-- `npx myte create-prd ./drafts/auth-prd.md --print-context`
-- `npx myte update-team "Backend deploy completed; QAQC rerun queued."`
-- `npx myte update-owner --subject "QAQC progress" --body-file ./updates/owner.md`
-- `npx myte update-client --subject "Weekly client update" --body-file ./updates/week-12.md`
+- Node `18+`
+- `MYTE_API_KEY` for project-scoped commands
+- `MYTEAI_API_KEY` for `myte ai`
+- `git` only when using `query --with-diff`
 
-This package is published under the org scope for governance; the public `myte` wrapper delegates here.
+## Behavior Summary
 
-`--json-response` sends both the Myte convenience flag (`myte_json_response: true`) and the OpenAI-compatible chat-completions shape (`response_format: { type: "json_object" }`). On the public developer API, that strict-JSON path also defaults to `medium` reasoning unless the caller explicitly overrides reasoning.
+- Snapshot-style commands such as `bootstrap`, `sync-qaqc`, `feedback-sync`, and `suggestions sync` write local `MyteCommandCenter` data.
+- `query --with-diff` requires project repos to be configured for diff collection and fails fast when no matching local project repo can be resolved.
+- Public package documentation is intentionally minimal. Internal rollout and design notes are not part of the npm package contract.

package/cli.js

@@ -4,7 +4,7 @@
  *
  * - Auth: MYTE_API_KEY (project key) from `.env` or env
  * - Default API: https://api.myte.dev (override with MYTE_API_BASE or --base-url)
- * - Deterministic diffs: fetch /api/project-assistant/config to get repo folder names
+ * - Deterministic diffs: fetch project config, resolve local project repos, then collect scoped git context
  */
 
 const fs = require("fs");
@@ -194,7 +194,7 @@ function parseArgs(argv) {
 
 function printHelp() {
   const text = [
-    "myte - Myte Project Assistant CLI",
+    "myte - Myte CLI",
     "",
     "Usage:",
     "  myte query \"<text>\" [--with-diff] [--context \"...\"]",
@@ -232,13 +232,13 @@ function printHelp() {
     "  - Set MYTEAI_API_KEY in a workspace .env (or env var) for `myte ai`",
     "",
     "bootstrap contract:",
-    "  - Run from the wrapper root that contains the project's configured repo folders",
+    "  - Run from any workspace where you want local MyteCommandCenter data written",
     "  - Writes MyteCommandCenter/data/project.yml plus phases, epics, stories, and missions locally",
     "  - Uses the project-scoped bootstrap snapshot from the Myte API",
     "  - Mission cards include richer execution context like complexity, estimated_hours, due_date, subtasks, technical_requirements, resources_needed, labels, and normalized test_cases",
     "",
     "sync-qaqc contract:",
-    "  - Run from the wrapper root that contains the project's configured repo folders",
+    "  - Run from any workspace where you want local MyteCommandCenter data written",
     "  - Works even if bootstrap has not been run yet; it creates MyteCommandCenter/data/qaqc.yml",
     "  - Writes the active mission QAQC working set into one deterministic file: MyteCommandCenter/data/qaqc.yml",
     "",
@@ -285,13 +285,13 @@ function printHelp() {
     "  - If the project has no linked client contacts, the backend falls back to the project owner for internal projects",
     "",
     "feedback-sync contract:",
-    "  - Runs from the wrapper root that contains the project's configured repo folders",
+    "  - Runs from any workspace where you want local MyteCommandCenter data written",
     "  - Syncs pending feedback by default so local Command Center data stays focused on active work",
     "  - 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",
     "",
     "Options:",
-    "  --with-diff           Include deterministic git diffs (project-scoped)",
+    "  --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: 200000)",
     "  --timeout-ms <ms>     Request timeout (default: 300000)",
     "  --base-url <url>      API base (default: https://api.myte.dev)",
@@ -299,7 +299,7 @@ function printHelp() {
     "  --json-response       Ask the Myte AI gateway to return clean JSON only and send OpenAI-compatible response_format",
     "  --max-output-tokens   Output token cap for `myte ai` simple queries",
     "  --temperature <num>   Temperature for `myte ai` simple queries",
-    "  --output-dir <path>   Command Center output directory (default: <wrapper-root>/MyteCommandCenter)",
+    "  --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",
@@ -589,18 +589,25 @@ function summarizeDiffDiagnosticsForContext(diagnostics) {
     project_id: diagnostics.project_id || null,
     mode: diagnostics.mode,
     requested_repos: diagnostics.requested_repo_names || [],
+    requested_repo_bindings: diagnostics.requested_repo_bindings || [],
     found_repos: diagnostics.found_repos || [],
     missing_repos: diagnostics.missing_repos || [],
     collected_any: Boolean(diagnostics.collected_any),
     truncation: diagnostics.truncated ? "truncated" : "full",
     repos: repos.map((repo) => ({
       name: repo.name,
+      role: repo.role || null,
       status: repo.status || "ok",
       head_branch: repo.head_branch || null,
       base_ref: repo.base_ref || null,
+      base_ref_label: repo.base_ref_label || repo.base_ref || null,
+      baseline_branch: repo.baseline_branch || null,
+      compare_mode: repo.compare_mode || "local_origin",
+      compare_remote_url: repo.compare_remote_url || null,
       has_changes: Boolean(repo.has_changes),
       changed_blocks: repo.changed_blocks || {},
       untracked_file_count: repo.untracked_file_count || 0,
+      matched_by: repo.matched_by || [],
       error_count: Array.isArray(repo.errors) ? repo.errors.length : 0,
     })),
     warnings: diagnostics.warnings || [],
@@ -642,8 +649,29 @@ const IGNORED_PATTERNS = [
   /^out\//,
 ];
 
+const DIFF_MARKDOWN_ALLOWLIST = new Set([
+  "README.md",
+  "AGENTS.md",
+  "CodexContext.MD",
+  "CLAUDE.md",
+  "GEMINI.md",
+]);
+
+function normalizeRepoPathForDiff(p) {
+  return String(p || "").replace(/\\/g, "/");
+}
+
+function shouldIgnoreMarkdownPath(p) {
+  const normalized = normalizeRepoPathForDiff(p);
+  if (!/\.md$/i.test(normalized)) return false;
+  const base = path.posix.basename(normalized);
+  return !DIFF_MARKDOWN_ALLOWLIST.has(base);
+}
+
 function shouldIgnore(p) {
-  return IGNORED_PATTERNS.some((re) => re.test(p));
+  const normalized = normalizeRepoPathForDiff(p);
+  if (shouldIgnoreMarkdownPath(normalized)) return true;
+  return IGNORED_PATTERNS.some((re) => re.test(normalized));
 }
 
 function hasGitDir(repoPath) {
@@ -833,12 +861,359 @@ function resolveConfiguredRepos(repoNames) {
   return { mode: "none", root: null, repos: [], missing: names };
 }
 
-function fetchBaseBranches(repoPath) {
+function findGitTopLevel(startPath) {
+  const result = runGitRaw(startPath, ["rev-parse", "--show-toplevel"]);
+  if (!result.ok) return null;
+  const value = String(result.stdout || "").trim();
+  return value || null;
+}
+
+function normalizeRemoteFingerprint(value) {
+  const raw = String(value || "").trim();
+  if (!raw) return "";
+
+  const cleaned = raw.replace(/\\/g, "/").replace(/\.git$/i, "");
+  const looksLikeLocalPath =
+    !cleaned.includes("://") &&
+    (/^[a-zA-Z]:\//.test(cleaned) || cleaned.startsWith("/") || cleaned.startsWith("./") || cleaned.startsWith("../"));
+  if (looksLikeLocalPath) {
+    return `local/${cleaned.toLowerCase()}`;
+  }
+  const sshMatch = cleaned.match(/^(?:.+@)?([^:/]+)[:/](.+)$/);
+  if (!cleaned.includes("://") && sshMatch) {
+    const host = String(sshMatch[1] || "").trim().toLowerCase();
+    const repoPath = String(sshMatch[2] || "")
+      .trim()
+      .replace(/^\/+/, "")
+      .replace(/\/+$/, "")
+      .toLowerCase();
+    return host && repoPath ? `${host}/${repoPath}` : "";
+  }
+
+  try {
+    const parsed = new URL(cleaned);
+    const host = String(parsed.hostname || "").trim().toLowerCase();
+    const repoPath = String(parsed.pathname || "")
+      .trim()
+      .replace(/^\/+/, "")
+      .replace(/\/+$/, "")
+      .toLowerCase();
+    return host && repoPath ? `${host}/${repoPath}` : "";
+  } catch {
+    return cleaned.toLowerCase();
+  }
+}
+
+function uniqueNormalizedStrings(values) {
+  const seen = new Set();
+  const ordered = [];
+  for (const value of Array.isArray(values) ? values : []) {
+    const text = String(value || "").trim();
+    if (!text) continue;
+    const key = text.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    ordered.push(text);
+  }
+  return ordered;
+}
+
+function normalizeRepoBindingEntry(binding, index = 0) {
+  if (!binding || typeof binding !== "object") return null;
+
+  const role = String(binding.role || "").trim().toLowerCase();
+  const canonicalRepoName = String(binding.canonical_repo_name || "").trim();
+  const canonicalRemoteUrl = String(binding.canonical_remote_url || "").trim();
+  const clientRepoName = String(binding.client_repo_name || "").trim();
+  const clientRemoteUrl = String(binding.client_remote_url || "").trim();
+  const localRepoAliases = uniqueNormalizedStrings(binding.local_repo_aliases || []);
+  const baselineBranch = String(binding.baseline_branch || "").trim();
+
+  const remoteFingerprints = uniqueNormalizedStrings([
+    ...(Array.isArray(binding.remote_fingerprints) ? binding.remote_fingerprints : []),
+    normalizeRemoteFingerprint(canonicalRemoteUrl),
+    normalizeRemoteFingerprint(clientRemoteUrl),
+  ]);
+
+  const matchingNames = uniqueNormalizedStrings([
+    ...(Array.isArray(binding.matching_names) ? binding.matching_names : []),
+    canonicalRepoName,
+    clientRepoName,
+    ...localRepoAliases,
+  ]);
+
+  if (!role && !matchingNames.length && !remoteFingerprints.length) return null;
+
+  return {
+    role: role || `repo_${index + 1}`,
+    canonical_repo_name: canonicalRepoName || null,
+    canonical_remote_url: canonicalRemoteUrl || null,
+    client_repo_name: clientRepoName || null,
+    client_remote_url: clientRemoteUrl || null,
+    local_repo_aliases: localRepoAliases,
+    baseline_branch: baselineBranch || null,
+    matching_names: matchingNames,
+    remote_fingerprints: remoteFingerprints,
+  };
+}
+
+function normalizeRepoBindings(bindings) {
+  const normalized = [];
+  const seenRoles = new Set();
+  for (const [index, binding] of (Array.isArray(bindings) ? bindings : []).entries()) {
+    const item = normalizeRepoBindingEntry(binding, index);
+    if (!item) continue;
+    const roleKey = String(item.role || "").trim().toLowerCase();
+    if (seenRoles.has(roleKey)) continue;
+    seenRoles.add(roleKey);
+    normalized.push(item);
+  }
+  return normalized;
+}
+
+function getRepoRemoteFingerprints(repoPath) {
+  const output = runGitTry(repoPath, ["remote", "-v"]);
+  if (!output) return [];
+  const fingerprints = [];
+  for (const line of String(output).split(/\r?\n/)) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 2) continue;
+    const normalized = normalizeRemoteFingerprint(parts[1]);
+    if (normalized) fingerprints.push(normalized);
+  }
+  return uniqueNormalizedStrings(fingerprints);
+}
+
+function listGitRepoCandidates(searchRoot, currentRepoRoot) {
+  const candidates = [];
+  const seen = new Set();
+
+  function pushCandidate(absPath, rootForDir) {
+    const abs = path.resolve(absPath);
+    if (!hasGitDir(abs) || seen.has(abs)) return;
+    seen.add(abs);
+    const rootBase = rootForDir ? path.resolve(rootForDir) : path.dirname(abs);
+    const rel = path.relative(rootBase, abs);
+    const dir = rel && rel !== "" ? rel : ".";
+    const repoName = path.basename(abs);
+    candidates.push({
+      abs,
+      dir,
+      name: repoName,
+      prefix: `${repoName.replace(/\\\\/g, "/")}/`,
+      remote_fingerprints: getRepoRemoteFingerprints(abs),
+      is_current_repo: currentRepoRoot ? path.resolve(currentRepoRoot) === abs : false,
+    });
+  }
+
+  if (currentRepoRoot) {
+    pushCandidate(currentRepoRoot, path.dirname(currentRepoRoot));
+  }
+
+  pushCandidate(searchRoot, path.dirname(searchRoot));
+
+  let entries = [];
+  try {
+    entries = fs.readdirSync(searchRoot, { withFileTypes: true });
+  } catch {
+    entries = [];
+  }
+  for (const entry of entries) {
+    if (!entry || !entry.isDirectory || !entry.isDirectory()) continue;
+    const abs = path.join(searchRoot, entry.name);
+    pushCandidate(abs, searchRoot);
+  }
+
+  return candidates;
+}
+
+function scoreBindingCandidate(binding, candidate) {
+  const candidateName = String(candidate?.name || "").trim().toLowerCase();
+  const bindingNames = new Set((binding?.matching_names || []).map((name) => String(name || "").trim().toLowerCase()).filter(Boolean));
+  const bindingRemotes = new Set((binding?.remote_fingerprints || []).map((value) => String(value || "").trim().toLowerCase()).filter(Boolean));
+  const candidateRemotes = new Set((candidate?.remote_fingerprints || []).map((value) => String(value || "").trim().toLowerCase()).filter(Boolean));
+  const canonicalRemoteFingerprint = normalizeRemoteFingerprint(binding?.canonical_remote_url).toLowerCase();
+  const clientRemoteFingerprint = normalizeRemoteFingerprint(binding?.client_remote_url).toLowerCase();
+
+  let score = 0;
+  const matchedBy = [];
+
+  if (binding.canonical_repo_name && candidateName === String(binding.canonical_repo_name).trim().toLowerCase()) {
+    score = Math.max(score, 240);
+    matchedBy.push("canonical_name");
+  }
+  if (binding.client_repo_name && candidateName === String(binding.client_repo_name).trim().toLowerCase()) {
+    score = Math.max(score, 260);
+    matchedBy.push("client_name");
+  }
+  if (bindingNames.has(candidateName)) {
+    score = Math.max(score, 200);
+    matchedBy.push("alias");
+  }
+  for (const remote of candidateRemotes) {
+    if (clientRemoteFingerprint && remote === clientRemoteFingerprint) {
+      score = Math.max(score, 340);
+      matchedBy.push("client_remote");
+      break;
+    }
+    if (canonicalRemoteFingerprint && remote === canonicalRemoteFingerprint) {
+      score = Math.max(score, 300);
+      matchedBy.push("canonical_remote");
+      break;
+    }
+    if (bindingRemotes.has(remote)) {
+      score = Math.max(score, 320);
+      matchedBy.push("remote");
+      break;
+    }
+  }
+
+  return { score, matchedBy: uniqueNormalizedStrings(matchedBy) };
+}
+
+function resolveConfiguredRepoBindings(bindings) {
+  const normalizedBindings = normalizeRepoBindings(bindings);
+  if (!normalizedBindings.length) {
+    return { mode: "none", root: null, repos: [], missing: [], bindings: [] };
+  }
+
+  const cwd = process.cwd();
+  const currentRepoRoot = findGitTopLevel(cwd);
+  const scanStart = currentRepoRoot ? path.dirname(currentRepoRoot) : cwd;
+
+  const ancestors = [];
+  let cur = scanStart;
+  for (let i = 0; i < 8; i += 1) {
+    ancestors.push(cur);
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+
+  let fallbackCandidates = currentRepoRoot ? listGitRepoCandidates(path.dirname(currentRepoRoot), currentRepoRoot) : [];
+  let fallbackRoot = currentRepoRoot ? path.dirname(currentRepoRoot) : null;
+
+  for (const candidateRoot of ancestors) {
+    const candidates = listGitRepoCandidates(candidateRoot, currentRepoRoot);
+    if (!fallbackCandidates.length && candidates.length) {
+      fallbackCandidates = candidates;
+      fallbackRoot = candidateRoot;
+    }
+
+    const assigned = new Set();
+    const found = [];
+    for (const binding of normalizedBindings) {
+      let best = null;
+      for (const candidate of candidates) {
+        if (assigned.has(candidate.abs)) continue;
+        const match = scoreBindingCandidate(binding, candidate);
+        if (!match.score) continue;
+        if (!best || match.score > best.match.score) {
+          best = { candidate, match };
+        }
+      }
+      if (!best) continue;
+      assigned.add(best.candidate.abs);
+      found.push({
+        name: best.candidate.name,
+        dir: best.candidate.dir,
+        abs: best.candidate.abs,
+        prefix: best.candidate.prefix,
+        role: binding.role,
+        canonical_repo_name: binding.canonical_repo_name,
+        canonical_remote_url: binding.canonical_remote_url,
+        client_repo_name: binding.client_repo_name,
+        client_remote_url: binding.client_remote_url,
+        baseline_branch: binding.baseline_branch || null,
+        matched_by: best.match.matchedBy,
+        remote_fingerprints: best.candidate.remote_fingerprints,
+      });
+    }
+
+    if (found.length) {
+      const foundRoles = new Set(found.map((repo) => repo.role));
+      const missing = normalizedBindings
+        .filter((binding) => !foundRoles.has(binding.role))
+        .map((binding) => binding.client_repo_name || binding.canonical_repo_name || binding.role);
+      return {
+        mode: currentRepoRoot && found.length === 1 && found[0].abs === currentRepoRoot ? "repo" : "workspace",
+        root: candidateRoot,
+        repos: found,
+        missing,
+        bindings: normalizedBindings,
+      };
+    }
+  }
+
+  return {
+    mode: currentRepoRoot ? "repo" : "none",
+    root: fallbackRoot,
+    repos: [],
+    missing: normalizedBindings.map((binding) => binding.client_repo_name || binding.canonical_repo_name || binding.role),
+    bindings: normalizedBindings,
+  };
+}
+
+function fetchBaseBranches(repoPath, preferredBranch) {
+  const preferred = String(preferredBranch || "").trim();
+  if (preferred && runGitOk(repoPath, ["fetch", "origin", preferred, "--prune", "--quiet"])) return true;
   if (runGitOk(repoPath, ["fetch", "origin", "main", "master", "--prune", "--quiet"])) return true;
   return runGitOk(repoPath, ["fetch", "--all", "--prune", "--quiet"]);
 }
 
-function resolveBaseRef(repoPath) {
+function buildExternalBaseRefName(remoteUrl, branch) {
+  const branchSlug = String(branch || "main")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "main";
+  const digest = createHash("sha1")
+    .update(`${String(remoteUrl || "").trim()}::${branchSlug}`)
+    .digest("hex")
+    .slice(0, 12);
+  return `refs/myte/bases/${branchSlug}-${digest}`;
+}
+
+function fetchExternalBaseRef(repoPath, remoteUrl, preferredBranch) {
+  const remote = String(remoteUrl || "").trim();
+  if (!remote) return null;
+
+  const candidateBranches = uniqueNormalizedStrings([preferredBranch, "main", "master"]);
+  for (const branch of candidateBranches) {
+    const refName = buildExternalBaseRefName(remote, branch);
+    if (runGitOk(repoPath, ["fetch", "--quiet", "--no-tags", remote, `${branch}:${refName}`])) {
+      return { ref: refName, branch };
+    }
+  }
+  return null;
+}
+
+function resolveExternalCompareRemoteUrl(repo) {
+  const canonicalRemoteUrl = String(repo?.canonical_remote_url || "").trim();
+  const clientRemoteUrl = String(repo?.client_remote_url || "").trim();
+  if (!canonicalRemoteUrl || !clientRemoteUrl) return null;
+
+  const canonicalFingerprint = normalizeRemoteFingerprint(canonicalRemoteUrl);
+  const clientFingerprint = normalizeRemoteFingerprint(clientRemoteUrl);
+  if (!canonicalFingerprint || !clientFingerprint || canonicalFingerprint === clientFingerprint) return null;
+
+  const candidateFingerprints = new Set(
+    (Array.isArray(repo?.remote_fingerprints) ? repo.remote_fingerprints : [])
+      .map((value) => String(value || "").trim().toLowerCase())
+      .filter(Boolean)
+  );
+  if (!candidateFingerprints.has(clientFingerprint.toLowerCase())) return null;
+  if (candidateFingerprints.has(canonicalFingerprint.toLowerCase())) return null;
+
+  return canonicalRemoteUrl;
+}
+
+function resolveBaseRef(repoPath, preferredBranch) {
+  const preferred = String(preferredBranch || "").trim();
+  if (preferred) {
+    if (runGitOk(repoPath, ["rev-parse", "--verify", `refs/remotes/origin/${preferred}`])) return `origin/${preferred}`;
+    if (runGitOk(repoPath, ["rev-parse", "--verify", `refs/heads/${preferred}`])) return preferred;
+  }
   if (runGitOk(repoPath, ["rev-parse", "--verify", "refs/remotes/origin/main"])) return "origin/main";
   if (runGitOk(repoPath, ["rev-parse", "--verify", "refs/remotes/origin/master"])) return "origin/master";
   if (runGitOk(repoPath, ["rev-parse", "--verify", "refs/heads/main"])) return "main";
@@ -849,13 +1224,24 @@ function resolveBaseRef(repoPath) {
 function collectGitDiffWithDiagnostics({
   projectId,
   repoNames,
+  repoBindings,
   maxChars,
   fetchRemote = true,
 } = {}) {
   const configuredRepos = Array.isArray(repoNames) ? repoNames.map(String).map((s) => s.trim()).filter(Boolean) : [];
+  const configuredBindings = normalizeRepoBindings(repoBindings);
   const diagnostics = {
     project_id: projectId || null,
     requested_repo_names: configuredRepos,
+    requested_repo_bindings: configuredBindings.map((binding) => ({
+      role: binding.role,
+      canonical_repo_name: binding.canonical_repo_name,
+      canonical_remote_url: binding.canonical_remote_url,
+      client_repo_name: binding.client_repo_name,
+      client_remote_url: binding.client_remote_url,
+      local_repo_aliases: binding.local_repo_aliases,
+      baseline_branch: binding.baseline_branch,
+    })),
     fetch_remote: Boolean(fetchRemote),
     mode: "none",
     search_root: null,
@@ -870,7 +1256,9 @@ function collectGitDiffWithDiagnostics({
   };
 
   try {
-    const resolved = resolveConfiguredRepos(configuredRepos);
+    const resolved = configuredBindings.length
+      ? resolveConfiguredRepoBindings(configuredBindings)
+      : resolveConfiguredRepos(configuredRepos);
     diagnostics.mode = resolved.mode || "none";
     diagnostics.search_root = resolved.root || null;
     diagnostics.found_repos = (resolved.repos || []).map((r) => r.name);
@@ -888,7 +1276,15 @@ function collectGitDiffWithDiagnostics({
     const sections = [];
     if (projectId) sections.push(`# Project: ${projectId}`);
     sections.push(`# Mode: ${resolved.mode}`);
-    sections.push(`# Configured repos: ${configuredRepos.join(", ") || ""}`);
+    if (configuredBindings.length) {
+      sections.push(
+        `# Configured repo bindings: ${configuredBindings
+          .map((binding) => `${binding.role}=${binding.client_repo_name || binding.canonical_repo_name || binding.role}`)
+          .join(", ")}`
+      );
+    } else {
+      sections.push(`# Configured repos: ${configuredRepos.join(", ") || ""}`);
+    }
     if (resolved.missing && resolved.missing.length) {
       sections.push(`# Missing locally (skipped): ${resolved.missing.join(", ")}`);
     }
@@ -900,8 +1296,12 @@ function collectGitDiffWithDiagnostics({
         dir: repo.dir || ".",
         root: repo.abs,
         status: "ok",
+        role: repo.role || null,
         head_branch: null,
         base_ref: null,
+        base_ref_label: null,
+        compare_mode: "local_origin",
+        compare_remote_url: null,
         has_changes: false,
         changed_blocks: {
           base_vs_head: false,
@@ -914,22 +1314,55 @@ function collectGitDiffWithDiagnostics({
       };
 
       const { name, dir, abs, prefix } = repo;
-      const fetchDiag = { attempted: false, ok: false, message: "" };
+      const externalCompareRemoteUrl = resolveExternalCompareRemoteUrl(repo);
+      const fetchDiag = {
+        attempted: false,
+        ok: false,
+        message: "",
+        compare_mode: externalCompareRemoteUrl ? "external_remote" : "local_origin",
+        compare_remote_url: externalCompareRemoteUrl || null,
+      };
+      let baseRef = null;
+      let baseRefLabel = null;
       if (fetchRemote) {
         fetchDiag.attempted = true;
-        fetchDiag.ok = fetchBaseBranches(abs);
-        if (!fetchDiag.ok) {
-          fetchDiag.message = "failed to refresh origin main/master";
-          repoSummary.errors.push(fetchDiag.message);
-          diagnostics.warnings.push(`Repo "${name}": ${fetchDiag.message}`);
+        if (externalCompareRemoteUrl) {
+          const externalBase = fetchExternalBaseRef(abs, externalCompareRemoteUrl, repo.baseline_branch);
+          fetchDiag.ok = Boolean(externalBase?.ref);
+          if (externalBase?.ref) {
+            baseRef = externalBase.ref;
+            baseRefLabel = `${externalBase.branch}@canonical`;
+          } else {
+            fetchDiag.message = `failed to refresh canonical compare branch from ${externalCompareRemoteUrl}`;
+            repoSummary.errors.push(fetchDiag.message);
+            diagnostics.warnings.push(`Repo "${name}": ${fetchDiag.message}`);
+          }
+        } else {
+          fetchDiag.ok = fetchBaseBranches(abs, repo.baseline_branch);
+          if (!fetchDiag.ok) {
+            fetchDiag.message = "failed to refresh origin main/master";
+            repoSummary.errors.push(fetchDiag.message);
+            diagnostics.warnings.push(`Repo "${name}": ${fetchDiag.message}`);
+          }
         }
       }
 
       const headBranch = runGitTry(abs, ["rev-parse", "--abbrev-ref", "HEAD"]) || "HEAD";
-      const baseRef = resolveBaseRef(abs);
+      if (!baseRef && !externalCompareRemoteUrl) {
+        baseRef = resolveBaseRef(abs, repo.baseline_branch);
+      }
       repoSummary.head_branch = headBranch;
       repoSummary.base_ref = baseRef || "base-unresolved";
+      repoSummary.base_ref_label = baseRefLabel || repoSummary.base_ref;
       repoSummary.fetch = fetchDiag;
+      repoSummary.compare_mode = fetchDiag.compare_mode;
+      repoSummary.compare_remote_url = fetchDiag.compare_remote_url;
+      if (repo.matched_by) repoSummary.matched_by = repo.matched_by;
+      if (repo.baseline_branch) repoSummary.baseline_branch = repo.baseline_branch;
+      if (repo.canonical_repo_name) repoSummary.canonical_repo_name = repo.canonical_repo_name;
+      if (repo.canonical_remote_url) repoSummary.canonical_remote_url = repo.canonical_remote_url;
+      if (repo.client_repo_name) repoSummary.client_repo_name = repo.client_repo_name;
+      if (repo.client_remote_url) repoSummary.client_remote_url = repo.client_remote_url;
 
       let baseDiff = "";
       if (baseRef) {
@@ -999,8 +1432,16 @@ function collectGitDiffWithDiagnostics({
         repoSummary.status = "partial";
       }
 
-      let section = `### ${name} (${dir || "."})\n\n`;
-      section += `# ?? Base vs HEAD (${repoSummary.base_ref}...HEAD | head=${headBranch})\n`;
+      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`;
@@ -1469,7 +1910,7 @@ async function runRunQaqc(args) {
 
       let resolved;
       try {
-        resolved = resolveBootstrapWorkspace(snapshot.repo_names || []);
+        resolved = resolvePortableWorkspace(snapshot.repo_names || []);
       } catch (err) {
         console.error(err?.message || err);
         process.exit(1);
@@ -2063,6 +2504,20 @@ function resolveBootstrapWorkspace(repoNames) {
   return resolved;
 }
 
+function resolvePortableWorkspace(repoNames) {
+  const configured = Array.isArray(repoNames) ? repoNames.map(String).map((s) => s.trim()).filter(Boolean) : [];
+  const resolved = resolveConfiguredRepos(configured);
+  if (resolved.root) {
+    return resolved;
+  }
+  return {
+    mode: "cwd",
+    root: process.cwd(),
+    repos: [],
+    missing: configured,
+  };
+}
+
 function resolveCommandCenterRoots(wrapperRoot, outputDir) {
   const targetRoot = outputDir
     ? path.resolve(process.cwd(), String(outputDir))
@@ -2545,7 +3000,7 @@ async function resolveSuggestionsOutputContext({ args, key, apiBase, timeoutMs,
   const repoNames = Array.isArray(snapshot?.repo_names) && snapshot.repo_names.length
     ? snapshot.repo_names
     : (await fetchProjectConfig({ apiBase, key, timeoutMs })).repo_names || [];
-  const resolved = resolveBootstrapWorkspace(repoNames);
+  const resolved = resolvePortableWorkspace(repoNames);
   return {
     wrapperRoot: resolved.root,
     targetRoot: path.join(resolved.root, "MyteCommandCenter"),
@@ -3155,11 +3610,15 @@ async function runConfig(args) {
   }
 
   const repoNames = Array.isArray(cfg.repo_names) ? cfg.repo_names : [];
-  const resolved = resolveConfiguredRepos(repoNames);
+  const repoBindings = Array.isArray(cfg.repo_bindings) ? cfg.repo_bindings : [];
+  const resolved = repoBindings.length
+    ? resolveConfiguredRepoBindings(repoBindings)
+    : resolveConfiguredRepos(repoNames);
   const payload = {
     api_base: apiBase,
     project_id: cfg.project_id,
     repo_names: repoNames,
+    repo_bindings: repoBindings,
     local: {
       mode: resolved.mode,
       root: resolved.root,
@@ -3174,6 +3633,13 @@ async function runConfig(args) {
     console.log(`Project: ${payload.project_id || "(unknown)"}`);
     console.log(`API base: ${payload.api_base}`);
     console.log(`Configured repos: ${repoNames.join(", ") || "(none)"}`);
+    if (repoBindings.length) {
+      console.log(
+        `Repo bindings: ${repoBindings
+          .map((binding) => `${binding.role}=${binding.client_repo_name || binding.canonical_repo_name || binding.role}`)
+          .join(", ")}`
+      );
+    }
     console.log(`Local mode: ${payload.local.mode}`);
     if (payload.local.found.length) console.log(`Found locally: ${payload.local.found.join(", ")}`);
     if (payload.local.missing.length) console.log(`Missing locally: ${payload.local.missing.join(", ")}`);
@@ -3209,7 +3675,7 @@ async function runBootstrap(args) {
 
   let resolved;
   try {
-    resolved = resolveBootstrapWorkspace(snapshot.repo_names || []);
+    resolved = resolvePortableWorkspace(snapshot.repo_names || []);
   } catch (err) {
     console.error(err?.message || err);
     process.exit(1);
@@ -3303,7 +3769,7 @@ async function runSyncQaqc(args) {
 
   let resolved;
   try {
-    resolved = resolveBootstrapWorkspace(snapshot.repo_names || []);
+    resolved = resolvePortableWorkspace(snapshot.repo_names || []);
   } catch (err) {
     console.error(err?.message || err);
     process.exit(1);
@@ -3397,7 +3863,7 @@ async function runFeedbackSync(args) {
 
   let resolved;
   try {
-    resolved = resolveBootstrapWorkspace(snapshot.repo_names || []);
+    resolved = resolvePortableWorkspace(snapshot.repo_names || []);
   } catch (err) {
     console.error(err?.message || err);
     process.exit(1);
@@ -4037,30 +4503,41 @@ async function runQuery(args) {
     try {
       cfg = await fetchProjectConfig({ apiBase, key, timeoutMs });
     } catch (err) {
-      console.warn("Warning: project config unavailable for --with-diff. Continuing without diff context.");
-      console.warn(`Detail: ${err?.message || err}`);
-      cfg = null;
+      console.error("Failed to fetch project config for --with-diff:", err?.message || err);
+      process.exit(1);
     }
 
-    if (cfg) {
-      const repoNames = Array.isArray(cfg.repo_names) ? cfg.repo_names : [];
-      const diffResult = collectGitDiffWithDiagnostics({
-        projectId: cfg.project_id,
-        repoNames,
-        maxChars: diffLimit,
-        fetchRemote,
-      });
-      diffText = diffResult.text;
-      diffDiagnostics = diffResult.diagnostics;
-      if (diffDiagnostics?.errors?.length) {
-        for (const warning of diffDiagnostics.errors) console.warn(`Warning: ${warning}`);
-      }
-    } else {
-      diffText = "";
-      diffDiagnostics = null;
+    const repoNames = Array.isArray(cfg.repo_names) ? cfg.repo_names : [];
+    const repoBindings = Array.isArray(cfg.repo_bindings) ? cfg.repo_bindings : [];
+    if (!repoBindings.length && !repoNames.length) {
+      console.error("No project repositories are configured for --with-diff.");
+      console.error("Ask the project owner or builder to configure the project repos in Myte first.");
+      process.exit(1);
+    }
+
+    const diffResult = collectGitDiffWithDiagnostics({
+      projectId: cfg.project_id,
+      repoNames,
+      repoBindings,
+      maxChars: diffLimit,
+      fetchRemote,
+    });
+    diffText = diffResult.text;
+    diffDiagnostics = diffResult.diagnostics;
+    if (diffDiagnostics?.errors?.length) {
+      for (const warning of diffDiagnostics.errors) console.warn(`Warning: ${warning}`);
     }
-    if (!diffText) {
-      console.error("Warning: no diff context collected. Continuing without --with-diff context.");
+    if (!Array.isArray(diffDiagnostics?.found_repos) || !diffDiagnostics.found_repos.length) {
+      console.error("No configured project repos were found locally for --with-diff.");
+      const expectedBindings = Array.isArray(diffDiagnostics?.requested_repo_bindings)
+        ? diffDiagnostics.requested_repo_bindings
+            .map((binding) => binding.client_repo_name || binding.canonical_repo_name || binding.role)
+            .filter(Boolean)
+        : [];
+      const expected = expectedBindings.length ? expectedBindings : repoNames;
+      console.error(`Expected repo mapping or folder match for: ${expected.join(", ")}`);
+      console.error("Run `myte config --json` to inspect the configured repos and local resolution.");
+      process.exit(1);
     }
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mytegroupinc/myte-core",
-  "version": "0.0.19",
-  "description": "Myte CLI core implementation (Project Assistant + Myte AI gateway).",
+  "version": "0.0.20",
+  "description": "Myte CLI core implementation.",
   "type": "commonjs",
   "main": "cli.js",
   "files": [