@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/src/lib/deploy/local-studio.js

@@ -0,0 +1,283 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { assertProductionDeployAllowed, inspectDeployGit } from './git-guard.js';
+import { assertNoDeploySecrets } from './secret-scan.js';
+import { parseWranglerVersionId, probeDeployHealth, resolveHealthOrigin } from './health.js';
+
+export const LOCAL_STUDIO_REL = 'apps/local-studio';
+export const WRANGLER_CONFIG_REL = 'backend/wrangler.jsonc';
+export const DEPLOY_INPUT_GLOBS = Object.freeze([
+  'apps/local-studio',
+  'packages/agentsam-contracts',
+  'packages/agentsam-workbench',
+  'packages/connectors/cloudflare',
+]);
+
+export function findRepoRoot(start = process.cwd()) {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, 'apps/local-studio/backend/wrangler.jsonc'))) return dir;
+    if (fs.existsSync(path.join(dir, 'backend/wrangler.jsonc')) && path.basename(dir) === 'local-studio') {
+      return path.dirname(path.dirname(dir));
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return start;
+    dir = parent;
+  }
+}
+
+export function resolveLocalStudioDeployable(cwd = process.cwd()) {
+  const repoRoot = findRepoRoot(cwd);
+  const appRoot = path.join(repoRoot, LOCAL_STUDIO_REL);
+  const wranglerConfig = path.join(appRoot, WRANGLER_CONFIG_REL);
+  if (!fs.existsSync(wranglerConfig)) {
+    throw new Error(`wrangler config missing: ${wranglerConfig}`);
+  }
+  return {
+    repoRoot,
+    appRoot,
+    wranglerConfig,
+    wranglerArgs: ['deploy', '-c', WRANGLER_CONFIG_REL],
+    provider: 'cloudflare',
+    app: 'local-studio',
+  };
+}
+
+export function loadOptionalCloudflareEnv(appRoot) {
+  const file = path.join(appRoot, '.env.cloudflare');
+  if (!fs.existsSync(file)) return { loaded: false, vars: {} };
+  const vars = {};
+  for (const line of fs.readFileSync(file, 'utf8').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq < 1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    vars[key] = value;
+  }
+  return { loaded: true, vars };
+}
+
+function hashFile(file) {
+  const h = crypto.createHash('sha256');
+  h.update(fs.readFileSync(file));
+  return h.digest('hex');
+}
+
+function walkFiles(dir, acc = []) {
+  if (!fs.existsSync(dir)) return acc;
+  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (ent.name === 'node_modules' || ent.name === '.output' || ent.name === '.wrangler' || ent.name === '.git') continue;
+    const full = path.join(dir, ent.name);
+    if (ent.isDirectory()) walkFiles(full, acc);
+    else acc.push(full);
+  }
+  return acc;
+}
+
+export function computeDeployFingerprint(repoRoot) {
+  const h = crypto.createHash('sha256');
+  const files = [];
+  for (const rel of DEPLOY_INPUT_GLOBS) {
+    walkFiles(path.join(repoRoot, rel), files);
+  }
+  files.sort();
+  for (const file of files) {
+    const rel = path.relative(repoRoot, file).split(path.sep).join('/');
+    h.update(rel);
+    h.update('\0');
+    h.update(hashFile(file));
+    h.update('\n');
+  }
+  return h.digest('hex');
+}
+
+export function readBaselineFingerprint(appRoot) {
+  const receipt = path.join(appRoot, '.agentsam/deploy-merkle/latest.receipt.json');
+  if (!fs.existsSync(receipt)) return null;
+  try {
+    const json = JSON.parse(fs.readFileSync(receipt, 'utf8'));
+    return json.deployProjectionHash || json.fingerprint || null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeDeployReceipt(appRoot, receipt) {
+  const dir = path.join(appRoot, '.agentsam/deploy-merkle');
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, receipt.promoted ? 'latest.receipt.json' : 'pending.receipt.json');
+  fs.writeFileSync(file, JSON.stringify(receipt, null, 2) + '\n');
+  return file;
+}
+
+export function wranglerDeployCommand(target, { dryRun = false } = {}) {
+  const args = ['wrangler', ...target.wranglerArgs];
+  if (dryRun) args.push('--dry-run');
+  return { cwd: target.appRoot, args, bin: 'npx' };
+}
+
+export function isLocalStudioCheckout(cwd = process.cwd()) {
+  try {
+    resolveLocalStudioDeployable(cwd);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function runLocalStudioDeploy({
+  cwd = process.cwd(),
+  dryRun = false,
+  planOnly = false,
+  skipBuild = false,
+  execute = true,
+  skipSecretScan = false,
+  probeHealth = null,
+} = {}) {
+  const target = resolveLocalStudioDeployable(cwd);
+  if (path.resolve(cwd) === target.repoRoot && !target.wranglerConfig.endsWith(path.join('backend', 'wrangler.jsonc')) && !target.wranglerConfig.endsWith('backend/wrangler.jsonc')) {
+    throw new Error('refusing generic repo-root wrangler deploy');
+  }
+  const envFile = loadOptionalCloudflareEnv(target.appRoot);
+  const fingerprint = computeDeployFingerprint(target.repoRoot);
+  const baseline = readBaselineFingerprint(target.appRoot);
+  const gitInfo = inspectDeployGit(target.repoRoot);
+  const wranglerText = fs.readFileSync(target.wranglerConfig, 'utf8');
+  const healthOrigin = resolveHealthOrigin({ env: { ...process.env, ...envFile.vars }, wranglerConfigText: wranglerText });
+  const plan = {
+    provider: 'cloudflare',
+    app: 'local-studio',
+    wranglerConfig: path.relative(target.repoRoot, target.wranglerConfig).split(path.sep).join('/'),
+    wranglerArgs: target.wranglerArgs,
+    cwd: path.relative(target.repoRoot, target.appRoot).split(path.sep).join('/') || '.',
+    envLoaded: envFile.loaded,
+    fingerprint,
+    baseline,
+    skip: Boolean(baseline && baseline === fingerprint && !dryRun && !planOnly),
+    genericRootDeploy: false,
+    productionGitRequired: Boolean(execute && !dryRun && !planOnly),
+    healthOrigin,
+    git: {
+      branch: gitInfo.branch,
+      head: gitInfo.head,
+      originMain: gitInfo.originMain,
+      equal: Boolean(gitInfo.head && gitInfo.head === gitInfo.originMain),
+    },
+  };
+  if (!skipSecretScan) {
+    plan.secretScan = assertNoDeploySecrets([
+      target.wranglerConfig,
+      path.join(target.appRoot, '.env.cloudflare.example'),
+      path.join(target.appRoot, 'backend/worker/index.js'),
+      path.join(target.repoRoot, 'packages/connectors/cloudflare/src/index.js'),
+    ]);
+  }
+  if (plan.skip) {
+    const receipt = {
+      ok: true,
+      skipped: true,
+      reason: 'unchanged_deploy_fingerprint',
+      deployProjectionHash: fingerprint,
+      promoted: false,
+      git: plan.git,
+      wranglerConfig: plan.wranglerConfig,
+      hostname: healthOrigin.replace(/^https?:\/\//, ''),
+    };
+    writeDeployReceipt(target.appRoot, receipt);
+    return { target, plan, receipt };
+  }
+  if (!execute || planOnly) {
+    return {
+      target,
+      plan,
+      receipt: {
+        ok: true,
+        skipped: false,
+        plan: true,
+        dryRun,
+        deployProjectionHash: fingerprint,
+        promoted: false,
+        git: plan.git,
+        wranglerConfig: plan.wranglerConfig,
+        hostname: healthOrigin.replace(/^https?:\/\//, ''),
+      },
+    };
+  }
+
+  if (!dryRun) {
+    plan.git = assertProductionDeployAllowed(target.repoRoot);
+    plan.git.equal = plan.git.head === plan.git.originMain;
+  }
+
+  const env = { ...process.env, ...envFile.vars };
+  const lock = spawnSync('npm', ['run', 'verify:npm10-lock'], { cwd: target.appRoot, env, encoding: 'utf8' });
+  if (lock.status !== 0) throw new Error(lock.stderr || lock.stdout || 'verify:npm10-lock failed');
+  if (!skipBuild) {
+    const build = spawnSync('npm', ['run', 'build'], { cwd: target.appRoot, env, encoding: 'utf8' });
+    if (build.status !== 0) throw new Error(build.stderr || build.stdout || 'build failed');
+    const verify = spawnSync('npm', ['run', 'cf:verify-output'], { cwd: target.appRoot, env, encoding: 'utf8' });
+    if (verify.status !== 0) throw new Error(verify.stderr || verify.stdout || 'cf:verify-output failed');
+  }
+  const cmd = wranglerDeployCommand(target, { dryRun });
+  const deployed = spawnSync(cmd.bin, cmd.args, { cwd: cmd.cwd, env, encoding: 'utf8' });
+  const wranglerOut = `${deployed.stdout || ''}\n${deployed.stderr || ''}`;
+  const workerVersion = parseWranglerVersionId(wranglerOut);
+  if (deployed.status !== 0) {
+    const receipt = {
+      ok: false,
+      skipped: false,
+      deployProjectionHash: fingerprint,
+      promoted: false,
+      git: plan.git,
+      workerVersion,
+      error: wranglerOut,
+    };
+    writeDeployReceipt(target.appRoot, receipt);
+    throw new Error(receipt.error || 'wrangler deploy failed');
+  }
+  let health = null;
+  if (!dryRun) {
+    const probe = probeHealth || probeDeployHealth;
+    health = await probe(healthOrigin);
+    if (!health.ok) {
+      const receipt = {
+        ok: false,
+        skipped: false,
+        deployProjectionHash: fingerprint,
+        promoted: false,
+        git: plan.git,
+        workerVersion,
+        hostname: healthOrigin.replace(/^https?:\/\//, ''),
+        health,
+        error: 'postdeploy_health_failed',
+      };
+      writeDeployReceipt(target.appRoot, receipt);
+      throw new Error('postdeploy_health_failed');
+    }
+  }
+  const receipt = {
+    ok: true,
+    skipped: false,
+    dryRun,
+    deployProjectionHash: fingerprint,
+    promoted: !dryRun,
+    provider: 'cloudflare',
+    app: 'local-studio',
+    wranglerConfig: plan.wranglerConfig,
+    git: plan.git,
+    worker: 'agentsam-sdk',
+    workerVersion,
+    hostname: healthOrigin.replace(/^https?:\/\//, ''),
+    health,
+    originMainEqual: Boolean(plan.git?.head && plan.git.head === plan.git.originMain),
+  };
+  writeDeployReceipt(target.appRoot, receipt);
+  return { target, plan, receipt };
+}

package/src/lib/deploy/secret-scan.js

@@ -0,0 +1,65 @@
+/** Scan deployable files for live secrets. Fixtures and .example placeholders are allowed. */
+import fs from 'node:fs';
+
+const FIXTURES = new Set([
+  'sillynotreal',
+  'sillynotreal-secret',
+  'CHANGEME',
+  'replace-me',
+  'your-token-here',
+  '***',
+]);
+
+const LIVE_PATTERNS = [
+  { re: /\bsk-[A-Za-z0-9]{20,}\b/g, label: 'openai-like' },
+  { re: /\bxai-[A-Za-z0-9]{20,}\b/g, label: 'xai-like' },
+  { re: /\bAKIA[0-9A-Z]{16}\b/g, label: 'aws-like' },
+];
+
+const ASSIGN_RE = /((?:CLOUDFLARE_OAUTH_CLIENT_SECRET|CLOUDFLARE_API_TOKEN|IAM_CLIENT_SECRET|VAULT_MASTER_KEY)\s*=\s*)([^\s#]+)/g;
+
+function isExample(filename = '') {
+  return filename.endsWith('.example') || filename.includes('.env.cloudflare.example');
+}
+
+export function scanTextForSecrets(text, { filename = '' } = {}) {
+  const findings = [];
+  const src = String(text || '');
+  for (const { re, label } of LIVE_PATTERNS) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(src))) {
+      if (FIXTURES.has(m[0])) continue;
+      findings.push({ filename, label, preview: `${m[0].slice(0, 5)}…` });
+    }
+  }
+  if (isExample(filename)) return findings;
+  ASSIGN_RE.lastIndex = 0;
+  let m;
+  while ((m = ASSIGN_RE.exec(src))) {
+    const val = m[2].replace(/^[\'"]|[\'"]$/g, '');
+    if (!val || FIXTURES.has(val) || val.includes('your-') || val.length < 16) continue;
+    findings.push({ filename, label: 'assigned-secret', preview: `${m[1].trim()}[redacted]` });
+  }
+  return findings;
+}
+
+export function scanFilesForSecrets(files = []) {
+  const findings = [];
+  for (const file of files) {
+    if (!file || !fs.existsSync(file) || !fs.statSync(file).isFile()) continue;
+    findings.push(...scanTextForSecrets(fs.readFileSync(file, 'utf8'), { filename: file }));
+  }
+  return findings;
+}
+
+export function assertNoDeploySecrets(files = []) {
+  const findings = scanFilesForSecrets(files);
+  if (findings.length) {
+    const err = new Error('secret_scan_failed: ' + findings.map((f) => f.label).join(', '));
+    err.code = 'secret_scan_failed';
+    err.findings = findings;
+    throw err;
+  }
+  return { ok: true, findings: [] };
+}

package/src/lib/deploy-receipt/index.js

@@ -146,7 +146,7 @@ export async function captureDeployReceipt({
     }
   }
 
-  const tree = await buildMerkleTree(rootPath, { policy });
+  const tree = await buildMerkleTree(rootPath, { policy, semantic: true });
   await atomicJson(state.pendingSnapshot, tree);
 
   let diff = null;
@@ -163,7 +163,7 @@ export async function captureDeployReceipt({
   const receipt = {
     format: 'agentsam-deploy-merkle',
     version: 1,
-    engine: 'agentsam-merkle-v1',
+    engine: tree.semantic ? 'agentsam-merkle-v1+agentsam-filemeta-v1' : 'agentsam-merkle-v1',
     status: 'captured',
     project: project || path.basename(rootPath),
     repository: gitInfo.repository || null,
@@ -171,6 +171,9 @@ export async function captureDeployReceipt({
     git_branch: gitInfo.git_branch || null,
     captured_at: new Date().toISOString(),
     root_hash: tree.rootHash,
+    policy_hash: tree.policyHash || null,
+    metadata_root: tree.semantic?.rootHash || null,
+    classifier: tree.semantic?.classifier || null,
     previous_root_hash: baseline?.rootHash || null,
     has_baseline: Boolean(baseline),
     baseline_source: resolvedBaselineSource,

package/src/lib/detect-context.js

@@ -5,6 +5,7 @@
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { coreBaseUrl } from './core-client.js';
+import { resolveAccountSdkKey } from './account-session.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -220,22 +221,22 @@ async function detectIam(explicitToken = '') {
     });
   }
 
-  const sdkToken = explicitToken || process.env.AGENTSAM_SDK_TOKEN || '';
+  const sdkToken = resolveAccountSdkKey({ env: process.env, explicit: explicitToken }).value;
   if (sdkToken.trim()) {
     const probe = await probeSdkBearer(sdkToken);
     if (probe.valid) {
       return {
-        source: 'sdk-token',
+        source: 'sdk-key',
         ready: true,
-        detail: `AGENTSAM_SDK_TOKEN · user ${probe.user_id || '?'}`,
+        detail: `AGENTSAM_SDK_KEY · user ${probe.user_id || '?'}`,
         probe,
         aux,
       };
     }
     return {
-      source: 'sdk-token',
+      source: 'sdk-key',
       ready: false,
-      detail: `AGENTSAM_SDK_TOKEN invalid (${probe.error}) → will open browser`,
+      detail: `AGENTSAM_SDK_KEY invalid (${probe.error}) → will open browser`,
       probe,
       aux,
     };

package/src/lib/execution-approvals.js

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const SCHEMA = 'agentsam-execution-approvals-v1';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function homeDirectory(options = {}) { return path.resolve(clean(options.home) || clean(options.env?.HOME) || clean(options.env?.USERPROFILE) || os.homedir()); }
+function approvalsPath(options = {}) { return path.join(homeDirectory(options), '.agentsam', 'execution-approvals.json'); }
+
+function readStore(options = {}) {
+  const filename = approvalsPath(options);
+  if (!fs.existsSync(filename)) return { schema_version: SCHEMA, approvals: [] };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filename, 'utf8'));
+    if (parsed?.schema_version !== SCHEMA || !Array.isArray(parsed.approvals)) return { schema_version: SCHEMA, approvals: [] };
+    return parsed;
+  } catch { return { schema_version: SCHEMA, approvals: [] }; }
+}
+
+function writeStore(store, options = {}) {
+  const filename = approvalsPath(options);
+  fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+  const temp = `${filename}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(temp, 0o600); } catch { /* best effort */ }
+  }
+  fs.renameSync(temp, filename);
+}
+
+export function toolApprovalKey(capabilityId, input = {}) {
+  const id = clean(capabilityId);
+  const command = clean(input?.command);
+  if (id === 'cloudflare.wrangler.native' && /^[A-Za-z0-9._-]+$/.test(command)) return `${id}:${command}`;
+  return id;
+}
+
+export function isExecutionApproved({ cwd, key }, options = {}) {
+  const root = path.resolve(clean(cwd) || process.cwd());
+  const target = clean(key);
+  if (!target) return false;
+  return readStore(options).approvals.some((row) => row?.cwd === root && row?.key === target);
+}
+
+export function grantExecutionApproval({ cwd, key, label = '' }, options = {}) {
+  const root = path.resolve(clean(cwd) || process.cwd());
+  const target = clean(key);
+  if (!target) throw new Error('execution_approval_key_required');
+  const store = readStore(options);
+  const approvals = store.approvals.filter((row) => !(row?.cwd === root && row?.key === target));
+  approvals.push({ cwd: root, key: target, label: clean(label) || target, created_at: new Date().toISOString() });
+  writeStore({ schema_version: SCHEMA, approvals }, options);
+  return { cwd: root, key: target, persisted: true };
+}
+
+export function listExecutionApprovals(options = {}) {
+  return readStore(options).approvals.map((row) => ({ ...row }));
+}

package/src/lib/identity-scaffold.js

@@ -75,7 +75,7 @@ migrations_dir = "migrations"
   files['.env.example'] = `# Minted at install/build — secrets via wrangler secret put (never commit)
 # IAM_CLIENT_ID=          # plaintext var (public by OAuth design)
 # IAM_CLIENT_SECRET=      # wrangler secret put only
-# IAM_OAUTH_ISSUER=https://inneranimalmedia.com
+# IAM_ORIGIN=https://inneranimalmedia.com
 
 # Developer BYOK — takes /api/oauth/{google|github}/start when set
 # GOOGLE_CLIENT_ID=

package/src/lib/local-scaffold.js

@@ -4,6 +4,8 @@
  */
 
 import pkg from '../../package.json' with { type: 'json' };
+import { createProjectManifest } from './project-config.js';
+import { defaultProjectRules } from './project-rules.js';
 
 const LANE_KEYS = {
   '1': 'fullstack',
@@ -139,37 +141,24 @@ export function buildLocalScaffoldFiles({
   const migration = migrationSql(laneKey);
 
   return [
-    {
-      path: 'agentsam.config.js',
-      content: `export default {
-  project: '${projectName}',
-  lane: '${laneKey}',
-  agent: '${agent}',
-  runTarget: '${runTarget}',
-  api: { baseUrl: '/api/agentsam' },
-};
-`,
-    },
     {
       path: '.agentsam/config.json',
       content: `${JSON.stringify(
-        {
-          project: projectName,
-          lane: laneKey,
-          agent,
-          run_target: 'local',
-          deploy_target: runTarget === 'local' ? null : runTarget,
-          pty_port: 3099,
-          dev_port: 8787,
-          db_path: '.agentsam/data/agentsam.sqlite',
-          db_schema: 'db/schema.sql',
-          ui: 'terminal',
-          scaffold_version: sdkVersion,
-        },
+        createProjectManifest({
+          projectName,
+          preset: laneKey,
+          profile: agent,
+          runTarget,
+          sdkVersion,
+        }),
         null,
         2,
       )}\n`,
     },
+    {
+      path: '.agentsamrules',
+      content: defaultProjectRules(projectName),
+    },
     {
       path: '.agentsam/start-local.md',
       content: `# Agent Sam local project
@@ -187,9 +176,10 @@ Useful local surfaces:
 
 \`\`\`bash
 npm run db:status
-npm run tui
-npm run tui:rich -- --install   # optional Rich UI in isolated .agentsam venv
+npx agentsam                    # enter Agent Sam
 npx agentsam start-local        # PTY on ws://127.0.0.1:3099
+npm run ollama:setup            # optional local/free model config
+npm run ollama:status           # probe local Ollama + models
 \`\`\`
 
 The local SQLite database lives at \`.agentsam/data/agentsam.sqlite\` and is initialized from \`db/schema.sql\`.
@@ -209,7 +199,12 @@ npx agentsam deploy
 dist/
 .wrangler/
 .agentsam/data/
+.agentsam/cli.json
 .agentsam/tui-venv/
+.agentsam/knowledge/
+.agentsam/cache/
+.agentsam/merkle/
+.agentsam/merkle.json
 *.db
 *.sqlite
 *.sqlite-*
@@ -231,8 +226,8 @@ dist/
             'db:init': 'agentsam db init',
             'db:status': 'agentsam db status',
             pty: 'agentsam start-local',
-            tui: 'agentsam tui',
-            'tui:rich': 'agentsam tui rich',
+            'ollama:setup': 'agentsam ollama setup',
+            'ollama:status': 'agentsam ollama status',
             deploy: 'agentsam deploy',
           },
           engines: {
@@ -262,6 +257,11 @@ AGENTSAM_LANE=${laneKey}
 AGENTSAM_AGENT=${agent}
 AGENTSAM_DB=.agentsam/data/agentsam.sqlite
 PORT=8787
+
+# Optional free/local model runtime. Enable with: agentsam ollama setup
+# OLLAMA_BASE_URL=http://127.0.0.1:11434
+# OLLAMA_MODEL=qwen2.5-coder
+# OLLAMA_EMBED_MODEL=mxbai-embed-large
 `,
     },
     {
@@ -399,13 +399,15 @@ Local state:
 ## Agent Sam terminal experience
 
 \`\`\`bash
-npm run tui                  # zero-dependency ANSI dashboard
-npm run tui:rich             # Python Rich dashboard if installed
-npm run tui:rich -- --install
+npx agentsam                  # enter the interactive Agent Sam experience
 npm run pty                  # local PTY on ws://127.0.0.1:3099
 npm run db:status
+npm run ollama:setup         # optional local/free model config
+npm run ollama:status        # local Ollama + model readiness
 \`\`\`
 
+Ollama is optional and local-only; it is not deployed as an edge model. Remote AgentSam sessions can reach it by executing the CLI through the existing user-hosted terminal tunnel.
+
 No Worker or cloud account is required for local development.
 
 ## Graduate intentionally
@@ -443,9 +445,9 @@ export function buildLocalScaffoldMeta(body, sdkVersion = pkg.version) {
       'npm run smoke',
       'npm run status',
       'npm run dev',
-      'npm run tui',
+      'npx agentsam',
       'npm run db:status',
-      'Optional: npm run tui:rich -- --install',
+      'Optional free/local models: npm run ollama:setup',
       'Optional: npm run pty',
       'When ready for cloud: npm run deploy',
     ],