@vibecompass/vibecompass 0.3.0 → 0.3.1

package/README.md

@@ -20,7 +20,7 @@ Shipped today:
 - `vibecompass end-session` as a discoverable alias for `close-session`
 - `vibecompass sync-agents` for generated `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, and `.github/copilot-instructions.md` views
 - `vibecompass docs-review --guided` — print a comprehensive review prompt for your chosen LLM to run
-- `vibecompass docs-review --submit-hosted` — submit the review request to the hosted app (execution paused; details below)
+- `vibecompass docs-review --submit-hosted` — submit the review request to the hosted app and poll for proposal/artifact output
 - `vibecompass docs-review --run-local --provider anthropic` — local provider adapter that saves review output locally
 - `vibecompass docs-review --apply-output` — apply accepted architecture-doc blocks into canonical `architecture/` docs
 - `vibecompass docs-review --complete` — mark the review accepted after the docs land
@@ -153,15 +153,17 @@ VibeCompass dogfoods: read project memory first, inspect source evidence,
 write component docs with review metadata, preserve the starter overview, and
 emit accepted docs as `vibecompass-architecture-doc` blocks.
 
-The package never calls an AI itself — that's intentional. You stay in
-control of which provider runs the review and what gets saved.
+Plain `--guided` never calls an AI itself. You stay in control of which
+provider runs the review and what gets saved. Use `--run-local --provider
+anthropic` when you want the package to execute the same review through your
+local Anthropic key.
 
 ### Other ways to run a review
 
 - `--submit-hosted` sends the review request to the hosted app and records a
-  run ID. The hosted worker that actually runs the review and writes docs
-  isn't live yet, so the submission is durably accepted but no scan runs
-  against it.
+  run ID. Hosted execution creates proposals and docs-review artifacts; for
+  local-primary projects, canonical local files change only after
+  pull-preview/export/apply and a confirming push.
 - `--run-local --provider anthropic` calls Anthropic directly with your
   `ANTHROPIC_API_KEY` and saves the raw output to
   `state/docs-review-output.md`.
@@ -243,7 +245,23 @@ npx -y @vibecompass/vibecompass sync-agents --root .compass
 Content outside those markers is preserved. Existing files without markers are
 reported as warnings and left untouched.
 
-Create a `local-primary` root when you also want the hosted sync binding written into `project.yaml`:
+Connect hosted VibeCompass later when you want browser views, team sync, or hosted docs-review:
+
+```bash
+npx -y @vibecompass/vibecompass connect-hosted \
+  --sync-api-url https://vibecompass.dev \
+  --sync-project-id vc_proj_example \
+  --sync-credential-env-var VIBECOMPASS_SYNC_TOKEN
+```
+
+Then set the secret locally and push the first baseline:
+
+```bash
+export VIBECOMPASS_SYNC_TOKEN='your-sync-token'
+npx -y @vibecompass/vibecompass push
+```
+
+Create a `local-primary` root non-interactively when you also want the hosted sync binding written into `project.yaml` during init:
 
 ```bash
 npx -y @vibecompass/vibecompass init \
