agentlinkops 0.5.0

package/cli/check.js

@@ -0,0 +1,119 @@
+// `agentlinkops check`: the exact cloud verifier, over a ledger file, without an account.
+//
+// Two things make it the real thing rather than a lookalike.
+//
+// **It imports `verifyLink` from `src/verifier/`.** Not a copy, not a port. The cases in
+// `test/fixtures/verifier-cases.js` are asserted against both this and the cloud path, so the
+// two cannot drift and still show green.
+//
+// **It paces.** Supplying `beforeFetch` is not politeness garnish: without it the verifier
+// REFUSES every host that states a robots crawl delay, and a CLI that skipped it would report
+// our own omission to the customer as the publisher's fault.
+import { verifyLink } from '../src/verifier/index.js';
+import { observationRow } from './mirror.js';
+import { cadenceSeconds, DEFAULT_CADENCE } from './ledger.js';
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const hostOf = url => { try { return new URL(url).hostname; } catch { return null; } };
+
+/** A courtesy floor per host, honouring a publisher's own stated delay when it is longer. */
+export function createPacer({ hostDelayMs = 2000, now = () => Date.now(), wait = sleep } = {}) {
+  const nextAllowed = new Map();
+  return {
+    async beforeFetch(url, context = {}) {
+      const host = hostOf(url);
+      if (!host) return;
+      const stated = Number(context.crawlDelaySeconds ?? 0) * 1000;
+      const floor = Math.max(hostDelayMs, Number.isFinite(stated) ? stated : 0);
+      const allowed = nextAllowed.get(host) ?? 0;
+      const delay = allowed - now();
+      if (delay > 0) await wait(delay);
+      nextAllowed.set(host, now() + floor);
+    },
+  };
+}
+
+/** Entries a check should visit. `retired` is kept for its history and never fetched. */
+export function selectEntries(entries, { filter = null, includeRetired = false } = {}) {
+  return entries.filter(entry => {
+    if (entry.intent === 'retired' && !includeRetired) return false;
+    if (!filter) return true;
+    const haystack = [entry.id, entry.source, entry.target, entry.ref ?? '', ...(entry.tags ?? [])].join(' ').toLowerCase();
+    return haystack.includes(String(filter).toLowerCase());
+  });
+}
+
+/**
+ * Entries whose cadence says they are due. A check with no `--all` does not refetch the web.
+ *
+ * `lastChecked` comes from `state.json`, not from the observation mirror, because the mirror
+ * only records CHANGES — reading the last check time from it would make an entry that has been
+ * stably present for a month look like it had never been checked since the day it appeared.
+ */
+export function dueEntries(entries, lastChecked, { now = Date.now() } = {}) {
+  return entries.filter(entry => {
+    const last = lastChecked.get(entry.id);
+    if (!last) return true;
+    const seconds = cadenceSeconds(entry.cadence ?? DEFAULT_CADENCE[entry.intent] ?? 'daily') ?? 86_400;
+    return now - Date.parse(last) >= seconds * 1000;
+  });
+}
+
+/**
+ * Runs the verifier over a set of entries. Hosts run in parallel, a host never runs in parallel
+ * with itself, and the result rows come back in the ledger's own order so a diff is stable.
+ */
+export async function runCheck(entries, {
+  concurrency = 6, timeoutMs = 20_000, hostDelayMs = 2000,
+  verify = verifyLink, pacer = null, onResult = null,
+} = {}) {
+  const paced = pacer ?? createPacer({ hostDelayMs });
+  const byHost = new Map();
+  for (const entry of entries) {
+    const host = hostOf(entry.source) ?? entry.id;
+    if (!byHost.has(host)) byHost.set(host, []);
+    byHost.get(host).push(entry);
+  }
+  const queue = [...byHost.values()];
+  const rows = new Map();
+  const worker = async () => {
+    while (queue.length) {
+      for (const entry of queue.pop()) {
+        const result = await verify(
+          { sourceUrl: entry.source, targetUrl: entry.target, targetScope: entry.scope,
+            expectedAnchor: entry.expect?.anchor, expectedRel: entry.expect?.rel },
+          // `includeHtml: false` is a contract commitment, not a size optimisation: the bytes
+          // must not reach the repository.
+          { publicFetchSafe: true, timeoutMs, includeHtml: false, beforeFetch: paced.beforeFetch });
+        const row = observationRow(entry.id, result);
+        rows.set(entry.id, row);
+        onResult?.(entry, row);
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(concurrency, queue.length)) }, worker));
+  return entries.map(entry => rows.get(entry.id)).filter(Boolean);
+}
+
+/**
+ * The exit code, which is where "unknown is never absent" either holds or quietly stops.
+ *
+ * Only an `expected` entry observed ABSENT with COMPLETE evidence fails. None of the 471
+ * unknowns the T01 benchmark measured is evidence that a link is gone, and a CLI that failed on
+ * them would teach people to pass a flag that turns the check off.
+ */
+export function summarize(entries, rows) {
+  const byId = new Map(rows.map(row => [row.id, row]));
+  const counts = { present: 0, absent: 0, unknown: 0, source_unavailable: 0, unchecked: 0 };
+  const failures = [], appeared = [];
+  for (const entry of entries) {
+    const row = byId.get(entry.id);
+    if (!row) { counts.unchecked++; continue; }
+    counts[row.state] = (counts[row.state] ?? 0) + 1;
+    if (entry.intent === 'expected' && row.state === 'absent' && row.complete) failures.push({ entry, row });
+    // A `wanted` link that turned up is the whole selling moment, so it is a headline rather
+    // than a line in a table.
+    if (entry.intent === 'wanted' && row.state === 'present') appeared.push({ entry, row });
+  }
+  return { counts, failures, appeared, exitCode: failures.length ? 1 : 0 };
+}

