@joenandez/academy 0.4.0 → 0.5.12

package/scripts/cli/args.mjs

@@ -1,4 +1,8 @@
-import { CLI_NAME, NAME_RE, RUNTIMES } from './core.mjs';
+import { parseCreateArgs, parseSkillsArgs } from './args-kinds.mjs';
+import { parseNotesArgs } from './args-notes.mjs';
+import { parseRenameArgs, parseStartArgs } from './args-owner.mjs';
+import { parseRunArgs } from './args-run.mjs';
+import { CLI_NAME } from './core.mjs';
 import { UNIMPLEMENTED_COMMANDS } from './doctor.mjs';
 
 const COMMAND_PARSERS = {
@@ -6,7 +10,7 @@ const COMMAND_PARSERS = {
   // dispatch can answer them in the envelope instead of a usage dump.
   ...Object.fromEntries(UNIMPLEMENTED_COMMANDS.map((command) => [command, jsonOnlyCommand])),
   doctor: (command, rest) => jsonOnlyCommand(command, rest),
-  create: (command, rest) => namedJsonCommand(command, rest),
+  create: (command, rest) => parseCreateArgs(command, rest),
   hire: (command, rest) => parseHireArgs(command, rest),
   run: (_command, rest) => parseRunArgs(rest),
   nightly: (_command, rest) => {
@@ -15,6 +19,8 @@ const COMMAND_PARSERS = {
   },
   events: (command, rest) => parseEventsArgs(command, rest),
   migrate: (command, rest) => parseMigrateArgs(command, rest),
+  start: (command, rest) => parseStartArgs(command, rest),
+  stop: (command, rest) => namedJsonCommand(command, rest),
   rename: (command, rest) => parseRenameArgs(command, rest),
   archive: (command, rest) => namedJsonCommand(command, rest),
   unarchive: (command, rest) => namedJsonCommand(command, rest),
@@ -25,9 +31,14 @@ const COMMAND_PARSERS = {
   budget: (command, rest) => namedJsonCommand(command, rest),
   clean: (command, rest) => ({ command, name: rest[0] }),
   delete: (command, rest) => namedJsonCommand(command, rest),
-  destroy: (command, rest) => ({ command, name: rest[0], force: rest.includes('--force') }),
+  destroy: (command, rest) => ({
+    command,
+    name: rest[0],
+    force: rest.includes('--force'),
+  }),
   root: (command, rest) => jsonOnlyCommand(command, rest),
   notes: (_command, rest) => parseNotesArgs(rest),
+  skills: (command, rest) => parseSkillsArgs(command, rest),
 };
 
 export function parseArgs(argv) {
@@ -48,7 +59,11 @@ function jsonOnlyCommand(command, rest) {
 }
 
 function namedJsonCommand(command, rest) {
-  return { command, name: rest.find((arg) => arg !== '--json'), json: hasFlag(rest, '--json') };
+  return {
+    command,
+    name: rest.find((arg) => arg !== '--json'),
+    json: hasFlag(rest, '--json'),
+  };
 }
 
 // `hire [--spec <path>] [--json] [-- ...]`. `--spec` selects the headless form
@@ -69,44 +84,13 @@ function parseHireArgs(command, rest) {
     else if (arg.startsWith('--spec=')) spec = arg.slice('--spec='.length);
     else if (arg.startsWith('--')) invalidOption ??= arg;
   }
-  return { command, json, spec, invalidOption, passthrough: extractPassthrough(rest) };
-}
-
-function parseRunArgs(rest) {
-  const name = rest[0];
-  const afterName = rest.slice(1);
-  const dashIdx = afterName.indexOf('--');
-  const optionArgs = dashIdx >= 0 ? afterName.slice(0, dashIdx) : afterName;
-  const passthrough = dashIdx >= 0 ? afterName.slice(dashIdx + 1) : [];
-  // No default here. The agent is not resolved yet, and defaulting before it is
-  // what re-registered a codex agent's nightly job as claude-code for ten
-  // nights. A null runtime means "not explicit"; `run` reads the persisted
-  // scalar instead.
-  let runtime = null;
-
-  for (let i = 0; i < optionArgs.length; i++) {
-    const arg = optionArgs[i];
-    if (arg === '--agent') {
-      const value = optionArgs[++i];
-      if (!RUNTIMES.has(value))
-        return invalidRunOption(`Invalid --agent value: ${value ?? '(none)'}`);
-      runtime = value;
-    } else if (arg?.startsWith('--agent=')) {
-      const value = arg.slice('--agent='.length);
-      if (!RUNTIMES.has(value))
-        return invalidRunOption(`Invalid --agent value: ${value || '(none)'}`);
-      runtime = value;
-    } else if (arg) {
-      return invalidRunOption(`Unknown run option: ${arg}`);
-    }
-  }
-
-  return { command: 'run', name, runtime, passthrough };
-}
-
-function invalidRunOption(message) {
-  console.error(`${message}. Use --agent claude-code or --agent codex before --.`);
-  return { command: 'help', exitCode: 1 };
+  return {
+    command,
+    json,
+    spec,
+    invalidOption,
+    passthrough: extractPassthrough(rest),
+  };
 }
 
 // `events --since <seq> [--logid <id>] [--json]`. `--since` stays a raw string:
@@ -160,71 +144,20 @@ function parseSessionsArgs(command, rest) {
   return { command, json, agent };
 }
 
-// `rename <old> <new> [--json]`. Like `events`, `migrate` and `sessions`, an
-// option Academy does not know stays on the command so the handler answers it
-// inside the envelope the caller asked for.
-function parseRenameArgs(command, rest) {
-  const json = hasFlag(rest, '--json');
-  const positional = [];
-  for (const arg of rest) {
-    if (arg === '--json') continue;
-    else if (arg.startsWith('--')) return { command, json, invalidOption: arg };
-    else positional.push(arg);
-  }
-  return { command, json, name: positional[0], newName: positional[1] };
-}
-
 function extractPassthrough(rest) {
   const dashIdx = rest.indexOf('--');
   return dashIdx >= 0 ? rest.slice(dashIdx + 1) : [];
 }
 
-// `notes add [<agent>] "text"` and `notes list [<agent>] [--last N]`. The first
-// positional token is treated as an agent only when it looks like an agent name
-// (NAME_RE) AND there is more to follow — so quoted single-arg text stays text.
-function parseNotesArgs(rest) {
-  const action = rest[0];
-  if (action !== 'add' && action !== 'list') {
-    console.error(`Unknown notes action: ${action ?? '(none)'}. Use 'add' or 'list'.`);
-    return { command: 'help', exitCode: 1 };
-  }
-  const args = rest.slice(1);
-
-  if (action === 'add') {
-    let name;
-    let textParts = args;
-    if (args.length >= 2 && NAME_RE.test(args[0])) {
-      name = args[0];
-      textParts = args.slice(1);
-    }
-    return { command: 'notes', action, name, text: textParts.join(' ') };
-  }
-
-  // list — pull out --last N (or --last=N), the rest is an optional agent name.
-  let last = 12;
-  const positional = [];
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--last') {
-      last = Number.parseInt(args[++i], 10);
-    } else if (args[i].startsWith('--last=')) {
-      last = Number.parseInt(args[i].slice('--last='.length), 10);
-    } else {
-      positional.push(args[i]);
-    }
-  }
-  if (!Number.isInteger(last) || last <= 0) last = 12;
-  const name = positional[0] && NAME_RE.test(positional[0]) ? positional[0] : undefined;
-  return { command: 'notes', action, name, last };
-}
-
-export function printUsage() {
-  console.log(
-    `
+// A module constant, so the command list can grow without growing a function.
+const USAGE = `
 Usage: ${CLI_NAME} <command> [options]
 
 Commands:
   doctor [--json]         Report Academy's version, roots, runtimes, and capability
-  create <name> [--json]  Scaffold a new portable agent at ~/.academy/agents/<name>/
+  create [<name>] [--kind specialist|principal|owner] [--no-start] [--json]
+                          Scaffold a portable agent at ~/.academy/agents/<name>/ (default
+                          specialist); a terminal Principal opens its first session
   hire                    Interactive hire flow — produces 8 boot files via Claude Code
   hire --spec <path> [--json]
                           Headless hire from a JSON specification file
@@ -243,8 +176,13 @@ Commands:
                           List sessions whose agent directory is inside
                           AGENTS_ROOT
   rename <old> <new> [--json]
-                          Move an agent to a new name, rewriting its ownership
-                          marker and re-registering its nightly job
+                          Change an agent's name: the name: field and the seeded
+                          name lines. No folder moves and no job changes; safe
+                          any time, also mid-session
+  start <name> [--mandate <file>] [--hours <h>] [--contact <c>] [--trust 1-4] [--json]
+                          Start an agent and register its jobs; an Owner needs a
+                          signed mandate and gets one first daily run
+  stop <name> [--json]    Stop an agent and delete its jobs; its files stay
   archive <name> [--json] Move an agent into the archived holding area
   unarchive <name> [--json]
                           Restore an archived agent to its canonical slot
@@ -252,15 +190,16 @@ Commands:
   inspect <name>          Inspect one agent
   tokens <name>           Estimate generated prompt tokens by surface
   budget <name>           Check prompt token budget by surface
-  clean <name>            Truncate transient surfaces (notes.md, threads.md)
+  clean <name>            Reset notes.md (work.md is kept)
   destroy <name> --force  Remove an agent and all its files
   root                    Print Academy package root
-  notes add [<agent>] "…" Append a short note to the agent's notes.md
+  notes add [<agent>] [--user] "…"  Append a note to notes.md; --user proposes it in user.md
   notes list [<agent>] [--last N]  Show recent notes (default last 12)
 
 Examples:
   ${CLI_NAME} doctor --json
   ${CLI_NAME} create kai
+  ${CLI_NAME} create ada --kind principal --json
   ${CLI_NAME} hire
   ${CLI_NAME} hire --spec ./kai.json --json
   ${CLI_NAME} run kai
@@ -271,10 +210,14 @@ Examples:
   ${CLI_NAME} migrate --dry-run --json
   ${CLI_NAME} sessions --agent kai --json
   ${CLI_NAME} rename kai nova --json
+  ${CLI_NAME} start owner-one --mandate ./mandate.md --trust 3 --json
+  ${CLI_NAME} stop owner-one --json
   ${CLI_NAME} notes add "User prefers short status updates before edits"
   ${CLI_NAME} notes list --last 20
-  `.trim(),
-  );
+`.trim();
+
+export function printUsage() {
+  console.log(USAGE);
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/scripts/cli/beads.mjs

@@ -0,0 +1,57 @@
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { ACADEMY_HOME, resolveExecutable } from './core.mjs';
+
+// Agents track work in Beads (`bd`). Academy never wraps it: skills call
+// `bd … --json` directly, so Academy only pins the version range, points every
+// agent at the one user database, and turns telemetry off.
+
+const BEADS_VERSION_RANGE = '>=1.3.1 <1.4';
+const RANGE_FLOOR = [1, 3, 1];
+const RANGE_CEILING = [1, 4, 0];
+
+/**
+ * The env a run adds: the one Beads database of the user (embedded, shared by
+ * every agent), no telemetry, and, for a session, its own actor. Beads refuses
+ * a second actor's claim on an item another holds, so two sessions can never
+ * work the same item, and the actor's pid tells the heartbeat whether the
+ * holder is still running.
+ */
+export function beadsEnv(actor) {
+  return {
+    BEADS_DIR: join(ACADEMY_HOME, '.beads'),
+    OTEL_SDK_DISABLED: 'true',
+    ...(actor ? { BEADS_ACTOR: actor } : {}),
+  };
+}
+
+function compareVersions(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] - right[index];
+  }
+  return 0;
+}
+
+function inPinnedRange(version) {
+  const parts = version.split('.').map(Number);
+  return compareVersions(parts, RANGE_FLOOR) >= 0 && compareVersions(parts, RANGE_CEILING) < 0;
+}
+
+// A probe, like doctor's runtime check: it never exits and never throws. An
+// output it cannot read is reported out of range, because the pin cannot be
+// confirmed.
+export function beadsStatus() {
+  let bin;
+  try {
+    bin = resolveExecutable('ACADEMY_BD_BIN', 'bd', { throwOnMissing: true });
+  } catch {
+    return { status: 'missing', version: null, range: BEADS_VERSION_RANGE };
+  }
+  const probe = spawnSync(bin, ['version'], { encoding: 'utf8', timeout: 2000 });
+  if (probe.error || probe.status !== 0) {
+    return { status: 'missing', version: null, range: BEADS_VERSION_RANGE };
+  }
+  const version = /\b(\d+\.\d+\.\d+)\b/.exec(probe.stdout)?.[1] ?? null;
+  const status = version && inPinnedRange(version) ? 'ok' : 'out_of_range';
+  return { status, version, range: BEADS_VERSION_RANGE };
+}

package/scripts/cli/codex.mjs

@@ -2,9 +2,13 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { ACADEMY_ROOT, memoryBridgeEnabled, resolveExecutable, shellSingleQuote } from './core.mjs';
+import { ACADEMY_ROOT, resolveExecutable, shellSingleQuote } from './core.mjs';
+import { childExitCode } from './exit-code.mjs';
 import { MEMORY_BRIDGE_ENV_KEYS } from '../../hooks/memory_bridge.mjs';
 
+const ROQUE_POST_TOOL_USE_TAG = 'academy-roque-post-tool-use-v1';
+const ROQUE_COMPACT_TAG = 'academy-roque-compact-v1';
+
 function codexHome() {
   return process.env.CODEX_HOME || join(homedir(), '.codex');
 }
@@ -30,6 +34,15 @@ function academyHookCommand(scriptName, contextPath) {
   ].join(' ');
 }
 
+// Only a kind that renders the curator agent may point Codex at its config.
+function knowledgeCuratorProfileSection(configPath) {
+  return `
+[agents.knowledge_curator]
+description = "Apply evidence-gated note graduations during Academy nightly consolidation."
+config_file = ${tomlString(configPath)}
+`;
+}
+
 export function writeCodexProfile(dir, name) {
   const profileName = codexProfileName(name);
   const profilePath = join(codexHome(), `${profileName}.config.toml`);
@@ -44,11 +57,7 @@ writable_roots = [${tomlString(dir)}]
 
 [features]
 hooks = true
-
-[agents.knowledge_curator]
-description = "Apply evidence-gated note graduations during Academy nightly consolidation."
-config_file = ${tomlString(knowledgeCuratorConfigPath)}
-`;
+${existsSync(knowledgeCuratorConfigPath) ? knowledgeCuratorProfileSection(knowledgeCuratorConfigPath) : ''}`;
   writeFileSync(profilePath, toml);
   return { profileName, profilePath };
 }
@@ -139,19 +148,55 @@ export function writeCodexHooks(contextPath) {
 
   const sessionStartIndex = upsertCodexHookGroup(config.hooks.SessionStart, sessionStartGroup);
   const stopIndex = upsertCodexHookGroup(config.hooks.Stop, stopGroup);
+  config.hooks.PostToolUse = Array.isArray(config.hooks.PostToolUse)
+    ? config.hooks.PostToolUse
+    : [];
+  const roquePostToolUseIndex = upsertCodexHookGroup(
+    config.hooks.PostToolUse,
+    roqueGroup(ROQUE_POST_TOOL_USE_TAG),
+    ROQUE_POST_TOOL_USE_TAG,
+  );
+  const roqueCompactIndex = upsertCodexHookGroup(
+    config.hooks.SessionStart,
+    roqueGroup(ROQUE_COMPACT_TAG, 'compact'),
+    ROQUE_COMPACT_TAG,
+  );
 
   mkdirSync(dirname(hooksPath), { recursive: true });
   writeFileSync(hooksPath, JSON.stringify(config, null, 2) + '\n');
   writeCodexHookState([
     `${hooksPath}:session_start:${sessionStartIndex}:0`,
     `${hooksPath}:stop:${stopIndex}:0`,
+    `${hooksPath}:post_tool_use:${roquePostToolUseIndex}:0`,
+    `${hooksPath}:session_start:${roqueCompactIndex}:0`,
   ]);
   return hooksPath;
 }
 
-function upsertCodexHookGroup(groups, nextGroup) {
+// The guard keeps a checkout without hooks/roque from failing Codex tool calls.
+function roqueCommand() {
+  const bundle = shellSingleQuote(join(ACADEMY_ROOT, 'hooks', 'roque', 'roque.js'));
+  return `[ ! -f ${bundle} ] || node ${bundle} --tool codex`;
+}
+
+// One hook per group: Codex trust is keyed by group index plus hook index :0.
+function roqueGroup(tag, matcher) {
+  return {
+    ...(matcher ? { matcher } : {}),
+    hooks: [
+      {
+        _academy: tag,
+        type: 'command',
+        command: roqueCommand(),
+        timeout: 10,
+      },
+    ],
+  };
+}
+
+function upsertCodexHookGroup(groups, nextGroup, tag = 'academy-runtime-hooks-v1') {
   const index = groups.findIndex((group) => {
-    return (group?.hooks || []).some((hook) => hook?._academy === 'academy-runtime-hooks-v1');
+    return (group?.hooks || []).some((hook) => hook?._academy === tag);
   });
   if (index >= 0) {
     groups[index] = nextGroup;
@@ -163,14 +208,15 @@ function upsertCodexHookGroup(groups, nextGroup) {
 
 function writeCodexRuntimeContext(env, contextPath) {
   // The Codex sandbox strips the ambient environment, so forward Academy's own
-  // keys — plus whatever the memory bridge declares it needs, but only when the
-  // bridge is switched on.
+  // keys — plus whatever the memory bridge declares it needs. The nightly flag
+  // must reach the Stop hook, or a nightly re-arms its own pending marker.
   const keys = [
     'ACADEMY_AGENT_DIR',
     'ACADEMY_AGENT_NAME',
+    'ACADEMY_NIGHTLY_RUN',
     'ACADEMY_PROJECT_DIR',
     'HOME',
-    ...(memoryBridgeEnabled() ? MEMORY_BRIDGE_ENV_KEYS : []),
+    ...MEMORY_BRIDGE_ENV_KEYS,
   ];
   const context = {
     expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
@@ -180,6 +226,14 @@ function writeCodexRuntimeContext(env, contextPath) {
   writeFileSync(contextPath, JSON.stringify(context, null, 2) + '\n');
 }
 
+// `codex exec` refuses a folder that is not a git repository unless told
+// otherwise, and an agent home is not one. The flag belongs right after `exec`.
+export function withRepoCheck(argv) {
+  const exec = argv.indexOf('exec');
+  if (exec === -1 || argv.slice(exec + 1).includes('--skip-git-repo-check')) return argv;
+  return [...argv.slice(0, exec + 1), '--skip-git-repo-check', ...argv.slice(exec + 1)];
+}
+
 export function launchCodex(
   args,
   { cwd, env, message, profileName, profilePath, runtimeContextPath },
@@ -208,7 +262,7 @@ export function launchCodex(
     );
     process.exit(1);
   }
-  process.exit(result.status ?? 0);
+  process.exit(childExitCode(result));
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/scripts/cli/core.mjs

@@ -13,8 +13,11 @@ import {
 } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
+import { childExitCode } from './exit-code.mjs';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { readAgentYaml } from './yaml.mjs';
+import { agentIdOf } from './agent-id.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -28,6 +31,11 @@ const DEFAULT_AGENTS_ROOT = join(homedir(), '.academy', 'agents');
 const NAMED_AGENTS_ROOT = process.env.AGENTS_ROOT;
 export const AGENTS_ROOT = NAMED_AGENTS_ROOT || DEFAULT_AGENTS_ROOT;
 
+/** Shared home for files no one agent owns: user.md, user-work.md, proposals/. */
+// Resolved, because every kind now reports shared surface paths and a relative
+// AGENTS_ROOT would otherwise leave `user.md` relative.
+export const ACADEMY_HOME = resolve(process.env.ACADEMY_HOME || dirname(AGENTS_ROOT));
+
 // Whether the root is Academy's own or one an operator named. The two states
 // disagree about exactly one thing — a missing parent — and about nothing else.
 const AGENTS_ROOT_IS_DEFAULT = !NAMED_AGENTS_ROOT;
@@ -38,42 +46,23 @@ export const CLI_NAME = process.env.ACADEMY_CLI_NAME?.trim() || 'academy';
 /** Allowed agent name pattern: kebab-case, 1–32 chars. */
 export const NAME_RE = /^[a-z][a-z0-9-]{0,31}$/;
 
-export const SURFACES = [
-  'identity',
-  'role',
-  'knowledge',
-  'goals',
-  'priorities',
-  'threads',
-  'notes',
-  'dailys',
-];
-export const SURFACE_CAPS = {
-  identity: 400,
-  role: 400,
-  knowledge: 2500,
-  goals: 150,
-  priorities: 250,
-  threads: 1750,
-  notes: 500,
-  dailys: 1050,
-};
-export const TOTAL_SURFACE_CAP = Object.values(SURFACE_CAPS).reduce((sum, cap) => sum + cap, 0);
-export const ENFORCED_SURFACES = new Set(['knowledge', 'priorities', 'threads', 'notes', 'dailys']);
 export const UNIVERSAL_SKILLS = [
   'check-in',
-  'self-update',
+  'work-graph',
   'nightly-consolidation',
   'knowledge-curation',
+  'local-rules',
+  'skill-method',
 ];
 export const NIGHTLY_JOB_CRON = '0 22 * * *';
-export const SCHEDULED_CLAUDE_PERMISSION_ARGS = ['--permission-mode', 'auto'];
+// Unattended runs bypass permissions: auto mode refused every memory write
+// with "no verdict", so nightly runs could not save their work.
+export const SCHEDULED_CLAUDE_PERMISSION_ARGS = ['--permission-mode', 'bypassPermissions'];
 export const SCHEDULED_CODEX_PERMISSION_ARGS = [
-  '--ask-for-approval',
-  'never',
-  '--sandbox',
-  'workspace-write',
+  '--dangerously-bypass-approvals-and-sandbox',
   'exec',
+  // An agent home is not a git repository; without this, exec refuses to run.
+  '--skip-git-repo-check',
 ];
 export const ACADEMY_SYSTEM_PROMPT = 'academy-system-prompt.md';
 export const RUNTIMES = new Set(['claude-code', 'codex']);
@@ -99,9 +88,10 @@ function invalidName(message, name, json) {
   process.exit(1);
 }
 
-export function agentDir(name) {
-  return join(AGENTS_ROOT, name);
-}
+// The folder name is an agent's fixed id; agent.yaml `name:` is its current
+// name, so a name change never moves a running session's directory. Every
+// command accepts either. A folder answers first; YAML is read only on a miss.
+export const agentDir = (nameOrId) => join(AGENTS_ROOT, agentIdOf(nameOrId));
 
 // The holding area — `.archived`, its containment rule and every command's
 // question about it — lives in archived.mjs, which imports from here.
@@ -115,6 +105,97 @@ export function agentLifecycleLockPath(dir) {
   return join(dirname(resolved), `.${basename(resolved)}.lifecycle.lock`);
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Kind registry
+// ─────────────────────────────────────────────────────────────────────────────
+
+// The registry is the one surface and skill source for compile (scaffold),
+// measurement (inspect, tokens, budget), skills and create. Its contract:
+//
+//   KIND_PROFILES[kind] = {
+//     surfaces: [{ name, path: (dir) => absolutePath, cap, enforced }],
+//     skills:   [skillName],
+//   }
+//
+// `surfaces` is ordered, and the order is the compile order. `path` takes the
+// agent dir; shared surfaces ignore it and resolve under ACADEMY_HOME. `cap` is
+// an estimated-token cap; a kind's total cap is the sum of its surface caps.
+// `skills` lists only names whose templates exist — a later name enters this
+// list together with its template, because rendering throws on a missing one.
+// Each kind owns its own copy of the list, so a pack skill added to one kind
+// never reaches another. A name renders from `templates/packs/<kind>/<name>`
+// when that exists, else from `templates/skills/<name>`.
+// `surfacesFor(dir)` is the per-agent view with `path` already resolved.
+
+// A shared surface lives under ACADEMY_HOME, not in the agent dir.
+const surface = (name, cap, enforced, { shared = false } = {}) => ({
+  name,
+  path: (dir) => join(shared ? ACADEMY_HOME : dir, `${name}.md`),
+  cap,
+  enforced,
+});
+
+// Every kind compiles the same nine surfaces, in this order: the agent's own
+// seven, then the user's two. Only the cap of `work` differs by kind: a
+// Principal's work.md is thin (only work unique to it); an Owner's is full.
+const surfaceSet = (workCap) => [
+  surface('identity', 400, false),
+  surface('craft', 600, false),
+  surface('mandate', 600, true),
+  surface('work', workCap, true),
+  surface('knowledge', 2500, true),
+  surface('notes', 500, true),
+  surface('local-rules', 500, true),
+  surface('user', 1000, true, { shared: true }),
+  surface('user-work', 1000, true, { shared: true }),
+];
+
+const OWNER_PACK = [
+  'owner',
+  'owner-work',
+  'owner-review',
+  'owner-heartbeat',
+  'owner-feedback',
+  'owner-nightly',
+];
+
+export const KIND_PROFILES = {
+  // The curator is an ordinary Specialist, so `user-nightly` is the one skill a
+  // Specialist has that no other kind has.
+  specialist: { surfaces: surfaceSet(1000), skills: [...UNIVERSAL_SKILLS, 'user-nightly'] },
+  principal: {
+    surfaces: surfaceSet(500),
+    skills: [
+      'principal-nightly',
+      'principal-brief',
+      'principal-intro',
+      'work-graph',
+      'check-in',
+      'knowledge-curation',
+      'local-rules',
+      'skill-method',
+    ],
+  },
+  owner: { surfaces: surfaceSet(1000), skills: [...OWNER_PACK, ...UNIVERSAL_SKILLS] },
+};
+
+// A missing `kind:` is a Specialist: every agent created before kinds. An
+// unknown one is raised, not defaulted, the way the runtime is: compiling it as
+// a Specialist would hand the agent the wrong prompt.
+export function kindOf(dir) {
+  const kind = readAgentYaml(dir).kind || 'specialist';
+  if (Object.hasOwn(KIND_PROFILES, kind)) return kind;
+
+  const message = `Agent kind "${kind}" is not a kind Academy supports. Use ${Object.keys(KIND_PROFILES).join(', ')}.`;
+  if (jsonMode()) exitJsonError('invalid_spec', message, { kind, dir: resolve(dir) });
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+export function surfacesFor(dir) {
+  return KIND_PROFILES[kindOf(dir)].surfaces.map((entry) => ({ ...entry, path: entry.path(dir) }));
+}
+
 // The read-only root audit, as an answer rather than an exit. `doctor` reports
 // on a root it cannot use and must never exit from inside a probe, so the
 // finding and the reaction to it live apart. It never creates the root: `list`
@@ -166,11 +247,12 @@ export function checkAgentsRoot(json = jsonMode()) {
 }
 
 // The default root creates its own parent, because on a first run there is none
-// and nothing else will make it. A named root does not: its parent was proved
-// to exist by the audit above, so one level is all this ever has to create.
+// and nothing else will make it. A named root's parent was proved to exist by
+// the audit above, so for it `recursive` still creates one level. It is set for
+// both because without it two first creates race on the mkdir and one fails.
 export function validateAgentsRoot(json = jsonMode()) {
   const { root, exists } = checkAgentsRoot(json);
-  if (!exists) mkdirSync(root, { recursive: AGENTS_ROOT_IS_DEFAULT });
+  if (!exists) mkdirSync(root, { recursive: true });
   return root;
 }
 
@@ -246,12 +328,6 @@ export function exitJsonError(code, message, fields = {}) {
   contractError(activeCommandName(), code, message, fields);
 }
 
-// The memory bridge is Academy's one client-specific surface, and it is opt-in.
-// Unset, a scaffolded agent names no client at all.
-export function memoryBridgeEnabled() {
-  return process.env.ACADEMY_MEMORY_BRIDGE === '1';
-}
-
 export function isSymlink(path) {
   try {
     return lstatSync(path).isSymbolicLink();
@@ -334,7 +410,7 @@ export function delegateLegacyRun(name, passthrough, legacyRoot) {
     cwd: process.cwd(),
     env: process.env,
   });
-  process.exit(result.status ?? 0);
+  process.exit(childExitCode(result));
 }
 
 export function isInside(childPath, parentPath) {