@@ -269,14 +287,8 @@ That creates:
     manifest.json
 ```
 
-Next step after init:
-
-```bash
-export VIBECOMPASS_SYNC_TOKEN='your-sync-token'
-```
-
-`vibecompass` does not yet perform hosted sync itself. The sync fields in
-`project.yaml` are the non-secret binding for the upcoming push/pull flows.
+The sync fields in `project.yaml` are non-secret. The token value stays in
+your environment and is never written to canonical project memory.
 
 ## CLI
 
@@ -296,9 +308,9 @@ Options:
 - `--guided`: ask placement and setup questions interactively
 - `--repo <id=remote>`: repeatable repo descriptor
 - `--repo-branch <id=branch>`: optional per-repo default branch
-- `--sync-api-url <url>`: hosted sync API URL for `local-primary`
-- `--sync-project-id <id>`: hosted sync project ID for `local-primary`
-- `--sync-credential-env-var <name>`: local env-var reference for `local-primary`
+- `--sync-api-url <url>`: hosted sync API URL for `local-primary` or `hosted-only`
+- `--sync-project-id <id>`: hosted sync project ID for `local-primary` or `hosted-only`
+- `--sync-credential-env-var <name>`: local env-var reference for `local-primary` or `hosted-only`
 - `--with-workflow`: generate `context.md` plus workflow guide files
 - `--with-claude`: create a starter `CLAUDE.md` if it does not already exist
 - `--with-agents`: create a starter `AGENTS.md` if it does not already exist
@@ -315,6 +327,31 @@ Guided init can also record workflow defaults in
 `project.yaml.metadata.workflow`, including whether close-session should
 include a Git publish step and which remote name to use for that step.
 
+Guided init is inference-first for the common single-repo case: it reads
+`package.json`, detects the current Git `origin`, asks you to confirm the
+detected repo, and maps a friendly setup goal to the stored project mode.
+Hosted credentials are deferred by default; run `vibecompass connect-hosted`
+when you are ready to connect the local root to `vibecompass.dev`.
+
+### `vibecompass connect-hosted`
+
+```text
+vibecompass connect-hosted [options]
+```
+
+Options:
+
+- `--root <path>`: project-memory root; defaults to `.compass`
+- `--sync-api-url <url>`: hosted sync API URL
+- `--sync-project-id <id>`: hosted sync project ID
+- `--sync-credential-env-var <name>`: local env-var reference
+
+Without all three sync flags, `connect-hosted` prompts for the missing fields.
+It updates only the non-secret `project.yaml.sync` binding; you still set the
+actual token in your environment before running hosted commands.
+Running it again replaces the existing hosted binding in `project.yaml`, which
+is the intended rotation path after you create a new sync credential.
+
 ### `vibecompass start-session`
 
 ```text
@@ -417,7 +454,7 @@ Options:
 
 - `--root <path>`: project-memory root; defaults to `.compass`
 - `--guided`: print a comprehensive review prompt for your chosen LLM to run (recommended)
-- `--submit-hosted`: submit the review request to the hosted app (execution paused; submission durable)
+- `--submit-hosted`: submit the review request to the hosted app
 - `--run-local`: run the generated review request with a local provider
 - `--provider <name>`: local provider for `--run-local`; currently `anthropic`
 - `--run-local-anthropic`: compatibility alias for `--run-local --provider anthropic`
@@ -443,9 +480,11 @@ Project-mode requirements:
 hosted binding, so hosted precedence does not apply when that flag is set.
 
 `--submit-hosted` uses `sync.credential_env_var` and records the hosted run
-ID in `state/docs-review.json`. Submission is durable today; the hosted
-worker that runs the review and writes canonical docs is not yet live, so
-no scan executes against the submitted request. Local files stay untouched.
+ID in `state/docs-review.json`. Hosted execution creates review proposals and
+artifacts; for `local-primary` roots, local files stay untouched until you
+pull-preview, export, apply locally, and push to confirm the accepted output.
+Missing or stale hosted baselines fail with package-facing next-step guidance
+instead of running model work against the wrong source of truth.
 
 `--run-local-anthropic` remains as a compatibility alias. New scripts should
 use `--run-local --provider anthropic`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecompass/vibecompass",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Local-first project-memory core for VibeCompass",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -2,11 +2,17 @@
 
 import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
-import { initializeProjectMemory } from './init.js';
+import { connectHostedProjectMemory, initializeProjectMemory } from './init.js';
 import { preflightDocsReview } from './docs-review.js';
-import { resolveInitCliOptions } from './setup.js';
+import { resolveConnectHostedCliOptions, resolveInitCliOptions } from './setup.js';
 import { closeProjectSession, listProjectSessions, startProjectSession, switchProjectSession } from './session.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
+import {
+  applyPullExport,
+  pullExportProjectMemory,
+  pullPreviewProjectMemory,
+  pushProjectMemory,
+} from './sync.js';
 
 export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
   const parsed = parseCliArgs(argv);
