@vibecompass/vibecompass 0.14.0 → 0.16.0

package/src/cli.js

@@ -5,6 +5,9 @@ import { pathToFileURL } from 'node:url';
 import { connectHostedProjectMemory, initializeProjectMemory, setDefaultSyncTarget } from './init.js';
 import { preflightDocsReview } from './docs-review.js';
 import { planDocsUpdate, renderDocsUpdatePlan } from './docs-update.js';
+import { buildSessionBrief, resolveBriefRequest } from './brief.js';
+import { generateLaneBrief, inspectLaneBrief } from './brief-lifecycle.js';
+import { renderBrief } from './brief-render.js';
 import { resolveConnectHostedCliOptions, resolveInitCliOptions } from './setup.js';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -18,6 +21,17 @@ import { refreshWorkflow } from './refresh-workflow.js';
 import { inspectProjectCompatibility, formatCompatibilityWarnings } from './compatibility.js';
 import { PACKAGE_VERSION } from './version.js';
 import { demoteHosted, promoteHosted } from './mode-transition.js';
+import { loginHosted } from './login.js';
+import {
+  credentialStoreKey,
+  credentialStoreOptionsFrom,
+  listSyncCredentials,
+  removeSyncCredential,
+  storeSyncCredential,
+} from './credential-store.js';
+import { canPromptSecret, promptSecret, readSecretFromStdin } from './secret-prompt.js';
+import { resolveSyncBinding, readSyncTargets } from './sync-binding.js';
+import { parseSimpleYaml } from './simple-yaml.js';
 import {
   adoptRemoteHead,
   applyPullExport,
@@ -71,7 +85,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     if (result.syncEnvVar) {
       const rootFlag = formatOptionalRootFlag(initPlan.initOptions.rootDir);
       io.stdout.write(`Hosted binding: configured for ${initPlan.initOptions.mode}\n`);
-      io.stdout.write(`Next step: set ${result.syncEnvVar} locally before your first hosted command.\n`);
+      io.stdout.write(`Next step: sign in with "vibecompass login${rootFlag}" (opens the dashboard and stores the sync token locally).\n`);
       if (initPlan.initOptions.mode === 'local-primary') {
         io.stdout.write(`Then run: vibecompass push${rootFlag}\n`);
         io.stdout.write(`Hosted docs-review: vibecompass docs-review --submit-hosted${rootFlag}\n`);
@@ -156,6 +170,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
       io.stdout.write(`Runtime: port ${result.runtime.port}, temp dir ${result.runtime.tmpDir}\n`);
       io.stdout.write('Export into a shell with: eval "$(vibecompass lane-env)" (D-282; pass --session <lane-id> when multiple lanes are active; use --worktree for independently runnable same-repo lanes).\n');
     }
+    writeLifecycleBriefResult(io, result.brief);
     writeWarnings(io, result.warnings);
     writeAgentFileSyncResult(io, result.agentFileSync);
     return 0;
@@ -204,7 +219,22 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
       io.stdout.write(`Sync target: ${result.syncTarget.name} (default: ${result.syncTarget.defaultTarget})\n`);
       io.stdout.write(`Select per command with --sync-target ${result.syncTarget.name}, or switch the default with: vibecompass sync-target ${result.syncTarget.name}\n`);
     }
-    io.stdout.write(`Next step: set ${result.syncEnvVar} locally before your first hosted command.\n`);
+    const capture = await captureSyncTokenAfterConnect(io, runtime, {
+      binding: {
+        apiUrl: connectPlan.sync.apiUrl,
+        projectId: connectPlan.sync.projectId,
+        credentialEnvVar: result.syncEnvVar,
+        target: result.syncTarget?.name ?? null,
+      },
+      rootDir: parsed.options.rootDir,
+      tokenStdin: Boolean(parsed.options.tokenStdin),
+      noStore: Boolean(parsed.options.noStore),
+      credentialStore: parsed.options.credentialStore,
+      rootFlag: formatOptionalRootFlag(parsed.options.rootDir),
+    });
+    if (capture?.viaLogin) {
+      return 0;
+    }
     if (result.mode === 'local-primary') {
       io.stdout.write('Then run: vibecompass push\n');
       io.stdout.write('Hosted docs-review: vibecompass docs-review --submit-hosted\n');
@@ -214,6 +244,22 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'login') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
+    const result = await loginHosted(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      io,
+      runtime,
+    });
+    writeLoginResult(io, result);
+    return 0;
+  }
+
+  if (parsed.command === 'sync-credential') {
+    return runSyncCredentialCommand(io, runtime, parsed.options);
+  }
+
   if (parsed.command === 'sync-target') {
     const result = await setDefaultSyncTarget({
       ...parsed.options,
@@ -272,6 +318,94 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'brief' && (parsed.options.write || parsed.options.check)) {
+    // Lane brief (D-364): --write regenerates the lane's brief.md under the
+    // lane root's lock; --check reports its freshness and writes nothing. A
+    // --source-root is only ever read.
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
+    const cwd = runtime.cwd ? path.resolve(runtime.cwd) : process.cwd();
+    const request = await resolveBriefRequest({
+      rootDir: parsed.options.rootDir,
+      sessionId: parsed.options.sessionId,
+      cwd,
+    });
+    if (!request.laneId) {
+      throw new Error(`brief ${parsed.options.write ? '--write' : '--check'} needs an active lane: pass --session <lane-id>, or run it from a lane worktree.`);
+    }
+    const sourceRootDir = parsed.options.sourceRootDir ? path.resolve(cwd, parsed.options.sourceRootDir) : undefined;
+    if (parsed.options.check) {
+      const inspection = await inspectLaneBrief({
+        rootDir: request.rootDir,
+        laneId: request.laneId,
+        sourceRootDir,
+        sourceSessionId: parsed.options.sourceSessionId,
+      });
+      if (parsed.options.json) {
+        io.stdout.write(`${JSON.stringify({
+          lane_id: request.laneId,
+          path: inspection.path,
+          exists: inspection.exists,
+          stale: inspection.stale,
+          reasons: inspection.reasons,
+          status: inspection.status,
+          generated_at: inspection.generatedAt,
+        }, null, 2)}\n`);
+      } else {
+        const state = !inspection.exists ? 'missing' : inspection.stale ? 'stale' : 'current';
+        io.stdout.write(`Brief: ${state}${inspection.status ? ` (status ${inspection.status}${inspection.generatedAt ? `, generated ${inspection.generatedAt}` : ''})` : ''} — ${inspection.path}\n`);
+        for (const reason of inspection.exists ? inspection.reasons : []) {
+          io.stdout.write(`- ${reason}\n`);
+        }
+      }
+      writeWarnings(io, request.warnings);
+      return 0;
+    }
+
+    const generated = await generateLaneBrief({
+      rootDir: request.rootDir,
+      laneId: request.laneId,
+      sourceRootDir,
+      sourceSessionId: parsed.options.sourceSessionId,
+      ...(parsed.options.budget !== undefined ? { budget: parsed.options.budget } : {}),
+    });
+    if (parsed.options.json) {
+      io.stdout.write(`${JSON.stringify({ lane_id: request.laneId, ...generated }, null, 2)}\n`);
+    } else {
+      const from = generated.source?.adapter ? ` from ${generated.source.root_dir}` : '';
+      io.stdout.write(`Brief: ${generated.status}${generated.state === 'written' ? '' : ` (${generated.state}: ${generated.reason})`} — wrote ${generated.path}${from}\n`);
+    }
+    writeWarnings(io, [...request.warnings, ...generated.warnings]);
+    return generated.state === 'written' ? 0 : 1;
+  }
+
+  if (parsed.command === 'brief') {
+    // Strictly read-only (plan task A3): no manifest refresh, state write,
+    // lane write, or agent-file sync, so it is safe against a legacy root.
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
+    const request = await resolveBriefRequest({
+      rootDir: parsed.options.rootDir,
+      sessionId: parsed.options.sessionId,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    });
+    const result = await buildSessionBrief({
+      rootDir: request.rootDir,
+      laneId: request.laneId,
+      task: parsed.options.task,
+      files: parsed.options.files,
+      featureSlugs: parsed.options.featureSlugs,
+      claims: parsed.options.claims,
+      budget: parsed.options.budget,
+    });
+    const markdown = renderBrief(result);
+    if (parsed.options.json) {
+      io.stdout.write(`${JSON.stringify({ ...result, lane_source: request.laneSource, cli_warnings: request.warnings, markdown }, null, 2)}\n`);
+    } else {
+      io.stdout.write(markdown);
+    }
+    writeWarnings(io, request.warnings);
+    return 0;
+  }
+
   if (parsed.command === 'close-session' || parsed.command === 'end-session') {
     await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await closeProjectSession({
@@ -318,6 +452,9 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
       io.stdout.write('Read next:\n');
       io.stdout.write(`- ${result.wipFilePath}\n`);
       io.stdout.write(`- ${result.handoffFilePath}\n`);
+      if (result.brief?.path && result.brief.state !== 'off' && !(result.brief.state === 'failed' && !result.brief.status)) {
+        io.stdout.write(`- ${result.brief.path} (session brief — read before planning)\n`);
+      }
       if (result.latestFinalizedSessionPath) {
         io.stdout.write(`- ${result.latestFinalizedSessionPath} (latest finalized note)\n`);
       }
@@ -335,6 +472,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
           io.stdout.write(`- ${lane.id}: ${lane.workingOn ?? 'No summary recorded'}\n`);
         }
       }
+      writeLifecycleBriefResult(io, result.brief);
     }
     writeWarnings(io, result.warnings);
     writeAgentFileSyncResult(io, result.agentFileSync);
@@ -762,6 +900,14 @@ export function parseCliArgs(argv) {
       return parseSyncTargetArgs(rest);
     }
 
+    if (command === 'login') {
+      return parseLoginArgs(rest);
+    }
+
+    if (command === 'sync-credential') {
+      return parseSyncCredentialArgs(rest);
+    }
+
     if (command === 'status') {
       return parseStatusArgs(rest);
     }
@@ -774,6 +920,10 @@ export function parseCliArgs(argv) {
       return parseDocsUpdateArgs(rest);
     }
 
+    if (command === 'brief') {
+      return parseBriefArgs(rest);
+    }
+
     if (command === 'close-session' || command === 'end-session') {
       return parseCloseSessionArgs(rest);
     }
@@ -1050,6 +1200,10 @@ function parseStartSessionArgs(argv) {
     if (token.startsWith('--worktree=')) {
       throw new Error('Flag "--worktree" takes no value; the worktree container is fixed to <workspace>/worktrees/<lane-id> (D-279).');
     }
+    if (token === '--no-brief') {
+      parsed.brief = false;
+      continue;
+    }
 
     const value = argv[index + 1];
     if (value === undefined) {
@@ -1162,6 +1316,16 @@ function parseConnectHostedArgs(argv) {
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index];
 
+    if (token === '--token-stdin') {
+      parsed.tokenStdin = true;
+      continue;
+    }
+
+    if (token === '--no-store') {
+      parsed.noStore = true;
+      continue;
+    }
+
     if (!token.startsWith('--')) {
       throw new Error(`Unexpected argument "${token}".`);
     }
@@ -1188,6 +1352,9 @@ function parseConnectHostedArgs(argv) {
       case '--sync-credential-env-var':
         parsed.syncCredentialEnvVar = value;
         break;
+      case '--credential-store':
+        parsed.credentialStore = value;
+        break;
       default:
         throw new Error(`Unknown flag "${token}".`);
     }
@@ -1203,6 +1370,9 @@ function parseConnectHostedArgs(argv) {
     command: 'connect-hosted',
     options: {
       rootDir: parsed.rootDir,
+      ...(parsed.tokenStdin ? { tokenStdin: true } : {}),
+      ...(parsed.noStore ? { noStore: true } : {}),
+      ...(parsed.credentialStore ? { credentialStore: parsed.credentialStore } : {}),
       ...(parsed.targetName ? { targetName: parsed.targetName } : {}),
       ...(syncValues.length > 0
         ? {
@@ -1217,6 +1387,363 @@ function parseConnectHostedArgs(argv) {
   };
 }
 
+function parseLoginArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === '--no-browser') {
+      parsed.noBrowser = true;
+      continue;
+    }
+
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--sync-target':
+        parsed.syncTarget = value;
+        break;
+      case '--api-url':
+        parsed.apiUrl = value;
+        break;
+      case '--project-id':
+        parsed.projectId = value;
+        break;
+      case '--sync-credential-env-var':
+        parsed.credentialEnvVar = value;
+        break;
+      case '--label':
+        parsed.label = value;
+        break;
+      case '--credential-store':
+        parsed.credentialStore = value;
+        break;
+      case '--poll-timeout': {
+        const seconds = Number(value);
+        if (!Number.isFinite(seconds) || seconds <= 0) {
+          throw new Error('--poll-timeout requires a positive number of seconds.');
+        }
+        parsed.pollTimeoutSeconds = seconds;
+        break;
+      }
+      default:
+        throw new Error(`Unknown flag "${token}" for login.`);
+    }
+  }
+
+  return { command: 'login', options: parsed };
+}
+
+const SYNC_CREDENTIAL_ACTIONS = new Set(['set', 'remove', 'list']);
+
+function parseSyncCredentialArgs(argv) {
+  const parsed = { action: null };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === '--token-stdin') {
+      parsed.tokenStdin = true;
+      continue;
+    }
+    if (token === '--from-env') {
+      parsed.fromEnv = true;
+      continue;
+    }
+    if (token === '--json') {
+      parsed.json = true;
+      continue;
+    }
+
+    if (!token.startsWith('--')) {
+      if (parsed.action !== null) {
+        throw new Error(`Unexpected argument "${token}".`);
+      }
+      if (!SYNC_CREDENTIAL_ACTIONS.has(token)) {
+        throw new Error(`Unknown sync-credential action "${token}". Use set, remove, or list.`);
+      }
+      parsed.action = token;
+      continue;
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--sync-target':
+        parsed.syncTarget = value;
+        break;
+      case '--api-url':
+        parsed.apiUrl = value;
+        break;
+      case '--project-id':
+        parsed.projectId = value;
+        break;
+      case '--label':
+        parsed.label = value;
+        break;
+      case '--credential-store':
+        parsed.credentialStore = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}" for sync-credential.`);
+    }
+  }
+
+  if (!parsed.action) {
+    throw new Error('sync-credential requires an action: set, remove, or list.');
+  }
+  if ((parsed.apiUrl && !parsed.projectId) || (!parsed.apiUrl && parsed.projectId)) {
+    throw new Error('--api-url and --project-id must be given together.');
+  }
+
+  return { command: 'sync-credential', options: parsed };
+}
+
+async function readRootSyncBindings(cwd, rootDirOption) {
+  const rootDir = path.resolve(cwd, rootDirOption ?? '.compass');
+  const projectFilePath = path.join(rootDir, 'project.yaml');
+  let project;
+  try {
+    project = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), { sourceName: projectFilePath });
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') {
+      return { rootDir, project: null, bindings: [] };
+    }
+    throw error;
+  }
+  const named = readSyncTargets(project);
+  const bindings = [];
+  if (named) {
+    for (const name of Object.keys(named.targets)) {
+      try {
+        bindings.push(resolveSyncBinding(project, name));
+      } catch {
+        // incomplete target; skip in listings
+      }
+    }
+  } else {
+    const flat = resolveSyncBinding(project, null);
+    if (flat) bindings.push(flat);
+  }
+  return { rootDir, project, bindings };
+}
+
+async function resolveSyncCredentialBinding(runtime, options) {
+  if (options.apiUrl && options.projectId) {
+    return {
+      target: null,
+      apiUrl: options.apiUrl,
+      projectId: options.projectId,
+      credentialEnvVar: 'VIBECOMPASS_SYNC_TOKEN',
+    };
+  }
+  const cwd = runtime.cwd ? path.resolve(runtime.cwd) : process.cwd();
+  const { rootDir, project } = await readRootSyncBindings(cwd, options.rootDir);
+  if (!project) {
+    throw new Error(`No project.yaml found in ${rootDir}. Run "vibecompass login" from an initialized root, or pass --api-url and --project-id.`);
+  }
+  const binding = resolveSyncBinding(project, options.syncTarget ?? null);
+  if (!binding) {
+    throw new Error('This root has no hosted sync binding yet. Run "vibecompass login" (recommended) or "vibecompass connect-hosted", or pass --api-url and --project-id.');
+  }
+  return binding;
+}
+
+function writeLoginResult(io, result) {
+  io.stdout.write(`Signed in to ${result.apiUrl} for project ${result.project.name} (${result.project.id}).\n`);
+  writeStoredCredentialLines(io, result.stored, {
+    apiUrl: result.apiUrl,
+    projectId: result.project.id,
+    credentialEnvVar: result.binding?.syncEnvVar ?? result.previousBinding?.credentialEnvVar ?? 'VIBECOMPASS_SYNC_TOKEN',
+  });
+  if (result.binding) {
+    io.stdout.write(`Connected hosted VibeCompass for ${result.binding.mode}\n`);
+    if (result.binding.modeChanged) {
+      io.stdout.write(`Project mode: ${result.binding.previousMode} -> ${result.binding.mode}\n`);
+    }
+    io.stdout.write(`Updated ${result.binding.projectFilePath}\n`);
+    if (result.binding.syncTarget) {
+      io.stdout.write(`Sync target: ${result.binding.syncTarget.name} (default: ${result.binding.syncTarget.defaultTarget})\n`);
+    }
+  }
+  for (const warning of result.warnings) {
+    io.stdout.write(`WARNING: ${warning}\n`);
+  }
+  const targetFlag = result.previousBinding?.target ?? result.binding?.syncTarget?.name;
+  const targetSuffix = targetFlag ? ` --sync-target ${targetFlag}` : '';
+  if (result.mode === 'local-primary') {
+    io.stdout.write(`Then run: vibecompass push${targetSuffix}\n`);
+  }
+  io.stdout.write(`Hosted docs-review: vibecompass docs-review --submit-hosted${targetSuffix}\n`);
+}
+
+function writeStoredCredentialLines(io, stored, binding) {
+  for (const warning of stored.warnings ?? []) {
+    io.stdout.write(`WARNING: ${warning}\n`);
+  }
+  const where = stored.backend === 'keychain' ? `the ${stored.backendDescription}` : stored.storePath;
+  io.stdout.write(`Stored the sync token for ${binding.apiUrl} (project ${binding.projectId}) in ${where}${stored.replaced ? ', replacing the previous entry' : ''}.\n`);
+  io.stdout.write(`Hosted commands find it automatically in every terminal; ${binding.credentialEnvVar} still overrides it per shell.\n`);
+}
+
+async function captureSyncTokenAfterConnect(io, runtime, spec) {
+  const { binding } = spec;
+  const env = runtime.env ?? process.env;
+  const targetFlag = binding.target ? ` --sync-target ${binding.target}` : '';
+  const loginHint = `vibecompass login${spec.rootFlag}${targetFlag}`;
+
+  if (spec.noStore) {
+    io.stdout.write(`Token not stored (--no-store). Set ${binding.credentialEnvVar} in every shell that runs hosted commands, or later run: ${loginHint}\n`);
+    return null;
+  }
+
+  let token = null;
+  if (spec.tokenStdin) {
+    token = await readSecretFromStdin(io, runtime);
+    if (!token) {
+      throw new Error('--token-stdin was given but no token arrived on stdin.');
+    }
+  } else if (typeof env[binding.credentialEnvVar] === 'string' && env[binding.credentialEnvVar].trim() !== '') {
+    io.stdout.write(`${binding.credentialEnvVar} is set in this shell and takes precedence for hosted commands. Persist it for new terminals with: vibecompass sync-credential set${spec.rootFlag}${targetFlag} --from-env\n`);
+    return null;
+  } else if (canPromptSecret(io, runtime)) {
+    // D-356: the recommended path is the browser sign-in. A pasted dashboard
+    // token is the advanced alternative; Enter falls through to login.
+    token = await promptSecret('Press Enter to sign in with your browser, or paste a dashboard token (input hidden)', io, runtime);
+    if (!token) {
+      const result = await loginHosted(
+        {
+          rootDir: spec.rootDir,
+          ...(binding.target ? { syncTarget: binding.target } : {}),
+          ...(spec.credentialStore ? { credentialStore: spec.credentialStore } : {}),
+        },
+        { cwd: runtime.cwd, env, io, runtime },
+      );
+      writeLoginResult(io, result);
+      return { viaLogin: true, stored: result.stored };
+    }
+  } else {
+    io.stdout.write(`Next step: sign in with "${loginHint}" (opens the dashboard and stores the sync token locally). CI or scripts: set ${binding.credentialEnvVar}, or pipe a dashboard token into "vibecompass connect-hosted ... --token-stdin".\n`);
+    return null;
+  }
+
+  const stored = await storeSyncCredential(
+    {
+      apiUrl: binding.apiUrl,
+      projectId: binding.projectId,
+      token,
+      label: `VibeCompass sync token (${binding.projectId})`,
+      source: 'connect-hosted',
+      backend: spec.credentialStore,
+    },
+    credentialStoreOptionsFrom({ env, runtime }),
+  );
+  writeStoredCredentialLines(io, stored, binding);
+  return stored;
+}
+
+async function runSyncCredentialCommand(io, runtime, options) {
+  const env = runtime.env ?? process.env;
+  const storeOptions = credentialStoreOptionsFrom({ env, runtime });
+
+  if (options.action === 'list') {
+    const listing = await listSyncCredentials(storeOptions);
+    const cwd = runtime.cwd ? path.resolve(runtime.cwd) : process.cwd();
+    const { bindings } = await readRootSyncBindings(cwd, options.rootDir).catch(() => ({ bindings: [] }));
+    const boundKeys = new Map();
+    for (const binding of bindings) {
+      try {
+        boundKeys.set(credentialStoreKey(binding.apiUrl, binding.projectId), binding);
+      } catch {
+        // an unparseable binding URL cannot be annotated; the entry still lists
+      }
+    }
+    if (options.json) {
+      io.stdout.write(`${JSON.stringify({ storePath: listing.storePath, entries: listing.entries }, null, 2)}\n`);
+      return 0;
+    }
+    io.stdout.write(`Credential store: ${listing.storePath} (${listing.entries.length} ${listing.entries.length === 1 ? 'entry' : 'entries'})\n`);
+    if (listing.entries.length === 0) {
+      io.stdout.write('No stored sync tokens. Run "vibecompass login" to sign in from this terminal.\n');
+      return 0;
+    }
+    for (const entry of listing.entries) {
+      const bound = boundKeys.get(entry.key);
+      const boundNote = bound ? (bound.target ? ` — bound here as target ${bound.target}` : ' — bound here') : '';
+      io.stdout.write(
+        `- ${entry.apiUrl} project ${entry.projectId}: ${entry.backend}, prefix ${entry.tokenPrefix ?? '?'}, stored ${entry.storedAt ?? '?'} via ${entry.source ?? '?'}${boundNote}\n`,
+      );
+    }
+    return 0;
+  }
+
+  const binding = await resolveSyncCredentialBinding(runtime, options);
+
+  if (options.action === 'remove') {
+    const result = await removeSyncCredential(binding, storeOptions);
+    io.stdout.write(
+      result.removed
+        ? `Removed the stored sync token for ${binding.apiUrl} (project ${binding.projectId}) from the ${result.backend === 'keychain' ? 'OS keychain' : 'credential store file'}.\n`
+        : `No stored sync token for ${binding.apiUrl} (project ${binding.projectId}).\n`,
+    );
+    io.stdout.write('Revoke the credential on the hosted dashboard under Setup -> Hosted sync if it should stop working everywhere.\n');
+    return 0;
+  }
+
+  let token = null;
+  if (options.tokenStdin) {
+    token = await readSecretFromStdin(io, runtime);
+    if (!token) {
+      throw new Error('--token-stdin was given but no token arrived on stdin.');
+    }
+  } else if (options.fromEnv) {
+    token = typeof env[binding.credentialEnvVar] === 'string' ? env[binding.credentialEnvVar].trim() : '';
+    if (!token) {
+      throw new Error(`--from-env requires ${binding.credentialEnvVar} to be set in this shell.`);
+    }
+  } else if (canPromptSecret(io, runtime)) {
+    token = await promptSecret('Paste the sync token from the dashboard (input hidden)', io, runtime);
+    if (!token) {
+      throw new Error('No token entered.');
+    }
+  } else {
+    throw new Error('sync-credential set needs a token: run it in an interactive terminal, pipe one with --token-stdin, or use --from-env.');
+  }
+
+  const stored = await storeSyncCredential(
+    {
+      apiUrl: binding.apiUrl,
+      projectId: binding.projectId,
+      token,
+      label: options.label ?? `VibeCompass sync token (${binding.projectId})`,
+      source: 'sync-credential',
+      backend: options.credentialStore,
+    },
+    storeOptions,
+  );
+  writeStoredCredentialLines(io, stored, binding);
+  return 0;
+}
+
 function parseStatusArgs(argv) {
   const parsed = {};
 
@@ -1434,6 +1961,105 @@ function parseDocsUpdateArgs(argv) {
   };
 }
 
