atris 3.1.0 → 3.5.0

package/commands/business.js

@@ -3,7 +3,8 @@ const path = require('path');
 const os = require('os');
 const { loadCredentials } = require('../utils/auth');
 const { apiRequestJson } = require('../utils/api');
-const { syncBusinessCanonical } = require('./sync');
+const { syncBusinessCanonical, ensureWorkspaceStateFiles } = require('./sync');
+const { ensureContextScaffold, writeWikiStatus, appendWikiLog } = require('../lib/wiki');
 
 function getBusinessConfigPath() {
   const home = require('os').homedir();
@@ -88,6 +89,7 @@ function createCanonicalBusinessWorkspace(targetRoot, bizMeta, options = {}) {
     throw new Error(`Target already contains .atris/business.json: ${targetRoot}`);
   }
 
+  const workspaceTemplate = options.templateName || bizMeta.workspace_template || 'business';
   fs.mkdirSync(atrisMetaDir, { recursive: true });
   fs.writeFileSync(businessJsonPath, JSON.stringify({
     business_id: bizMeta.business_id,
@@ -95,11 +97,669 @@ function createCanonicalBusinessWorkspace(targetRoot, bizMeta, options = {}) {
     name: bizMeta.name,
     slug: bizMeta.slug,
     owner_email: bizMeta.owner_email || '',
+    workspace_template: workspaceTemplate,
     created_at: new Date().toISOString(),
   }, null, 2));
 
-  syncBusinessCanonical(targetRoot, bizMeta, { force: false, dryRun: false });
-  return { targetRoot, businessJsonPath };
+  syncBusinessCanonical(targetRoot, bizMeta, { force: false, dryRun: false, templateName: workspaceTemplate });
+  return { targetRoot, businessJsonPath, workspaceTemplate };
+}
+
+function parseRecordFlags(args, cwd = process.cwd()) {
+  const options = {
+    cwd,
+    reportPath: null,
+    summary: '',
+    metric: '',
+    outcome: 'recorded',
+    reward: null,
+    loop: 'manual',
+    actor: 'operator',
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const next = args[i + 1];
+
+    if ((arg === '--summary' || arg === '-s') && next) {
+      options.summary = next;
+      i++;
+    } else if ((arg === '--metric' || arg === '-m') && next) {
+      options.metric = next;
+      i++;
+    } else if ((arg === '--outcome' || arg === '-o') && next) {
+      options.outcome = next;
+      i++;
+    } else if ((arg === '--reward' || arg === '-r') && next) {
+      options.reward = next;
+      i++;
+    } else if (arg === '--loop' && next) {
+      options.loop = next;
+      i++;
+    } else if (arg === '--actor' && next) {
+      options.actor = next;
+      i++;
+    } else if (!arg.startsWith('-') && !options.reportPath) {
+      options.reportPath = arg;
+    }
+  }
+
+  return options;
+}
+
+function parseOnboardFlags(args, cwd = process.cwd()) {
+  const options = {
+    cwd,
+    name: '',
+    website: '',
+    links: [],
+    notes: [],
+    sources: [],
+    contactName: '',
+    contactEmail: '',
+    contactRole: '',
+  };
+  const freeform = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const next = args[i + 1];
+
+    if ((arg === '--name' || arg === '--business') && next) {
+      options.name = next;
+      i++;
+    } else if ((arg === '--website' || arg === '--site') && next) {
+      options.website = next;
+      i++;
+    } else if ((arg === '--link' || arg === '--url') && next) {
+      options.links.push(next);
+      i++;
+    } else if ((arg === '--from' || arg === '--source') && next) {
+      options.sources.push(next);
+      i++;
+    } else if ((arg === '--note' || arg === '--notes') && next) {
+      options.notes.push(next);
+      i++;
+    } else if ((arg === '--contact' || arg === '--person') && next) {
+      options.contactName = next;
+      i++;
+    } else if (arg === '--email' && next) {
+      options.contactEmail = next;
+      i++;
+    } else if (arg === '--role' && next) {
+      options.contactRole = next;
+      i++;
+    } else if (!arg.startsWith('-')) {
+      const resolved = path.resolve(cwd, arg);
+      if (/^https?:\/\//i.test(arg)) {
+        if (!options.website) options.website = arg;
+        else options.links.push(arg);
+      } else if (fs.existsSync(resolved)) {
+        options.sources.push(arg);
+      } else {
+        freeform.push(arg);
+      }
+    }
+  }
+
+  if (freeform.length > 0) {
+    options.notes.push(freeform.join(' '));
+  }
+
+  return options;
+}
+
+function readWorkspaceBusinessMeta(cwd = process.cwd()) {
+  const bizFile = path.join(cwd, '.atris', 'business.json');
+  if (!fs.existsSync(bizFile)) {
+    throw new Error('Run this command inside a business environment with .atris/business.json.');
+  }
+  try {
+    return JSON.parse(fs.readFileSync(bizFile, 'utf8'));
+  } catch (error) {
+    throw new Error(`Failed to read .atris/business.json: ${error.message}`);
+  }
+}
+
+function resolveWorkspaceReport(cwd, reportPath) {
+  if (!reportPath) {
+    throw new Error('Usage: atris business record <report-path> [--summary "text"] [--metric name] [--outcome positive|mixed|negative] [--reward N]');
+  }
+  const absPath = path.resolve(cwd, reportPath);
+  if (!fs.existsSync(absPath) || !fs.statSync(absPath).isFile()) {
+    throw new Error(`Report not found: ${reportPath}`);
+  }
+  const relPath = path.relative(cwd, absPath).replace(/\\/g, '/');
+  return { absPath, relPath };
+}
+
+function extractReportTitle(content, absPath) {
+  const heading = String(content || '').match(/^#\s+(.+)$/m);
+  if (heading) return heading[1].trim();
+  return path.basename(absPath, path.extname(absPath));
+}
+
+function normalizeOutcome(value) {
+  const normalized = String(value || 'recorded').trim().toLowerCase();
+  if (['positive', 'win', 'success', 'improved'].includes(normalized)) return 'positive';
+  if (['negative', 'loss', 'failed', 'regressed'].includes(normalized)) return 'negative';
+  if (['mixed', 'partial', 'unclear'].includes(normalized)) return 'mixed';
+  return 'recorded';
+}
+
+function defaultRewardForOutcome(outcome) {
+  if (outcome === 'positive') return 5;
+  if (outcome === 'negative') return -3;
+  if (outcome === 'mixed') return 1;
+  return 0;
+}
+
+function appendJsonl(filePath, record) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.appendFileSync(filePath, `${JSON.stringify(record)}\n`, 'utf8');
+}
+
+function slugifyName(value) {
+  return String(value || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'item';
+}
+
+function upsertIndexEntry(indexPath, sectionName, relativePath, description) {
+  const normalizedPath = relativePath.replace(/\\/g, '/');
+  const entryLine = `- [[${normalizedPath}]] - ${description}`;
+  let lines = fs.readFileSync(indexPath, 'utf8').split('\n');
+  const existingIndex = lines.findIndex((line) => line.includes(`[[${normalizedPath}]]`));
+  if (existingIndex >= 0) {
+    lines[existingIndex] = entryLine;
+    fs.writeFileSync(indexPath, `${lines.join('\n').replace(/\n*$/, '\n')}`, 'utf8');
+    return;
+  }
+
+  const header = `## ${sectionName}`;
+  const sectionIndex = lines.findIndex((line) => line.trim() === header);
+  if (sectionIndex === -1) return;
+
+  let insertAt = sectionIndex + 1;
+  while (insertAt < lines.length && !/^##\s+/.test(lines[insertAt])) {
+    insertAt++;
+  }
+
+  lines.splice(insertAt, 0, entryLine);
+  fs.writeFileSync(indexPath, `${lines.join('\n').replace(/\n*$/, '\n')}`, 'utf8');
+}
+
+function writeMarkdownWithFrontmatter(filePath, frontmatter, body) {
+  const yaml = Object.entries(frontmatter).map(([key, value]) => {
+    if (Array.isArray(value)) {
+      return `${key}:\n${value.map((item) => `  - ${item}`).join('\n')}`;
+    }
+    return `${key}: ${value}`;
+  }).join('\n');
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `---\n${yaml}\n---\n\n${body.trim()}\n`, 'utf8');
+}
+
+function walkOnboardingFiles(dir, options = {}) {
+  const skipDirs = new Set(['.git', '.atris', 'atris', '_ingest', 'node_modules', 'dist', 'build', 'coverage', '.next']);
+  const allowedExt = new Set(['.md', '.txt', '.pdf', '.csv', '.json', '.html', '.htm', '.docx', '.xlsx', '.png', '.jpg', '.jpeg']);
+  const maxFiles = options.maxFiles || 25;
+  const output = [];
+
+  function walk(currentDir) {
+    if (!fs.existsSync(currentDir) || output.length >= maxFiles) return;
+    for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+      if (output.length >= maxFiles) break;
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (skipDirs.has(entry.name)) continue;
+        walk(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (entry.name.startsWith('.')) continue;
+      if (!allowedExt.has(path.extname(entry.name).toLowerCase())) continue;
+      output.push(fullPath);
+    }
+  }
+
+  walk(dir);
+  return output;
+}
+
+function extractUrlsFromText(text) {
+  return Array.from(new Set((String(text || '').match(/https?:\/\/[^\s)<>"']+/g) || []).map((item) => item.replace(/[.,]$/, ''))));
+}
+
+function isTextLike(filePath) {
+  return new Set(['.md', '.txt', '.json', '.csv', '.html', '.htm']).has(path.extname(filePath).toLowerCase());
+}
+
+function readSmallText(filePath, maxBytes = 200000) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (stat.size > maxBytes || !isTextLike(filePath)) return null;
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function discoverOnboardingSignals(cwd, options = {}) {
+  const explicitSourcePaths = (options.sources || [])
+    .map((value) => path.resolve(cwd, value))
+    .filter((fullPath) => fs.existsSync(fullPath));
+
+  const rootCandidates = walkOnboardingFiles(cwd, { maxFiles: 20 })
+    .filter((fullPath) => {
+      const relative = path.relative(cwd, fullPath).replace(/\\/g, '/');
+      return !relative.startsWith('atris/') && !relative.startsWith('.atris/');
+    });
+
+  const contextDir = path.join(cwd, 'atris', 'context');
+  const contextCandidates = walkOnboardingFiles(contextDir, { maxFiles: 20 })
+    .filter((fullPath) => {
+      const relative = path.relative(contextDir, fullPath).replace(/\\/g, '/');
+      return !relative.startsWith('_ingest/') && relative !== 'README.md' && relative !== 'live-workspace.md';
+    });
+
+  const sourcePaths = Array.from(new Set([...explicitSourcePaths, ...rootCandidates, ...contextCandidates]));
+  const urls = new Set([options.website, ...(options.links || [])].filter(Boolean));
+
+  for (const note of options.notes || []) {
+    for (const url of extractUrlsFromText(note)) urls.add(url);
+  }
+
+  for (const sourcePath of sourcePaths) {
+    const text = readSmallText(sourcePath);
+    if (!text) continue;
+    for (const url of extractUrlsFromText(text)) urls.add(url);
+  }
+
+  return {
+    website: options.website || Array.from(urls)[0] || '',
+    urls: Array.from(urls),
+    sourcePaths,
+  };
+}
+
+function stageOnboardingSources(cwd, packDir, sourcePaths = []) {
+  const stagedDir = path.join(packDir, 'sources');
+  fs.mkdirSync(stagedDir, { recursive: true });
+  const stagedEntries = [];
+  let counter = 0;
+
+  for (const sourcePath of sourcePaths) {
+    if (!fs.existsSync(sourcePath)) continue;
+    counter += 1;
+    const baseName = path.basename(sourcePath);
+    const targetPath = path.join(stagedDir, `${String(counter).padStart(2, '0')}-${baseName}`);
+    const stat = fs.statSync(sourcePath);
+    if (stat.isDirectory()) {
+      fs.cpSync(sourcePath, targetPath, { recursive: true });
+    } else {
+      fs.copyFileSync(sourcePath, targetPath);
+    }
+    stagedEntries.push({
+      original: path.relative(cwd, sourcePath).replace(/\\/g, '/'),
+      staged: path.relative(cwd, targetPath).replace(/\\/g, '/'),
+      kind: stat.isDirectory() ? 'directory' : 'file',
+    });
+  }
+
+  return stagedEntries;
+}
+
+function suggestStarterAction(signals) {
+  if (signals.contactEmail && signals.website) {
+    return {
+      title: 'Draft a founder-context note',
+      action: `Write a short note to ${signals.contactName || 'the contact'} that reflects the website, asks for the current priority, and proposes one concrete first loop.`,
+      why: 'This is the shortest safe path to real feedback from a named human.',
+    };
+  }
+  if (signals.website) {
+    return {
+      title: 'Map the offer into one loop',
+      action: 'Read the website and turn it into one measurable workflow with a clear reward signal.',
+      why: 'A website is enough to define a first useful business loop without waiting for perfect intake.',
+    };
+  }
+  if ((signals.sourceEntries || []).length > 0) {
+    return {
+      title: 'Extract the first workflow from local evidence',
+      action: 'Read the strongest local source, summarize what the company does, and choose one workflow worth operationalizing first.',
+      why: 'Local evidence is already better than a blank template and can anchor the first action.',
+    };
+  }
+  return {
+    title: 'Collect one anchor signal',
+    action: 'Get one website, one named human, or one source doc so the environment can stop guessing.',
+    why: 'The system can work from partial input, but it still needs one concrete anchor.',
+  };
+}
+
+async function onboardBusiness(...flags) {
+  const options = parseOnboardFlags(flags, process.cwd());
+  const cwd = options.cwd || process.cwd();
+
+  const bizFile = path.join(cwd, '.atris', 'business.json');
+  if (!fs.existsSync(bizFile) && options.name) {
+    const slug = slugifyName(options.name);
+    createCanonicalBusinessWorkspace(cwd, {
+      business_id: '',
+      workspace_id: '',
+      name: options.name,
+      slug,
+      owner_email: '',
+      workspace_template: 'business',
+    }, { here: true });
+  }
+
+  const bizMeta = readWorkspaceBusinessMeta(cwd);
+
+  ensureWorkspaceStateFiles(cwd, {
+    slug: bizMeta.slug || 'business',
+    business_id: bizMeta.business_id || '',
+    workspace_id: bizMeta.workspace_id || '',
+    workspace_template: bizMeta.workspace_template || 'business',
+  }, { dryRun: false });
+
+  const contextDir = ensureContextScaffold(cwd, 'public');
+  const stamp = new Date().toISOString().replace(/[:]/g, '-').slice(0, 16);
+  const packDir = path.join(contextDir, '_ingest', `${stamp}-onboarding`);
+  fs.mkdirSync(packDir, { recursive: true });
+
+  const discovered = discoverOnboardingSignals(cwd, options);
+  const stagedSources = stageOnboardingSources(cwd, packDir, discovered.sourcePaths);
+  const links = Array.from(new Set([discovered.website, ...discovered.urls].filter(Boolean)));
+  const starterAction = suggestStarterAction({
+    website: discovered.website,
+    contactName: options.contactName,
+    contactEmail: options.contactEmail,
+    sourceEntries: stagedSources,
+  });
+  const intakeLines = [
+    `# ${bizMeta.name} Onboarding Intake`,
+    '',
+    `- Business: ${bizMeta.name}`,
+    `- Slug: ${bizMeta.slug}`,
+    discovered.website ? `- Website: ${discovered.website}` : null,
+    options.contactName ? `- Contact: ${options.contactName}` : null,
+    options.contactRole ? `- Contact role: ${options.contactRole}` : null,
+    options.contactEmail ? `- Contact email: ${options.contactEmail}` : null,
+    '',
+    '## Notes',
+    ...(options.notes.length > 0 ? options.notes.map((note) => `- ${note}`) : ['- No notes captured yet.']),
+    '',
+    '## Discovered Sources',
+    ...(stagedSources.length > 0 ? stagedSources.map((entry) => `- ${entry.original} -> ${entry.staged}`) : ['- No local files discovered yet.']),
+    '',
+    '## Links',
+    ...(links.length > 0 ? links.map((link) => `- ${link}`) : ['- No links captured yet.']),
+  ].filter(Boolean);
+  const intakePath = path.join(packDir, 'intake.md');
+  fs.writeFileSync(intakePath, `${intakeLines.join('\n')}\n`, 'utf8');
+
+  const linksPath = path.join(packDir, 'links.txt');
+  fs.writeFileSync(linksPath, `${links.join('\n')}${links.length > 0 ? '\n' : ''}`, 'utf8');
+  const sourcesPath = path.join(packDir, 'sources.txt');
+  fs.writeFileSync(
+    sourcesPath,
+    `${stagedSources.map((entry) => `${entry.original} -> ${entry.staged}`).join('\n')}${stagedSources.length > 0 ? '\n' : ''}`,
+    'utf8'
+  );
+
+  const intakeRel = path.relative(cwd, intakePath).replace(/\\/g, '/');
+  const linksRel = path.relative(cwd, linksPath).replace(/\\/g, '/');
+  const sourcesRel = path.relative(cwd, sourcesPath).replace(/\\/g, '/');
+  const today = new Date().toISOString().slice(0, 10);
+
+  const briefSlug = `${bizMeta.slug}-starter-brief`;
+  const briefPath = path.join(cwd, 'atris', 'wiki', 'briefs', `${briefSlug}.md`);
+  writeMarkdownWithFrontmatter(briefPath, {
+    type: 'brief',
+    slug: briefSlug,
+    title: `${bizMeta.name} Starter Brief`,
+    sources: [intakeRel, linksRel, sourcesRel],
+    last_compiled: today,
+    created: today,
+    updated: today,
+    tags: ['business', 'onboarding', 'starter'],
+  }, `
+# ${bizMeta.name} Starter Brief
+
+## What We Know
+
+- Website: ${discovered.website || 'unknown'}
+- Contact: ${options.contactName || 'unknown'}
+- Contact role: ${options.contactRole || 'unknown'}
+- Contact email: ${options.contactEmail || 'unknown'}
+${options.notes.map((note) => `- Note: ${note}`).join('\n') || '- Notes: none captured yet'}
+${stagedSources.length > 0 ? `- Local sources discovered: ${stagedSources.length}` : '- Local sources discovered: 0'}
+
+## Unknowns
+
+- Primary customer or audience
+- Revenue model and buying motion
+- Main operator inside the business
+- Tool stack and source systems
+- First measurable operating loop
+
+## Next Moves
+
+- Read the staged intake in \`${intakeRel}\`
+- ${starterAction.action}
+- Turn the first real interaction into a recap, then run \`atris business record ...\`
+`);
+  upsertIndexEntry(path.join(cwd, 'atris', 'wiki', 'index.md'), 'Briefs', path.relative(cwd, briefPath), 'Starter business brief from onboarding intake');
+
+  let personRelativePath = null;
+  if (options.contactName) {
+    const personSlug = slugifyName(options.contactName);
+    const personPath = path.join(cwd, 'atris', 'wiki', 'people', `${personSlug}.md`);
+    writeMarkdownWithFrontmatter(personPath, {
+      type: 'person',
+      slug: personSlug,
+      title: options.contactName,
+      sources: [intakeRel, sourcesRel],
+      last_compiled: today,
+      created: today,
+      updated: today,
+      tags: ['person', 'contact', 'onboarding'],
+    }, `
+# ${options.contactName}
+
+## Known
+
+- Business: ${bizMeta.name}
+- Role: ${options.contactRole || 'unknown'}
+- Email: ${options.contactEmail || 'unknown'}
+
+## Unknown
+
+- Decision authority
+- Preferred communication rhythm
+- Main business pain
+
+## Cross-References
+
+- [[atris/wiki/briefs/${path.basename(briefPath)}]] - starter brief
+`);
+    personRelativePath = path.relative(cwd, personPath).replace(/\\/g, '/');
+    upsertIndexEntry(path.join(cwd, 'atris', 'wiki', 'index.md'), 'People', personRelativePath, `Seed contact for ${bizMeta.name}`);
+  }
+
+  const conceptSlug = `${bizMeta.slug}-first-loop`;
+  const conceptPath = path.join(cwd, 'atris', 'wiki', 'concepts', `${conceptSlug}.md`);
+  writeMarkdownWithFrontmatter(conceptPath, {
+    type: 'concept',
+    slug: conceptSlug,
+    title: `${bizMeta.name} First Loop`,
+    sources: [intakeRel, linksRel, sourcesRel],
+    last_compiled: today,
+    created: today,
+    updated: today,
+    tags: ['concept', 'loop', 'onboarding'],
+  }, `
+# ${bizMeta.name} First Loop
+
+## Candidate Loop
+
+- Trigger: a new lead, meeting, client request, or operator handoff
+- Action: summarize context, propose the next move, and draft one concrete output
+- Reward: operator approval, reply, booked meeting, or visible pipeline progress
+
+## Known Signals
+
+${links.map((link) => `- ${link}`).join('\n') || '- No external links captured yet'}
+${stagedSources.length > 0 ? `- Local evidence files: ${stagedSources.length}` : ''}
+
+## Unknowns
+
+- Best first workflow to automate
+- Exact reward signal
+- Required integrations
+`);
+  upsertIndexEntry(path.join(cwd, 'atris', 'wiki', 'index.md'), 'Concepts', path.relative(cwd, conceptPath), 'Seed first-loop hypothesis from onboarding intake');
+
+  const cheatSheetPath = path.join(cwd, 'atris', 'reports', `${today}-${bizMeta.slug}-onboarding-cheat-sheet.md`);
+  const onePagerPath = path.join(cwd, 'atris', 'reports', `${today}-${bizMeta.slug}-operator-one-pager.md`);
+  const operatorSummary = [
+    `# ${bizMeta.name} Onboarding Cheat Sheet`,
+    '',
+    '## What Exists',
+    `- Starter brief: ${path.relative(cwd, briefPath).replace(/\\/g, '/')}`,
+    personRelativePath ? `- Contact page: ${personRelativePath}` : null,
+    `- First loop page: ${path.relative(cwd, conceptPath).replace(/\\/g, '/')}`,
+    `- Raw intake: ${intakeRel}`,
+    `- Source list: ${sourcesRel}`,
+    stagedSources.length > 0 ? `- Staged sources: ${stagedSources.length}` : '- Staged sources: 0',
+    '',
+    '## Best Next Action',
+    `- ${starterAction.title}`,
+    `- Action: ${starterAction.action}`,
+    `- Why: ${starterAction.why}`,
+    '- Swarlo join: placeholder preserved for the next live join step.',
+    '',
+    '## Next 3 Moves',
+    '- Open the starter brief and correct anything false.',
+    `- ${starterAction.action}`,
+    '- After the first real run, write a recap and record it with `atris business record ...`.',
+  ].filter(Boolean).join('\n') + '\n';
+  fs.writeFileSync(cheatSheetPath, operatorSummary, 'utf8');
+  fs.writeFileSync(onePagerPath, operatorSummary.replace('# ', '# One Pager — '), 'utf8');
+
+  const todoPath = path.join(cwd, 'atris', 'TODO.md');
+  if (fs.existsSync(todoPath)) {
+    let todoContent = fs.readFileSync(todoPath, 'utf8');
+    const taskLine = `- **Onboard:** ${starterAction.title} — ${starterAction.action} [execute]\n`;
+    const backlogMatch = todoContent.match(/^## Backlog\s*$/m);
+    if (backlogMatch) {
+      const insertAt = backlogMatch.index + backlogMatch[0].length;
+      todoContent = todoContent.slice(0, insertAt) + '\n' + taskLine + todoContent.slice(insertAt);
+    } else {
+      todoContent += '\n## Backlog\n\n' + taskLine;
+    }
+    fs.writeFileSync(todoPath, todoContent, 'utf8');
+  }
+
+  writeWikiStatus(cwd, {
+    health: `starter onboarding compiled from ${intakeRel}`,
+    nextMove: `review ${path.relative(cwd, briefPath).replace(/\\/g, '/')} and tighten the first loop`,
+  }, 'public', { lastIngest: `${today} ${new Date().toTimeString().slice(0, 5)}` });
+  appendWikiLog(cwd, `starter onboarding compiled for ${bizMeta.slug}`, [
+    `intake ${intakeRel}`,
+    `sources ${sourcesRel}`,
+    `brief ${path.relative(cwd, briefPath).replace(/\\/g, '/')}`,
+    personRelativePath ? `person ${personRelativePath}` : null,
+    `concept ${path.relative(cwd, conceptPath).replace(/\\/g, '/')}`,
+    `cheat sheet ${path.relative(cwd, cheatSheetPath).replace(/\\/g, '/')}`,
+    `one pager ${path.relative(cwd, onePagerPath).replace(/\\/g, '/')}`,
+  ].filter(Boolean), 'public', 'ONBOARD');
+
+  console.log('');
+  console.log(`Onboarded ${bizMeta.name}.`);
+  console.log(`  Intake:      ${intakeRel}`);
+  console.log(`  Sources:     ${sourcesRel}`);
+  console.log(`  Brief:       ${path.relative(cwd, briefPath).replace(/\\/g, '/')}`);
+  if (personRelativePath) console.log(`  Contact:     ${personRelativePath}`);
+  console.log(`  First loop:  ${path.relative(cwd, conceptPath).replace(/\\/g, '/')}`);
+  console.log(`  Cheat sheet: ${path.relative(cwd, cheatSheetPath).replace(/\\/g, '/')}`);
+  console.log(`  One pager:   ${path.relative(cwd, onePagerPath).replace(/\\/g, '/')}`);
+  console.log(`  Next action: ${starterAction.title}`);
+  console.log('');
+}
+
+async function recordBusinessRun(reportArg, ...flags) {
+  const options = parseRecordFlags([reportArg, ...flags], process.cwd());
+  const cwd = options.cwd || process.cwd();
+  const bizMeta = readWorkspaceBusinessMeta(cwd);
+  const { absPath, relPath } = resolveWorkspaceReport(cwd, options.reportPath);
+
+  ensureWorkspaceStateFiles(cwd, {
+    slug: bizMeta.slug || 'business',
+    business_id: bizMeta.business_id || '',
+    workspace_id: bizMeta.workspace_id || '',
+    workspace_template: bizMeta.workspace_template || 'business',
+  }, { dryRun: false });
+
+  const reportContent = fs.readFileSync(absPath, 'utf8');
+  const title = extractReportTitle(reportContent, absPath);
+  const outcome = normalizeOutcome(options.outcome);
+  const reward = options.reward != null ? Number(options.reward) : defaultRewardForOutcome(outcome);
+  if (!Number.isFinite(reward)) {
+    throw new Error(`Invalid reward: ${options.reward}`);
+  }
+
+  const recordedAt = new Date().toISOString();
+  const summary = options.summary || title;
+  const metric = options.metric || null;
+  const loop = options.loop || 'manual';
+  const actor = options.actor || 'operator';
+  const stateDir = path.join(cwd, '.atris', 'state');
+
+  const shared = {
+    recorded_at: recordedAt,
+    business_slug: bizMeta.slug || null,
+    business_name: bizMeta.name || null,
+    business_id: bizMeta.business_id || null,
+    workspace_id: bizMeta.workspace_id || null,
+    workspace_template: bizMeta.workspace_template || 'business',
+    report_path: relPath,
+    report_title: title,
+    summary,
+    metric,
+    outcome,
+    reward,
+    loop,
+    actor,
+  };
+
+  appendJsonl(path.join(stateDir, 'events.jsonl'), {
+    ...shared,
+    type: 'report_recorded',
+  });
+
+  appendJsonl(path.join(stateDir, 'episodes.jsonl'), {
+    ...shared,
+    type: 'episode',
+  });
+
+  appendJsonl(path.join(stateDir, 'scorecards.jsonl'), {
+    ...shared,
+    type: 'scorecard',
+  });
+
+  console.log('');
+  console.log(`Recorded recap for ${bizMeta.name || bizMeta.slug || 'workspace'}.`);
+  console.log(`  Report:  ${relPath}`);
+  console.log(`  Outcome: ${outcome}`);
+  console.log(`  Reward:  ${reward}`);
+  if (metric) console.log(`  Metric:  ${metric}`);
+  console.log('  State:   .atris/state/events.jsonl, episodes.jsonl, scorecards.jsonl');
+  console.log('');
 }
 
 function detectBusinessSlug(explicitSlug) {
@@ -198,7 +858,7 @@ async function listBusinesses(opts = {}) {
  * Walk ~/arena/atris-business/ and print a fleet status table for every
  * customer workspace. Pure local — no API calls, no rate-limit risk.
  *
- * Classifies each dir as: canonical, flat, unbound, nested, bare, or superseded.
+ * Classifies each dir as: ready, flat, unbound, nested, bare, or superseded.
  *
  * Discovered the need for this during overnight loop tick #3 when we hand-wrote
  * /tmp/customer_fleet.md. Now any team member can run `atris business list --local`
@@ -253,7 +913,7 @@ function listBusinessesLocal(opts = {}) {
 
     let state, action, icon;
     if (hasBizJson && hasAtris) {
-      state = 'canonical'; action = 'none'; icon = '🟢';
+      state = 'ready'; action = 'none'; icon = '🟢';
     } else if (hasBizJson && !hasAtris) {
       state = 'flat'; action = 'migrate to atris/ wrapper'; icon = '🟡';
     } else if (!hasBizJson && hasAtris) {
@@ -263,7 +923,7 @@ function listBusinessesLocal(opts = {}) {
     } else if (total < 5) {
       state = 'bare'; action = 'not yet onboarded'; icon = '⚪';
     } else {
-      state = 'flat-unbound'; action = 'needs canonical init'; icon = '🟡';
+      state = 'flat-unbound'; action = 'needs business init'; icon = '🟡';
     }
 
     let bizName = name;
@@ -309,7 +969,7 @@ function listBusinessesLocal(opts = {}) {
   console.log('  CUSTOMER              STATE         FILES   BIZ.JSON  ATRIS/  ACTION');
   console.log('  ' + '─'.repeat(83));
 
-  const order = ['canonical', 'flat', 'unbound', 'flat-unbound', 'bare', 'nested', 'superseded'];
+  const order = ['ready', 'flat', 'unbound', 'flat-unbound', 'bare', 'nested', 'superseded'];
   const grouped = {};
   for (const c of customers) {
     if (!grouped[c.state]) grouped[c.state] = [];
@@ -678,7 +1338,7 @@ async function createBusinessInternal(name, flags = [], mode = 'auto') {
     }, { here: options.here });
     console.log(`  Local workspace: ${scaffold.targetRoot}/`);
   } else if (!options.noLocal) {
-    console.log('  Tip: run `atris business init "<name>"` or add `--workspace` for a local canonical workspace.');
+    console.log('  Tip: run `atris business init "<name>"` or add `--workspace` for a local business environment.');
   }
 
   const template = options.template;
@@ -1152,9 +1812,18 @@ async function quickstart() {
   2. Open the local workspace:
      cd ~/arena/atris-business/my-company
 
-  3. Push local state to cloud:
+  3. Seed onboarding context:
+     atris business onboard --website https://example.com --contact "Founder Name" --note "what they do"
+
+  4. Push local state to cloud:
      atris align --fix
 
+  Then open atris/TODO.md and work the starter queue:
+     define the first loop -> add named humans -> write the first recap
+
+  After the first recap lands:
+     atris business record atris/reports/YYYY-MM-DD-your-recap.md --outcome mixed --metric "operator speed"
+
   Optional:
      atris business connect slack --business my-company
      atris business connect github --business my-company
@@ -1225,6 +1894,13 @@ async function businessCommand(subcommand, ...args) {
     case 'push':
       await deployBusiness(args[0]);
       break;
+    case 'record':
+    case 'record-recap':
+      await recordBusinessRun(args[0], ...args.slice(1));
+      break;
+    case 'onboard':
+      await onboardBusiness(...args);
+      break;
     case 'quickstart':
     case 'start':
     case 'guide':
@@ -1235,9 +1911,9 @@ async function businessCommand(subcommand, ...args) {
       console.log('');
       console.log('  quickstart           ← Start here! 3-command guide');
       console.log('');
-      console.log('  init <name>          Create a canonical business workspace (cloud + local)');
+      console.log('  init <name>          Create a business environment (cloud + local)');
       console.log('  workspace <name>     Alias for init');
-      console.log('  create <name>        Create the cloud business; add --workspace for local canonical scaffold');
+      console.log('  create <name>        Create the cloud business; add --workspace for a local business environment');
       console.log('  add <slug>           Register an existing cloud business');
       console.log('  list                 Show registered businesses');
       console.log('  team [slug]          Show members, roles, and admin access');
@@ -1247,6 +1923,8 @@ async function businessCommand(subcommand, ...args) {
       console.log('  connect <service>    Connect a skill/integration');
       console.log('  notify <mode>        Set notification mode (digest/silent/push)');
       console.log('  deploy <slug>        Push local business to cloud');
+      console.log('  onboard              Seed brief, person, first loop, safe next action, and one-pager from sparse input');
+      console.log('  record <report>      Append recap state into events, episodes, and scorecards');
       console.log('  remove <slug>        Unregister locally');
   }
 }
@@ -1261,4 +1939,6 @@ module.exports = {
   getBusinessConfigPath,
   createCanonicalBusinessWorkspace,
   initBusinessWorkspace,
+  onboardBusiness,
+  recordBusinessRun,
 };