@@ -41,7 +47,20 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     );
 
     if (result.syncEnvVar) {
-      io.stdout.write(`Next step: set ${result.syncEnvVar} locally before your first sync.\n`);
+      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`);
+      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`);
+      } else if (initPlan.initOptions.mode === 'hosted-only') {
+        io.stdout.write(`Hosted docs-review: vibecompass docs-review --submit-hosted${rootFlag}\n`);
+      }
+    } else if (initPlan.initOptions.mode === 'hosted-only') {
+      io.stdout.write('Hosted-only projects need a hosted sync binding before hosted commands.\n');
+      io.stdout.write('After creating a sync credential, rerun init with --force and --sync-api-url/--sync-project-id/--sync-credential-env-var, or add project.yaml.sync manually.\n');
+    } else if (initPlan.initOptions.mode === 'local-primary') {
+      io.stdout.write('Optional hosted setup later: vibecompass connect-hosted\n');
     }
 
     if (result.contextFilePath) {
@@ -92,6 +111,28 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'connect-hosted') {
+    const connectPlan = await resolveConnectHostedCliOptions(parsed.options, {
+      cwd: runtime.cwd,
+      io,
+      runtime,
+    });
+    const result = await connectHostedProjectMemory({
+      ...connectPlan,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    });
+    io.stdout.write(`Connected hosted VibeCompass for ${result.mode}\n`);
+    io.stdout.write(`Updated ${result.projectFilePath}\n`);
+    io.stdout.write(`Next step: set ${result.syncEnvVar} locally before your first hosted command.\n`);
+    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');
+    } else {
+      io.stdout.write('Hosted docs-review: vibecompass docs-review --submit-hosted\n');
+    }
+    return 0;
+  }
+
   if (parsed.command === 'close-session' || parsed.command === 'end-session') {
     const result = await closeProjectSession({
       ...parsed.options,
@@ -168,6 +209,9 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     }
     if (result.hosted) {
       io.stdout.write(`Hosted run: ${result.hosted.run_id}\n`);
+      if (result.hosted.phase) {
+        io.stdout.write(`Hosted phase: ${result.hosted.phase}\n`);
+      }
     }
     if (result.localReview) {
       io.stdout.write(`Local review output: ${result.localReview.output_path}\n`);
@@ -178,6 +222,11 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
         io.stdout.write(`- ${entry.path} (${entry.status})\n`);
       }
     }
+    if (result.appliedDecisionArtifact) {
+      io.stdout.write(`Applied decision artifact: ${result.appliedDecisionArtifact.artifact_id}\n`);
+      io.stdout.write(`Decision: D-${String(result.appliedDecisionArtifact.decision_id).padStart(3, '0')}\n`);
+      io.stdout.write(`Target: ${result.appliedDecisionArtifact.target_path}\n`);
+    }
     writeWarnings(io, result.warnings);
     io.stdout.write(`Recorded ${result.statePath}\n`);
     io.stdout.write(`${result.message}\n`);
@@ -188,6 +237,80 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'push') {
+    const result = await pushProjectMemory(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Push: ${result.status}\n`);
+    io.stdout.write(`Remote revision: ${result.remoteRevisionId}\n`);
+    io.stdout.write(`Run: ${result.runId}\n`);
+    if (result.appliedProposalIds.length > 0) {
+      io.stdout.write(`Applied proposals: ${result.appliedProposalIds.join(', ')}\n`);
+    }
+    if (result.staleProposalIds.length > 0) {
+      io.stdout.write(`Stale proposals: ${result.staleProposalIds.join(', ')}\n`);
+    }
+    io.stdout.write(`Recorded ${result.manifestPath}\n`);
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
+  if (parsed.command === 'pull-preview') {
+    const result = await pullPreviewProjectMemory(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Pull-preview: ${result.status}\n`);
+    io.stdout.write(`Preview token: ${result.previewToken}\n`);
+    io.stdout.write(`Pending proposals: ${result.proposals.length}\n`);
+    for (const proposal of result.proposals) {
+      io.stdout.write(`- ${proposal.proposal_id}: ${proposal.summary}\n`);
+    }
+    if (result.conflicts.length > 0) {
+      io.stdout.write(`Conflicts: ${result.conflicts.length}\n`);
+      for (const conflict of result.conflicts) {
+        io.stdout.write(`- ${conflict.code}: ${conflict.message}\n`);
+      }
+    }
+    writeWarnings(io, result.warnings.map((warning) => `${warning.code}: ${warning.message}`));
+    io.stdout.write(`Recorded ${result.manifestPath}\n`);
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
+  if (parsed.command === 'pull-export') {
+    const result = await pullExportProjectMemory(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Pull-export: ${result.status}\n`);
+    io.stdout.write(`Run: ${result.runId}\n`);
+    io.stdout.write(`Proposal IDs: ${result.proposalIds.join(', ')}\n`);
+    io.stdout.write(`Operations: ${result.operationCount}\n`);
+    io.stdout.write(`Wrote ${result.outputPath}\n`);
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
+  if (parsed.command === 'apply-export') {
+    const result = await applyPullExport(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Apply-export: ${result.status}\n`);
+    for (const entry of result.applied) {
+      io.stdout.write(`- ${entry.path} (${entry.status})\n`);
+    }
+    io.stdout.write(`Recorded ${result.outputPath}\n`);
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
   throw new Error(`Unknown command "${parsed.command}".`);
 }
 
@@ -203,6 +326,10 @@ export function parseCliArgs(argv) {
       return parseStartSessionArgs(rest);
     }
 
+    if (command === 'connect-hosted') {
+      return parseConnectHostedArgs(rest);
+    }
+
     if (command === 'close-session' || command === 'end-session') {
       return parseCloseSessionArgs(rest);
     }
@@ -223,6 +350,22 @@ export function parseCliArgs(argv) {
       return parseDocsReviewArgs(rest);
     }
 
+    if (command === 'push') {
+      return parsePushArgs(rest);
+    }
+
+    if (command === 'pull-preview') {
+      return parsePullPreviewArgs(rest);
+    }
+
+    if (command === 'pull-export') {
+      return parsePullExportArgs(rest);
+    }
+
+    if (command === 'apply-export') {
+      return parseApplyExportArgs(rest);
+    }
+
     return { command };
   }
 
