@descix/cli 1.0.6 → 1.0.8

package/lib/core/ManifestLoader.js

@@ -13,6 +13,7 @@
  */
 
 import * as fs from 'fs/promises';
+import { statSync, realpathSync } from 'fs';
 import * as path from 'path';
 import { execFileSync } from 'child_process';
 // Canonical doc_class taxonomy lives in CorpusDenyLint — import it, never re-list.
@@ -110,6 +111,73 @@ export function detectRepoSlug(dir) {
   }
 }
 
+/**
+ * THE ONE OWNER OF "WHICH REPOSITORY OWNS THIS FILE".
+ *
+ * A workspace is NOT one repository. This one crosses three kinds of boundary at once:
+ * the superrepo itself; git SUBMODULES (DeSciX/DeSciX_Cloud|Core|Powch are gitlinks —
+ * `git ls-tree HEAD DeSciX/` shows mode 160000); and SIBLING repos that are not submodules
+ * at all but independent checkouts the superrepo deliberately ignores (EGPT-research via
+ * .gitignore:9, FRAQTL — each with its own `.git` and its own `origin` remote).
+ *
+ * A REF HAS NO MEANING EXCEPT RELATIVE TO A REPOSITORY. Resolving one against the ambient
+ * workspace root is what made this gate refuse 596 files that ARE committed: the superrepo
+ * sees a submodule only as a gitlink commit, and an ignored sibling repo not at all.
+ * `git rev-parse --show-toplevel` walks UP from the path and stops at the FIRST enclosing
+ * repository — which is precisely the repository whose branches the source's `ref` names,
+ * and which settles submodule and sibling boundaries with ONE mechanism rather than two.
+ *
+ * This is NOT the question `detectRepoSlug` answers. That one is "what is this repository
+ * CALLED" (for the cross-repo self-naming refusal); this one is "where does it BEGIN", so a
+ * ref and a repo-relative path can be formed. Both live here so repository identity has a
+ * single home and no consumer re-derives either.
+ *
+ * @param {string} absolutePath - absolute path to a file or directory in the workspace
+ * @returns {{repoRoot: string, repoRelativePath: string}|null} null when the path lies in
+ *          NO git repository at all — callers must fail loud, never assume a root.
+ */
+const OWNING_REPO_CACHE = new Map(); // real directory -> repoRoot. POSITIVE results only.
+export function resolveOwningRepo(absolutePath) {
+  const abs = path.resolve(absolutePath);
+  // `--show-toplevel` needs a directory that exists, and a source may name a file. Split
+  // off the basename ONLY for a non-directory: for a DIRECTORY source, `path.dirname` would
+  // step over the very boundary being resolved (dirname of `DeSciX/DeSciX_Cloud` is the
+  // superrepo, which is the wrong answer).
+  let dir = abs, base = null;
+  try {
+    if (!statSync(abs).isDirectory()) { dir = path.dirname(abs); base = path.basename(abs); }
+  } catch {
+    dir = path.dirname(abs); base = path.basename(abs);
+  }
+
+  // BOTH SIDES MUST BE REAL PATHS OR THE SUBTRACTION IS GARBAGE. `git rev-parse
+  // --show-toplevel` always answers with symlinks resolved, so comparing it against a
+  // caller path that still contains one yields a `../../..`-riddled relative path that
+  // matches nothing. This is not a corner case: on macOS every temp dir is /var ->
+  // /private/var, and this repo's own dev flow serves the Core tree through a symlink.
+  let realDir;
+  try { realDir = realpathSync(dir); } catch { realDir = dir; }
+
+  let repoRoot = OWNING_REPO_CACHE.get(realDir);
+  if (repoRoot === undefined) {
+    try {
+      repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+        cwd: realDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+    } catch {
+      return null; // No repository. NOT cached: a negative is not durable — the directory
+    }              //  may be `git init`-ed later in the same process (fixtures do exactly this).
+    if (!repoRoot) return null;
+    OWNING_REPO_CACHE.set(realDir, repoRoot);
+  }
+
+  const repoRelativeDir = path.relative(repoRoot, realDir);
+  return {
+    repoRoot,
+    repoRelativePath: base ? path.join(repoRelativeDir, base) : repoRelativeDir,
+  };
+}
+
 /**
  * Enforce the two-shape source contract on ONE source entry.
  *

package/lib/core/Syncer.js

@@ -25,6 +25,54 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { loadChunks } from './Chunker.js';
 
+/**
+ * THE ONE VALUE this CLI uses to mean "the store did not report a count".
+ *
+ * A receipt is derived from the STORE, never from the REQUEST. Where the store
+ * cannot report, we say so — we never substitute the number of things we ASKED
+ * to be changed, because that number is a description of our own request and
+ * carries no information about what happened.
+ *
+ * @type {number}
+ */
+export const UNREPORTED_COUNT = -1;
+
+/**
+ * Normalize a count the store returned into either that count or UNREPORTED_COUNT.
+ * This is the ONLY place the "did the store report a number?" decision is made.
+ *
+ * @param {*} value - the raw count field as it arrived from the store
+ * @returns {number} the store's count, or UNREPORTED_COUNT if it reported none
+ */
+export function reportedCount(value) {
+  return Number.isFinite(value) ? value : UNREPORTED_COUNT;
+}
+
+/**
+ * True when `value` is a count the store actually reported. Callers use this to
+ * choose between printing a number and printing "unknown" — never to fabricate one.
+ *
+ * @param {*} value
+ * @returns {boolean}
+ */
+export function isReportedCount(value) {
+  return Number.isFinite(value) && value >= 0;
+}
+
+/**
+ * Sum counts across batches while preserving unknown-ness: if ANY batch could not
+ * be reported, the total is not a number we can honestly state.
+ *
+ * @param {number} runningTotal - UNREPORTED_COUNT once any batch was unreportable
+ * @param {*} batchValue - the raw count field from this batch's store response
+ * @returns {number}
+ */
+export function accumulateReportedCount(runningTotal, batchValue) {
+  const next = reportedCount(batchValue);
+  if (!isReportedCount(runningTotal) || !isReportedCount(next)) return UNREPORTED_COUNT;
+  return runningTotal + next;
+}
+
 /**
  * Compute delta between local chunks and remote Pinecone records
  * Uses content_hash for efficient change detection when available.
@@ -73,39 +121,64 @@ export function computeChunkDelta(localChunks, remoteChunks) {
 }
 
 /**
- * Get existing chunk metadata from Pinecone (with content_hash for delta)
- * Falls back to IDs-only if metadata endpoint not available.
- * 
+ * Get existing chunk metadata from Pinecone (with content_hash for delta).
+ * Falls back to the IDs-only endpoint when the metadata endpoint is unavailable.
+ *
+ * An empty array means the STORE REPORTED an empty KB. It never means "we could
+ * not find out" — when neither endpoint can report, this THROWS naming both
+ * endpoints and both causes, because an unknown remote set presented as an empty
+ * one makes every caller conclude that nothing is stale.
+ *
  * @param {Object} apiClient - DeSciXApiClient instance
  * @param {string} communityId - Community ID
  * @param {string} appId - App ID
  * @param {string} kbId - Knowledge base ID
- * @returns {Promise<Array<{id: string, content_hash: string}>>} Chunk metadata
+ * @returns {Promise<Array<{id: string, content_hash: string}>|Array<string>>} Chunk
+ *          metadata, or plain chunk ids from the compatibility endpoint.
+ * @throws {Error} when neither endpoint reports the remote chunk set.
  */
 export async function getRemoteChunkMetadata(apiClient, communityId, appId, kbId) {
+  // A fallback is a COMPATIBILITY PATH, not an error handler: we fall back when
+  // the newer endpoint is absent, and we FAIL LOUD when neither can report.
+  // Returning [] here would present a transport failure as a store state
+  // ("remote is empty"), and every caller would then compute that nothing is
+  // stale and re-upsert everything — silently.
+  const failures = [];
+
   try {
-    // Try new metadata endpoint first
     const result = await apiClient.invoke('kb_get_chunk_metadata', {
       app_id: appId,
       kb_id: kbId
     });
     // apiClient.invoke returns { status, message: { chunks, count, ... } }
-    const data = result.message || result;
-    return data.chunks || [];
+    const data = result?.message || result;
+    // An empty ARRAY is the store reporting an empty KB — legal, and preserved.
+    // An ABSENT field is the store not reporting at all — not the same fact.
+    if (Array.isArray(data?.chunks)) return data.chunks;
+    failures.push("kb_get_chunk_metadata: response carried no 'chunks' array");
   } catch (error) {
-    // Fall back to IDs-only endpoint
-    try {
-      const result = await apiClient.invoke('kb_get_chunk_ids', {
-        app_id: appId,
-        kb_id: kbId
-      });
-      // apiClient.invoke returns { status, message: { chunk_ids, count, ... } }
-      const data = result.message || result;
-      return data.chunk_ids || [];
-    } catch {
-      return [];
-    }
+    failures.push(`kb_get_chunk_metadata: ${error.message}`);
   }
+
+  try {
+    const result = await apiClient.invoke('kb_get_chunk_ids', {
+      app_id: appId,
+      kb_id: kbId
+    });
+    // apiClient.invoke returns { status, message: { chunk_ids, count, ... } }
+    const data = result?.message || result;
+    if (Array.isArray(data?.chunk_ids)) return data.chunk_ids;
+    failures.push("kb_get_chunk_ids: response carried no 'chunk_ids' array");
+  } catch (error) {
+    failures.push(`kb_get_chunk_ids: ${error.message}`);
+  }
+
+  throw new Error(
+    `Cannot enumerate remote chunks for ${appId}/${kbId}: both endpoints failed to report. ` +
+    'The remote chunk set is UNKNOWN — it must NOT be treated as an empty KB, because ' +
+    'that would silently skip stale-chunk deletion and re-upsert everything. ' +
+    failures.join(' | ')
+  );
 }
 
 /**
@@ -129,7 +202,9 @@ export async function getRemoteChunkIds(apiClient, communityId, appId, kbId) {
  * @param {string} appId - App ID
  * @param {string} kbId - Knowledge base ID
  * @param {Array} chunks - Chunk records to upsert
- * @returns {Promise<{upserted: number}>}
+ * @returns {Promise<{upserted: number}>} `upserted` is the store's own count, or
+ *          UNREPORTED_COUNT if ANY batch's store response carried no count.
+ *          Test it with isReportedCount(); never print it unguarded.
  */
 export async function upsertChunks(apiClient, communityId, appId, kbId, chunks) {
   if (chunks.length === 0) {
@@ -147,7 +222,9 @@ export async function upsertChunks(apiClient, communityId, appId, kbId, chunks)
       kb_id: kbId,
       chunks: batch
     });