+function parseBriefArgs(argv) {
+  const parsed = {
+    files: [],
+    featureSlugs: [],
+    claims: [],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--json') {
+      parsed.json = true;
+      continue;
+    }
+    if (token === '--write' || token === '--check') {
+      parsed[token.slice(2)] = true;
+      continue;
+    }
+
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith('--')) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--session':
+        parsed.sessionId = value;
+        break;
+      case '--source-root':
+        parsed.sourceRootDir = value;
+        break;
+      case '--source-session':
+        parsed.sourceSessionId = value;
+        break;
+      case '--task':
+        parsed.task = value;
+        break;
+      case '--files':
+      case '--file':
+        // `--files a b c` and repeated `--files a --files b` both work.
+        parsed.files.push(value);
+        while (argv[index + 1] !== undefined && !argv[index + 1].startsWith('--')) {
+          index += 1;
+          parsed.files.push(argv[index]);
+        }
+        break;
+      case '--feature':
+        parsed.featureSlugs.push(value);
+        break;
+      case '--claim':
+        parsed.claims.push(value);
+        break;
+      case '--budget':
+        if (!/^\d+$/.test(value)) {
+          throw new Error(`--budget must be a whole number of estimated tokens (got "${value}").`);
+        }
+        parsed.budget = Number(value);
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  if (parsed.write && parsed.check) {
+    throw new Error('Choose one of --write (regenerate the lane brief) or --check (report its freshness).');
+  }
+  if (parsed.write || parsed.check) {
+    const laneDerived = [
+      parsed.task !== undefined && '--task',
+      parsed.files.length > 0 && '--files',
+      parsed.featureSlugs.length > 0 && '--feature',
+      parsed.claims.length > 0 && '--claim',
+      parsed.check && parsed.budget !== undefined && '--budget',
+    ].filter(Boolean);
+    if (laneDerived.length > 0) {
+      throw new Error(
+        `${laneDerived.join(', ')} cannot be combined with ${parsed.write ? '--write' : '--check'}: a lane brief takes its task from the lane's working-on, its files from the lane's claims, and its features from the lane's feature slugs (update them with continue-session --working-on or the lane metadata).`,
+      );
+    }
+  } else if (parsed.sourceRootDir || parsed.sourceSessionId) {
+    throw new Error('--source-root and --source-session apply only to --write or --check; to print a brief of another root, pass --root.');
+  }
+  if (parsed.sourceSessionId && !parsed.sourceRootDir) {
+    throw new Error('--source-session requires --source-root.');
+  }
+
+  return {
+    command: 'brief',
+    options: parsed,
+  };
+}
+
 function parseListSessionsArgs(argv) {
   const parsed = {};
 
@@ -1707,6 +2333,10 @@ function parseContinueSessionArgs(argv) {
       parsed.json = true;
       continue;
     }
+    if (token === '--no-brief') {
+      parsed.brief = false;
+      continue;
+    }
 
     const value = argv[index + 1];
     if (value === undefined) {
@@ -1724,6 +2354,12 @@ function parseContinueSessionArgs(argv) {
       case '--session':
         parsed.sessionId = value;
         break;
+      case '--source-root':
+        parsed.sourceRootDir = value;
+        break;
+      case '--source-session':
+        parsed.sourceSessionId = value;
+        break;
       case '--working-on':
         parsed.workingOn = value;
         break;
@@ -1756,6 +2392,13 @@ function parseContinueSessionArgs(argv) {
     parsed.sessionId = positional[0];
   }
 
+  if (parsed.brief === false && (parsed.sourceRootDir || parsed.sourceSessionId)) {
+    throw new Error('--no-brief cannot be combined with --source-root or --source-session.');
+  }
+  if (parsed.sourceSessionId && !parsed.sourceRootDir) {
+    throw new Error('--source-session requires --source-root.');
+  }
+
   return {
     command: 'continue-session',
     options: parsed,
@@ -2467,6 +3110,31 @@ function writeWarnings(io, warnings = []) {
   }
 }
 
+/** One status line for the lifecycle brief (D-364); failures also arrive as warnings. */
+function writeLifecycleBriefResult(io, brief) {
+  if (!brief) return;
+  const location = brief.path ? ` — ${brief.path}` : '';
+  const from = brief.source?.adapter ? ` (from ${brief.source.root_dir})` : '';
+  switch (brief.state) {
+    case 'off':
+      io.stdout.write(`Brief: off (${brief.reason})\n`);
+      return;
+    case 'kept':
+      io.stdout.write(`Brief: current, kept (status ${brief.status ?? 'unknown'}${brief.generatedAt ? `, generated ${brief.generatedAt}` : ''})${location}\n`);
+      return;
+    case 'regenerated':
+      io.stdout.write(`Brief: regenerated, ${brief.status}${from} (was stale: ${(brief.staleReasons ?? []).join('; ') || 'unknown'})${location}\n`);
+      return;
+    case 'written':
+      io.stdout.write(`Brief: ${brief.status}${from}${location}\n`);
+      return;
+    default:
+      io.stdout.write(brief.status
+        ? `Brief: incomplete (${brief.state}: ${brief.reason})${location}\n`
+        : 'Brief: not written (see warning)\n');
+  }
+}
+
 function splitAssignment(value, flagName) {
   const separatorIndex = value.indexOf('=');
   if (separatorIndex <= 0 || separatorIndex === value.length - 1) {
@@ -2487,15 +3155,23 @@ function usageText() {
     '  vibecompass --version',
     '  vibecompass version',
     '  vibecompass init --name <project-name> --mode <local-only|local-primary|hosted-only> --repo <id=remote> [options]',
-    '  vibecompass connect-hosted [options]',
+    '  vibecompass login [--sync-target <name>] [--api-url <url>] [--no-browser] [options]',
+    '                                        Recommended: connect this root to hosted VibeCompass from your browser',
     '  vibecompass sync-target [<name>] [options]',
+    '  vibecompass connect-hosted [options]  Advanced: bind with a dashboard token (login does this for you)',
+    '  vibecompass sync-credential <set|remove|list> [--sync-target <name>] [options]',
+    '                                        Advanced: manage stored tokens for CI or scripts',
     '  vibecompass status [options]',
     '  vibecompass refresh-workflow [--dry-run|--apply] [options]',
     '  vibecompass docs-update [--session <lane-id>] [options]',
-    '  vibecompass start-session --id <lane-id> --working-on <text> [--branch <name> [--worktree]] [options]',
+    '  vibecompass brief --task <text> [--files <repo:path>...] [--feature <slug>] [--claim <path>] [--session <lane-id>] [--budget <n>] [--json] [options]',
+    '                                        Read-only session brief: relevant memory, packed into an estimated token budget',
+    '  vibecompass brief --write|--check [--session <lane-id>] [--source-root <path> [--source-session <lane-id>]] [--budget <n>] [--json] [options]',
+    '                                        Regenerate the lane\'s sessions/active/<lane-id>/brief.md, or report whether it is stale (D-364)',
+    '  vibecompass start-session --id <lane-id> --working-on <text> [--branch <name> [--worktree]] [--no-brief] [options]',
     '  vibecompass close-session --title <text> --completed <text> --architecture-docs <status> --decision-log <status> --session-maintenance <status> [options]',
     '  vibecompass end-session --title <text> --completed <text> --architecture-docs <status> --decision-log <status> --session-maintenance <status> [options]  # alias',
-    '  vibecompass continue-session [<lane-id>] [--session <lane-id>] [--working-on <text>] [--json] [options]',
+    '  vibecompass continue-session [<lane-id>] [--session <lane-id>] [--working-on <text>] [--no-brief | --source-root <path>] [--json] [options]',
     '  vibecompass list-sessions [--json] [options]',
     '  vibecompass switch-session <id> [options]',
     '  vibecompass rebuild-active-index [--current <lane-id>] [options]',
@@ -2541,13 +3217,17 @@ function usageText() {
     '  --force                              Overwrite an existing project.yaml',
     '  --replace-active-lanes               Allow --force to replace a root that has active session lanes',
     '',
-    'Connect-hosted options:',
+    'Connect-hosted options (advanced; on a terminal, Enter at the token prompt starts the browser sign-in):',
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --target <name>                      Add or update a named sync target (e.g. dev, prod)',
     '                                        First named target becomes the default; flat sync fields mirror the default target',
     '  --sync-api-url <url>                 Hosted sync api_url',
     '  --sync-project-id <id>               Hosted sync project_id',
     '  --sync-credential-env-var <name>     Hosted sync env var reference',
+    '  --token-stdin                        Store the sync token read from stdin (first non-empty line)',
+    '  --no-store                           Do not store a token; rely on the env var only',
+    '  --credential-store <auto|keychain|file>',
+    '                                        Where to keep the token (D-355). auto prefers the OS keychain',
     '                                        Without --target, replaces any existing flat project.yaml sync binding',
     '',
     'Sync-target options:',
@@ -2555,6 +3235,33 @@ function usageText() {
     '  vibecompass sync-target <name>       Switch the default sync target (re-mirrors flat sync fields)',
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '',
+    'Login options (recommended path, D-355/D-356):',
+    '  vibecompass login                    Sign in from the terminal: opens the dashboard, you approve a short code, the sync token is stored locally',
+    '  --root <path>                        Project-memory root. Defaults to .compass',
+    '  --sync-target <name>                 Sign in for a named sync target (add --api-url to create a new one)',
+    '  --api-url <url>                      Hosted URL for an unbound root or a new target. Defaults to https://vibecompass.dev',
+    '  --project-id <id>                    Pre-select a hosted project on the approval page',
+    '  --sync-credential-env-var <name>     Override env-var name recorded in a new binding. Defaults to VIBECOMPASS_SYNC_TOKEN',
+    '  --label <text>                       Device label shown in the dashboard. Defaults to the hostname',
+    '  --credential-store <auto|keychain|file>',
+    '                                        Where to keep the token. auto prefers the OS keychain',
+    '  --poll-timeout <seconds>             Stop waiting for approval after this long. Defaults to the code lifetime',
+    '  --no-browser                         Print the link without opening a browser',
+    '',
+    'Sync-credential options (advanced, D-355):',
+    '  vibecompass sync-credential set      Store a dashboard token for the bound project (hidden prompt, --token-stdin, or --from-env)',
+    '  vibecompass sync-credential remove   Forget the stored token for the bound project',
+    '  vibecompass sync-credential list     List stored tokens (metadata only, never values)',
+    '  --root <path>                        Project-memory root. Defaults to .compass',
+    '  --sync-target <name>                 Address a named sync target',
+    '  --api-url <url> --project-id <id>    Address a hosted project without a bound root',
+    '  --token-stdin                        Read the token from stdin (first non-empty line)',
+    '  --from-env                           Store the value currently in the binding env var',
+    '  --credential-store <auto|keychain|file>',
+    '                                        Where to keep the token. auto prefers the OS keychain',
+    '  --label <text>                       Label recorded with the stored token',
+    '  --json                               list: print entries as JSON',
+    '',
     'Status options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --tooling-root <path>                Directory where agent files are inspected. Defaults to cwd',
@@ -2590,6 +3297,7 @@ function usageText() {
     '  --last-thing-completed <text>        Optional override for the CLAUDE.md current-session block',
     '  --blockers <text>                    Optional current blockers summary',
     '  --next-session-should <text>         Optional current-session handoff summary',
+    '  --no-brief                           Skip the lane brief for this command (sessions/active/<lane-id>/brief.md; D-359, D-364); lifecycle commands write it only when project.yaml sets brief.enabled: true (opt-in, D-368)',
     '',
     'Close-session options (also accepted by end-session):',
     '  --root <path>                        Project-memory root. Explicit --root wins; otherwise the nearest worktree lane marker supplies it, else .compass',
@@ -2617,7 +3325,23 @@ function usageText() {
     '  --last-thing-completed <text>        Optional override for the CLAUDE.md current-session block',
     '  --blockers <text>                    Optional current blockers summary',
     '  --next-session-should <text>         Optional current-session handoff summary',
-    '  --json                               Print the resume result (lane, paths, runtime, other lanes, warnings) as JSON',
+    '  --json                               Print the resume result (lane, paths, runtime, other lanes, brief, warnings) as JSON',
+    '  --no-brief                           Leave the lane brief as it is; with project.yaml brief.enabled: true (opt-in, D-368) resume keeps a current brief and regenerates a missing or stale one',
+    '  --source-root <path>                 D-255 dual-root dogfood: build the brief from this memory root\'s matching lane (same id, session date, and number) and write it only into this lane; the source root is only read',
+    '  --source-session <lane-id>           With --source-root: the source lane id, which must equal the resumed lane',
+    '',
+    'Brief options:',
+    '  --root <path>                        Project-memory root. Explicit --root wins; otherwise the nearest worktree lane marker supplies it, else .compass',
+    '  --session <lane-id>                  Lane to brief. Omitted: nearest worktree lane marker, else the single active lane; 2+ active lanes require --session or a marker (D-277)',
+    '  --task <text>                        Task text (print mode). Omitted: the lane\'s working-on',
+    '  --files <repo:path>...               Files the task touches (print mode)',
+    '  --feature <slug>, --claim <path>     Repeatable feature slug and path claim (print mode)',
+    '  --budget <n>                         Estimated-token budget (default 6000, minimum 800)',
+    '  --write                              Regenerate the lane\'s brief.md from its working-on, claims, and feature slugs, under the root lock',
+    '  --check                              Report whether the lane\'s brief.md is current or stale against its header bindings; writes nothing',
+    '  --source-root <path>                 With --write/--check: read this memory root\'s matching lane instead (D-255 dogfood); never written',
+    '  --source-session <lane-id>           With --source-root: the source lane id, which must equal the lane being briefed',
+    '  --json                               Print the result as JSON',
     '',
     'List/switch-session options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',