package/cli/citation.js

@@ -0,0 +1,109 @@
+// `agentlinkops citation` — watch AI citations as placements, locally.
+//
+// One prompt panel, run against engine APIs with the customer's own key, a hard
+// USD cap, and evidence written into the repository ledger. The vocabulary is the
+// contract's: rates with intervals and sample sizes, never "removed", and thin data
+// reported as insufficient rather than interpreted.
+//
+// Exit codes follow the link commands: 0 nothing actionable (including
+// insufficient_data — an unknown never fails), 1 a cell classified declined with
+// complete evidence, 2 usage, configuration or budget-abort errors.
+import { resolve } from 'node:path';
+
+import { parseArgs } from './args.js';
+import { loadPanel, runEpoch } from '../src/citations/runner.js';
+import { engineIdentity } from '../src/citations/contract.js';
+import { createMockEngine, createPerplexityEngine, EngineError } from '../src/citations/adapter.js';
+import { describeChange } from '../src/citations/stats.js';
+
+const USAGE = `agentlinkops citation — AI citation watches in this repository
+
+  agentlinkops citation run PANEL.json [--dir DIR] [--samples N] [--max-usd USD] [--json]
+                                            run one fixed-n epoch over a panel; evidence and
+                                            tallies land under .agentlinkops/citations/
+  agentlinkops citation help                 this help
+
+Panel (JSON): targets (domain or url, brand, aliases), prompts, engines
+([{ "engine": "mock" | "perplexity", "model": "…" }]), optional samples and maxUsd.
+Live engines need the matching environment credential (PERPLEXITY_API_KEY); the mock
+engine runs everything at zero cost. Every run states its estimated spend, and the
+cap is checked BEFORE each call, so it can be approached but never exceeded.
+
+Output language: citation RATE with a Wilson interval and n, classified against the
+previous epoch as declined, grown or not_distinguishable — never "removed", never
+"stable", and insufficient_data when n is too thin to interpret.`;
+
+export async function citationMain(argv = [], { cwd = process.cwd(), out = console.log, err = console.error, env = process.env } = {}) {
+  const args = parseArgs(argv);
+  const command = args._[0] ?? 'help';
+  if (command === 'help' || args.help) { out(USAGE); return 0; }
+  if (command !== 'run') { err(`unknown citation command: ${command}`); err(USAGE); return 2; }
+
+  const panelPath = args._[1];
+  if (!panelPath) { err('citation run needs a panel file'); return 2; }
+
+  let panel;
+  try {
+    panel = await loadPanel(resolve(cwd, panelPath));
+  } catch (cause) {
+    err(`panel could not be read or parsed: ${cause.message}`);
+    return 2;
+  }
+
+  const dir = resolve(cwd, args.dir ?? '.agentlinkops');
+  if (args.samples) panel.samples = Number(args.samples);
+  if (args['max-usd']) panel.maxUsd = Number(args['max-usd']);
+  // Overrides are stated, never silent: a number the panel did not ask for is a
+  // configuration decision the operator should see in the receipt.
+  if (args.samples || args['max-usd']) {
+    err(`overrides: samples=${panel.samples} maxUsd=${panel.maxUsd}`);
+  }
+
+  const engines = new Map();
+  for (const spec of panel.engines) {
+    const identity = engineIdentity(spec);
+    if (engines.has(identity)) continue;
+    if (spec.engine === 'mock') {
+      engines.set(identity, createMockEngine({ fixtures: panel.mockFixtures ?? {} }));
+    } else if (spec.engine === 'perplexity') {
+      // Presence only, never the value — the same rule doctor applies to tokens.
+      if (!env.PERPLEXITY_API_KEY) {
+        err(`engine ${identity} needs PERPLEXITY_API_KEY in the environment`);
+        return 2;
+      }
+      engines.set(identity, createPerplexityEngine({ apiKey: env.PERPLEXITY_API_KEY, model: spec.model ?? 'sonar' }));
+    } else {
+      err(`unknown engine: ${spec.engine}`);
+      return 2;
+    }
+  }
+
+  try {
+    const result = await runEpoch(panel, { dir, engines, delayMs: 250 });
+    if (args.json) {
+      out(JSON.stringify(result, null, 2));
+    } else {
+      for (const cell of result.cells) {
+        const line = describeChange(
+          { rate: cell.rate, ci_low: cell.ci_low, ci_high: cell.ci_high, n: cell.n },
+          cell.baseline ? { rate: cell.baseline.rate, ci_low: cell.baseline.ci_low, ci_high: cell.baseline.ci_high, n: null } : null,
+        );
+        out(`${cell.cell_id} — ${line} [${cell.classification}]`);
+      }
+      out(`epoch ${result.epochId}: estimated spend $${result.spentEstimateUsd.toFixed(4)} of $${result.maxUsd} cap`);
+    }
+    if (result.aborted) {
+      err(`budget abort before the next call (spent $${result.aborted.spent.toFixed(4)}, next estimate $${result.aborted.nextEstimate.toFixed(4)}, cap $${result.aborted.maxUsd}); partial tallies below the interpretation minimum report insufficient_data`);
+      return 2;
+    }
+    const declined = result.cells.filter((c) => c.classification === 'declined');
+    if (declined.length > 0) {
+      err(`${declined.length} cell${declined.length === 1 ? '' : 's'} declined with complete evidence`);
+      return 1;
+    }
+    return 0;
+  } catch (cause) {
+    if (cause instanceof EngineError) { err(cause.message); return 2; }
+    throw cause;
+  }
+}