-    totalUpserted += result.upserted_count || batch.length;
+    // apiClient.invoke returns the whole { status, message: {...} } envelope.
+    const data = result?.message || result;
+    totalUpserted = accumulateReportedCount(totalUpserted, data?.upserted_count);
   }
 
   return { upserted: totalUpserted };
@@ -164,7 +241,9 @@ export async function upsertChunks(apiClient, communityId, appId, kbId, chunks)
  * @param {string} appId - App ID
  * @param {string} kbId - Knowledge base ID
  * @param {Array<string>} chunkIds - Chunk IDs to delete
- * @returns {Promise<{deleted: number}>}
+ * @returns {Promise<{deleted: number}>} `deleted` is the store's own count, or
+ *          UNREPORTED_COUNT if the store reported none. It is NOT chunkIds.length.
+ *          Test it with isReportedCount(); never print it unguarded.
  */
 export async function deleteStaleChunks(apiClient, communityId, appId, kbId, chunkIds) {
   if (chunkIds.length === 0) {
@@ -179,7 +258,7 @@ export async function deleteStaleChunks(apiClient, communityId, appId, kbId, chu
   });
 
   const data = result?.message || result;
-  return { deleted: data.deleted_count ?? chunkIds.length };
+  return { deleted: reportedCount(data?.deleted_count) };
 }
 
 /**
@@ -198,7 +277,10 @@ export async function deleteStaleChunks(apiClient, communityId, appId, kbId, chu
  * @param {string} appId - App ID
  * @param {string} kbId - Knowledge base ID
  * @param {Array<string>} fileIds - file_id values to delete (e.g., ['corpus:abc...', 'local:def...'])
- * @returns {Promise<{deleted: number, deleted_by_file_id: number}>}
+ * @returns {Promise<{deleted: number, deleted_by_file_id: number}>} Each field is the
+ *          store's own count, or UNREPORTED_COUNT if the store reported that field.
+ *          The two are INDEPENDENT — one may be reported and the other not. Neither
+ *          is validFileIds.length. Test with isReportedCount(); never print unguarded.
  */
 export async function deleteStaleChunksByFileId(apiClient, communityId, appId, kbId, fileIds) {
   if (!Array.isArray(fileIds) || fileIds.length === 0) {
@@ -220,8 +302,8 @@ export async function deleteStaleChunksByFileId(apiClient, communityId, appId, k
 
   const data = result?.message || result;
   return {
-    deleted: data.deleted_count ?? validFileIds.length,
-    deleted_by_file_id: data.deleted_by_file_id ?? validFileIds.length
+    deleted: reportedCount(data?.deleted_count),
+    deleted_by_file_id: reportedCount(data?.deleted_by_file_id)
   };
 }
 
@@ -253,7 +335,8 @@ export async function deleteStaleChunksByFileId(apiClient, communityId, appId, k
  * @param {string} kbId - Knowledge base ID
  * @returns {Promise<{ deleted: number, purged_scope: boolean }>}
  *          `deleted` is the actual count of vectors purged (the batched path always
- *          reports it); -1 only if a future primitive cannot report a count.
+ *          reports it), or UNREPORTED_COUNT if the store reported no count.
+ *          Test it with isReportedCount(); never print it unguarded.
  */
 export async function purgeKbScope(apiClient, communityId, appId, kbId) {
   const result = await apiClient.invoke('kb_delete_chunks', {
@@ -264,7 +347,7 @@ export async function purgeKbScope(apiClient, communityId, appId, kbId) {
   });
   const data = result?.message || result;
   return {
-    deleted: typeof data?.deleted_count === 'number' ? data.deleted_count : -1,
+    deleted: reportedCount(data?.deleted_count),
     purged_scope: data?.purged_scope === true
   };
 }
@@ -286,10 +369,21 @@ export async function listRemoteFileIds(apiClient, appId, kbId) {
     kb_id: kbId
   });
   const data = result?.message || result;
+  // Same rule as getRemoteChunkMetadata: an empty array is the store REPORTING an
+  // empty namespace; an ABSENT array is the store not reporting. This list is the
+  // drift input (stale = remote_file_ids - local), so fabricating [] here would
+  // silently mean "nothing is stale" — the failure this module exists to prevent.
+  if (!Array.isArray(data?.file_ids)) {
+    throw new Error(
+      `Cannot enumerate remote file_ids for ${appId}/${kbId}: the store reported no ` +
+      `'file_ids' array. The remote file set is UNKNOWN and must NOT be treated as ` +
+      `empty — that would silently skip the stale purge.`
+    );
+  }
   return {
-    file_ids: data.file_ids || [],
-    unique_count: data.unique_count || 0,
-    total_chunks: data.total_chunks || 0
+    file_ids: data.file_ids,
+    unique_count: reportedCount(data?.unique_count),
+    total_chunks: reportedCount(data?.total_chunks)
   };
 }
 
@@ -336,9 +430,9 @@ export async function syncKb(apiClient, config, options = {}) {
   if (onProgress) onProgress('Fetching existing chunks from Pinecone...');
   const remoteChunks = await getRemoteChunkMetadata(apiClient, communityId, appId, kbId);
   
-  const remoteCount = Array.isArray(remoteChunks) 
-    ? remoteChunks.length 
-    : 0;
+  // getRemoteChunkMetadata returns an array or throws — it never reports an
+  // unknown remote set as an empty one, so there is no non-array case to default.
+  const remoteCount = remoteChunks.length;
   
   if (verbose) {
     console.log(`  Local chunks: ${localChunks.length}`);
@@ -361,7 +455,10 @@ export async function syncKb(apiClient, config, options = {}) {
       deleted = deleteResult.deleted;
       if (verbose) console.log(`  Deleted ${deleted} stale chunks`);
     } catch (error) {
-      if (verbose) console.log(`  Delete failed: ${error.message}`);
+      // The delete ERRORED: how many were removed is unknown. Leaving `deleted` at 0
+      // would report "nothing was deleted" — a claim about the store we cannot make.
+      deleted = UNREPORTED_COUNT;
+      console.warn(`  Delete failed (deleted count unknown): ${error.message}`);
     }
   }
   
@@ -385,12 +482,11 @@ export async function syncKb(apiClient, config, options = {}) {
   let deletedByFileId = 0;
   try {
     const localFileIds = new Set(localChunks.map(c => c.file_id).filter(Boolean));
-    const remoteFileIdsResp = await apiClient.invoke('kb_list_file_ids', {
-      app_id: appId,
-      kb_id: kbId
-    });
-    const remoteData = remoteFileIdsResp?.message || remoteFileIdsResp;
-    const remoteFileIds = remoteData?.file_ids || [];
+    // Consume the module's own enumeration owner rather than re-invoking
+    // kb_list_file_ids and hand-unwrapping its payload: two derivations of one
+    // fact drift apart silently, and this copy would keep the `|| []` defect
+    // that the owner no longer has.
+    const { file_ids: remoteFileIds } = await listRemoteFileIds(apiClient, appId, kbId);
     const staleFileIds = remoteFileIds.filter(fid => !localFileIds.has(fid));
     if (staleFileIds.length > 0) {
       if (onProgress) onProgress(`Purging ${staleFileIds.length} stale file_id(s)...`);
@@ -398,14 +494,18 @@ export async function syncKb(apiClient, config, options = {}) {
       deletedByFileId = purgeResult.deleted;
     }
   } catch (purgeErr) {
-    // Non-fatal: surface via verbose log. The chunk_id-based delete above is the primary
-    // path; this is a safety net. We do NOT silently swallow — caller sees a warning.
-    if (verbose) console.log(`  File-id purge skipped: ${purgeErr.message}`);
+    // Non-fatal: the chunk_id-based delete above is the primary path and this is a
+    // safety net. We do NOT silently swallow — the caller sees a warning. That claim
+    // was previously false: the warning sat behind `if (verbose)`, so a default run
+    // saw nothing. It is unconditional now, which is what makes the sentence true.
+    console.warn(`  File-id purge skipped (stale chunks may remain): ${purgeErr.message}`);
   }
 
   return {
     synced,
-    deleted: deleted + deletedByFileId,
+    // Unknown-ness survives the sum: if either leg could not be reported, their
+    // total is not a number we can state. (-1 + 5 would silently read as 4.)
+    deleted: accumulateReportedCount(deleted, deletedByFileId),
     deleted_chunk_ids: deleted,
     deleted_by_file_id: deletedByFileId,
     unchanged
@@ -433,7 +533,8 @@ export async function getSyncStatus(apiClient, config) {
   
   // Get remote chunk metadata
   const remoteChunks = await getRemoteChunkMetadata(apiClient, communityId, appId, kbId);
-  const remoteCount = Array.isArray(remoteChunks) ? remoteChunks.length : 0;
+  // Array-or-throw, as above: no fabricated zero for an unknown remote set.
+  const remoteCount = remoteChunks.length;
   
   // Compute delta using content_hash
   const { toUpsert, toDelete, unchanged } = computeChunkDelta(localChunks, remoteChunks);

package/lib/interactive.js

@@ -0,0 +1,158 @@
+/**
+ * ONE OWNER for the question "may I prompt?".
+ *
+ * Every prompt site in this CLI consumes this module. No site derives the answer itself, and
+ * there is no flag, env var or option that restores prompting when the environment cannot
+ * support it: the guard is a property of the ENVIRONMENT, not of the invocation. A flag would
+ * be a guard the caller must remember, and forgetting it reproduces the exact hang this module
+ * exists to remove.
+ *
+ * The rule is enforced by ENCAPSULATION, not by detection: you cannot obtain a prompt handle
+ * without passing the gate, because createPromptSession() is the only way to get one and it
+ * calls requireInteractive() before it constructs anything. A comment asking authors to check
+ * is not a guard — an author who does not read it ships the hang.
+ *
+ * Reference behaviour is gcloud: it refuses non-interactively rather than hanging or silently
+ * succeeding. Both failure modes were measured in this CLI before this module existed:
+ *   - stdin an open pipe or a FIFO whose write end is held: readline waits forever. SIGKILL.
+ *   - stdin /dev/null: readline closes, the question callback NEVER fires, the event loop
+ *     drains and node exits 0 having written NOTHING. That is worse than the hang, because it
+ *     is indistinguishable from success.
+ */
+
+import readline from 'readline';
+import chalk from 'chalk';
+
+/**
+ * The single derivation of "is there a human on the other end of stdin".
+ *
+ * stdin is the decisive stream: a prompt must READ. stdout being redirected does not stop a
+ * terminal user from answering, so it is deliberately not consulted.
+ *
+ * @returns {boolean}
+ */
+export function stdinIsInteractive() {
+  return process.stdin.isTTY === true;
+}
+
+/**
+ * Thrown when a command needs to prompt and cannot. Carries the refusal text already formatted.
+ * Command actions in bin/descix.js catch Error, print `error.message` and exit 1, so throwing
+ * this produces a LOUD, NON-ZERO refusal — never a hang, never a silent exit 0.
+ */
+export class NonInteractiveError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'NonInteractiveError';
+    this.isNonInteractive = true;
+  }
+}
+
+/**
+ * Build the refusal text. Names what was being asked and how to get the job done without a
+ * prompt. It NEVER prescribes a destructive remedy: where the non-interactive form overwrites
+ * or deletes something, the caller is told so explicitly and the non-destructive option leads.
+ *
+ * @param {Object} o
+ * @param {string} o.what - the command, e.g. 'descix init'
+ * @param {string} [o.question] - the question that cannot be asked
+ * @param {string[]} [o.nonInteractiveForm] - concrete lines the caller can run instead
+ */
+function refusalText({ what, question, nonInteractiveForm, destructive }) {
+  // NO leading blank line and NO ❌ marker: command actions print `❌ ${error.message}`
+  // themselves. Emitting one here produced a doubled marker — the message OWNS the sentence,
+  // the caller OWNS the decoration.
+  const lines = [];
+  lines.push(`${what} cannot prompt during non-interactive execution.`);
+  lines.push(chalk.gray('   stdin is not a terminal, so there is no one to answer.'));
+  if (question) {
+    lines.push('');
+    lines.push(chalk.gray(`   It needed to ask: ${question}`));
+  }
+  lines.push('');
+  if (destructive) {
+    // The confirmation being refused guards an IRREVERSIBLE act. The safe reading LEADS, and we
+    // never hand back a copy-pasteable destructive command as if it were the obvious next step.
+    lines.push(chalk.yellow('   This was a confirmation for an IRREVERSIBLE operation.'));
+    lines.push(chalk.gray('   Nothing has been changed.'));
+    lines.push('');
+  }
+  if (nonInteractiveForm && nonInteractiveForm.length > 0) {
+    lines.push(chalk.white('   Non-interactive form:'));
+    for (const line of nonInteractiveForm) lines.push(`     ${line}`);
+  } else {
+    lines.push(chalk.white(`   ${what} has no non-interactive form. Run it in a terminal.`));
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * The gate. Call this before ANY prompt — readline, inquirer, or anything else.
+ * Returns silently when a human can answer; throws a loud NonInteractiveError when not.
+ *
+ * @param {Object} o - see refusalText
+ * @throws {NonInteractiveError}
+ */
+export function requireInteractive({ what, question, nonInteractiveForm, destructive } = {}) {
+  if (stdinIsInteractive()) return;
+  throw new NonInteractiveError(refusalText({ what, question, nonInteractiveForm, destructive }));
+}
+
+/**
+ * The ONLY way to obtain a prompt handle in this CLI.
+ *
+ * Gated at construction, so a site physically cannot reach readline without the check. Each
+ * ask() also re-states the question in the refusal if the session is used later, and every
+ * ask() rejects rather than hanging if stdin stops being a terminal mid-session.
+ *
+ * @param {Object} o
+ * @param {string} o.what - the command, e.g. 'descix init'
+ * @param {string[]} [o.nonInteractiveForm]
+ * @param {boolean} [o.terminal] - readline terminal option (airdrop needs true to mask input)
+ * @returns {{ask: Function, askYesNo: Function, close: Function}}
+ */
+export function createPromptSession({ what, nonInteractiveForm, terminal, destructive } = {}) {
+  requireInteractive({ what, nonInteractiveForm, destructive });
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    ...(terminal === undefined ? {} : { terminal })
+  });
+
+  /** Ask for free text, with an optional default. */
+  const ask = (question, defaultValue = '') => {
+    requireInteractive({ what, question, nonInteractiveForm, destructive });
+    const suffix = defaultValue ? `${question} [${defaultValue}]: ` : `${question}: `;
+    return new Promise((resolve) => {
+      rl.question(suffix, (answer) => resolve(answer.trim() || defaultValue));
+    });
+  };
+
+  /** Ask a yes/no question with an explicit default. */
+  const askYesNo = (question, defaultYes = true) => {
+    requireInteractive({ what, question, nonInteractiveForm, destructive });
+    const suffix = defaultYes ? '(Y/n)' : '(y/N)';
+    return new Promise((resolve) => {
+      rl.question(`${question} ${suffix}: `, (answer) => {
+        const trimmed = answer.trim().toLowerCase();
+        if (trimmed === '') return resolve(defaultYes);
+        resolve(trimmed === 'y' || trimmed === 'yes');
+      });
+    });
+  };
+
+  /**
+   * Ask with the prompt text EXACTLY as given — no added suffix. For sites that already spell
+   * their own "[y/N] " and must keep their wording verbatim.
+   */
+  const askRaw = (question) => {
+    requireInteractive({ what, question, nonInteractiveForm, destructive });
+    return new Promise((resolve) => rl.question(question, resolve));
+  };
+
+  return { ask, askYesNo, askRaw, close: () => rl.close() };
+}
+
+export default { stdinIsInteractive, requireInteractive, createPromptSession, NonInteractiveError };

package/lib/origin.js

@@ -79,15 +79,16 @@ export const ORIGIN_SOURCE_LABELS = {
     flagEnv: '--env flag',
     envVar: 'DESCIX_API_URL environment variable',
     workspaceEnvApiUrl: '.descix/workspace.json env.apiUrl',
-    legacyApiUrl: '.descix/workspace.json apiUrl (legacy)',
     globalApiUrl: '~/.descix/config.json api_url',
 };
 
 /**
  * The resolution order, most explicit first. The ORDER is the contract; this array is the only
  * place it is written down. Labels come from ORIGIN_SOURCE_LABELS, never from a second literal.
+ * The workspace names its origin at `env.apiUrl` and nowhere else — a top-level `apiUrl` is a
+ * retired v1 key that `WorkspaceConfig.load()` refuses by name.
  */
-const PRECEDENCE = ['envVar', 'workspaceEnvApiUrl', 'legacyApiUrl', 'globalApiUrl'];
+const PRECEDENCE = ['envVar', 'workspaceEnvApiUrl', 'globalApiUrl'];
 
 /**
  * What this invocation's FLAGS named, if anything: `{ origin, sourceKey }`.
@@ -181,7 +182,6 @@ function isUsableOrigin(value) {
  * @param {object} sources
  * @param {string|null} [sources.envVar]              process.env.DESCIX_API_URL
  * @param {string|null} [sources.workspaceEnvApiUrl]  workspace.json env.apiUrl
- * @param {string|null} [sources.legacyApiUrl]        workspace.json top-level apiUrl
  * @param {string|null} [sources.globalApiUrl]        ~/.descix/config.json api_url
  * @returns {{ origin: string, source: string, isDefault: boolean }} the origin AND which source
  *          supplied it — the source is returned because "where did this come from" is the

package/lib/sdk-assets.js

@@ -0,0 +1,28 @@
+/**
+ * The SDK's agent assets (instructions, guides, reference) ship inside this package at
+ * agent-assets/. `pullSdkAssets` copies them into a workspace at .descix/sdk-assets/ so a local AI
+ * agent can read them. A missing source is a broken install and throws; it is never skipped.
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+
+/** agent-assets/ at the package root, one level above lib/. */
+export const SDK_ASSETS_SOURCE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'agent-assets');
+
+/**
+ * Copy the package's agent-assets/ to <workspaceRoot>/.descix/sdk-assets/.
+ * @param {string} workspaceRoot
+ * @returns {Promise<string>} the target directory
+ * @throws when the package's agent-assets/ is absent or the copy fails
+ */
+export async function pullSdkAssets(workspaceRoot) {
+  const target = path.join(workspaceRoot, '.descix', 'sdk-assets');
+  try {
+    await fs.access(SDK_ASSETS_SOURCE);
+  } catch {
+    throw new Error(`SDK agent assets are missing from this install (${SDK_ASSETS_SOURCE}). Reinstall @descix/cli.`);
+  }
+  await fs.cp(SDK_ASSETS_SOURCE, target, { recursive: true });
+  return target;
+}