@inneranimalmedia/agentsam-sdk 2.6.5 → 2.6.7

package/src/cli/command-catalog.js

@@ -3,7 +3,7 @@
  * Alias ≠ authority: skill tips and SAM operation ids live here so help is not a prose-only dump.
  */
 
-/** @typedef {{ id: string, aliases?: string[], summary: string, topic: string, skill?: string, operation?: string, common?: boolean }} CliCommandEntry */
+/** @typedef {{ id: string, aliases?: string[], summary: string, topic: string, skill?: string, operation?: string, common?: boolean, usage?: string[], options?: Array<{ flag: string, description: string }> }} CliCommandEntry */
 
 /** @type {CliCommandEntry[]} */
 export const CLI_COMMAND_CATALOG = Object.freeze([
@@ -13,11 +13,36 @@ export const CLI_COMMAND_CATALOG = Object.freeze([
   { id: 'plugins', summary: 'Install and manage AgentSam plugins', topic: 'create', skill: 'agentsam-app-fundamentals' },
   { id: 'dev', summary: 'Run this project’s npm dev script', topic: 'work', skill: 'agentsam-app-fundamentals' },
   { id: 'inspect', summary: 'Bounded repository inspect / authority view', topic: 'work', skill: 'agentsam-app-fundamentals', operation: 'repository.inspect', common: true },
+  { id: 'machine', summary: 'Deterministic local machine perception (inspect / asset discovery)', topic: 'work', skill: 'agentsam-app-fundamentals', operation: 'machine.inspect', common: true },
   { id: 'capabilities', summary: 'Inspect capability contracts', topic: 'create', skill: 'agentsam-app-fundamentals' },
-  { id: 'setup', summary: 'Discover → plan → approve → install capabilities (Homebrew-style)', topic: 'start', skill: 'agentsam-app-fundamentals', common: true },
+  {
+    id: 'setup',
+    summary: 'Discover → plan → approve → install capabilities (Homebrew-style)',
+    topic: 'start',
+    skill: 'agentsam-app-fundamentals',
+    common: true,
+    usage: [
+      'agentsam setup [capability-id] [--dry-run|--yes]',
+      'agentsam setup runtime [--profile <id>] [--dry-run|--yes]',
+      'agentsam setup --list',
+    ],
+  },
   { id: 'skills', aliases: ['skill'], summary: 'List or load portable skill instructions', topic: 'create', skill: 'agentsam-app-fundamentals', common: true },
   { id: 'context', summary: 'Git + bridge context from any repo', topic: 'work', skill: 'agentsam-app-fundamentals' },
-  { id: 'status', summary: 'Account, models, terminal, and live deploy awareness', topic: 'runtime', skill: 'agentsam-progression-guard', common: true },
+  {
+    id: 'status',
+    summary: 'Account, models, terminal, and live deploy awareness',
+    topic: 'runtime',
+    skill: 'agentsam-progression-guard',
+    common: true,
+    usage: ['agentsam status [--offline] [--no-discover] [--json] [-i|--interactive]'],
+    options: [
+      { flag: '--offline', description: 'Skip network-dependent status probes.' },
+      { flag: '--no-discover', description: 'Skip provider model discovery.' },
+      { flag: '--json', description: 'Emit the machine-readable status + next-action plan.' },
+      { flag: '-i, --interactive', description: 'Open the interactive next-action menu.' },
+    ],
+  },
   { id: 'db', summary: 'Project-local SQLite status/init', topic: 'runtime', skill: 'agentsam-app-fundamentals' },
   { id: 'models', summary: 'Probe hosted/local model availability', topic: 'start', skill: 'agentsam-app-fundamentals', common: true },
   { id: 'providers', summary: 'Configure machine provider credentials', topic: 'start', skill: 'agentsam-app-fundamentals' },
@@ -47,7 +72,24 @@ export const CLI_COMMAND_CATALOG = Object.freeze([
   { id: 'eval', summary: 'Context fixtures and live eval telemetry', topic: 'runtime', skill: 'agentsam-app-fundamentals' },
   { id: 'index', summary: 'Plan/run incremental AST (+ optional embeddings)', topic: 'work', skill: 'agentsam-codebaseindex', operation: 'codebaseindex.ingest' },
   { id: 'search', summary: 'Retrieve indexed code/text', topic: 'work', skill: 'agentsam-codebaseindex' },
-  { id: 'repo', summary: 'Repository snapshot / observations', topic: 'work', skill: 'agentsam-app-fundamentals', operation: 'repository.inspect' },
+  {
+    id: 'repo',
+    summary: 'Repository snapshot / observations',
+    topic: 'work',
+    skill: 'agentsam-app-fundamentals',
+    operation: 'repository.inspect',
+    usage: [
+      'agentsam repo [snapshot] [--cwd <path>] [--churn-days <days>] [--save] [--json]',
+      'agentsam repo history [--cwd <path>]',
+      'agentsam repo compare [--cwd <path>]',
+    ],
+    options: [
+      { flag: '--json', description: 'Emit the full deterministic repository-intelligence receipt.' },
+      { flag: '--save', description: 'Persist the observation for history/compare.' },
+      { flag: '--churn-days <days>', description: 'Set the Git churn window (1..3650).' },
+      { flag: '--cwd <path>', description: 'Inspect another repository root.' },
+    ],
+  },
   { id: 'init', summary: 'Knowledge setup or local scaffold', topic: 'create', skill: 'agentsam-app-fundamentals' },
   { id: 'codebaseindex', aliases: ['ingest', 'codebase-index'], summary: 'Guided codebase ingest: materials, allowlist, embeddings, storage', topic: 'work', skill: 'agentsam-codebaseindex', operation: 'codebaseindex.ingest', common: true },
   { id: 'brand', summary: 'Deterministic brand intelligence', topic: 'work', skill: 'agentsam-app-fundamentals', operation: 'brand.scan' },

package/src/cli/dispatch.js

@@ -10,6 +10,7 @@ const HANDLERS = {
   codebaseindex: async () => (await import('../commands/codebaseindex.js')).runCodebaseindex,
   ingest: async () => (await import('../commands/codebaseindex.js')).runCodebaseindex,
   'codebase-index': async () => (await import('../commands/codebaseindex.js')).runCodebaseindex,
+  machine: async () => (await import('../commands/machine.js')).runMachine,
   skill: async () => (await import('../commands/skill.js')).runSkill,
   skills: async () => (await import('../commands/skills.js')).runSkills,
 };

package/src/cli.js

@@ -33,6 +33,7 @@ import { runDeployReceipt } from './commands/deploy-receipt.js';
 import { runSecurity } from './commands/security.js';
 import { runRecon } from './commands/recon.js';
 import { runCad } from './commands/cad.js';
+import { runMachine } from './commands/machine.js';
 import { runSkills } from './commands/skills.js';
 import { runSkill } from './commands/skill.js';
 import { runEval } from './commands/eval.js';
@@ -95,6 +96,7 @@ function printLegacyHelp() {
     agentsam plugins list|install|connect|status|remove [@agentsam-mcp]
     agentsam dev               Run this project's existing npm dev script
     agentsam inspect [--json]  Bounded repository index by default; use --view full for authority envelope
+    agentsam machine inspect   Native deterministic perception + asset discovery (--json)
     agentsam brand [scan|…]    Deterministic brand intelligence on repository.snapshot authority
     agentsam plan brand        Composable brand normalization plan (--goap optional)
     agentsam deploy            Graduate an AgentSam project intentionally
@@ -450,6 +452,14 @@ if (command === '--version' || command === '-v') {
 } else if (command === 'inspect') {
   try { await runInspect(rest); }
   catch (e) { reportCliError(e); process.exitCode = 1; }
+} else if (command === 'machine') {
+  try {
+    const code = await runMachine(rest);
+    if (typeof code === 'number' && code !== 0) process.exitCode = code;
+  } catch (e) {
+    reportCliError(e);
+    process.exitCode = e?.exitCode || 1;
+  }
 } else if (command === 'capabilities') {
   try { await runCapabilities(rest); }
   catch (e) { reportCliError(e); process.exitCode = 1; }

package/src/cloudflare/runtime-status.js

@@ -37,7 +37,7 @@ function parseJsonc(source) {
 }
 
 export function parseWranglerToml(source = '') {
-  const result = { vars: {}, d1_databases: [], r2_buckets: [], hyperdrive: [], kv_namespaces: [], services: [] };
+  const result = { vars: {}, d1_databases: [], r2_buckets: [], hyperdrive: [], kv_namespaces: [], services: [], vectorize: [] };
   const lines = source.split(/\r?\n/);
   let currentSection = '';
   let currentBlock = null;
@@ -55,6 +55,7 @@ export function parseWranglerToml(source = '') {
       else if (currentSection === 'hyperdrive') result.hyperdrive.push(currentBlock);
       else if (currentSection === 'kv_namespaces') result.kv_namespaces.push(currentBlock);
       else if (currentSection === 'services') result.services.push(currentBlock);
+      else if (currentSection === 'vectorize') result.vectorize.push(currentBlock);
       continue;
     }
 

package/src/commands/autorag.js

@@ -2,10 +2,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { createInterface } from 'node:readline/promises';
-import { repositoryRoot, readConfig, validateConfig, CONFIG_PATH } from '../knowledge/config.js';
+import { repositoryRoot, readConfig, validateConfig, defaultConfig, scopeKey, CONFIG_PATH } from '../knowledge/config.js';
 import { openSqliteStore } from '../knowledge/stores/sqlite.js';
 import { openPostgresStore } from '../knowledge/stores/postgres.js';
 import { planIndex, runIndex, retrieve } from '../knowledge/engine.js';
+import { discoverKnowledgeRuntime } from '../knowledge/runtime-discovery.js';
+import { getRepositoryId, portableRepositoryIdFromGit, tryReadProjectConfig } from '../lib/project-config.js';
 import { discoverAutoRag, recommendAutoRag, safeAutoRagConfig, runAutoRagProbe, createProviderRegistry, createBackendRegistry } from '../../packages/agentsam-knowledge/src/index.js';
 
 const show = value => console.log(JSON.stringify(value, null, 2));
@@ -16,6 +18,12 @@ const parse = argv => parseArgs({ args: argv, allowPositionals: true, options: {
   kind: { type: 'string' }, scope: { type: 'string' }, provider: { type: 'string' }, backend: { type: 'string' }, model: { type: 'string' }, dimensions: { type: 'string' }, semantic: { type: 'boolean' }, 'allow-paid': { type: 'boolean' }, query: { type: 'string' },
 } });
 function readExisting(root) { try { return readConfig(root); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } }
+function generationConfig(root, existing) {
+  if (existing) return existing;
+  const project = tryReadProjectConfig(root);
+  const repositoryId = getRepositoryId(project) || portableRepositoryIdFromGit(root);
+  return repositoryId ? defaultConfig({ repositoryId }) : null;
+}
 function writeConfig(root, config) {
   const filename = path.join(root, CONFIG_PATH); fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
   const safe = JSON.stringify(validateConfig(config), null, 2) + '\n';
@@ -28,10 +36,20 @@ function adapterFor(config) {
   return { validate: profile => adapter.validate(profile), async embed(text, profile, context) { return context?.kind === 'query' ? adapter.embedQuery(text, profile, context) : (await adapter.embedDocuments([text], profile, context))[0]; } };
 }
 async function storeFor(root, config, readOnly = false) { return config.storage.driver === 'sqlite' ? openSqliteStore(localPath(root), { readOnly }) : openPostgresStore(process.env[config.storage.connection_env]); }
-function defaults(discovery, opts, existing) {
+function defaults(discovery, opts, existing, runtime) {
   const purpose = opts.kind || existing?.scope?.name || 'code';
-  const recommendation = recommendAutoRag({ discovery, purpose, include: opts.scope ? split(opts.scope) : existing?.scope?.include, provider: opts.provider || 'none', backend: opts.backend || existing?.lane?.backend || 'local_exact', semantic: Boolean(opts.semantic) });
+  const declaredVectorize = (runtime?.cloudflare?.vectorize || []).filter(row => row.binding && row.index);
+  const adoptVectorize = !opts.backend && !existing?.lane?.backend && declaredVectorize.length === 1;
+  const backend = opts.backend || existing?.lane?.backend || (adoptVectorize ? 'cloudflare_vectorize' : 'local_exact');
+  const recommendation = recommendAutoRag({ discovery, purpose, include: opts.scope ? split(opts.scope) : existing?.scope?.include, provider: opts.provider || 'none', backend, semantic: Boolean(opts.semantic) });
   const config = safeAutoRagConfig({ existing: existing || {}, recommendation, repositoryId: existing?.repository_id || discovery.repository.identity, projectKey: existing?.project_key || discovery.repository.identity });
+  if (adoptVectorize) {
+    const resource = declaredVectorize[0];
+    config.lane.id = `${purpose}-cloudflare-vectorize`;
+    config.lane.backend = 'cloudflare_vectorize';
+    config.lane.binding = resource.binding;
+    config.lane.index = resource.index;
+  }
   if (opts.provider) {
     const models = { fixture: 'deterministic', gemini: 'gemini-embedding-2', openai: 'text-embedding-3-small', 'workers-ai': '@cf/baai/bge-base-en-v1.5', ollama: 'nomic-embed-text' };
     config.embedding = opts.provider === 'none' ? { provider: 'none', model: 'none', revision: '1', dimensions: 0, parameters: {} } : { provider: opts.provider, model: opts.model || models[opts.provider] || '', revision: '1', dimensions: Number(opts.dimensions || (opts.provider === 'fixture' ? 3 : 768)), parameters: { task: 'code retrieval' } };
@@ -43,7 +61,7 @@ async function interactiveOptions(discovery, opts) {
   const prompt = createInterface({ input: process.stdin, output: process.stdout });
   try {
     const kind = opts.kind || await prompt.question('What kind of knowledge? code, documents, schema, media, memory, mixed [code]: ') || 'code';
-    const suggested = kind === 'code' ? discovery.scopes.filter(scope => ['packages', 'src'].includes(scope)).join(',') : discovery.scopes.filter(scope => /docs|README|schema|migrations/.test(scope)).join(',');
+    const suggested = recommendAutoRag({ discovery, purpose: kind }).scope.join(',');
     const scope = opts.scope || await prompt.question(`Sources (literal paths, comma separated) [${suggested || '.'}]: `) || suggested || '.';
     const semantic = opts.semantic || (await prompt.question('Enable semantic embeddings for this setup? [no]: ')).toLowerCase() === 'yes';
     const provider = opts.provider || (semantic ? await prompt.question('Provider: fixture, gemini, openai, workers-ai, ollama [fixture]: ') || 'fixture' : 'none');
@@ -55,18 +73,54 @@ export async function runAutoRag(argv) {
   if (opts.help || !['setup', 'status', 'doctor', 'lanes', 'configure', 'probe', 'providers', 'backends', 'scope'].includes(command)) {
     console.log('agentsam autorag setup|status|doctor|lanes|configure|probe|providers|backends|scope [--cwd PATH] [--yes] [--kind code|documents|schema|media|memory|mixed] [--scope a,b] [--provider none|fixture|gemini|openai|workers-ai|ollama] [--backend local_exact|postgres_pgvector|supabase_pgvector|cloudflare_vectorize] [--semantic]'); return;
   }
-  const root = repositoryRoot(opts.cwd); const discovery = await discoverAutoRag({ root }); const existing = readExisting(root);
-  if (command === 'providers') return show(await createProviderRegistry().capabilities());
-  if (command === 'backends') return show(createBackendRegistry().capabilities());
-  if (command === 'status') return show({ discovery, config: existing || null, generation: existing ? await (async () => { const store = await storeFor(root, existing, true); try { return await store?.active((await import('../knowledge/config.js')).scopeKey(existing)); } finally { await store?.close(); } })() : null });
+  const root = repositoryRoot(opts.cwd); const discovery = await discoverAutoRag({ root }); const existing = readExisting(root); const runtime = discoverKnowledgeRuntime(root, { knowledgeConfig: existing });
+  if (command === 'providers') {
+    const providers = await createProviderRegistry().capabilities();
+    const workersAi = runtime.resources.workers_ai;
+    return show(providers.map(item => item.id === 'workers-ai'
+      ? { ...item, runtime_configured: workersAi.configured, runtime_binding: workersAi.binding, locally_executable: workersAi.locally_executable, remotely_executable: workersAi.remotely_executable, credential_state: workersAi.credential_state }
+      : item));
+  }
+  if (command === 'backends') {
+    const backends = createBackendRegistry().capabilities();
+    const vectorize = runtime.resources.vectorize;
+    return show(backends.map(item => item.id === 'cloudflare_vectorize'
+      ? { ...item, declared_resources: vectorize, locally_executable: vectorize.some(row => row.locally_executable), remotely_executable: vectorize.some(row => row.remotely_executable), conflicts: runtime.conflicts }
+      : item));
+  }
+  if (command === 'status') {
+    const generationProfile = runtime.local_index.exists ? generationConfig(root, existing) : null;
+    const generation = generationProfile ? await (async () => {
+      const store = await storeFor(root, generationProfile, true);
+      try { return await store?.active(scopeKey(generationProfile)); }
+      finally { await store?.close(); }
+    })() : null;
+    return show({ discovery, config: existing || null, project_context: runtime, runtime, generation });
+  }
   if (command === 'doctor') {
-    const checks = [{ check: 'knowledge_config', ok: Boolean(existing), detail: existing ? CONFIG_PATH : 'Run agentsam autorag setup.' }, { check: 'local_sqlite', ok: true }, { check: 'git_merkle', ok: discovery.capabilities.git }];
-    if (existing?.embedding?.provider !== 'none') { try { adapterFor(existing).validate(existing.embedding); checks.push({ check: `provider:${existing.embedding.provider}`, ok: true }); } catch (error) { checks.push({ check: `provider:${existing.embedding.provider}`, ok: false, detail: error.message }); } }
-    return show({ ok: checks.every(check => check.ok), checks });
+    const hasRuntimeLane = runtime.lanes.some(lane => lane.configured);
+    const checks = [
+      { check: 'knowledge_authority', ok: Boolean(existing) || hasRuntimeLane, detail: existing ? CONFIG_PATH : hasRuntimeLane ? 'Detected repository knowledge runtime.' : 'No local config or declared runtime lane found.' },
+      { check: 'local_sqlite', ok: runtime.local_index.exists, blocking: false, detail: runtime.local_index.exists ? runtime.local_index.path : 'Not indexed yet; run agentsam index run or agentsam autorag probe.' },
+      { check: 'git_merkle', ok: discovery.repository.merkle, blocking: false, detail: discovery.repository.merkle ? '.agentsam/merkle.json' : 'No Merkle snapshot yet; run agentsam merkle root . --json when snapshot evidence is needed.' },
+    ];
+    if (existing?.embedding && existing.embedding.provider !== 'none') {
+      try { adapterFor(existing).validate(existing.embedding); checks.push({ check: 'provider:' + existing.embedding.provider, ok: true }); }
+      catch (error) { checks.push({ check: 'provider:' + existing.embedding.provider, ok: false, detail: error.message }); }
+    }
+    if (runtime.resources.vectorize.length) checks.push({ check: 'cloudflare_vectorize', ok: runtime.conflicts.length === 0 && runtime.resources.vectorize.every(row => row.configured && (row.locally_executable || row.remotely_executable)), detail: runtime.resources.vectorize });
+    if (runtime.resources.workers_ai.observed) checks.push({ check: 'workers_ai_runtime', ok: runtime.resources.workers_ai.remotely_executable || runtime.resources.workers_ai.locally_executable, detail: runtime.resources.workers_ai });
+    if (runtime.conflicts.length) checks.push({ check: 'project_context_conflicts', ok: false, detail: runtime.conflicts });
+    return show({ ok: checks.filter(check => check.blocking !== false).every(check => check.ok), checks, project_context: runtime, runtime });
+  }
+  if (command === 'lanes') {
+    const configured = existing ? [existing.lane || { id: 'legacy-local', backend: existing.storage.driver === 'sqlite' ? 'local_exact' : 'postgres_pgvector', source: CONFIG_PATH }] : [];
+    const laneKey = lane => [lane.backend, lane.binding || '', lane.index || ''].join(':');
+    const seen = new Set(configured.map(laneKey));
+    return show([...configured, ...runtime.lanes.filter(lane => !seen.has(laneKey(lane)))]);
   }
-  if (command === 'lanes') return show(existing ? [existing.lane || { id: 'legacy-local', backend: existing.storage.driver === 'sqlite' ? 'local_exact' : 'postgres_pgvector' }] : []);
   if (command === 'setup' || command === 'configure' || command === 'scope') {
-    const selected = opts.yes ? opts : await interactiveOptions(discovery, opts); const { recommendation, config } = defaults(discovery, selected, existing);
+    const selected = opts.yes ? opts : await interactiveOptions(discovery, opts); const { recommendation, config } = defaults(discovery, selected, existing, runtime);
     writeConfig(root, config); return show({ action: command, config: CONFIG_PATH, recommendation, config, next: ['agentsam autorag probe', 'agentsam index plan', 'agentsam index run', 'agentsam search "symbol or phrase"'] });
   }
   if (!existing) throw new Error('AutoRAG is not configured. Run agentsam autorag setup first.');

package/src/commands/cheat-sheet.js

@@ -1,6 +1,7 @@
 /**
  * Canonical Agent Sam cheat-sheet — gcloud-like command groups.
  * Old top-level commands remain as compatibility aliases.
+ * Every row shows a copy-pasteable `agentsam …` invocation.
  */
 
 const GROUPS = Object.freeze([
@@ -19,8 +20,13 @@ const GROUPS = Object.freeze([
     label: 'Repository',
     commands: [
       ['inspect', 'Bounded repository authority view'],
+      ['machine', 'Deterministic local perception + asset discovery'],
+      ['machine inspect', 'Inspect a path (file or directory)'],
       ['recon', 'Bounded-worker finding packets'],
       ['codebaseindex', 'AST ingest + optional embeddings'],
+      ['index', 'Project inventory + knowledge index commands'],
+      ['index status', 'Show knowledge index freshness'],
+      ['search', 'Retrieve from the local knowledge index'],
       ['merkle', 'Integrity snapshots'],
       ['security', 'Dependency + trust-boundary scan'],
     ],
@@ -103,16 +109,30 @@ const GROUPS = Object.freeze([
       ['update', 'Component update preview (gcloud-like)'],
       ['billing', 'Billing account relationships (not --billing-project)'],
       ['cheat-sheet', 'This page'],
-      ['version', 'agentsam --version'],
+      ['version', 'Print CLI version'],
     ],
   },
 ]);
 
+/** Expand "a / b" rows into copy-pasteable `agentsam …` invocations. */
+export function agentsamInvocations(cmd) {
+  const raw = String(cmd || '').trim();
+  if (!raw) return [];
+  if (raw.includes(' / ')) {
+    return raw.split(' / ').map((part) => `agentsam ${part.trim()}`);
+  }
+  return [`agentsam ${raw}`];
+}
+
 export function listCheatSheetGroups() {
   return GROUPS.map((group) => ({
     id: group.id,
     label: group.label,
-    commands: group.commands.map(([cmd, summary]) => ({ cmd, summary })),
+    commands: group.commands.map(([cmd, summary]) => ({
+      cmd,
+      summary,
+      invocations: agentsamInvocations(cmd),
+    })),
   }));
 }
 
@@ -120,13 +140,18 @@ export function renderCheatSheet(version) {
   const lines = [
     '',
     `  Agent Sam cheat-sheet${version ? ` · v${version}` : ''}`,
-    '  Organized hierarchy · old top-level commands remain compatibility aliases.',
+    '  Organized hierarchy · each row shows a runnable `agentsam …` command.',
     '',
   ];
   for (const group of GROUPS) {
     lines.push(`  ${group.label}`);
     for (const [cmd, summary] of group.commands) {
-      lines.push(`    ${String(cmd).padEnd(42)}  ${summary}`);
+      const invocations = agentsamInvocations(cmd);
+      const primary = invocations[0] || `agentsam ${cmd}`;
+      lines.push(`    ${primary.padEnd(52)}  ${summary}`);
+      for (const extra of invocations.slice(1)) {
+        lines.push(`    ${extra.padEnd(52)}  (same group)`);
+      }
     }
     lines.push('');
   }

package/src/commands/codebaseindex.js

@@ -16,6 +16,8 @@ import { openSqliteStore } from '../knowledge/stores/sqlite.js';
 import { openPostgresStore } from '../knowledge/stores/postgres.js';
 import { planIndex, retrieve, runIndex } from '../knowledge/engine.js';
 import { createProviderRegistry } from '../../packages/agentsam-knowledge/src/providers/index.js';
+import { createBackendRegistry } from '../../packages/agentsam-knowledge/src/backends/index.js';
+import { discoverProjectContext } from '../knowledge/runtime-discovery.js';
 import { ensureProjectManifest, getRepositoryId, portableRepositoryIdFromGit, tryReadProjectConfig } from '../lib/project-config.js';
 import { parsePastedPaths, stageMaterials } from '../indexing/ingest/materials.js';
 import {
@@ -74,6 +76,21 @@ function writeKnowledgeConfig(root, config) {
   return validated;
 }
 
+function resolveVectorLane(root, vectors, input = {}) {
+  if (vectors !== 'vectorize') return null;
+  const explicitBinding = String(input.vectorBinding || input.binding || '').trim();
+  const explicitIndex = String(input.vectorIndex || input.index || '').trim();
+  if (explicitBinding || explicitIndex) {
+    if (!explicitBinding || !explicitIndex) throw new Error('Vectorize requires both vectorBinding and vectorIndex when either is supplied.');
+    return { backend: 'cloudflare_vectorize', binding: explicitBinding, index: explicitIndex };
+  }
+  const context = discoverProjectContext(root);
+  const resources = context.resources.vectorize.filter(row => row.configured);
+  if (resources.length === 1) return { backend: 'cloudflare_vectorize', binding: resources[0].binding, index: resources[0].index };
+  if (!resources.length) throw new Error('No Cloudflare Vectorize binding is declared by this project. Configure Wrangler or pass vectorBinding/vectorIndex explicitly.');
+  throw new Error('Multiple Cloudflare Vectorize bindings are declared. Select vectorBinding/vectorIndex explicitly.');
+}
+
 function loadOrBuildConfig(root, preferences) {
   const project = tryReadProjectConfig(root) || ensureProjectManifest(root, {});
   const repositoryId = getRepositoryId(project) || portableRepositoryIdFromGit(root) || preferences.repositoryId;
@@ -103,7 +120,14 @@ function loadOrBuildConfig(root, preferences) {
     storage: preferences.storage === 'postgres'
       ? { driver: 'postgres', connection_env: preferences.connectionEnv || 'AGENTSAM_DATABASE_URL' }
       : { driver: 'sqlite' },
-    lane: {
+    lane: preferences.vectorLane ? {
+      id: `${preferences.scopeName || 'default'}-cloudflare-vectorize`,
+      backend: 'cloudflare_vectorize',
+      resource: null,
+      binding: preferences.vectorLane.binding,
+      index: preferences.vectorLane.index,
+      metric: 'cosine',
+    } : {
       id: `${preferences.scopeName || 'default'}-ingest`,
       backend: preferences.storage === 'postgres' ? 'postgres_pgvector' : 'local_exact',
       resource: null,
@@ -172,11 +196,13 @@ export async function runCodebaseindexIngest(input = {}, ctx = {}) {
   const vectors = input.vectors || (embedding.provider === 'none' ? 'none'
     : storage === 'postgres' ? 'pgvector' : 'sqlite_exact');
 
+  const vectorLane = resolveVectorLane(root, vectors, input);
   const config = loadOrBuildConfig(root, {
     include,
     exclude,
     embedding,
     storage,
+    vectorLane,
     scopeName: input.scope || 'ingest',
     connectionEnv: input.connectionEnv,
   });
@@ -185,6 +211,9 @@ export async function runCodebaseindexIngest(input = {}, ctx = {}) {
   jobGraph = advanceJobGraph(jobGraph, 'lane.resolve');
 
   const embed = Boolean(input.embed) && embedding.provider !== 'none';
+  if (vectors === 'vectorize' && !embed && !input.planOnly) {
+    throw new Error('Cloudflare Vectorize execution requires an embedding provider and embed=true. Use planOnly to inspect the lane without writing vectors.');
+  }
   const store = await openStore(root, config, false);
   try {
     if (input.planOnly) {
@@ -214,12 +243,26 @@ export async function runCodebaseindexIngest(input = {}, ctx = {}) {
       validate: (...args) => (adapter ??= providerAdapter(config.embedding)).validate(...args),
       embed: (...args) => (adapter ??= providerAdapter(config.embedding)).embed(...args),
     };
+    const vectorBackend = config.lane?.backend === 'cloudflare_vectorize'
+      ? createBackendRegistry().get('cloudflare_vectorize')
+      : null;
+    const vectorContext = {
+      ...(ctx.cloudflare || {}),
+      ...(input.vectorContext || {}),
+      env: input.env || ctx.env || process.env,
+      ownerId: input.ownerId || ctx.ownerId || ctx.owner_id || '',
+      accountId: input.accountId || ctx.accountId || '',
+      workerBinding: input.workerBinding || ctx.workerBinding,
+      apiClient: input.apiClient || ctx.apiClient,
+    };
     const result = await runIndex({
       root,
       config,
       store,
       embed,
       embedder,
+      vectorBackend,
+      vectorContext,
       maxInputs: Number(input.maxInputs ?? 200),
       maxCharacters: Number(input.maxCharacters ?? 400000),
     });
@@ -568,7 +611,7 @@ async function runWizard(root, opts) {
   }));
   const storage = lane === 'supabase' ? 'postgres' : 'sqlite';
   if (lane === 'vectorize') {
-    note('Vectorize lane recorded for plan/receipt; full CF adapter wiring is a follow-up slice.', 'Lane note');
+    note('Uses this project’s declared Vectorize binding via Worker runtime or the current user’s authorized Cloudflare API transport.', 'Lane note');
   }
   if (lane === 'supabase') {
     note('Uses AGENTSAM_DATABASE_URL / Hyperdrive-style postgres. Owner IAM already has node-api.', 'Lane note');

package/src/commands/knowledge.js

@@ -169,10 +169,66 @@ export async function runSearch(argv) {
   finally { await store?.close(); }
 }
 
+function compactNumber(value) {
+  const n = Number(value || 0);
+  if (!Number.isFinite(n)) return '0';
+  if (Math.abs(n) >= 1_000_000) return `${(n / 1_000_000).toFixed(n >= 10_000_000 ? 1 : 2).replace(/\.0+$/, '')}m`;
+  if (Math.abs(n) >= 1_000) return `${(n / 1_000).toFixed(n >= 100_000 ? 0 : 1).replace(/\.0$/, '')}k`;
+  return String(n);
+}
+
+export function renderRepositoryObservation(observation) {
+  const data = observation?.data || {};
+  const git = data.git || {};
+  const summary = data.summary || {};
+  const top = Array.isArray(data.top_level) ? data.top_level.slice(0, 5) : [];
+  const pressure = Array.isArray(data.pressure_points) ? data.pressure_points.slice(0, 6) : [];
+  const dirty = git.dirty ? `dirty · ${git.changed_paths || 0} changed` : 'clean';
+  const head = git.head_sha ? String(git.head_sha).slice(0, 10) : 'unknown';
+
+  const lines = [
+    '',
+    '  Agent Sam · repository',
+    '',
+    `  repo       ${data.repo_name || path.basename(data.repo_root || '') || 'unknown'}`,
+    `  root       ${data.repo_root || 'unknown'}`,
+    `  git        ${git.branch || 'unknown'} @ ${head} · ${dirty}`,
+    `  scale      ${compactNumber(summary.file_count)} files · ${compactNumber(summary.source_file_count)} source · ${compactNumber(summary.total_lines)} lines`,
+  ];
+
+  if (top.length) {
+    lines.push('', '  Primary areas');
+    for (const row of top) {
+      lines.push(`    ${String(row.path || '.').padEnd(28)} ${compactNumber(row.files)} files · ${compactNumber(row.lines)} lines`);
+    }
+  }
+
+  if (pressure.length) {
+    lines.push('', '  Change pressure');
+    for (const row of pressure) {
+      lines.push(`    ${String(row.path || '.').padEnd(28)} pressure ${Number(row.pressure_score || 0).toFixed(1)} · stability ${Number(row.stability_score || 0).toFixed(1)}`);
+    }
+    lines.push('    relative activity heuristics — not quality grades');
+  }
+
+  lines.push(
+    '',
+    '  More',
+    '    agentsam repo --json              full deterministic receipt',
+    '    agentsam repo history             saved observations',
+    '    agentsam repo compare             compare latest saved observations',
+    '    agentsam inspect                  bounded architecture / authority view',
+    '    agentsam machine inspect          native deterministic perception',
+    '',
+  );
+  return lines.join('\n');
+}
+
 export async function runRepository(argv) {
   const { values: opts, positionals } = flags(argv, { save: { type: 'boolean' }, 'churn-days': { type: 'string' } });
   const command = positionals[0] || 'snapshot';
-  if (opts.help) { console.log('agentsam repo snapshot [--cwd PATH] [--churn-days 30] [--save] [--json]\nagentsam repo history|compare [--cwd PATH]\nUses the bundled Python repository intelligence; --save retains observations for comparisons.'); return; }
+  if (opts.help) { console.log('agentsam repo [snapshot] [--cwd PATH] [--churn-days 30] [--save] [--json]\nagentsam repo history|compare [--cwd PATH]\nDefault output is a human summary; --json emits the full deterministic receipt.'); return; }
+  if (command === 'context') throw new Error('Repository context is `agentsam context`. Use `agentsam repo snapshot|history|compare` for repository intelligence.');
   if (positionals.length > 1 || !['snapshot', 'history', 'compare'].includes(command)) throw new Error('Use agentsam repo snapshot|history|compare.');
   const root = repositoryRoot(opts.cwd);
   let store;
@@ -190,6 +246,7 @@ export async function runRepository(argv) {
     });
     const observation = { id: randomUUID(), created_at: new Date().toISOString(), kind: 'repository-intelligence', data: JSON.parse(result.stdout) };
     if (store) await store.observe(cacheNamespace(readConfig(root)), observation);
-    show(observation);
+    if (opts.json) show(observation);
+    else console.log(renderRepositoryObservation(observation));
   } finally { await store?.close(); }
 }

package/src/commands/machine-binary.js

@@ -0,0 +1,103 @@
+/**
+ * Resolve the agentsam-machine native binary.
+ * Preference order:
+ *   1. AGENTSAM_MACHINE_BIN
+ *   2. agentsam-machine on PATH
+ *   3. Built binary under native/agentsam-machine/target/{release,debug}
+ *   4. cargo run --manifest-path … (dev fallback inside the SDK repo)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const sdkRoot = path.resolve(here, '../..');
+const machineCrate = path.join(sdkRoot, 'native/agentsam-machine');
+const machineManifest = path.join(machineCrate, 'Cargo.toml');
+
+/**
+ * @typedef {{ kind: 'binary', path: string, source: string } | { kind: 'cargo', manifest: string, source: string } | { kind: 'missing', tried: string[] }} MachineBinaryResolution
+ */
+
+/**
+ * @returns {MachineBinaryResolution}
+ */
+export function resolveMachineBinary(env = process.env) {
+  const tried = [];
+
+  const explicit = String(env.AGENTSAM_MACHINE_BIN || '').trim();
+  if (explicit) {
+    tried.push(explicit);
+    if (fs.existsSync(explicit) && fs.statSync(explicit).isFile()) {
+      return { kind: 'binary', path: explicit, source: 'AGENTSAM_MACHINE_BIN' };
+    }
+  }
+
+  const pathHit = which('agentsam-machine');
+  if (pathHit) {
+    return { kind: 'binary', path: pathHit, source: 'PATH' };
+  }
+  tried.push('PATH:agentsam-machine');
+
+  for (const rel of ['target/release/agentsam-machine', 'target/debug/agentsam-machine']) {
+    const candidate = path.join(machineCrate, rel);
+    tried.push(candidate);
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      return { kind: 'binary', path: candidate, source: rel.includes('release') ? 'crate-release' : 'crate-debug' };
+    }
+  }
+
+  if (fs.existsSync(machineManifest)) {
+    const cargo = which('cargo');
+    if (cargo) {
+      return { kind: 'cargo', manifest: machineManifest, source: 'cargo-run' };
+    }
+    tried.push('cargo');
+  }
+
+  return { kind: 'missing', tried };
+}
+
+/**
+ * @param {MachineBinaryResolution} resolution
+ * @param {string[]} machineArgv  args after `agentsam machine` (e.g. ['inspect', './site', '--json'])
+ * @param {{ stdio?: import('node:child_process').StdioOptions, env?: NodeJS.ProcessEnv }} [options]
+ */
+export function spawnMachine(resolution, machineArgv, options = {}) {
+  const env = options.env || process.env;
+  const stdio = options.stdio || 'inherit';
+  const maxBuffer = options.maxBuffer || 32 * 1024 * 1024;
+
+  if (resolution.kind === 'binary') {
+    return spawnSync(resolution.path, machineArgv, { stdio, env, encoding: 'utf8', maxBuffer });
+  }
+  if (resolution.kind === 'cargo') {
+    return spawnSync(
+      'cargo',
+      ['run', '--quiet', '--manifest-path', resolution.manifest, '--bin', 'agentsam-machine', '--', ...machineArgv],
+      { stdio, env, encoding: 'utf8', maxBuffer },
+    );
+  }
+  const err = new Error(
+    `agentsam-machine binary not found. Tried: ${(resolution.tried || []).join(', ') || '(none)'}. Build with: cargo build --manifest-path native/agentsam-machine/Cargo.toml --release`,
+  );
+  err.code = 'AGENTSAM_MACHINE_BINARY_MISSING';
+  throw err;
+}
+
+function which(cmd) {
+  const probe = process.platform === 'win32' ? ['where', [cmd]] : ['which', [cmd]];
+  const result = spawnSync(probe[0], probe[1], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  if (result.status !== 0) return null;
+  const line = String(result.stdout || '')
+    .split(/\r?\n/)
+    .map((s) => s.trim())
+    .find(Boolean);
+  return line || null;
+}
+
+export function machineSdkRoot() {
+  return sdkRoot;
+}