@inneranimalmedia/agentsam-sdk 2.4.1 → 2.5.0

package/src/cli.js

@@ -2,14 +2,17 @@
 
 import pkg from '../package.json' with { type: 'json' };
 import readline from 'readline';
+import { cancel, intro, isCancel, outro, select, text } from '@clack/prompts';
 import path from 'node:path';
-import { buildLocalScaffoldMeta, LANE_KEYS, RUN_TARGETS } from './lib/local-scaffold.js';
+import { buildLocalScaffoldMeta } from './lib/local-scaffold.js';
 import { writeScaffoldFiles } from './lib/write-files.js';
 import { initializeGitRepository } from './lib/init-git.js';
 import { initializeLocalSqlite } from './local/sqlite.js';
 import { printContextSummary } from './lib/detect-context.js';
 import { promptOptionalByokKeys } from './lib/prompt-byok.js';
 import { runStartLocal } from './commands/start-local.js';
+import { runOllama } from './commands/ollama.js';
+import { runModels } from './commands/models.js';
 import { runTunnel } from './commands/tunnel.js';
 import { runDeploy } from './commands/deploy.js';
 import { runIdentityPreview } from './commands/identity-preview.js';
@@ -17,7 +20,7 @@ import { runIdentityInit } from './commands/identity-init.js';
 import { runContext } from './commands/context.js';
 import { runDb } from './commands/db.js';
 import { runStatus } from './commands/status.js';
-import { runTui } from './commands/tui.js';
+import { runInteractive } from './commands/interactive.js';
 import { runShell } from './commands/shell.js';
 import { runDockerize } from './commands/dockerize.js';
 import { runMini } from './commands/mini.js';
@@ -26,10 +29,12 @@ 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 { runSkills } from './commands/skills.js';
 import { applyPresetSelection, runAdd, runCapabilities, runDev, runInspect } from './commands/product.js';
 import { listPresets, resolvePreset } from './presets/index.js';
 import fs from 'node:fs';
 import { repositoryRoot } from './knowledge/config.js';
+import { resolveSdkKey } from '../packages/identity/src/contracts/auth-config.js';
 
 const VERSION = pkg.version;
 