@@ -448,6 +591,63 @@ function parseStartSessionArgs(argv) {
   };
 }
 
+function parseConnectHostedArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    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-api-url':
+        parsed.syncApiUrl = value;
+        break;
+      case '--sync-project-id':
+        parsed.syncProjectId = value;
+        break;
+      case '--sync-credential-env-var':
+        parsed.syncCredentialEnvVar = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  const syncValues = [
+    parsed.syncApiUrl,
+    parsed.syncProjectId,
+    parsed.syncCredentialEnvVar,
+  ].filter(Boolean);
+
+  return {
+    command: 'connect-hosted',
+    options: {
+      rootDir: parsed.rootDir,
+      ...(syncValues.length > 0
+        ? {
+            sync: {
+              apiUrl: parsed.syncApiUrl,
+              projectId: parsed.syncProjectId,
+              credentialEnvVar: parsed.syncCredentialEnvVar,
+            },
+          }
+        : {}),
+    },
+  };
+}
+
 function parseCloseSessionArgs(argv) {
   const parsed = {
     completed: [],
@@ -651,6 +851,11 @@ function parseDocsReviewArgs(argv) {
       continue;
     }
 
+    if (token === '--poll-hosted') {
+      parsed.pollHosted = true;
+      continue;
+    }
+
     if (token === '--complete') {
       parsed.complete = true;
       continue;
@@ -671,6 +876,16 @@ function parseDocsReviewArgs(argv) {
       continue;
     }
 
+    if (token === '--apply-decision-artifact') {
+      parsed.applyDecisionArtifact = true;
+      continue;
+    }
+
+    if (token === '--refresh-index') {
+      parsed.refreshIndex = true;
+      continue;
+    }
+
     if (!token.startsWith('--')) {
       throw new Error(`Unexpected argument "${token}".`);
     }
@@ -700,6 +915,9 @@ function parseDocsReviewArgs(argv) {
       case '--output':
         parsed.outputPath = value;
         break;
+      case '--artifact':
+        parsed.artifactId = value;
+        break;
       case '--max-tokens':
         parsed.maxTokens = value;
         break;
@@ -714,6 +932,151 @@ function parseDocsReviewArgs(argv) {
   };
 }
 
+function parsePushArgs(argv) {
+  return {
+    command: 'push',
+    options: parseRootOnlyArgs(argv, 'push'),
+  };
+}
+
+function parsePullPreviewArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--no-pending-proposals') {
+      parsed.includePendingProposals = false;
+      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;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return {
+    command: 'pull-preview',
+    options: parsed,
+  };
+}
+
+function parsePullExportArgs(argv) {
+  const parsed = {
+    proposalIds: [],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    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 '--preview-token':
+        parsed.previewToken = value;
+        break;
+      case '--proposal':
+        parsed.proposalIds.push(value);
+        break;
+      case '--output':
+        parsed.outputPath = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return {
+    command: 'pull-export',
+    options: parsed,
+  };
+}
+
+function parseApplyExportArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    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 '--output':
+        parsed.outputPath = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return {
+    command: 'apply-export',
+    options: parsed,
+  };
+}
+
+function parseRootOnlyArgs(argv, commandName) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    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;
+      default:
+        throw new Error(`Unknown flag "${token}" for ${commandName}.`);
+    }
+  }
+
+  return parsed;
+}
+
 function writeAgentFileSyncResult(io, result) {
   if (!result) {
     return;
@@ -746,12 +1109,17 @@ function usageText() {
   return [
     'Usage:',
     '  vibecompass init --name <project-name> --mode <local-only|local-primary|hosted-only> --repo <id=remote> [options]',
+    '  vibecompass connect-hosted [options]',
     '  vibecompass start-session --id <lane-id> --working-on <text> [options]',
     '  vibecompass close-session --title <text> --completed <text> --next-step <text> [options]',
     '  vibecompass end-session --title <text> --completed <text> --next-step <text> [options]  # alias',
     '  vibecompass list-sessions [options]',
     '  vibecompass switch-session <id> [options]',
     '  vibecompass sync-agents [options]',
+    '  vibecompass push [options]',
+    '  vibecompass pull-preview [options]',
+    '  vibecompass pull-export [options]',
+    '  vibecompass apply-export [options]',
     '  vibecompass docs-review --guided [options]',
     '',
     'Init options:',
@@ -777,6 +1145,13 @@ function usageText() {
     '  --close-session-git-remote <name>    Default Git remote name for that close-session publish step',
     '  --force                              Overwrite an existing project.yaml',
     '',
+    'Connect-hosted options:',
+    '  --root <path>                        Project-memory root. Defaults to .compass',
+    '  --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',
+    '                                        Replaces any existing project.yaml sync binding',
+    '',
     'Start-session options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --tooling-root <path>                Tooling root that contains CLAUDE.md. Defaults to cwd',
@@ -814,16 +1189,29 @@ function usageText() {
     '  --format <name>                      Optional format: claude_md, agents_md, cursor_rules, copilot_instructions',
     '  --dry-run                            Show planned writes without changing files',
     '',
+    'Sync transport options:',
+    '  push --root <path>                   Push canonical local project memory to hosted',
+    '  pull-preview --root <path>           Preview hosted proposals and remote state',
+    '  pull-preview --no-pending-proposals  Exclude pending proposals from preview',
+    '  pull-export --proposal <id>          Export a selected proposal; repeatable',
+    '  pull-export --preview-token <token>  Export from a specific preview token',
+    '  pull-export --output <path>          Output path under root; defaults to state/pull-export.json',
+    '  apply-export --output <path>         Apply exported bundle; defaults to state/pull-export.json',
+    '',
     'Docs-review options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --guided                             Accepted for the explicit comprehensive-review workflow',
     '  --submit-hosted                      Submit the generated review request to hosted sync',
+    '  --poll-hosted                        Poll hosted docs-review run status and update state/docs-review.json',
     '  --complete                           Mark accepted docs-review changes as completed locally',
     '  --run-local                          Run the generated review request with a local provider',
     '  --provider <name>                    Local provider for --run-local. Currently: anthropic',
     '  --run-local-anthropic                Compatibility alias for --run-local --provider anthropic',
     '  --apply-output                       Apply accepted architecture doc blocks from review output',
     '  --output <path>                      Review output path for --apply-output; defaults to state/docs-review-output.md',
+    '  --apply-decision-artifact            Append an accepted hosted decision artifact locally',
+    '  --artifact <id>                      Artifact ID for --apply-decision-artifact',
+    '  --refresh-index                      Also regenerate decisions/INDEX.md after applying a decision artifact',
     '  --llm <name>                         Preferred LLM/provider to run the external architecture review',
     '  --model <name>                       Model name to record for the review',
     '  --anthropic-env-var <name>           Env var to use for local Anthropic docs-review runtime',
@@ -839,6 +1227,14 @@ function createDefaultIo() {
   };
 }
 
+function formatOptionalRootFlag(rootDir) {
+  if (!rootDir || rootDir === '.compass') {
+    return '';
+  }
+
+  return ` --root ${rootDir}`;
+}
+
 async function main() {
   try {
     const exitCode = await runCli(process.argv.slice(2));