package/cli/client.js

@@ -0,0 +1,60 @@
+import {restResponseContract} from '../shared/response-contract.js';
+// A small HTTP client for the cloud. Scoped keys only; no human session ever reaches here.
+// DP-0036-T13: the CLI names itself so the usage counters can tell it from other REST callers.
+// The version follows the plugin manifests; bump it with them.
+export const CLI_VERSION = '0.5.0';
+export const CLI_USER_AGENT = `agentlinkops-cli/${CLI_VERSION}`;
+export class CloudError extends Error {
+  constructor(code, status, details = null) {
+    super(`${code}${status ? ` (${status})` : ''}`);
+    this.name = 'CloudError'; this.code = code; this.status = status; this.details = details;
+    this.exitCode = 2;
+  }
+}
+
+export function createClient({ origin, token, workspaceId, projectId, fetchImpl = globalThis.fetch } = {}) {
+  if (!origin) throw new CloudError('NO_CLOUD_ORIGIN', 0);
+  if (!token) throw new CloudError('NO_TOKEN', 0);
+  const base = origin.replace(/\/$/u, '');
+  async function call(method, path, { body = null, query = null } = {}) {
+    const url = new URL(base + path);
+    for (const [key, value] of Object.entries(query ?? {})) if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
+    const response = await fetchImpl(url.href, {
+      method, redirect: 'error', signal: AbortSignal.timeout(30000),
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'User-Agent': CLI_USER_AGENT,
+        ...(workspaceId ? { 'X-Workspace-ID': workspaceId } : {}),
+        ...(body ? { 'Content-Type': 'application/json' } : {}),
+      },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    const text = await response.text();
+    let payload = null;
+    try { payload = text ? JSON.parse(text) : null; } catch { payload = null; }
+    if (!response.ok) {
+      // The error BODY is the useful part — a 410 carries the resync instructions, and losing
+      // them would turn a recoverable expiry into "the sync failed, try again forever".
+      throw new CloudError(payload?.error?.code ?? `HTTP_${response.status}`, response.status, payload?.error?.details ?? null);
+    }
+    const parsed=restResponseContract(path,method).safeParse(payload);
+    if(!parsed.success)throw new CloudError('INVALID_RESPONSE',502);
+    return parsed.data;
+  }
+  return {
+    listCommands: () => call('GET', '/v1/commands', { query: { include: 'schemas' } }),
+    describeCommand: name => call('GET', `/v1/commands/${encodeURIComponent(name)}`),
+    callCommand: (name, args = {}) => call('POST', `/v1/commands/${encodeURIComponent(name)}`, { body: args }),
+    getWorkspace: () => call('GET', '/v1/workspace'),
+    getProject: projectId => call('GET', `/v1/projects/${encodeURIComponent(projectId)}`),
+    importWatches: (projectId, watches) => call('POST', '/v1/watches/import', { body: { projectId, watches } }),
+    updateWatch: (watchId, patch) => call('PATCH', `/v1/watches/${encodeURIComponent(watchId)}`, { body: patch }),
+    listWatches: query => call('GET', '/v1/watches', { query: { ...query, ...(projectId ? { projectId } : {}) } }),
+    listEvents: query => call('GET', '/v1/events', { query: { ...query, ...(projectId ? { projectId } : {}) } }),
+    // The cloud keeps a SEPARATE sequence for target events. One client method per feed, because
+    // one method with a flag is how two feeds end up sharing a cursor.
+    listTargets: query => call('GET', '/v1/targets', { query: { ...query, ...(projectId ? { projectId } : {}) } }),
+    listTargetEvents: query => call('GET', '/v1/target-events', { query: { ...query, ...(projectId ? { projectId } : {}) } }),
+    exportWatches: query => call('GET', '/v1/exports/watches', { query: { ...query, ...(projectId ? { projectId } : {}) } }),
+  };
+}

package/cli/commands.js

@@ -0,0 +1,183 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { loadConfig, ConfigError } from './config.js';
+import { cloudConnection } from './connection.js';
+import { createClient, CloudError } from './client.js';
+import { parseArgs } from './args.js';
+import { NUDGE } from './skill.js';
+import { CATALOG_COMMANDS, CATALOG_TOOLSETS } from './catalog.js';
+import { oneLiner } from '../src/tool-views.js';
+
+// DP-0036-T05: the CLI's three-level discovery over the cloud catalog — index (`tools`),
+// describe (`describe NAME`) and call (`call NAME`). `tools` and `describe` answer from the
+// bundled snapshot in cli/catalog.js with no account and no network; `--refresh` reads the
+// live catalog instead. Output is JSON whenever stdout is not a terminal or --json is given,
+// and one error shape ({ error: { code, message, next } }) on every failure.
+const USAGE = 'tools [TOOLSET] [--json] [--refresh] | describe NAME [--examples] [--output-schema] [--json] [--refresh] | call NAME [--args JSON | --file FILE | --set PATH=VALUE ...] [--dry-run] [-y] [--json]';
+const NAME = /^[a-z][a-z0-9_]*$/;
+const NEXT = {
+  TOOL_NOT_FOUND: 'Run `agentlinkops tools` to list commands, or `agentlinkops tools TOOLSET` for one group.',
+  INVALID_INPUT: 'Run `agentlinkops describe NAME` for the exact input schema.',
+  INSUFFICIENT_SCOPE: 'This credential lacks a scope the command needs; request it through your connection or a new project-scoped key.',
+  NO_CLOUD_ORIGIN: 'Run `agentlinkops connect` or set AGENTLINKOPS_API_URL.',
+  INVALID_CLOUD_ORIGIN: 'Cloud commands need an HTTPS origin without a path, for example https://app.agentlinkops.com.',
+  NO_TOKEN: 'Set AGENTLINKOPS_TOKEN or AGENTLINKOPS_API_KEY from a project-scoped key.',
+  PROVIDER_NOT_CONFIGURED: 'An operator must enable this supplier admission; retrying does not change it.',
+  OWNED_DISCOVERY_NOT_CONFIGURED: 'An operator must configure owned discovery; retrying does not change it.',
+  IDEMPOTENCY_CONFLICT: 'Reuse an idempotency key only with identical arguments; choose a new key for a new request.',
+};
+export const explain = code => NEXT[code] ?? 'Run `agentlinkops describe NAME` and check the arguments, scopes and availability.';
+
+export const resolveName = (commands, name) => commands.find(c => c.name === name) ?? commands.find(c => c.aliases?.includes(name)) ?? null;
+
+// The index: grouped by toolset, one line per command, core and write and admission marked.
+export function renderIndex(commands, { toolset = null, json = false } = {}) {
+  const selected = toolset ? commands.filter(c => c.toolset === toolset) : commands;
+  if (json) return JSON.stringify({ toolsets: toolset ? { [toolset]: CATALOG_TOOLSETS[toolset] } : CATALOG_TOOLSETS, commands: selected.map(c => ({ name: c.name, toolset: c.toolset, tier: c.tier, readOnly: c.readOnly, summary: oneLiner(c.description, 96), ...(c.admissionGated ? { admission: 'gated' } : {}), ...(c.aliases?.length ? { aliases: c.aliases } : {}) })), next: 'Run `agentlinkops describe NAME` for a schema, then `agentlinkops call NAME --args JSON`.' }, null, 2);
+  const groups = new Map();
+  for (const c of selected) (groups.get(c.toolset) ?? groups.set(c.toolset, []).get(c.toolset)).push(c);
+  const lines = [];
+  for (const [group, members] of [...groups].sort()) {
+    lines.push(CATALOG_TOOLSETS[group] ? `${group}: ${CATALOG_TOOLSETS[group]}` : `${group}:`);
+    for (const c of members.sort((a, b) => a.name.localeCompare(b.name))) lines.push(`  ${c.name}${c.tier === 'core' ? ' (core)' : ''}${c.readOnly ? '' : ' [write]'}${c.admissionGated ? ' [admission-gated]' : ''}  ${oneLiner(c.description, 48)}`);
+    lines.push('');
+  }
+  lines.push(`${selected.length} commands${toolset ? ` in ${toolset}` : ''}. describe NAME shows the schema; call NAME --args JSON runs it.`);
+  return lines.join('\n');
+}
+
+// One definition: what a describe_tools call returns, printed for a terminal or as JSON.
+export function renderDescription(command, requested, { examples = false, outputSchema = false, json = false } = {}) {
+  const props = command.inputSchema?.properties ?? {};
+  const required = new Set(command.inputSchema?.required ?? []);
+  const definition = {
+    name: command.name, ...(requested !== command.name ? { requestedAs: requested, note: `${requested} is a retired name; use ${command.name}.` } : {}),
+    toolset: command.toolset, tier: command.tier, readOnly: command.readOnly, scopes: command.scopes, description: command.description,
+    ...(command.admissionGated ? { admission: 'gated', note: 'Unavailable until an operator enables its supplier admission; calls return the configuration error.' } : {}),
+    ...(command.confirm && command.confirm !== 'none' ? { confirm: command.confirm } : {}),
+    inputSchema: command.inputSchema,
+    ...(outputSchema ? { outputSchema: command.outputSchema } : {}),
+    ...(examples && command.examples?.length ? { examples: command.examples } : {}),
+    ...(command.aliases?.length ? { aliases: command.aliases } : {}),
+    runWith: `agentlinkops call ${command.name} --args '{...}'`,
+  };
+  if (json) return JSON.stringify(definition, null, 2);
+  const lines = [`${command.name}  (${command.toolset}${command.tier === 'core' ? ', core' : ''}${command.readOnly ? ', read-only' : ', write'})`];
+  if (definition.note) lines.push(`note: ${definition.note}`);
+  lines.push(`scopes: ${command.scopes.join(' ')}`, '', command.description, '', 'parameters:');
+  if (!Object.keys(props).length) lines.push('  (none)');
+  for (const [key, schema] of Object.entries(props)) {
+    const type = schema.enum ? schema.enum.join('|') : schema.type ?? 'any';
+    const bounds = [schema.minimum !== undefined ? `min ${schema.minimum}` : null, schema.maximum !== undefined ? `max ${schema.maximum}` : null, schema.maxLength !== undefined ? `≤${schema.maxLength} chars` : null].filter(Boolean).join(', ');
+    lines.push(`  ${key}${required.has(key) ? '' : '?'}: ${type}${bounds ? ` (${bounds})` : ''}${schema.description ? `  ${schema.description}` : ''}`);
+  }
+  if (definition.examples) lines.push('', 'examples:', ...definition.examples.map(e => `  ${JSON.stringify(e)}`));
+  if (outputSchema) lines.push('', 'output schema:', JSON.stringify(command.outputSchema, null, 1));
+  if (definition.aliases) lines.push('', `also known as: ${definition.aliases.join(', ')}`);
+  lines.push('', `run: agentlinkops call ${command.name} --args '{...}'`);
+  return lines.join('\n');
+}
+
+// --set PATH=VALUE overlays: dotted paths, JSON values when they parse, strings otherwise.
+export function applySet(target, assignments) {
+  const result = structuredClone(target);
+  for (const assignment of assignments) {
+    const at = assignment.indexOf('=');
+    if (at <= 0) throw new ConfigError(`--set expects PATH=VALUE, got "${assignment}"`);
+    const path = assignment.slice(0, at).split('.').filter(Boolean);
+    const raw = assignment.slice(at + 1);
+    let value; try { value = JSON.parse(raw); } catch { value = raw; }
+    let cursor = result;
+    for (const key of path.slice(0, -1)) { if (typeof cursor[key] !== 'object' || cursor[key] === null) cursor[key] = {}; cursor = cursor[key]; }
+    cursor[path.at(-1)] = value;
+  }
+  return result;
+}
+
+const errorJson = (code, message, next) => JSON.stringify({ error: { code, message, next } });
+
+export async function commandsMain(argv, { cwd = process.cwd(), env = process.env, out = console.log, err = console.error, fetchImpl = globalThis.fetch, isTTY = process.stdout.isTTY === true } = {}) {
+  const flags = new Set(argv.filter(a => a === '-y' || a === '--yes'));
+  const args = parseArgs(argv.filter(a => a !== '-y' && a !== '--yes'), ['set']);
+  const [command, name] = args._;
+  const json = args.json === true || !isTTY;
+  const fail = (code, message) => { if (json) err(errorJson(code, message, explain(code))); else err(`${message}\n${explain(code)}`); return 2; };
+  const allowed = { tools: ['_', 'json', 'refresh'], describe: ['_', 'json', 'refresh', 'examples', 'output-schema'], call: ['_', 'args', 'file', 'set', 'dry-run', 'json'] };
+  if (!allowed[command] || Object.keys(args).some(key => !allowed[command].includes(key)) || (command === 'tools' && args._.length > 2) || (command !== 'tools' && (args._.length !== 2 || !NAME.test(name)))) throw new ConfigError(USAGE);
+  if (args.set?.length && (args.set.some(v => typeof v !== 'string') || args.args !== undefined || args.file !== undefined)) throw new ConfigError('--set cannot be combined with --args or --file');
+  if (args.args !== undefined && args.file !== undefined) throw new ConfigError(USAGE);
+
+  // Arguments are validated before any configuration or network is touched.
+  let input = {};
+  if (command === 'call') {
+    if (args.args !== undefined || args.file !== undefined) {
+      if ((args.args !== undefined && typeof args.args !== 'string') || (args.file !== undefined && typeof args.file !== 'string')) throw new ConfigError('Provide a JSON object or a file path.');
+      try { input = JSON.parse(args.file ? await readFile(resolve(cwd, args.file), 'utf8') : args.args); }
+      catch { throw new ConfigError('Cannot read command arguments as JSON.'); }
+      if (!input || Array.isArray(input) || typeof input !== 'object') throw new ConfigError('Command arguments must be a JSON object.');
+    }
+    if (args.set?.length) input = applySet(input, args.set);
+  }
+
+  // Catalog: bundled snapshot, or the live one when asked (needs a configured origin and key).
+  let commands = CATALOG_COMMANDS, client = null;
+  const connect = () => {
+    const connection = cloudConnection(loadConfigSync(), env);
+    if (!connection.origin) throw new CloudError('NO_CLOUD_ORIGIN', 0);
+    let origin;
+    try { origin = new URL(connection.origin); } catch { throw new CloudError('INVALID_CLOUD_ORIGIN', 0); }
+    if (origin.protocol !== 'https:' || origin.username || origin.password || origin.pathname !== '/' || origin.search || origin.hash) throw new CloudError('INVALID_CLOUD_ORIGIN', 0);
+    return createClient({ ...connection, fetchImpl });
+  };
+  let loaded = null;
+  const loadConfigSync = () => loaded;
+  const needsConfig = args.refresh === true || command === 'call';
+  if (needsConfig) loaded = await loadConfig({ cwd });
+  if (args.refresh === true) {
+    try {
+      client = connect();
+      const live = await client.listCommands();
+      commands = live.items.map(item => ({ ...item, readOnly: item.annotations?.readOnlyHint === true, admissionGated: false }));
+    } catch (error) {
+      if (error instanceof CloudError) return fail(error.code, `catalog refresh: ${error.code}${error.status ? ` (${error.status})` : ''}`);
+      throw error;
+    }
+  }
+
+  if (command === 'tools') {
+    const toolset = args._[1] ?? null;
+    if (toolset && !commands.some(c => c.toolset === toolset)) return fail('TOOLSET_NOT_FOUND', `No toolset named ${toolset}. Toolsets: ${[...new Set(commands.map(c => c.toolset))].sort().join(', ')}.`);
+    out(renderIndex(commands, { toolset, json }));
+    // DP-0037-T05: the index is the discovery moment; a person at a terminal gets one line on
+    // stderr pointing at the reference. A JSON reader (an agent piping the index) gets nothing
+    // extra: the stub skill already sent it to the reference, and stderr stays error objects.
+    if (!json) err(NUDGE);
+    return 0;
+  }
+  if (command === 'describe') {
+    const found = resolveName(commands, name);
+    if (!found) return fail('TOOL_NOT_FOUND', `No command named ${name}.`);
+    out(renderDescription(found, name, { examples: args.examples === true, outputSchema: args['output-schema'] === true, json }));
+    return 0;
+  }
+
+  // call
+  const found = resolveName(commands, name);
+  const canonical = found?.name ?? name;
+  if (args['dry-run'] === true) {
+    const plan = { dryRun: true, command: canonical, ...(canonical !== name ? { requestedAs: name } : {}), arguments: input,
+      ...(found ? { scopes: found.scopes, readOnly: found.readOnly, ...(found.confirm && found.confirm !== 'none' ? { confirm: found.confirm } : {}) } : { note: 'Not in the bundled catalog; the cloud decides.' }),
+      next: found?.readOnly === false && !flags.has('-y') && !flags.has('--yes') ? 'This command writes; run again without --dry-run (add -y to answer confirmations).' : 'Run again without --dry-run to send it.' };
+    out(JSON.stringify(plan, null, 2));
+    return 0;
+  }
+  try {
+    client ??= connect();
+    const result = await client.callCommand(canonical, input);
+    out(JSON.stringify(result, null, 2));
+    return 0;
+  } catch (error) {
+    if (error instanceof CloudError) return fail(error.code, `${canonical}: ${error.code}${error.status ? ` (${error.status})` : ''}${error.details ? ` ${JSON.stringify(error.details)}` : ''}`);
+    throw error;
+  }
+}

package/cli/config.js

@@ -0,0 +1,104 @@
+// Where the ledger lives, and everything else the CLI needs to know.
+//
+// Every path is configurable and every default is named here. The product direction is
+// opinionated about truth and about the fetch boundary, and explicitly not about where a
+// customer keeps their files — so the config is read before anything else is.
+//
+// The directory has two names for the pilot compatibility window (DP-0029-T03). `.agentlinkops/`
+// is the default; `.linktrail/` is read transparently when the new directory is absent, with one
+// hint per process pointing at `agentlinkops migrate`. Nothing here moves files: a directory
+// rename in a customer's repository is an explicit command with a receipt, never a side effect
+// of reading.
+import { readFile, stat } from 'node:fs/promises';
+import { resolve, dirname, join } from 'node:path';
+
+export const LEGACY_DIR = '.linktrail';
+
+export const DEFAULTS = Object.freeze({
+  dir: '.agentlinkops',
+  ledger: 'links.jsonl',
+  receipts: 'receipts.jsonl',
+  observations: 'observations.jsonl',
+  events: 'events.jsonl',
+  candidates: 'candidates.jsonl',
+  state: 'state.json',
+  // A courtesy floor between two requests to the same host. The verifier REFUSES any host
+  // stating a robots crawl delay unless a pacing hook is supplied, so a CLI without one would
+  // report our own omission as the publisher's fault.
+  hostDelayMs: 2000,
+  concurrency: 6,
+  timeoutMs: 20_000,
+});
+
+/** Both spellings, preferred first. Any config or state that names the directory accepts both. */
+export const DIR_NAMES = Object.freeze([DEFAULTS.dir, LEGACY_DIR]);
+
+export class ConfigError extends Error {
+  constructor(message) { super(message); this.name = 'ConfigError'; this.exitCode = 2; }
+}
+
+// Compatibility notices (the legacy-directory hint here, the LINKTRAIL_* warnings in env.js) go
+// to one sink, once per process per subject, so a command that loads the config in three places
+// does not say the same thing three times.
+const noticed = new Set();
+let noticeSink = message => console.error(message);
+export function setNoticeSink(sink) { noticeSink = typeof sink === 'function' ? sink : message => console.error(message); }
+export function resetCompatibilityNotices() { noticed.clear(); }
+export function noticeOnce(key, message) {
+  if (noticed.has(key)) return false;
+  noticed.add(key);
+  noticeSink(message);
+  return true;
+}
+
+export const migrateHint = dir => `${dir} uses the old directory name; run \`agentlinkops migrate\` to rename it to ${DEFAULTS.dir}/ (nothing is moved until you do).`;
+
+const isDirectory = path => stat(path).then(info => info.isDirectory(), () => false);
+
+/**
+ * Which directory name is in use under `base`: the preferred one when it exists, the legacy one
+ * when only it exists, and the preferred one (not yet created) otherwise.
+ */
+export async function resolveDirName(base) {
+  if (await isDirectory(join(base, DEFAULTS.dir))) return { name: DEFAULTS.dir, legacy: false, exists: true };
+  if (await isDirectory(join(base, LEGACY_DIR))) return { name: LEGACY_DIR, legacy: true, exists: true };
+  return { name: DEFAULTS.dir, legacy: false, exists: false };
+}
+
+/** Finds the ledger directory from `from` upwards, the way git finds its own root. */
+export async function findRoot(from = process.cwd(), dir = null) {
+  let current = resolve(from);
+  const names = dir ? [dir] : DIR_NAMES;
+  for (;;) {
+    for (const name of names) {
+      try {
+        await readFile(join(current, name, DEFAULTS.ledger));
+        return current;
+      } catch { /* keep walking */ }
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+export async function loadConfig({ cwd = process.cwd(), root = null } = {}) {
+  const base = root ?? await findRoot(cwd) ?? cwd;
+  const which = await resolveDirName(base);
+  const dir = join(base, which.name);
+  if (which.legacy) noticeOnce(`legacy-dir:${dir}`, migrateHint(dir));
+  let file = {};
+  try { file = JSON.parse(await readFile(join(dir, 'config.json'), 'utf8')); }
+  catch (error) { if (error.code !== 'ENOENT') throw new ConfigError(`config.json is not valid JSON: ${error.message}`); }
+  const paths = { ...DEFAULTS, ...file.paths };
+  const at = name => resolve(dir, paths[name]);
+  return {
+    root: base, dir, dirName: which.name, legacyDir: which.legacy,
+    project: file.project ?? null, cloud: file.cloud ?? null,
+    defaults: { ...DEFAULTS, ...file.defaults },
+    paths: {
+      ledger: at('ledger'), observations: at('observations'), events: at('events'),
+      candidates: at('candidates'), state: at('state'), receipts: at('receipts'),
+    },
+  };
+}