@@ -46,14 +51,16 @@ function printHelp() {
   Agent Sam SDK — CLI v${VERSION}
 
   Product UX:
+    agentsam                     Enter the interactive Agent Sam experience
     agentsam create <name> --preset <fullstack|cms|prototype|data>
     agentsam add <auth|cms|knowledge|agent|deploy-cloudflare>
     agentsam dev               Run this project's existing npm dev script
-    agentsam inspect [--json]  Canonical deterministic repository.snapshot
+    agentsam inspect [--json]  Bounded repository index by default; use --view full for authority envelope
     agentsam deploy            Graduate an AgentSam project intentionally
 
   Capability discovery:
     agentsam capabilities [capability-id] [--json]
+    agentsam skills [skill-id-or-alias] [--references] [--json]
 
   Power-user UX:
     agentsam context [--json]  Git repo/revision + bridge configuration from any repo
@@ -63,15 +70,15 @@ function printHelp() {
     agentsam repo snapshot     Git composition/churn; --save retains observations
     agentsam cad blender       Programmatic Blender inspect/build/render/export (--help)
     agentsam mini <name>       Create and preview a small local gadget (--help for options)
-    agentsam merkle            File integrity, snapshots, comparisons, and TUI (--help)
+    agentsam merkle            File integrity, snapshots, comparisons, and interactive explorer (--help)
     agentsam deploy-receipt    Merkle deploy/checkpoint capture + promote/failure receipts (--help)
     agentsam recon             Bounded-worker task packets + finding-report validation (--help)
     agentsam security          Dependency scan, log triage, and verified repair (--help)
     agentsam status [--json]   Live local Git + DB + API + PTY status
     agentsam db init|status    Manage the project-local SQLite database
-    agentsam tui               Zero-dependency ANSI Agent Sam dashboard
-    agentsam tui rich          Optional Python Rich dashboard (--install for local venv)
+    agentsam models            Show configured providers and local model inventory
     agentsam start-local       Local PTY on ws://127.0.0.1:3099 (no tunnel, no Cloudflare)
+    agentsam ollama            Opt-in local Ollama setup/status/model management
     agentsam shell             Interactive Agent Sam slash-command shell
     agentsam tunnel            Explicitly expose local PTY when remote access is wanted
     agentsam deploy            Graduate to Cloudflare / GCP when ready
@@ -84,6 +91,21 @@ function printHelp() {
   Context options:
     --json                     Machine-readable output
     --cwd <path>               Resolve a different working directory
+
+  Inspect options:
+    --view <full|index|files>  Full authority envelope, facet index, or bounded matching files (default index)
+    --full                     Explicitly request the full authority envelope
+    --system/--package <name>  Filter semantic ownership
+    --category/--tag <value>   Filter semantic classification
+    --layer/--role <value>     Filter architecture role
+    --path <prefix|glob>       Filter repository paths (supports * and **)
+    --symbol/--import <value>  Filter AST symbols or imports
+    --match <text>             Lexical AND-match across semantic routing metadata
+    --limit <1..500>           Bound files view (default 50)
+    --facet-limit <1..200>     Bound each facet list (default 48)
+    --snapshot-file <file>     Reuse a saved canonical repository.snapshot; skips Merkle/AST rescan
+    --save-snapshot <file>     Save the canonical full snapshot while emitting the selected view
+    --pretty                   Pretty-print JSON; machine JSON is compact by default
     --remote <name>            Preferred Git remote (default origin; falls back to first remote)
 
   Init is completable with Node only — no IAM login, no OAuth, no Cloudflare.
@@ -93,7 +115,7 @@ function printHelp() {
     --quick                    Quick tunnel (default) — trycloudflare.com URL
     --named                    Named CF tunnel (needs --tunnel-name --hostname --zone-id)
     --port <n>                 Local PTY port (default 3099)
-    --token <sdk_…>            Use existing AGENTSAM_SDK_TOKEN (skip browser auth)
+    --token <sdk_…>            Use existing AGENTSAM_SDK_KEY (skip browser auth)
 
   Init options:
     --name <name>              Project directory name
@@ -176,7 +198,7 @@ async function runLocalInit(config) {
   ✓ Environment  ${path.join(dir, '.env')}
   ✓ SQLite       ${db.dbPath} (${db.tables.length} tables)
   ✓ Local API    Node · http://127.0.0.1:8787
-  ✓ Terminal UI  ANSI built in · Rich optional
+  ✓ Agent Sam     interactive CLI ready
 
   Next:`);
   console.log(`    cd ${meta.projectName}`);
@@ -184,9 +206,10 @@ async function runLocalInit(config) {
     console.log(`    ${step}`);
   }
 
-  if (prompt && process.env.AGENTSAM_SDK_TOKEN) {
+  const sdkKey = resolveSdkKey(process.env);
+  if (prompt && sdkKey) {
     console.log('\n  Optional — BYOK keys for IAM dashboard Agent Sam (skip with Enter):\n');
-    await promptOptionalByokKeys(process.env.AGENTSAM_SDK_TOKEN, prompt);
+    await promptOptionalByokKeys(sdkKey, prompt);
   }
 
   console.log(`
@@ -196,58 +219,61 @@ async function runLocalInit(config) {
 }
 
 async function initInteractive(partial = {}) {
-  const prompt = createPrompt();
-
-  console.log(`
-  ╔════════════════════════════════╗
-  ║   Agent Sam SDK — Init            ║
-  ║   Local-first · Node only         ║
-  ╚════════════════════════════════╝
-  `);
-
-  const projectName =
-    partial.projectName ||
-    (await prompt.ask('  1) Project name: '));
-
-  if (!partial.lane) {
-    console.log(`
-  2) Lane:
-    1) Full Stack   2) CMS   3) Data   4) CRM   5) Creative
-  `);
-  }
-  const laneKey = partial.lane
-    ? partial.lane
-    : LANE_KEYS[await prompt.ask('  Pick lane [1-5]: ')] || 'fullstack';
+  const pick = (value) => {
+    if (!isCancel(value)) return value;
+    cancel('Agent Sam init cancelled.');
+    const error = new Error('init_cancelled');
+    error.code = 'AGENTSAM_INIT_CANCELLED';
+    throw error;
+  };
 
-  if (!partial.runTarget) {
-    console.log(`
-  3) Future deploy target?
+  intro('Create an Agent Sam project');
+
+  const projectName = partial.projectName || pick(await text({
+    message: 'Project name',
+    placeholder: 'my-agent',
+    validate(value) {
+      if (!String(value || '').trim()) return 'Project name is required';
+    },
+  }));
+
+  const laneKey = partial.lane || pick(await select({
+    message: 'Project type',
+    initialValue: 'fullstack',
+    options: [
+      { value: 'fullstack', label: 'Full Stack' },
+      { value: 'cms', label: 'CMS' },
+      { value: 'data', label: 'Data Solutions' },
+      { value: 'crm', label: 'Customer Management' },
+      { value: 'creative', label: 'Creative & Design' },
+    ],
+  }));
+
+  const runTarget = partial.runTarget || pick(await select({
+    message: 'Future deploy target',
+    initialValue: 'local',
+    options: [
+      { value: 'local', label: 'Local only / decide later' },
+      { value: 'cloudflare', label: 'Cloudflare later' },
+      { value: 'gcp', label: 'GCP later' },
+    ],
+  }));
 
-    1) Local only / decide later
-    2) Cloudflare later (Worker + D1 adapter at deploy time)
-    3) GCP later (your Google Cloud project)
-  `);
-  }
-  const runTarget = partial.runTarget
-    ? partial.runTarget
-    : RUN_TARGETS[await prompt.ask('  Select [1]: ')] || 'local';
-
-  // Credential detection is demand-driven, not unconditional. missingForInit()
-  // already knows local needs nothing (`if (runTarget === 'local') return []`)
-  // — it just never got consulted before this fix, because detectContext()
-  // used to run before runTarget was even known. runTarget alone is enough
-  // to decide whether detection is needed at all, so skip the subprocess
-  // calls entirely for local instead of just hiding their output.
   if (runTarget !== 'local') {
     const { detectContext, missingForInit } = await import('./lib/detect-context.js');
     const ctx = await detectContext();
-    if (missingForInit(ctx, process.env.AGENTSAM_SDK_TOKEN || '', { runTarget }).length) {
+    if (missingForInit(ctx, resolveSdkKey(process.env), { runTarget }).length) {
       printContextSummary(ctx);
     }
   }
 
-  await runLocalInit({ projectName, lane: laneKey, runTarget, prompt });
-  prompt.close();
+  const prompt = resolveSdkKey(process.env) ? createPrompt() : null;
+  try {
+    await runLocalInit({ projectName, lane: laneKey, runTarget, prompt });
+  } finally {
+    prompt?.close();
+  }
+  outro(`Created ${projectName}`);
 }
 
 async function initFromArgs(argv) {
@@ -264,8 +290,20 @@ const rest = process.argv.slice(3);
 
 if (command === '--version' || command === '-v') {
   console.log(VERSION);
-} else if (command === '--help' || command === '-h' || !command) {
+} else if (command === '--help' || command === '-h') {
   printHelp();
+} else if (!command) {
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    try { await runInteractive(); }
+    catch (e) {
+      if (e?.code !== 'AGENTSAM_SETUP_CANCELLED') {
+        console.error(`\n  ✗ ${e?.message || e}\n`);
+        process.exitCode = 1;
+      }
+    }
+  } else {
+    printHelp();
+  }
 } else if (command === 'create') {
   try {
     const opts = parseCreateArgs(rest);
@@ -311,9 +349,9 @@ if (command === '--version' || command === '-v') {
     console.error(`\n  ✗ ${e?.message || e}\n`);
     process.exit(1);
   }
-} else if (command === 'tui') {
+} else if (command === 'models') {
   try {
-    await runTui(rest);
+    await runModels(rest);
   } catch (e) {
     console.error(`\n  ✗ ${e?.message || e}\n`);
     process.exit(1);
@@ -327,6 +365,13 @@ if (command === '--version' || command === '-v') {
   }
 } else if (command === 'start-local') {
   await runStartLocal({});
+} else if (command === 'ollama') {
+  try {
+    await runOllama(rest);
+  } catch (e) {
+    console.error(`\n  ✗ ${e?.message || e}\n`);
+    process.exitCode = 1;
+  }
 } else if (command === 'tunnel') {
   try {
     await runTunnel(rest);
@@ -357,6 +402,13 @@ if (command === '--version' || command === '-v') {
   }
 } else if (command === 'security' || command === 'sca') {
   await runSecurity(rest);
+} else if (command === 'skills' || command === 'skill') {
+  try {
+    runSkills(rest);
+  } catch (e) {
+    console.error(`\n  ✗ ${e?.message || e}\n`);
+    process.exitCode = 1;
+  }
 } else if (command === 'merkle') {
   await runMerkle(rest);
 } else if (command === 'deploy-receipt') {

package/src/commands/context.js

@@ -1,5 +1,6 @@
 import { tryResolveGitContext } from '../lib/git-context.js';
 import { resolveAgentSamBaseUrl, resolveBridgeKey } from '../lib/bridge-client.js';
+import { loadProjectRules } from '../lib/project-rules.js';
 
 function parseArgs(argv = []) {
   const options = { json: false, cwd: process.cwd(), remote: 'origin' };
@@ -15,10 +16,20 @@ function parseArgs(argv = []) {
 
 export function buildContextReport(options = {}) {
   const env = options.env || process.env;
-  const git = tryResolveGitContext({ cwd: options.cwd || process.cwd(), remote: options.remote || 'origin' });
+  const cwd = options.cwd || process.cwd();
+  const git = tryResolveGitContext({ cwd, remote: options.remote || 'origin' });
+  const rules = loadProjectRules(cwd);
   return {
-    schemaVersion: 'agentsam-context-v1',
+    schemaVersion: 'agentsam-context-v2',
     git,
+    rules: {
+      found: rules.found,
+      path: rules.path,
+      chars: rules.chars,
+      source_chars: rules.source_chars || 0,
+      truncated: rules.truncated,
+      hash: rules.hash,
+    },
     bridge: {
       baseUrl: resolveAgentSamBaseUrl(env),
       configured: Boolean(resolveBridgeKey(env)),
@@ -46,6 +57,7 @@ export async function runContext(argv = []) {
   } else {
     console.log('  repo       not inside a Git repository');
   }
+  console.log(`  rules      ${report.rules.found ? `${report.rules.path} · ${report.rules.chars} chars` : 'none'}`);
   console.log(`  core       ${report.bridge.baseUrl}`);
   console.log(`  bridge     ${report.bridge.configured ? 'configured' : 'AGENTSAM_BRIDGE_KEY not set'}`);
   console.log('');

package/src/commands/db.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { initializeLocalSqlite, inspectLocalSqlite } from '../local/sqlite.js';
+import { getLocalDatabasePath, getLocalSchemaPath, readProjectConfig } from '../lib/project-config.js';
 
 function findProjectRoot(startDir) {
   let dir = path.resolve(startDir);
@@ -13,14 +14,10 @@ function findProjectRoot(startDir) {
   throw new Error('Not an Agent Sam project — run `agentsam init` first.');
 }
 
-function readConfig(root) {
-  return JSON.parse(fs.readFileSync(path.join(root, '.agentsam', 'config.json'), 'utf8'));
-}
-
 function resolveDb(root, config) {
   return {
-    dbPath: path.resolve(root, config.db_path || '.agentsam/data/agentsam.sqlite'),
-    schemaPath: path.resolve(root, config.db_schema || 'db/schema.sql'),
+    dbPath: path.resolve(root, getLocalDatabasePath(config)),
+    schemaPath: path.resolve(root, getLocalSchemaPath(config)),
   };
 }
 
@@ -31,7 +28,7 @@ export async function runDb(argv = [], opts = {}) {
   }
 
   const root = findProjectRoot(opts.cwd || process.cwd());
-  const config = readConfig(root);
+  const config = readProjectConfig(root);
   const paths = resolveDb(root, config);
 
   if (sub === 'init') {

package/src/commands/deploy.js

@@ -6,26 +6,16 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { authenticateViaBrowser } from '../lib/auth.js';
 import { getJson, streamScaffold } from '../lib/core-client.js';
-
-function readConfig(cwd) {
-  const configPath = path.join(cwd, '.agentsam', 'config.json');
-  if (!fs.existsSync(configPath)) {
-    throw new Error('Not an Agent Sam project — run agentsam init first.');
-  }
-  return JSON.parse(fs.readFileSync(configPath, 'utf8'));
-}
-
-function writeConfig(cwd, config) {
-  const configPath = path.join(cwd, '.agentsam', 'config.json');
-  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
-}
+import { resolveSdkKey } from '../../packages/identity/src/contracts/auth-config.js';
+import { getDefaultProfile, getDeployTarget, getLocalSchemaPath, getProjectName, getProjectPreset, readProjectConfig, setDeployTarget, writeProjectConfig } from '../lib/project-config.js';
 
 function writeCloudflareAdapter(cwd, config, cf) {
-  const workerName = cf.worker_name || config.project;
+  const projectName = getProjectName(config, path.basename(cwd));
+  const workerName = cf.worker_name || projectName;
   const adapterPath = path.join(cwd, 'src', 'cloudflare-worker.js');
   const migrationDir = path.join(cwd, 'migrations');
   const migrationPath = path.join(migrationDir, '0001_agentsam_core.sql');
-  const localSchemaPath = path.join(cwd, config.db_schema || 'db/schema.sql');
+  const localSchemaPath = path.join(cwd, getLocalSchemaPath(config));
   const tomlPath = path.join(cwd, 'wrangler.toml');
 
   fs.mkdirSync(path.dirname(adapterPath), { recursive: true });
@@ -33,7 +23,7 @@ function writeCloudflareAdapter(cwd, config, cf) {
 
   fs.writeFileSync(
     adapterPath,
-    `import { createAgent } from './agent.js';\n\nexport default {\n  async fetch(request, env) {\n    const app = createAgent({\n      env,\n      project: ${JSON.stringify(config.project)},\n      lane: ${JSON.stringify(config.lane)},\n      agent: ${JSON.stringify(config.agent)},\n    });\n    return app.handle(request);\n  },\n};\n`,
+    `import { createAgent } from './agent.js';\n\nexport default {\n  async fetch(request, env) {\n    const app = createAgent({\n      env,\n      project: ${JSON.stringify(projectName)},\n      lane: ${JSON.stringify(getProjectPreset(config))},\n      agent: ${JSON.stringify(getDefaultProfile(config))},\n    });\n    return app.handle(request);\n  },\n};\n`,
     'utf8',
   );
 
@@ -51,7 +41,7 @@ function writeCloudflareAdapter(cwd, config, cf) {
   if (cf.d1_database_id) {
     lines.push('', '[[d1_databases]]');
     lines.push('binding = "DB"');
-    lines.push(`database_name = ${JSON.stringify(cf.d1_database_name || `${config.project}-db`)}`);
+    lines.push(`database_name = ${JSON.stringify(cf.d1_database_name || `${projectName}-db`)}`);
     lines.push(`database_id = ${JSON.stringify(cf.d1_database_id)}`);
   }
   if (cf.kv_namespace_id) {
@@ -77,7 +67,7 @@ function ask(question) {
 async function runCloudflareDeploy(cwd, config, accountId) {
   console.log('\n  Cloudflare deploy — browser sign-in + resource provisioning…\n');
 
-  let token = process.env.AGENTSAM_SDK_TOKEN || '';
+  let token = resolveSdkKey(process.env);
   if (!token) {
     const session = await authenticateViaBrowser();
     token = session.access_token;
@@ -92,8 +82,8 @@ async function runCloudflareDeploy(cwd, config, accountId) {
   let complete = null;
   await streamScaffold(
     {
-      project_name: config.project,
-      lane: config.lane,
+      project_name: getProjectName(config, path.basename(cwd)),
+      lane: getProjectPreset(config),
       hosting: 'cloudflare',
       provision_only: true,
       account_id: accountId || undefined,
@@ -114,13 +104,8 @@ async function runCloudflareDeploy(cwd, config, accountId) {
   if (!complete?.cloudflare) throw new Error('deploy incomplete — no cloudflare ids returned');
 
   const adapter = writeCloudflareAdapter(cwd, config, complete.cloudflare);
-  writeConfig(cwd, {
-    ...config,
-    deploy_target: 'cloudflare',
-    cloudflare: complete.cloudflare,
-    cloud_adapter: path.relative(cwd, adapter.adapterPath),
-    deployed_at: new Date().toISOString(),
-  });
+  setDeployTarget(config, 'cloudflare');
+  writeProjectConfig(cwd, config);
 
   console.log(`
   ✓ Cloudflare resources provisioned in YOUR account
@@ -141,10 +126,10 @@ async function runCloudflareDeploy(cwd, config, accountId) {
  */
 export async function runDeploy(opts = {}) {
   const cwd = path.resolve(opts.cwd || process.cwd());
-  const config = readConfig(cwd);
+  const config = readProjectConfig(cwd);
 
-  let target = opts.target || config.deploy_target || 'cloudflare';
-  if (!opts.target && !config.deploy_target) {
+  let target = opts.target || getDeployTarget(config) || 'cloudflare';
+  if (!opts.target && !getDeployTarget(config)) {
     console.log(`
   Where do you want to deploy?
 
@@ -166,7 +151,8 @@ export async function runDeploy(opts = {}) {
   Your local project keeps running with npm run dev.
   Container/Worker deploy scripts are project-specific — add when ready.
   `);
-    writeConfig(cwd, { ...config, deploy_target: 'gcp' });
+    setDeployTarget(config, 'gcp');
+    writeProjectConfig(cwd, config);
     return;
   }
 

package/src/commands/interactive.js

@@ -0,0 +1,21 @@
+import { configureCliPreferences } from './preferences.js';
+import { runShell } from './shell.js';
+import { detectCliProject, readCliPreferences } from '../lib/cli-preferences.js';
+import { runBootScene } from '../ui/boot.js';
+
+export async function runInteractive(options = {}) {
+  let identity = detectCliProject(options.cwd || process.cwd());
+  let preferences = readCliPreferences(identity.root);
+
+  if (!preferences) {
+    const configured = await configureCliPreferences({ cwd: identity.root, firstRun: true });
+    identity = configured.identity;
+    preferences = configured.preferences;
+  }
+
+  await runBootScene({ identity, preferences, animate: options.animate !== false });
+  await runShell([], {
+    cwd: identity.root,
+    intro: 'quiet',
+  });
+}

package/src/commands/knowledge.js

@@ -6,12 +6,15 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { randomUUID } from 'node:crypto';
+import pkg from '../../package.json' with { type: 'json' };
 import { CONFIG_PATH, repositoryRoot, initRepository, readConfig, scopeKey, cacheNamespace } 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 { createGeminiEmbedder } from '../knowledge/providers/gemini.js';
 import { compareObservations } from '../knowledge/evolution.js';
+import { ensureProjectManifest, getProjectName, getRepositoryId } from '../lib/project-config.js';
+import { ensureProjectRules } from '../lib/project-rules.js';
 
 const execute = promisify(execFile);
 const split = text => text.split(',').map(s => s.trim()).filter(Boolean);
@@ -28,7 +31,20 @@ export async function runRepositoryInit(argv) {
   if (opts.help) { console.log('agentsam init [.] [--cwd PATH] [--yes] [--include src,docs] [--exclude src/generated] [--scope NAME] [--target local|production] [--dimensions 768]'); return; }
   if (positionals.length > 1 || (positionals[0] && positionals[0] !== '.')) throw new Error('Use init . --cwd PATH to adopt an existing repository, or init --name NAME to scaffold.');
   const root = repositoryRoot(opts.cwd);
-  if (fs.existsSync(path.join(root, CONFIG_PATH))) throw new Error(`${CONFIG_PATH} already exists; edit it to change scope/profile. Existing configuration was preserved.`);
+  const knowledgePath = path.join(root, CONFIG_PATH);
+  const existingKnowledge = fs.existsSync(knowledgePath) ? readConfig(root) : null;
+  const projectManifest = ensureProjectManifest(root, {
+    repositoryId: existingKnowledge?.repository_id || undefined,
+    sdkVersion: pkg.version,
+  });
+  ensureProjectRules(root, getProjectName(projectManifest));
+  const projectRepositoryId = getRepositoryId(projectManifest);
+  if (existingKnowledge) {
+    if (projectRepositoryId && existingKnowledge.repository_id !== projectRepositoryId) {
+      throw new Error(`repository_identity_mismatch: project=${projectRepositoryId} knowledge=${existingKnowledge.repository_id}`);
+    }
+    throw new Error(`${CONFIG_PATH} already exists; edit it to change scope/profile. Existing configuration was preserved.`);
+  }
   let include = opts.include, exclude = opts.exclude, target = opts.target, dimensions = opts.dimensions;
   if (!opts.yes) {
     if (!process.stdin.isTTY) throw new Error('Existing-repository setup needs a terminal or --yes with explicit options.');
@@ -41,7 +57,14 @@ export async function runRepositoryInit(argv) {
       dimensions ??= await prompt.question('4) Gemini Embedding 2 dimensions [768]: ') || '768';
     } finally { prompt.close(); }
   }
-  const config = initRepository(root, { include: split(include || '.'), exclude: split(exclude || ''), scope: opts.scope || 'default', target: target || 'local', dimensions: Number(dimensions || 768) });
+  const config = initRepository(root, {
+    include: split(include || '.'),
+    exclude: split(exclude || ''),
+    scope: opts.scope || 'default',
+    target: target || 'local',
+    dimensions: Number(dimensions || 768),
+    repositoryId: projectRepositoryId,
+  });
   show({ root, config: CONFIG_PATH, storage: config.storage.driver, next: config.storage.driver === 'postgres' ? ['agentsam index setup-store', 'agentsam index plan', 'agentsam index run'] : ['agentsam index plan', 'agentsam index run', 'agentsam search "your symbol"'], note: 'No indexing, credentials, network calls, or source-file changes during setup.' });
 }
 
@@ -73,9 +96,9 @@ export async function runKnowledge(argv) {
 
 export async function runSearch(argv) {
   const { values: opts, positionals } = flags(argv, { semantic: { type: 'boolean' }, 'top-k': { type: 'string' }, 'token-budget': { type: 'string' }, generation: { type: 'string' } });
-  if (opts.help) { console.log('agentsam search "query" [--cwd PATH] [--semantic] [--top-k 8] [--token-budget 8000] [--generation ID]'); return; }
+  if (opts.help) { console.log('agentsam search "query" [--cwd PATH] [--semantic] [--top-k 8] [--token-budget 6000] [--generation ID]'); return; }
   const root = repositoryRoot(opts.cwd), config = readConfig(root), store = await openStore(root, config, true);
-  try { show(await retrieve({ store, config, text: positionals.join(' '), semantic: opts.semantic, embedder: opts.semantic ? provider() : null, topK: Number(opts['top-k'] || 8), tokenBudget: Number(opts['token-budget'] || 8000), generationId: opts.generation })); }
+  try { show(await retrieve({ store, config, text: positionals.join(' '), semantic: opts.semantic, embedder: opts.semantic ? provider() : null, topK: Number(opts['top-k'] || 8), tokenBudget: Number(opts['token-budget'] || 6000), generationId: opts.generation })); }
   finally { await store?.close(); }
 }