@aetheros/cli 0.1.0 → 0.1.2

package/bin/aether.js

@@ -5,7 +5,7 @@ import { pathToFileURL } from 'node:url';
 import { checkProject, installKit, KITS, gitHooksStatus, installGitHooks, uninstallGitHooks, GROUPS, addIdea, addOwnerItem, completeOwnerItem, decideIdea, ownerSummary, planIdea, readOwner } from '@aetheros/workflow';
 import { installClaudeCodeTemplates } from '@aetheros/provider-claude';
 import { installOpenAITemplates } from '@aetheros/provider-openai';
-import { approveSpec, checkSpecRecords, evaluateApprovedSpecGate, linkSpec, listSpecs, specStatus } from '@aetheros/spec-kit';
+import { approveSpec, checkSpecRecords, createSpec, evaluateApprovedSpecGate, linkSpec, listSpecs, specStatus } from '@aetheros/specs';
 const flag = (args, name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
 const describe = s => `${s.spec}: ${s.approved ? 'approved by ' + s.approvedBy : s.stale ? 'changed since approval (' + s.changed.join(', ') + ')' : s.ready ? 'ready, not approved' : 'missing ' + s.missing.join(', ')}${s.feature ? ' | ' + s.feature : ''}${s.issue ? ' | #' + s.issue : ''}`;
 import { checkMachine, setup } from '../src/setup.js';
@@ -89,7 +89,8 @@ export function run(args, cwd = process.cwd(), log = console.log) {
   if (command === 'spec') {
     const [, sub, path] = args;
     if (sub === 'list') { const all = listSpecs(cwd); if (!all.length) log('no specs/ directories'); for (const s of all) log(describe(s)); return; }
-    if (!path || !['status', 'link', 'approve', 'gate'].includes(sub)) throw new Error('Usage: aether spec <list|status <path>|link <path> [--feature <dir>] [--issue <n>]|approve <path> --by <name>|gate <path>>');
+    if (sub === 'new') { log('created ' + createSpec(cwd, args.slice(2).filter(a => !a.startsWith('--')).join(' '))); return; }
+    if (!path || !['status', 'link', 'approve', 'gate'].includes(sub)) throw new Error('Usage: aether spec <list|new <name>|status <path>|link <path> [--feature <dir>] [--issue <n>]|approve <path> --by <name>|gate <path>>');
     if (sub === 'status') { log(describe(specStatus(cwd, path))); return; }
     if (sub === 'link') { const issue = flag(args, '--issue'); linkSpec(cwd, path, { feature: flag(args, '--feature'), issue: issue === undefined ? undefined : Number(issue) }); log(describe(specStatus(cwd, path))); return; }
     if (sub === 'approve') { approveSpec(cwd, path, { approver: flag(args, '--by') }); log(describe(specStatus(cwd, path))); return; }
@@ -107,9 +108,36 @@ export function run(args, cwd = process.cwd(), log = console.log) {
     log('workflow docs ok');
     return;
   }
-  throw new Error('Usage: aether <init|doctor|status|install <kit>...|check|spec ...|run <pack>|run init <dir>|room [serve|snapshot|html <file>|install-vscode]|owner ...|idea ...|githooks <install|uninstall|status>|setup [--yes|--kits a,b] [--os-name ..] [--assistant ..] [--accent #hex] [--dry-run]|setup machine [--install [--yes]]|doctor machine|version|sprint <status|plan|close>|voice [--ai provider] [--model id|--tier t] [--agents [--agent id]] [--pack dir]|workspace [init] [--no-memory] [--no-price-refresh]|models [list|pick --tier cheap|balanced|strong|init|prices [update]]>');
+  throw new Error('Usage: aether <start [--reset|--where|--no-open|--no-voice|--launchers]|init|doctor|status|install <kit>...|check|spec ...|run <pack>|run init <dir>|room [serve|snapshot|html <file>|install-vscode]|owner ...|idea ...|step <id|reset> [note]|notice <text>|adopt [--dry-run] [--departments <file>]|autonomy [status|defaults|on|off]|githooks <install|uninstall|status>|setup [--yes|--kits a,b] [--os-name ..] [--assistant ..] [--accent #hex] [--dry-run]|setup machine [--install [--yes]]|doctor machine|version|sprint <status|plan|close>|voice [--ai provider] [--model id|--tier t] [--agents [--agent id]] [--pack dir]|workspace [init] [--no-memory] [--no-price-refresh]|models [list|pick --tier cheap|balanced|strong|init|prices [update]]>');
 }
-if (isMain && process.argv[2] === 'sprint') {
+if (isMain && process.argv[2] === 'start') {
+  import('../src/start.js').then(m => m.start(process.argv.slice(3), process.cwd())).catch(error => { console.error(error.message); process.exitCode = 1; });
+} else if (isMain && process.argv[2] === 'step') {
+  // aether step build "started the search page"  |  aether step reset   (the command centre's build track)
+  const [id, ...note] = process.argv.slice(3);
+  import('@aetheros/workspace').then(m => { if (!id) throw new Error('Usage: aether step <step id|reset> [short note]'); m.recordStep(process.cwd(), { step: id, note: note.join(' '), session: 'cli' }); console.log(id === 'reset' ? 'build track reset' : `step reached: ${id}`); }).catch(error => { console.error(error.message); process.exitCode = 1; });
+} else if (isMain && process.argv[2] === 'autonomy') {
+  // aether autonomy [status|defaults|on|off]: standing approvals (.aether/autonomy.json). Without the file, everything waits in Review.
+  import('@aetheros/workspace').then(m => {
+    const sub = process.argv[3] || 'status', root = process.cwd();
+    if (sub === 'defaults') { m.setAutonomy(root, { defaults: true }); console.log('wrote .aether/autonomy.json with the recommended standing approvals (handover and docs, owner list, notes, issues)'); return; }
+    if (sub === 'on' || sub === 'off') { m.setAutonomy(root, { enabled: sub === 'on' }); console.log('standing approvals are ' + sub); return; }
+    if (sub !== 'status') throw new Error('Usage: aether autonomy <status|defaults|on|off>');
+    const s = m.createAutonomy(root).status();
+    if (s.error) throw new Error('autonomy.json: ' + s.error);
+    if (!s.present) { console.log('Nothing is automatic. Everything waits in Review. (aether autonomy defaults writes the recommended starting point.)'); return; }
+    console.log('standing approvals are ' + (s.enabled ? 'on' : 'off'));
+    for (const r of s.rules) console.log('  ' + (r.enabled ? 'on ' : 'off') + ' ' + r.id + ' (' + r.tool + (r.paths ? ': ' + r.paths.join(', ') : '') + ') today ' + r.usedToday + ' of ' + r.maxPerDay);
+    console.log('always asks you: ' + s.neverAutomatic.join(', '));
+  }).catch(error => { console.error(error.message); process.exitCode = 1; });
+} else if (isMain && process.argv[2] === 'adopt') {
+  // aether adopt [--dry-run] [--departments <file>]: map an existing .claude/agents setup onto the command centre (writes only new files under .aether/)
+  import('../src/adopt.js').then(m => m.adopt(process.argv.slice(3), process.cwd(), console.log)).catch(error => { console.error(error.message); process.exitCode = 1; });
+} else if (isMain && process.argv[2] === 'notice') {
+  // aether notice "New 1-star review on the reviews page"  (shown as "Just happened" in the command centre for 15 minutes)
+  const text = process.argv.slice(3).join(' ');
+  import('@aetheros/workspace').then(m => { m.recordNotice(process.cwd(), text, { session: 'cli' }); console.log('notice recorded'); }).catch(error => { console.error(error.message); process.exitCode = 1; });
+} else if (isMain && process.argv[2] === 'sprint') {
   runSprint(process.argv.slice(3), process.cwd(), console.log).catch(error => { console.error(error.message); process.exitCode = 1; });
 } else if (isMain && process.argv[2] === 'setup') {
   (process.argv[3] === 'machine'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aetheros/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -12,21 +12,21 @@
     "aether": "./bin/aether.js"
   },
   "scripts": {
-    "check": "node --check bin/aether.js && node --check src/setup.js && node --check src/sprint.js && node --check src/machine.js",
+    "check": "node --check bin/aether.js && node --check src/setup.js && node --check src/sprint.js && node --check src/machine.js && node --check src/start.js",
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "@aetheros/workflow": "0.1.0",
-    "@aetheros/provider-claude": "0.1.0",
-    "@aetheros/provider-openai": "0.1.0",
-    "@aetheros/spec-kit": "0.1.0",
-    "@aetheros/runner": "0.1.0",
-    "@aetheros/control-room": "0.1.0",
-    "@aetheros/voice": "0.1.0",
-    "@aetheros/workspace": "0.1.0",
-    "@aetheros/models": "0.1.0",
-    "@aetheros/provider-google": "0.1.0",
-    "@aetheros/provider-openai-compatible": "0.1.0"
+    "@aetheros/workflow": "0.1.2",
+    "@aetheros/provider-claude": "0.1.2",
+    "@aetheros/provider-openai": "0.1.2",
+    "@aetheros/specs": "0.1.2",
+    "@aetheros/runner": "0.1.2",
+    "@aetheros/control-room": "0.1.2",
+    "@aetheros/voice": "0.1.2",
+    "@aetheros/workspace": "0.1.2",
+    "@aetheros/models": "0.1.2",
+    "@aetheros/provider-google": "0.1.2",
+    "@aetheros/provider-openai-compatible": "0.1.2"
   },
   "files": [
     "src",

package/src/adopt.js

@@ -0,0 +1,144 @@
+import {existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync} from 'node:fs';
+import {basename, dirname, isAbsolute, join, relative, resolve} from 'node:path';
+import {createHash} from 'node:crypto';
+import {nextSteps, readRules, skillsMentioning, validateAgent} from '@aetheros/workspace';
+
+const DEPARTMENT_FILES = ['departments.json', 'docs/departments.json', 'config/departments.json', '.claude/departments.json'];
+const READ_TOOLS = ['project.handover', 'project.read_file', 'project.list_files', 'project.search', 'git.status'];
+const TOOL_MAP = {Read: ['project.read_file'], Grep: ['project.search'], Glob: ['project.list_files'], LS: ['project.list_files'], Write: ['project.write_file'], Edit: ['project.write_file'], MultiEdit: ['project.write_file'], NotebookEdit: ['project.write_file']};
+const TIERS = {opus: 'strong', sonnet: 'balanced', haiku: 'cheap'};
+const COLORS = ['#4a5bd8', '#0f8a7a', '#b25e09', '#8a3fb5', '#c2410c', '#0369a1', '#4d7c0f', '#be185d'];
+const DEFAULT_GROUPS = [['plan', 'Plan', ['planner', 'architect']], ['build', 'Build', ['implementer', 'devops']], ['check', 'Check', ['reviewer', 'security-reviewer', 'screens']], ['ship', 'Ship', ['release', 'docs-writer']]];
+
+const slug = s => { const t = String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40); return /^[a-z]/.test(t) ? t : (t ? 'a-' + t : ''); };
+const hash = file => createHash('sha256').update(readFileSync(file)).digest('hex');
+const inside = (root, file) => { const rel = relative(root, resolve(root, file)); return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel); };
+
+/** `---` frontmatter with one `key: value` per line (what Claude Code agent files use), and the text after it. */
+export function parseAgentFile(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
+  const meta = {};
+  if (m) for (const line of m[1].split(/\r?\n/)) { const kv = /^([A-Za-z_-]+):\s*(.*)$/.exec(line); if (kv) meta[kv[1].toLowerCase()] = kv[2].trim().replace(/^["']|["']$/g, ''); }
+  return {meta, body: (m ? m[2] : text).trim()};
+}
+
+/** A Claude Code agent as a workspace agent: its tools are mapped to the workspace's, writes still wait in Review, and nothing is granted by silence. */
+export function toWorkspaceAgent(file, text) {
+  const {meta, body} = parseAgentFile(text);
+  const name = String(meta.name || basename(file, '.md')).replace(/[<>]/g, '').trim().slice(0, 40);
+  const id = slug(name);
+  if (!id) throw new Error('no usable name');
+  const requested = meta.tools ? meta.tools.split(',').map(t => t.trim()).filter(Boolean) : null;
+  const tools = requested ? [...new Set(requested.flatMap(t => TOOL_MAP[t] ?? []))] : [...READ_TOOLS];
+  if (requested && !tools.includes('project.handover')) tools.unshift('project.handover');
+  const unmapped = requested ? requested.filter(t => !TOOL_MAP[t]) : [];
+  const description = (meta.description || '').slice(0, 200);
+  const instructions = (body || description || 'Help with this project.').slice(0, 8000);
+  const tier = TIERS[String(meta.model || '').toLowerCase()];
+  const agent = validateAgent({schemaVersion: 1, id, name, ...(description && {description}), instructions, provider: 'claude', ...(tier && {tier}), tools, color: COLORS[parseInt(createHash('sha256').update(id).digest('hex').slice(0, 4), 16) % COLORS.length]});
+  return {agent, unmapped, truncated: body.length > 8000};
+}
+
+/** Read a department file of the shape {departments: [{id, name, agents: [...]}], brains?: {...}} and keep only plain values. */
+export function readDepartmentFile(file) {
+  const value = JSON.parse(readFileSync(file, 'utf8'));
+  if (!Array.isArray(value?.departments)) throw new Error('needs a "departments" list');
+  const text = (v, n) => typeof v === 'string' && v.trim() && v.length <= n && !/[<>]/.test(v);
+  const departments = value.departments.slice(0, 20).filter(d => d && text(d.name, 40) && Array.isArray(d.agents)).map(d => ({id: text(d.id, 40) ? d.id : slug(d.name), name: d.name.trim(), agents: d.agents.filter(a => text(a, 40)).slice(0, 30)}));
+  if (!departments.length) throw new Error('no usable departments');
+  const brains = value.brains && typeof value.brains === 'object' && !Array.isArray(value.brains) ? Object.fromEntries(Object.entries(value.brains).filter(([k, v]) => text(k, 80) && /^[\w .-]{1,20}$/.test(String(v))).slice(0, 30)) : undefined;
+  return {departments, ...(brains && Object.keys(brains).length && {brains})};
+}
+
+/**
+ * `aether adopt`: for a project that already has its own agents, skills, department file and hooks. Reads them and writes the matching
+ * `.aether/` files for the command centre. Never changes the project's own files and never overwrites an `.aether/` file that exists.
+ * Options: --dry-run (change nothing), --departments <file> (a department file anywhere inside the project).
+ */
+export async function adopt(args, cwd, log) {
+  const root = resolve(cwd);
+  const dryRun = args.includes('--dry-run');
+  const flag = name => (args.includes(name) ? args[args.indexOf(name) + 1] : undefined);
+  const wrote = [], kept = [], missing = [], notes = [];
+  const before = new Map();
+  const watch = rel => { const f = join(root, rel); if (existsSync(f) && statSync(f).isFile()) before.set(rel, hash(f)); };
+  const put = (rel, value) => {
+    const file = join(root, rel);
+    if (existsSync(file)) { kept.push(rel); return false; }
+    if (!dryRun) { mkdirSync(dirname(file), {recursive: true}); writeFileSync(file, JSON.stringify(value, null, 2) + '\n', {flag: 'wx'}); }
+    wrote.push(rel);
+    return true;
+  };
+  log(`${dryRun ? 'Looking at' : 'Adopting'} ${basename(root)} (your own files are only read; new files go under .aether/${dryRun ? ', nothing is written in this dry run' : ''})`);
+
+  // 1. Agents
+  const agentsDir = join(root, '.claude/agents');
+  const found = [];
+  let total = 0;
+  if (existsSync(agentsDir)) {
+    for (const name of readdirSync(agentsDir).filter(n => n.endsWith('.md')).sort()) {
+      total++;
+      watch(`.claude/agents/${name}`);
+      try { found.push({file: name, ...toWorkspaceAgent(name, readFileSync(join(agentsDir, name), 'utf8'))}); }
+      catch (error) { notes.push(`skipped .claude/agents/${name}: ${String(error.message).slice(0, 120)}`); }
+    }
+  }
+  let agentsWritten = 0;
+  for (const a of found) {
+    if (put(`.aether/agents/${a.agent.id}.json`, {schemaVersion: 1, ...a.agent})) agentsWritten++;
+    if (a.unmapped.length) notes.push(`${a.agent.name}: tools with no workspace equivalent left out (${a.unmapped.join(', ')})`);
+    if (a.truncated) notes.push(`${a.agent.name}: instructions cut to 8000 characters`);
+  }
+  log(found.length ? `agents: ${total} in .claude/agents${total !== found.length ? ` (${total - found.length} skipped, see notes)` : ''} → ${agentsWritten} ${dryRun ? 'to write' : 'written'} as .aether/agents/*.json, ${found.length - agentsWritten} already there and kept (writes by these agents wait in Review; no tool is granted that the agent file did not list)` : 'agents: none found in .claude/agents');
+  if (!found.length) missing.push('No agents: run `aether install claude` to add the starter agents, or `aether workspace init`.');
+
+  // 2. Departments
+  let source = flag('--departments');
+  if (source && !inside(root, source)) throw new Error('--departments must be a file inside the project');
+  if (source) source = relative(root, resolve(root, source)).split('\\').join('/');
+  source ??= DEPARTMENT_FILES.find(f => existsSync(join(root, f)));
+  let departments = null;
+  if (existsSync(join(root, '.aether/departments.json'))) { kept.push('.aether/departments.json'); log('departments: .aether/departments.json already exists and is kept'); }
+  else if (source) {
+    try {
+      watch(source);
+      departments = readDepartmentFile(join(root, source));
+      put('.aether/departments.json', departments);
+      log(`departments: ${departments.departments.length} from ${source} → .aether/departments.json${departments.brains ? ` (model words for ${Object.keys(departments.brains).length})` : ''}`);
+    } catch (error) { notes.push(`${source} could not be used: ${String(error.message).slice(0, 120)}`); }
+  } else if (found.length) {
+    const names = new Set(found.map(a => a.agent.name));
+    const inferred = DEFAULT_GROUPS.map(([id, name, list]) => ({id, name, agents: list.filter(n => names.has(n))})).filter(d => d.agents.length);
+    if (inferred.length) { departments = {departments: inferred}; put('.aether/departments.json', departments); log(`departments: no department file found; grouped ${inferred.flatMap(d => d.agents).length} known agent names into ${inferred.map(d => d.name).join(', ')} (agents with other names show under "Other")`); }
+    else { log('departments: no department file found; every agent will show in one "Team" group'); missing.push('Departments: add a department file (`{"departments": [{"id": "build", "name": "Build", "agents": ["builder"]}]}`) and run `aether adopt --departments <file>`.'); }
+  }
+
+  // 3. Skills, hooks, handover, rules (read only)
+  const skillsDir = join(root, '.claude/skills');
+  const skills = existsSync(skillsDir) ? readdirSync(skillsDir, {withFileTypes: true}).filter(e => e.isDirectory() && existsSync(join(skillsDir, e.name, 'SKILL.md'))).length : 0;
+  const naming = found.filter(a => skillsMentioning(root, a.agent).length).length;
+  log(skills ? `skills: ${skills} in .claude/skills; ${naming} of your agents are named by a skill (shown on the agent card)` : 'skills: none found in .claude/skills');
+  let hooks = false;
+  try { hooks = /status-event/.test(JSON.stringify(JSON.parse(readFileSync(join(root, '.claude/settings.json'), 'utf8')).hooks ?? {})); } catch {}
+  log(hooks ? 'hooks: status-event found in .claude/settings.json, so Claude Code sessions show as working now' : 'hooks: no status-event hook; the workspace still shows its own agents as working now');
+  if (!hooks) missing.push('Working now from Claude Code sessions: run `aether install claude` to add the status hook (it only records agent names and times).');
+  const next = nextSteps(root);
+  log(next.length ? `handover: "Up next" found; the status strip will show "Next: ${next[0].slice(0, 60)}"` : 'handover: no "Up next" section in HANDOVER.md');
+  if (!next.length) missing.push('Next step: add an "## Up next" list to HANDOVER.md to see it in the status strip.');
+  const rules = readRules(root);
+  log(rules.rules.length ? `rules: ${rules.rules.length} under "${rules.section}" in ${rules.file} (Project › Rules)` : 'rules: no "Working rules" section found');
+  if (!rules.rules.length) missing.push('Rules: add a "## Working rules" section to CLAUDE.md or HANDOVER.md, or name one in `.aether/rules.json`.');
+  if (!existsSync(join(root, '.aether/brand.json'))) missing.push('Names and look: run `aether setup --os-name "..." --assistant "..." [--style night-sky]` (no brand file yet; the defaults are AetherOS and Aevron).');
+  if (!existsSync(join(root, '.aether/status.json'))) missing.push('Site checks: add `.aether/status.json` to watch your site and (with GITHUB_TOKEN) the sprint, pull requests and issues.');
+  if (!existsSync(join(root, '.aether/pipeline.json'))) notes.push('build track: using the default steps (Plan, Build, Check, Pull request, Your test, Merged); list your own in .aether/pipeline.json');
+
+  // 4. Prove your own files were not touched
+  for (const [rel, digest] of before) if (!existsSync(join(root, rel)) || hash(join(root, rel)) !== digest) throw new Error(`Internal error: ${rel} changed; adopt must never change your files`);
+
+  for (const n of notes) log('note: ' + n);
+  log(`\n${dryRun ? 'Would write' : 'Wrote'} ${wrote.length} file${wrote.length === 1 ? '' : 's'}${kept.length ? `, kept ${kept.length} that already existed` : ''}.`);
+  log(`The command centre will show: ${found.length} agent${found.length === 1 ? '' : 's'}${departments ? ` in ${departments.departments.length} department${departments.departments.length === 1 ? '' : 's'}` : ''}, ${skills} skill${skills === 1 ? '' : 's'}, ${rules.rules.length} rule${rules.rules.length === 1 ? '' : 's'}${next.length ? ', the next step' : ''}.`);
+  if (missing.length) { log('Missing:'); for (const m of missing) log('  - ' + m); }
+  log('Next: `node .aether/aether.mjs start` (or `aether workspace`) to see it.');
+  return {wrote, kept, missing, notes, agents: found.length};
+}

package/src/setup.js

@@ -24,7 +24,7 @@ export async function setup(args, cwd, log, {installers, ask, interactive = Bool
   const dryRun = args.includes('--dry-run');
   const git = isGitRepo(root);
   const defaults = KIT_ORDER.filter(k => k !== 'mcp' && (k !== 'githooks' || git));
-  const listed = args.includes('--kits') ? (args[args.indexOf('--kits') + 1] || '').split(',').map(s => s.trim()).filter(Boolean) : null;
+  const listed = args.includes('--kits') ? (args[args.indexOf('--kits') + 1] || '').split(',').map(s => s.trim()).filter(k => k && k !== 'none') : null; // --kits "" or --kits none: no kits (for a project that already has its own setup; then run aether adopt)
   if (listed && listed.some(k => !installers[k])) throw new Error('Unknown kit in --kits; available: ' + KIT_ORDER.join(', '));
   if (listed?.includes('githooks') && !git) throw new Error('githooks needs a git repository (run git init first)');
   let kits = listed ?? defaults;
@@ -54,8 +54,11 @@ export async function setup(args, cwd, log, {installers, ask, interactive = Bool
       accent = String(await question('Accent colour (#rrggbb, empty for default)? ')).trim() || undefined;
     } finally { rl?.close(); }
   }
-  if (osName || assistantName) {
-    const next = {osName: osName || brand?.osName || `${basename(root)} OS`, assistantName: assistantName || brand?.assistantName || 'Aevron', theme: {...(brand?.theme ?? {}), ...(accent && {accent})}};
+  // Command-centre look: --style night-sky|daylight|graphite|terminal|high-contrast, --layout assistant-centre|conversation|board, --corners round|square.
+  const look = {style: flag('--style'), layout: flag('--layout'), corners: flag('--corners')};
+  if (osName || assistantName || look.style || look.layout || look.corners) {
+    const kept = Object.fromEntries(['style', 'layout', 'corners', 'allowUserStyle'].filter(k => brand?.[k] !== undefined).map(k => [k, brand[k]]));
+    const next = {osName: osName || brand?.osName || `${basename(root)} OS`, assistantName: assistantName || brand?.assistantName || 'Aevron', theme: {...(brand?.theme ?? {}), ...(accent && {accent})}, ...kept, ...Object.fromEntries(Object.entries(look).filter(([, v]) => v))};
     if (!dryRun) brand = writeBrand(root, next);
     log(`${dryRun ? 'would brand' : 'branded'}: ${next.osName} · assistant ${next.assistantName}`);
   }

package/src/start.js

@@ -0,0 +1,176 @@
+// `aether start`: one command (or a double-click on start-aetheros.cmd) that starts everything and opens it.
+// First run: asks for an AI provider key and saves it outside the project (in the home folder, owner-only).
+// Every run: starts the workspace and the voice console, then opens both in the browser.
+// Already running: opens the pages again and exits.
+import {spawn} from 'node:child_process';
+import {createHash} from 'node:crypto';
+import {chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {basename, join} from 'node:path';
+import {createInterface} from 'node:readline';
+import {fileURLToPath} from 'node:url';
+
+export const PROVIDER_KEYS = [
+  {env: 'ANTHROPIC_API_KEY', name: 'Anthropic (Claude)', hint: 'sk-ant-…, from console.anthropic.com (create it inside a workspace)'},
+  {env: 'OPENAI_API_KEY', name: 'OpenAI', hint: 'sk-…, from platform.openai.com'},
+  {env: 'GEMINI_API_KEY', name: 'Google Gemini', hint: 'from aistudio.google.com'},
+];
+const ALL_KEYS = [...PROVIDER_KEYS.map(p => p.env), 'GOOGLE_API_KEY', 'XAI_API_KEY', 'MISTRAL_API_KEY'];
+const STATE = join('.aether', 'local', 'start.json');
+
+export const LAUNCHERS = {
+  'start-aetheros.cmd': '@echo off\r\nREM Starts AetherOS for this project and opens it in the browser. Double-click or run: start-aetheros\r\ncd /d "%~dp0"\r\nnode .aether\\aether.mjs start %*\r\nif errorlevel 1 pause\r\n',
+  'start-aetheros.sh': '#!/bin/sh\n# Starts AetherOS for this project and opens it in the browser. Run: ./start-aetheros.sh\ncd "$(dirname "$0")" && exec node .aether/aether.mjs start "$@"\n',
+};
+
+/** Where this project's settings live: the home folder, never the project (keys must not reach git). */
+export function settingsFile(root, home = homedir()) {
+  let real = root;
+  try { real = realpathSync(root); } catch {}
+  const id = createHash('sha256').update(real.toLowerCase()).digest('hex').slice(0, 10);
+  return join(home, '.aether', 'projects', `${basename(real).replace(/[^\w.-]/g, '_')}-${id}.json`);
+}
+
+export function loadSettings(file) {
+  try { const s = JSON.parse(readFileSync(file, 'utf8')); return s && typeof s.env === 'object' ? s : {env: {}}; } catch { return {env: {}}; }
+}
+
+export function saveSettings(file, settings) {
+  mkdirSync(join(file, '..'), {recursive: true, mode: 0o700});
+  writeFileSync(file, JSON.stringify({schemaVersion: 1, ...settings}, null, 2) + '\n', {mode: 0o600});
+  try { chmodSync(file, 0o600); } catch {}
+}
+
+/** Writes the double-click launchers into the project when they're missing. Returns the names written. */
+export function writeLaunchers(root) {
+  const written = [];
+  for (const [name, text] of Object.entries(LAUNCHERS)) {
+    const file = join(root, name);
+    if (existsSync(file)) continue;
+    writeFileSync(file, text, {mode: 0o755});
+    written.push(name);
+  }
+  return written;
+}
+
+/** The keys to start with: the terminal's own variables win, then the saved ones. */
+export function resolveKeys(env, settings) {
+  const keys = {};
+  for (const name of ALL_KEYS) {
+    if (env[name]) keys[name] = env[name];
+    else if (settings.env?.[name]) keys[name] = settings.env[name];
+  }
+  return keys;
+}
+
+/** Asks for one key, Anthropic first; the typed key is not shown on screen. */
+export async function askForKey(ask, log) {
+  log('\nAetherOS needs one AI provider key so your agents can answer. It is saved in your home folder, never in the project.');
+  for (const p of PROVIDER_KEYS) {
+    const key = String(await ask(`Paste your ${p.name} API key (${p.hint}), or press Enter to skip: `, {secret: true})).trim();
+    if (key) return {[p.env]: key};
+  }
+  return {};
+}
+
+function terminalAsk() {
+  return (question, {secret} = {}) => new Promise(resolveAnswer => {
+    const rl = createInterface({input: process.stdin, output: process.stdout, terminal: true});
+    if (secret) {
+      const write = rl._writeToOutput?.bind(rl);
+      rl._writeToOutput = text => { if (text.startsWith(question)) write?.(text); else if (!/^\r?\n$/.test(text)) write?.('*'); else write?.(text); };
+    }
+    rl.question(question, answer => { rl.close(); if (secret) process.stdout.write('\n'); resolveAnswer(answer); });
+  });
+}
+
+export function openInBrowser(url, {spawnImpl = spawn, platform = process.platform} = {}) {
+  const [cmd, args] = platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', url]] : platform === 'darwin' ? ['open', [url]] : ['xdg-open', [url]];
+  try { spawnImpl(cmd, args, {stdio: 'ignore', detached: true}).unref?.(); return true; } catch { return false; }
+}
+
+async function answers(url, fetchImpl) {
+  try { return (await fetchImpl(url, {signal: AbortSignal.timeout(1500)})).status < 500; } catch { return false; }
+}
+
+/** Starts a child `aether <args>` and resolves with the first http URL it prints after `label`. */
+function startChild(cliPath, args, {root, env, label, log, spawnImpl}) {
+  return new Promise((resolveUrl, reject) => {
+    const child = spawnImpl(process.execPath, [cliPath, ...args], {cwd: root, env, stdio: ['ignore', 'pipe', 'pipe']});
+    let found = false, buffer = '';
+    const onData = chunk => {
+      buffer += chunk;
+      const lines = buffer.split(/\r?\n/);
+      buffer = lines.pop();
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        if (!found) {
+          const match = line.includes(label) && line.match(/https?:\/\/127\.0\.0\.1:\d+\/\S*/);
+          if (match) { found = true; resolveUrl({child, url: match[0]}); continue; }
+        }
+        log(`  [${args[0]}] ${line}`);
+      }
+    };
+    child.stdout.on('data', onData);
+    child.stderr.on('data', onData);
+    child.on('exit', code => { if (!found) reject(new Error(`aether ${args[0]} stopped (exit ${code}) before it was ready`)); });
+  });
+}
+
+export async function start(args, root, {log = console.log, env = process.env, home = homedir(), ask, interactive = Boolean(process.stdin.isTTY), cliPath, open = openInBrowser, spawnImpl = spawn, fetchImpl = fetch, wait = true} = {}) {
+  if (!existsSync(join(root, '.aether')) && !existsSync(join(root, 'aether.config.json'))) {
+    throw new Error('AetherOS is not set up in this folder yet. Run:  npx @aetheros/create');
+  }
+  for (const name of writeLaunchers(root)) log(`created ${name} (double-click it, or run it, to start AetherOS next time)`);
+  if (args.includes('--launchers')) return {launchersOnly: true};
+
+  const file = settingsFile(root, home);
+  const settings = loadSettings(file);
+  if (args.includes('--where')) { log(file); return {file}; }
+  let keys = resolveKeys(env, args.includes('--reset') ? {env: {}} : settings);
+  if (!Object.keys(keys).length || args.includes('--reset')) {
+    if (interactive) {
+      const typed = await askForKey(ask ?? terminalAsk(), log);
+      if (Object.keys(typed).length) {
+        saveSettings(file, {...settings, env: {...(args.includes('--reset') ? {} : settings.env), ...typed}});
+        log(`Saved in ${file} (only your user can read it; delete the file to forget the key).`);
+        keys = {...keys, ...typed};
+      }
+    }
+    if (!Object.keys(keys).length) log('No AI provider key: the pages open, but agents can only answer once you add one. Run  node .aether/aether.mjs start --reset  to add it.');
+  }
+
+  const noOpen = args.includes('--no-open') || env.AETHER_NO_OPEN === '1';
+  const statePath = join(root, STATE);
+  let state = {};
+  try { state = JSON.parse(readFileSync(statePath, 'utf8')); } catch {}
+  if (state.workspace && await answers(state.workspace, fetchImpl)) {
+    log(`AetherOS is already running.\n  Workspace:      ${state.workspace}\n  Voice console:  ${state.voice ?? '(not running)'}`);
+    if (!noOpen) { open(state.workspace); if (state.voice) open(state.voice); }
+    return {alreadyRunning: true, ...state};
+  }
+
+  const childEnv = {...env, ...keys};
+  const cli = cliPath ?? fileURLToPath(new URL('../bin/aether.js', import.meta.url));
+  log('Starting AetherOS…');
+  const workspace = await startChild(cli, ['workspace', '--port', String(Number(value(args, '--port') ?? 4850))], {root, env: childEnv, label: 'Workspace:', log, spawnImpl});
+  let voice;
+  if (!args.includes('--no-voice')) {
+    try { voice = await startChild(cli, ['voice', '--agents', '--port', String(Number(value(args, '--voice-port') ?? 4747))], {root, env: childEnv, label: 'Voice console:', log, spawnImpl}); }
+    catch (error) { log(`Voice console not started: ${error.message}`); }
+  }
+  mkdirSync(join(root, '.aether', 'local'), {recursive: true});
+  writeFileSync(statePath, JSON.stringify({workspace: workspace.url, ...(voice && {voice: voice.url}), startedAt: new Date().toISOString()}, null, 2) + '\n');
+  log(`\nAetherOS is running.\n  Workspace:      ${workspace.url}\n  Voice console:  ${voice?.url ?? '(not started)'}  (Chrome or Edge, allow the microphone)\nPress Ctrl+C here to stop.`);
+  if (!noOpen) { open(workspace.url); if (voice) open(voice.url); }
+  const children = [workspace.child, voice?.child].filter(Boolean);
+  const stop = () => { for (const c of children) try { c.kill(); } catch {} };
+  if (!wait) return {workspace: workspace.url, voice: voice?.url, stop};
+  process.on('SIGINT', () => { stop(); process.exit(0); });
+  process.on('SIGTERM', () => { stop(); process.exit(0); });
+  await new Promise(resolveDone => workspace.child.on('exit', resolveDone));
+  stop();
+  return {workspace: workspace.url, voice: voice?.url};
+}
+
+function value(args, name) { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; }