@hasna/instructions 0.4.19 → 0.4.21

package/dist/cli/index.js

@@ -2649,6 +2649,84 @@ var init_machine = __esm(() => {
   init_template();
 });
 
+// src/lib/compact-output.ts
+function parseLimit(value, fallback = DEFAULT_LIST_LIMIT, max = MAX_LIST_LIMIT) {
+  const parsed = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0)
+    return fallback;
+  return Math.min(Math.floor(parsed), max);
+}
+function parseCursor(value) {
+  const parsed = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
+  if (!Number.isFinite(parsed) || parsed < 0)
+    return 0;
+  return Math.floor(parsed);
+}
+function paginate(items, opts = {}) {
+  const limit = parseLimit(opts.limit, opts.defaultLimit ?? DEFAULT_LIST_LIMIT, opts.maxLimit ?? MAX_LIST_LIMIT);
+  const cursor = parseCursor(opts.cursor);
+  const pageItems = items.slice(cursor, cursor + limit);
+  const nextCursor = cursor + pageItems.length < items.length ? cursor + pageItems.length : null;
+  return {
+    items: pageItems,
+    total: items.length,
+    limit,
+    cursor,
+    next_cursor: nextCursor,
+    has_more: nextCursor !== null
+  };
+}
+function truncateText(value, max = 80) {
+  const text = (value ?? "").replace(/\s+/g, " ").trim();
+  if (text.length <= max)
+    return text;
+  if (max <= 3)
+    return text.slice(0, max);
+  return `${text.slice(0, max - 3)}...`;
+}
+function truncateMiddle(value, max = 80) {
+  const text = (value ?? "").replace(/\s+/g, " ").trim();
+  if (text.length <= max)
+    return text;
+  if (max <= 3)
+    return text.slice(0, max);
+  const head = Math.ceil((max - 3) * 0.55);
+  const tail = Math.floor((max - 3) * 0.45);
+  return `${text.slice(0, head)}...${text.slice(text.length - tail)}`;
+}
+var DEFAULT_LIST_LIMIT = 20, MAX_LIST_LIMIT = 100;
+
+// src/lib/bounded-read.ts
+function normalizeBoundedReadOptions(options = {}) {
+  return {
+    limit: parseLimit(options.limit, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT),
+    cursor: parseCursor(options.cursor)
+  };
+}
+function boundedReadPage(items, total, options = {}) {
+  const { limit, cursor } = normalizeBoundedReadOptions(options);
+  if (items.length > limit) {
+    throw new Error(`bounded read returned ${items.length} rows for limit ${limit}`);
+  }
+  const consumed = cursor + items.length;
+  const complete = consumed >= total;
+  if (!complete && items.length === 0) {
+    throw new Error(`bounded read did not advance at cursor ${cursor} of ${total}`);
+  }
+  return {
+    items,
+    total,
+    limit,
+    cursor,
+    next_cursor: complete ? null : consumed,
+    has_more: !complete,
+    complete,
+    truncated: false,
+    source_bounded: true
+  };
+}
+var init_bounded_read = () => {};
+
 // src/db/profiles.ts
 function rowToProfile(row) {
   return {
@@ -2692,9 +2770,12 @@ function getProfile(idOrSlug, db) {
     throw new ProfileNotFoundError(idOrSlug);
   return rowToProfile(row);
 }
-function listProfiles(db) {
+function listProfilesPage(options = {}, db) {
   const d = db || getDatabase();
-  return d.query("SELECT * FROM profiles ORDER BY name").all().map(rowToProfile);
+  const normalized = normalizeBoundedReadOptions(options);
+  const total = d.query("SELECT COUNT(*) AS total FROM profiles").get()?.total ?? 0;
+  const rows = d.query("SELECT * FROM profiles ORDER BY name LIMIT ? OFFSET ?").all(normalized.limit, normalized.cursor).map(rowToProfile);
+  return boundedReadPage(rows, total, normalized);
 }
 function updateProfile(idOrSlug, input, db) {
   const d = db || getDatabase();
@@ -2739,14 +2820,13 @@ function removeConfigFromProfile(profileIdOrSlug, configId, db) {
   const profile = getProfile(profileIdOrSlug, d);
   d.run("DELETE FROM profile_configs WHERE profile_id = ? AND config_id = ?", [profile.id, configId]);
 }
-function getProfileConfigs(profileIdOrSlug, db) {
+function getProfileConfigsPage(profileIdOrSlug, options = {}, db) {
   const d = db || getDatabase();
   const profile = getProfile(profileIdOrSlug, d);
-  const rows = d.query("SELECT config_id FROM profile_configs WHERE profile_id = ? ORDER BY sort_order").all(profile.id);
-  if (rows.length === 0)
-    return [];
-  const ids = rows.map((r) => r.config_id);
-  return listConfigs(undefined, d).filter((c) => ids.includes(c.id));
+  const normalized = normalizeBoundedReadOptions(options);
+  const total = d.query("SELECT COUNT(*) AS total FROM profile_configs WHERE profile_id = ?").get(profile.id)?.total ?? 0;
+  const rows = d.query("SELECT config_id FROM profile_configs WHERE profile_id = ? ORDER BY sort_order LIMIT ? OFFSET ?").all(profile.id, normalized.limit, normalized.cursor);
+  return boundedReadPage(rows.map((row) => getConfigById(row.config_id, d)), total, normalized);
 }
 function profileHasSelectors(profile) {
   const selectors = profile.selectors ?? {};
@@ -2762,20 +2842,46 @@ function profileMatchesMachine(profile, machine) {
   const hostnameMatches = !selectors.hostnames?.length || selectors.hostnames.some((candidate) => candidate.trim().toLowerCase() === machine.hostname.trim().toLowerCase());
   return osMatches && archMatches && hostnameMatches;
 }
-function resolveProfileForMachine(machine = detectMachineContext(), db) {
-  const profiles = listProfiles(db).filter(profileHasSelectors);
-  const matches = profiles.filter((profile) => profileMatchesMachine(profile, machine)).map((profile) => {
-    const selectors = profile.selectors;
-    const score = (selectors.hostnames?.length ? 100 : 0) + (selectors.os?.length ? 10 : 0) + (selectors.arch?.length ? 10 : 0);
-    return { profile, score };
-  }).sort((a, b) => b.score - a.score || a.profile.name.localeCompare(b.profile.name));
-  return matches[0]?.profile ?? null;
+function resolveProfileForMachineRead(machine = detectMachineContext(), options = {}, db) {
+  const d = db || getDatabase();
+  const { limit } = normalizeBoundedReadOptions(options);
+  let cursor = 0;
+  let scanned = 0;
+  let total = 0;
+  let selected = null;
+  while (true) {
+    const page = listProfilesPage({ limit, cursor }, d);
+    total = page.total;
+    scanned += page.items.length;
+    for (const profile of page.items) {
+      if (!profileHasSelectors(profile) || !profileMatchesMachine(profile, machine))
+        continue;
+      const selectors = profile.selectors;
+      const score = (selectors.hostnames?.length ? 100 : 0) + (selectors.os?.length ? 10 : 0) + (selectors.arch?.length ? 10 : 0);
+      if (!selected || score > selected.score || score === selected.score && profile.name.localeCompare(selected.profile.name) < 0) {
+        selected = { profile, score };
+      }
+    }
+    if (page.complete)
+      break;
+    cursor = page.next_cursor;
+  }
+  return {
+    profile: selected?.profile ?? null,
+    scanned,
+    total,
+    batch_limit: limit,
+    source_bounded: true,
+    complete: true,
+    truncated: false
+  };
 }
 var init_profiles = __esm(() => {
   init_types();
   init_database();
   init_configs();
   init_machine();
+  init_bounded_read();
 });
 
 // src/db/snapshots.ts
@@ -2853,6 +2959,32 @@ var init_machines = __esm(() => {
 
 // src/data/config-store.ts
 import { randomUUID as randomUUID5 } from "crypto";
+function parseBoundedPagePayload(value, label) {
+  const page = value;
+  const consumed = Number(page?.cursor) + (page?.items?.length ?? 0);
+  const complete = Boolean(page && Number.isSafeInteger(page.total) && consumed >= Number(page.total));
+  if (!page || !Array.isArray(page.items) || !Number.isSafeInteger(page.total) || Number(page.total) < 0 || !Number.isSafeInteger(page.limit) || Number(page.limit) < 1 || !Number.isSafeInteger(page.cursor) || Number(page.cursor) < 0 || page.items.length > Number(page.limit) || typeof page.has_more !== "boolean" || typeof page.complete !== "boolean" || page.truncated !== false || page.next_cursor !== null && !Number.isSafeInteger(page.next_cursor) || page.complete !== complete || page.has_more !== !complete || page.next_cursor !== (complete ? null : consumed)) {
+    throw new CloudHttpError(502, `${label} returned an invalid or truncated bounded-read envelope`, value);
+  }
+  return {
+    ...page,
+    source_bounded: page.source_bounded ?? true
+  };
+}
+function parseBoundedOrLegacyPage(value, legacyItems, options, label) {
+  if (value && typeof value === "object") {
+    const candidate = value;
+    if ("items" in candidate || "total" in candidate || "complete" in candidate || "truncated" in candidate || "next_cursor" in candidate) {
+      return parseBoundedPagePayload(value, label);
+    }
+  }
+  if (!Array.isArray(legacyItems)) {
+    throw new CloudHttpError(502, `${label} returned neither a bounded envelope nor a complete legacy array`, value);
+  }
+  const normalized = normalizeBoundedReadOptions(options);
+  const page = boundedReadPage(legacyItems.slice(normalized.cursor, normalized.cursor + normalized.limit), legacyItems.length, normalized);
+  return { ...page, source_bounded: false };
+}
 function isCloudAuthError(err) {
   return err instanceof CloudHttpError && (err.status === 401 || err.status === 403);
 }
@@ -2930,13 +3062,35 @@ class LocalConfigStore {
     return pruneSnapshots(configId, keep, this.db);
   }
   async listProfiles() {
-    return listProfiles(this.db);
+    const profiles = [];
+    let cursor = 0;
+    while (true) {
+      const page = await this.listProfilesPage({ limit: 100, cursor });
+      profiles.push(...page.items);
+      if (page.complete)
+        return profiles;
+      cursor = page.next_cursor;
+    }
+  }
+  async listProfilesPage(options = {}) {
+    return listProfilesPage(options, this.db);
   }
   async getProfile(idOrSlug) {
     return getProfile(idOrSlug, this.db);
   }
   async getProfileConfigs(idOrSlug) {
-    return getProfileConfigs(idOrSlug, this.db);
+    const configs = [];
+    let cursor = 0;
+    while (true) {
+      const page = await this.getProfileConfigsPage(idOrSlug, { limit: 100, cursor });
+      configs.push(...page.items);
+      if (page.complete)
+        return configs;
+      cursor = page.next_cursor;
+    }
+  }
+  async getProfileConfigsPage(idOrSlug, options = {}) {
+    return getProfileConfigsPage(idOrSlug, options, this.db);
   }
   async createProfile(input) {
     return createProfile(input, this.db);
@@ -2954,7 +3108,10 @@ class LocalConfigStore {
     removeConfigFromProfile(profileIdOrSlug, configId, this.db);
   }
   async resolveProfileForMachine(machine) {
-    return machine ? resolveProfileForMachine(machine, this.db) : resolveProfileForMachine(undefined, this.db);
+    return (await this.resolveProfileForMachineRead(machine)).profile;
+  }
+  async resolveProfileForMachineRead(machine, options = {}) {
+    return machine ? resolveProfileForMachineRead(machine, options, this.db) : resolveProfileForMachineRead(undefined, options, this.db);
   }
   async registerMachine(hostname2, os, arch2) {
     return registerMachine(hostname2, os, arch2, this.db);
@@ -3095,8 +3252,24 @@ class CloudConfigStore {
     return data?.pruned ?? 0;
   }
   async listProfiles() {
-    const { data } = await this.request("GET", "/profiles");
-    return data?.profiles ?? [];
+    const profiles = [];
+    let cursor = 0;
+    while (true) {
+      const page = await this.listProfilesPage({ limit: 100, cursor });
+      profiles.push(...page.items);
+      if (page.complete)
+        return profiles;
+      cursor = page.next_cursor;
+    }
+  }
+  async listProfilesPage(options = {}) {
+    const normalized = normalizeBoundedReadOptions(options);
+    const params = new URLSearchParams;
+    params.set("limit", String(normalized.limit));
+    params.set("cursor", String(normalized.cursor));
+    const qs = params.toString();
+    const { data } = await this.request("GET", `/profiles${qs ? `?${qs}` : ""}`);
+    return parseBoundedOrLegacyPage(data, data?.profiles, normalized, "profile list");
   }
   async getProfile(idOrSlug) {
     const { status, data } = await this.request("GET", `/profiles/${encodeURIComponent(idOrSlug)}`, undefined, { allow404: true });
@@ -3106,10 +3279,26 @@ class CloudConfigStore {
     return profile;
   }
   async getProfileConfigs(idOrSlug) {
-    const { status, data } = await this.request("GET", `/profiles/${encodeURIComponent(idOrSlug)}`, undefined, { allow404: true });
+    const configs = [];
+    let cursor = 0;
+    while (true) {
+      const page = await this.getProfileConfigsPage(idOrSlug, { limit: 100, cursor });
+      configs.push(...page.items);
+      if (page.complete)
+        return configs;
+      cursor = page.next_cursor;
+    }
+  }
+  async getProfileConfigsPage(idOrSlug, options = {}) {
+    const normalized = normalizeBoundedReadOptions(options);
+    const params = new URLSearchParams;
+    params.set("limit", String(normalized.limit));
+    params.set("cursor", String(normalized.cursor));
+    const qs = params.toString();
+    const { status, data } = await this.request("GET", `/profiles/${encodeURIComponent(idOrSlug)}${qs ? `?${qs}` : ""}`, undefined, { allow404: true });
     if (status === 404 || !data?.profile)
       throw new ProfileNotFoundError(idOrSlug);
-    return data.profile.configs ?? [];
+    return parseBoundedOrLegacyPage(data.configs, data.profile.configs, normalized, "profile membership");
   }
   async createProfile(input) {
     const { data } = await this.request("POST", "/profiles", input, {
@@ -3133,6 +3322,10 @@ class CloudConfigStore {
     await this.request("DELETE", `/profiles/${encodeURIComponent(profileIdOrSlug)}/configs/${encodeURIComponent(configId)}`, undefined, { allow404: true });
   }
   async resolveProfileForMachine(machine) {
+    return (await this.resolveProfileForMachineRead(machine)).profile;
+  }
+  async resolveProfileForMachineRead(machine, options = {}) {
+    const normalized = normalizeBoundedReadOptions(options);
     const params = new URLSearchParams;
     if (machine?.hostname)
       params.set("hostname", machine.hostname);
@@ -3140,11 +3333,40 @@ class CloudConfigStore {
       params.set("os", machine.os);
     if (machine?.arch)
       params.set("arch", machine.arch);
+    params.set("limit", String(normalized.limit));
     const qs = params.toString();
     const { status, data } = await this.request("GET", `/profiles/resolve${qs ? `?${qs}` : ""}`, undefined, { allow404: true });
-    if (status === 404 || !data?.profile)
-      return null;
-    return data.profile;
+    if (status === 404) {
+      return {
+        profile: null,
+        scanned: null,
+        total: null,
+        batch_limit: null,
+        source_bounded: false,
+        complete: true,
+        truncated: false
+      };
+    }
+    if (data && "complete" in data) {
+      if (data.complete !== true || data.truncated !== false) {
+        throw new CloudHttpError(502, "profile resolve returned an incomplete or truncated read", data);
+      }
+      return { ...data, source_bounded: data.source_bounded ?? true };
+    }
+    if (data && "profile" in data) {
+      return {
+        profile: data.profile,
+        scanned: null,
+        total: null,
+        batch_limit: null,
+        source_bounded: false,
+        complete: true,
+        truncated: false
+      };
+    }
+    {
+      throw new CloudHttpError(502, "profile resolve returned an incomplete or truncated read", data);
+    }
   }
   async registerMachine(hostname2, os, arch2) {
     const { data } = await this.request("POST", "/machines", { hostname: hostname2, os, arch: arch2 }, { idempotent: true });
@@ -3181,6 +3403,7 @@ var init_config_store = __esm(() => {
   init_machines();
   init_database();
   init_types();
+  init_bounded_read();
   CloudHttpError = class CloudHttpError extends Error {
     status;
     body;
@@ -13882,6 +14105,7 @@ import { basename as basename7, join as join15, resolve as resolve8 } from "path
 
 // src/lib/config-target-identity.ts
 init_apply();
+init_database();
 function findConfigsByTargetPath(configs, targetPath) {
   const wanted = normalizeTargetPath(targetPath);
   return configs.filter((config) => {
@@ -13892,6 +14116,20 @@ function findConfigsByTargetPath(configs, targetPath) {
     return normalizeTargetPath(config.target_path) === wanted;
   });
 }
+function findReferenceConfigsByName(configs, name) {
+  const wantedSlug = slugify(name);
+  return configs.filter((config) => config.kind === "reference" && (config.name === name || slugify(config.name) === wantedSlug));
+}
+function findDuplicateReferenceNameGroups(configs) {
+  const groups = new Map;
+  for (const config of configs) {
+    if (config.kind !== "reference")
+      continue;
+    const key = slugify(config.name);
+    groups.set(key, [...groups.get(key) ?? [], config]);
+  }
+  return [...groups.entries()].filter(([, rows]) => rows.length > 1).map(([, rows]) => ({ name: rows[0].name, configs: rows }));
+}
 function findDuplicateTargetPathGroups(configs) {
   const groups = new Map;
   for (const config of configs) {
@@ -14921,7 +15159,7 @@ var PROJECT_DASHBOARD_PROFILE_VARIABLES = {
   PROJECT_DASHBOARD_DIR: ".hasna/project",
   PROJECT_DASHBOARD_RENDER_MANIFEST: ".hasna/project/dashboard/render.json",
   PROJECT_DASHBOARD_SNAPSHOTS_DIR: ".hasna/project/dashboard/snapshots",
-  PROJECT_CHANNEL_PREFIX: "iproj-"
+  PROJECT_CHANNEL_PREFIX: ""
 };
 var PROJECT_DASHBOARD_STANDARD_CONTENT = `# Agent-Managed Project Dashboard Standard
 
@@ -14976,8 +15214,8 @@ context.
 
 ## Coordination
 
-- Project conversation channels use \`iproj-<project-slug>\` in the CLI and are
-  displayed to humans as \`#iproj-<project-slug>\`.
+- Project conversation channels use the normalized project slug in the CLI and
+  are displayed to humans as \`#<project-slug>\`.
 - Todos tasks are the source of truth for work; messages are only coordination.
 - Durable Codewith goal plans should own long-running implementation.
 - New implementation/verification work should route through task-triggered fresh
@@ -15082,10 +15320,15 @@ function mergeProfileSelectors(preset, existing) {
   };
 }
 function mergeProfileVariables(preset, existing) {
-  return {
+  const variables = {
     ...preset ?? {},
     ...existing
   };
+  for (const [key, value] of Object.entries(preset ?? {})) {
+    if (value === "")
+      variables[key] = value;
+  }
+  return variables;
 }
 function mergeUnique(preset, existing) {
   const values = [...new Set([...preset ?? [], ...existing ?? []])];
@@ -15388,56 +15631,6 @@ async function getConfigsStatus(store = resolveConfigStore()) {
 
 // src/cli/index.tsx
 init_config_store();
-
-// src/lib/compact-output.ts
-var DEFAULT_LIST_LIMIT = 20;
-var MAX_LIST_LIMIT = 100;
-function parseLimit(value, fallback = DEFAULT_LIST_LIMIT, max = MAX_LIST_LIMIT) {
-  const parsed = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
-  if (!Number.isFinite(parsed) || parsed <= 0)
-    return fallback;
-  return Math.min(Math.floor(parsed), max);
-}
-function parseCursor(value) {
-  const parsed = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
-  if (!Number.isFinite(parsed) || parsed < 0)
-    return 0;
-  return Math.floor(parsed);
-}
-function paginate(items, opts = {}) {
-  const limit = parseLimit(opts.limit, opts.defaultLimit ?? DEFAULT_LIST_LIMIT, opts.maxLimit ?? MAX_LIST_LIMIT);
-  const cursor = parseCursor(opts.cursor);
-  const pageItems = items.slice(cursor, cursor + limit);
-  const nextCursor = cursor + pageItems.length < items.length ? cursor + pageItems.length : null;
-  return {
-    items: pageItems,
-    total: items.length,
-    limit,
-    cursor,
-    next_cursor: nextCursor,
-    has_more: nextCursor !== null
-  };
-}
-function truncateText(value, max = 80) {
-  const text = (value ?? "").replace(/\s+/g, " ").trim();
-  if (text.length <= max)
-    return text;
-  if (max <= 3)
-    return text.slice(0, max);
-  return `${text.slice(0, max - 3)}...`;
-}
-function truncateMiddle(value, max = 80) {
-  const text = (value ?? "").replace(/\s+/g, " ").trim();
-  if (text.length <= max)
-    return text;
-  if (max <= 3)
-    return text.slice(0, max);
-  const head = Math.ceil((max - 3) * 0.55);
-  const tail = Math.floor((max - 3) * 0.45);
-  return `${text.slice(0, head)}...${text.slice(text.length - tail)}`;
-}
-
-// src/cli/index.tsx
 import { createRequire } from "module";
 var pkg = createRequire(import.meta.url)("../../package.json");
 var EAGAIN_SLEEP = new Int32Array(new SharedArrayBuffer(4));
@@ -15665,6 +15858,15 @@ function parseVarArgs(values) {
   }
   return Object.keys(vars).length > 0 ? vars : undefined;
 }
+function parseUnsetVarArgs(values) {
+  if (!values || values.length === 0)
+    return [];
+  const keys = [...new Set(values.map((value) => value.trim()))];
+  if (keys.some((key) => key.length === 0 || key.includes("="))) {
+    throw new Error('Invalid --unset-var (expected variable names without "=")');
+  }
+  return keys;
+}
 function parseProfileSelectors(opts) {
   const selectors = {};
   const os = splitCsv(opts.os);
@@ -15691,10 +15893,11 @@ function formatProfileSelectorSummary(profile) {
 function formatProfileVariables(profile) {
   return Object.entries(profile.variables).map(([key, value]) => `${key}=${value}`).join(", ");
 }
-async function getMachineProfileContext(opts, store) {
+async function getMachineProfileContext(opts, store, readOptions = {}) {
   const machine = detectMachineContext({ hostname: opts.hostname, os: opts.os, arch: opts.arch });
-  const profile = await store.resolveProfileForMachine(machine);
-  return { machine, profile, vars: resolveProfileVariables(profile, machine) };
+  const resolution = await store.resolveProfileForMachineRead(machine, readOptions);
+  const profile = resolution.profile;
+  return { machine, profile, resolution, vars: resolveProfileVariables(profile, machine) };
 }
 program.command("list").alias("ls").description("List stored configs").option("-c, --category <cat>", "filter by category").option("-a, --agent <agent>", "filter by agent").option("-k, --kind <kind>", "filter by kind (file|reference)").option("-t, --tag <tag>", "filter by tag").option("-s, --search <query>", "search name/description/content").option("-f, --format <fmt>", "output format: compact|table|json", "compact").option("--brief", "shorthand for --format compact").option("--verbose", "show expanded metadata for each listed config").option("--json", "output full matching records as JSON").option("--limit <n>", `max rows for human output (default ${DEFAULT_LIST_LIMIT})`).option("--cursor <n>", "zero-based pagination cursor for human output").action(async (opts) => {
   const fmt = opts.json ? "json" : opts.verbose ? "table" : opts.brief ? "compact" : opts.format;
@@ -15779,20 +15982,33 @@ program.command("add <path>").description("Ingest a file into the config DB").op
   const targetPath = abs.startsWith(homedir7()) ? abs.replace(homedir7(), "~") : abs;
   const name = opts.name || filePath.split("/").pop();
   const store = resolveConfigStore();
-  const existingOwners = opts.kind === "reference" ? [] : findConfigsByTargetPath(await store.listConfigs(), targetPath);
+  const allConfigs = await store.listConfigs();
+  const existingOwners = opts.kind === "reference" ? findReferenceConfigsByName(allConfigs, name) : findConfigsByTargetPath(allConfigs, targetPath);
+  const isReference = opts.kind === "reference";
+  const identityLabel = isReference ? `Reference config "${name}"` : targetPath;
+  const identityNoun = isReference ? "name" : "path";
   if (existingOwners.length > 0 && !opts.update) {
     const owners = existingOwners.map((owner) => `${owner.slug} (${owner.id})`).join(", ");
-    console.error(chalk.red(`${targetPath} is already tracked by: ${owners}`));
+    console.error(chalk.red(`${identityLabel} is already tracked by: ${owners}`));
     if (existingOwners.length > 1) {
-      console.error(chalk.red(`  ${existingOwners.length} rows already collide on this path \u2014 apply order between them is undefined.`));
+      console.error(chalk.red(`  ${existingOwners.length} rows already collide on this ${identityNoun} \u2014 apply order between them is undefined.`));
     }
     console.error(chalk.dim("  Use `instructions add <path> --update` to refresh that row in place,"));
-    console.error(chalk.dim("  `instructions sync` to pull disk changes in, or `instructions delete <id>` first."));
+    if (isReference) {
+      console.error(chalk.dim("  or `instructions delete <id>` first."));
+    } else {
+      console.error(chalk.dim("  `instructions sync` to pull disk changes in, or `instructions delete <id>` first."));
+    }
     process.exit(1);
   }
   let config;
   if (existingOwners.length > 0) {
-    const [target, ...rest] = existingOwners;
+    const exactIndex = isReference ? existingOwners.findIndex((owner) => owner.name === name) : -1;
+    const target = exactIndex >= 0 ? existingOwners[exactIndex] : existingOwners[0];
+    const rest = existingOwners.filter((owner) => owner.id !== target.id);
+    if (content !== target.content) {
+      await store.createSnapshot(target.id, target.content, target.version);
+    }
     config = await store.updateConfig(target.id, {
       content,
       format: fmt,
@@ -15802,7 +16018,7 @@ program.command("add <path>").description("Ingest a file into the config DB").op
     });
     console.log(chalk.green("\u2713") + ` Updated: ${chalk.bold(config.name)} ${chalk.dim(`(${config.slug})`)}`);
     if (rest.length > 0) {
-      console.log(chalk.yellow(`  \u26A0 ${rest.length} other row(s) still target ${targetPath}: ${rest.map((r) => r.slug).join(", ")}`));
+      console.log(chalk.yellow(`  \u26A0 ${rest.length} other row(s) still share this ${identityNoun}: ${rest.map((r) => r.slug).join(", ")}`));
       console.log(chalk.yellow("    Apply order between them is undefined. Delete the extras."));
     }
     if (redacted.length > 0) {
@@ -16024,29 +16240,28 @@ program.command("whoami").description("Show setup summary").action(async () => {
   }
 });
 var profileCmd = program.command("profile").description("Manage config profiles (named bundles)");
-profileCmd.command("list").description("List all profiles").option("--brief", "compact one-line output").option("-f, --format <fmt>", "compact|table|json", "compact").option("--verbose", "show expanded profile metadata").option("--json", "output full profiles as JSON").option("--limit <n>", `max rows for human output (default ${DEFAULT_LIST_LIMIT})`).option("--cursor <n>", "zero-based pagination cursor for human output").action(async (opts) => {
+profileCmd.command("list").description("List all profiles").option("--brief", "compact one-line output").option("-f, --format <fmt>", "compact|table|json", "compact").option("--verbose", "show expanded profile metadata").option("--json", "output full profiles as JSON").option("--limit <n>", `max rows requested from the source (default ${DEFAULT_LIST_LIMIT})`).option("--cursor <n>", "zero-based source pagination cursor").action(async (opts) => {
   const fmt = opts.json ? "json" : opts.verbose ? "table" : opts.brief ? "compact" : opts.format;
   const store = resolveConfigStore();
-  const profiles = await store.listProfiles();
+  const page = await store.listProfilesPage({ limit: opts.limit, cursor: opts.cursor });
   if (fmt === "json") {
-    printJson(profiles);
+    printJson(page);
     return;
   }
-  if (profiles.length === 0) {
+  if (page.total === 0) {
     console.log(chalk.dim("No profiles."));
     return;
   }
-  const page = paginate(profiles, { limit: opts.limit, cursor: opts.cursor });
   if (fmt === "compact")
     console.log(`${pad("slug", 28)} ${pad("configs", 8)} ${pad("match", 36)} vars`);
   for (const p of page.items) {
+    const configCount = (await store.getProfileConfigsPage(p.id, { limit: 1 })).total;
     if (fmt === "compact") {
       const selectorSummary2 = formatProfileSelectorSummary(p);
-      console.log(`${pad(p.slug, 28)} ${pad(String((await store.getProfileConfigs(p.id)).length), 8)} ${pad(selectorSummary2 || "-", 36)} ${Object.keys(p.variables).length}`);
+      console.log(`${pad(p.slug, 28)} ${pad(String(configCount), 8)} ${pad(selectorSummary2 || "-", 36)} ${Object.keys(p.variables).length}`);
       continue;
     }
-    const configs = await store.getProfileConfigs(p.id);
-    console.log(`${chalk.bold(p.name)} ${chalk.dim(`(${p.slug})`)} \u2014 ${configs.length} config(s)`);
+    console.log(`${chalk.bold(p.name)} ${chalk.dim(`(${p.slug})`)} \u2014 ${configCount} config(s)`);
     if (p.description)
       console.log(`  ${chalk.dim(p.description)}`);
     const selectorSummary = formatProfileSelectorSummary(p);
@@ -16067,11 +16282,40 @@ profileCmd.command("create <name>").description("Create a new profile").option("
   });
   console.log(chalk.green("\u2713") + ` Created profile: ${chalk.bold(p.name)} ${chalk.dim(`(${p.slug})`)}`);
 });
-profileCmd.command("show <id>").description("Show profile and its configs").option("--limit <n>", `max config rows (default ${DEFAULT_LIST_LIMIT})`).option("--cursor <n>", "zero-based pagination cursor").action(async (id, opts) => {
+profileCmd.command("update <id>").description("Update an existing profile's variables in one store operation").option("--var <vars...>", "set profile variable(s) as KEY=VALUE").option("--unset-var <keys...>", "remove profile variable(s) by key").action(async (id, opts) => {
+  try {
+    const setVariables = parseVarArgs(opts.var) ?? {};
+    const unsetVariables = parseUnsetVarArgs(opts.unsetVar);
+    const setKeys = new Set(Object.keys(setVariables));
+    const conflicts = unsetVariables.filter((key) => setKeys.has(key));
+    if (conflicts.length > 0) {
+      throw new Error(`Variables cannot be both set and unset: ${conflicts.join(", ")}`);
+    }
+    if (Object.keys(setVariables).length === 0 && unsetVariables.length === 0) {
+      throw new Error("Provide --var KEY=VALUE and/or --unset-var KEY");
+    }
+    const store = resolveConfigStore();
+    const profile = await store.getProfile(id);
+    const variables = { ...profile.variables };
+    for (const key of unsetVariables)
+      delete variables[key];
+    Object.assign(variables, setVariables);
+    const updated = await store.updateProfile(profile.id, { variables });
+    console.log(chalk.green("\u2713") + ` Updated profile: ${chalk.bold(updated.name)} ${chalk.dim(`(${updated.slug})`)}`);
+  } catch (e) {
+    console.error(chalk.red(formatCliError(e)));
+    process.exit(1);
+  }
+});
+profileCmd.command("show <id>").description("Show profile and its configs").option("--limit <n>", `max config rows (default ${DEFAULT_LIST_LIMIT})`).option("--cursor <n>", "zero-based pagination cursor").option("--json", "output the profile and bounded membership page as JSON").action(async (id, opts) => {
   try {
     const store = resolveConfigStore();
     const p = await store.getProfile(id);
-    const configs = await store.getProfileConfigs(id);
+    const page = await store.getProfileConfigsPage(id, { limit: opts.limit, cursor: opts.cursor });
+    if (opts.json) {
+      printJson({ profile: p, configs: page });
+      return;
+    }
     console.log(chalk.bold(p.name) + chalk.dim(` (${p.slug})`));
     if (p.description)
       console.log(chalk.dim(p.description));
@@ -16081,8 +16325,7 @@ profileCmd.command("show <id>").description("Show profile and its configs").opti
     const varSummary = formatProfileVariables(p);
     if (varSummary)
       console.log(chalk.dim(`vars: ${varSummary}`));
-    console.log(chalk.cyan(`${configs.length} config(s):`));
-    const page = paginate(configs, { limit: opts.limit, cursor: opts.cursor });
+    console.log(chalk.cyan(`${page.total} config(s):`));
     for (const c of page.items)
       console.log(`  ${c.slug} ${chalk.dim(`[${c.category}/${c.agent}]`)}`);
     if (page.has_more) {
@@ -16159,9 +16402,15 @@ ${changed}/${results.length} changed (${selected.slug} on ${machine.hostname} ${
     process.exit(1);
   }
 });
-profileCmd.command("resolve").description("Resolve the matching machine-aware profile").option("--hostname <hostname>", "override detected hostname").option("--os <os>", "override detected OS").option("--arch <arch>", "override detected arch").action(async (opts) => {
+profileCmd.command("resolve").description("Resolve the matching machine-aware profile").option("--hostname <hostname>", "override detected hostname").option("--os <os>", "override detected OS").option("--arch <arch>", "override detected arch").option("--limit <n>", `maximum profiles per source scan batch (default ${DEFAULT_LIST_LIMIT})`).option("--json", "output the complete bounded resolution read as JSON").action(async (opts) => {
   const store = resolveConfigStore();
-  const { machine, profile, vars } = await getMachineProfileContext(opts, store);
+  const { machine, profile, resolution, vars } = await getMachineProfileContext(opts, store, { limit: opts.limit });
+  if (opts.json) {
+    printJson({ ...resolution, machine, vars });
+    if (!profile)
+      process.exitCode = 1;
+    return;
+  }
   if (!profile) {
     console.log(chalk.yellow(`No matching profile for ${machine.hostname} ${machine.os_family}/${machine.arch}`));
     process.exit(1);
@@ -16843,6 +17092,20 @@ Stored configs (${allConfigs.length}):`));
     }
     console.log(chalk.dim("      Keep one row per path: `instructions delete <id>` for the extras."));
   }
+  const duplicateReferenceNames = findDuplicateReferenceNameGroups(allConfigs);
+  if (duplicateReferenceNames.length === 0) {
+    pass("No reference config name is claimed by more than one row");
+  } else {
+    const rowCount = duplicateReferenceNames.reduce((total, group) => total + group.configs.length, 0);
+    fail(`${duplicateReferenceNames.length} reference name(s) claimed by more than one row (${rowCount} rows) \u2014 only one is live in the next render`);
+    for (const group of duplicateReferenceNames) {
+      console.log(chalk.yellow(`      ${group.name}`));
+      for (const c of group.configs) {
+        console.log(chalk.dim(`        ${c.slug}  (${c.id})  updated ${c.updated_at}`));
+      }
+    }
+    console.log(chalk.dim("      Keep one row per name: `instructions delete <id>` for the extras."));
+  }
   console.log(`
 ${issues === 0 ? chalk.green("\u2713 All checks passed") : chalk.yellow(`${issues} issue(s) found`)}`);
 });