@vibecompass/vibecompass 0.2.1 → 0.3.1

package/README.md

@@ -12,19 +12,28 @@ Shipped today:
 
 - `vibecompass init` for scaffolding a project-memory root
 - interactive guided init for placement, workflow bootstrap, and first-session setup
+- lightweight starter architecture/session memory plus example-only decision guidance
 - generated `context.md` plus opt-in workflow guide files
 - opt-in starter `CLAUDE.md` / `AGENTS.md` templates that are created once and never overwritten
 - `vibecompass start-session` / `vibecompass close-session` for lane-aware local builder workflow
 - `vibecompass list-sessions` / `vibecompass switch-session` for multiple active session lanes
 - `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 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
 - canonical file scanning and validation
 - `state/manifest.json` generation
 - JavaScript read-model helpers for project, feature, decision, and file context
 
 Not shipped yet:
 
-- hosted sync commands such as push, pull-preview, and pull-export
+- hosted sync commands (push, pull-preview, pull-export)
+- hosted docs-review execution that runs the review and writes canonical docs
+- additional local docs-review providers beyond Anthropic
+- automatic acceptance of review findings without a local apply step
 
 The package is publishable now as the file-contract and read-model core. The
 broader local-primary sync workflow is still being built on top of it.
@@ -59,9 +68,9 @@ npx -y @vibecompass/vibecompass init --guided
 ```
 
 Guided init asks about repo topology, recommends a placement pattern
-(`workspace-root`, `dedicated-memory-repo`, or `primary-repo`), scaffolds the
-workflow files you opt into, and can open the first builder session
-immediately.
+(`workspace-root`, `dedicated-memory-repo`, or `primary-repo`), writes
+lightweight starter project memory, scaffolds the workflow files you opt into,
+and can open the first builder session immediately.
 
 When the owner directory is a workspace root or primary repo, the canonical
 root defaults to `.compass/` inside that directory. For a dedicated memory repo,
@@ -86,7 +95,22 @@ npx -y @vibecompass/vibecompass init \
   --session-working-on "Validate the local-first MCP workflow"
 ```
 
-That creates the canonical root plus, when workflow scaffolding is enabled:
+That creates the canonical root plus lightweight starter memory:
+
+```text
+PROJECT_MEMORY_ROOT/project.yaml
+PROJECT_MEMORY_ROOT/architecture/overview/project-shape.md
+PROJECT_MEMORY_ROOT/decisions/EXAMPLE.md      # example-only, ignored by canonical parsing
+PROJECT_MEMORY_ROOT/sessions/YYYY-MM-DD-1-project-memory-initialized.md
+PROJECT_MEMORY_ROOT/state/manifest.json
+```
+
+The starter architecture doc is intentionally marked as initial scaffold
+coverage. It is useful orientation, not a comprehensive review. Before risky
+implementation work, inspect the relevant code and replace or expand the
+starter docs with evidence-backed domain/feature/component docs.
+
+When workflow scaffolding is enabled, init also creates:
 
 ```text
 PROJECT_MEMORY_ROOT/context.md
@@ -100,6 +124,55 @@ AGENTS.md           # at the tooling root, only if missing and --with-agents is
 `context.md` is a derived package-owned file. Re-running `init --force --with-workflow`
 regenerates it; do not treat it as a hand-edited source document.
 
+## After init: generate real architecture docs
+
+`init` writes a small starter map of your project. To turn it into real
+architecture docs, run a docs-review and let your AI tool write them:
+
+```bash
+npx -y @vibecompass/vibecompass docs-review --guided
+```
+
+You can run this right after `init`, or any time later — for example after
+scope expands, or before risky implementation work. `start-session` will
+remind you with a non-blocking warning if no completed review exists.
+
+What happens:
+
+1. The CLI asks which LLM you'll use, then prints a versioned prompt template with fixed review criteria.
+2. You paste that prompt into your AI tool (Claude Code, Codex, Cursor, etc.).
+3. The AI reads your repo and writes architecture docs under
+   `architecture/<domain>/<feature>/<component>.md`.
+4. Run `vibecompass docs-review --apply-output` after accepting fenced
+   architecture-doc blocks, or `--complete` if accepted docs were written
+   manually.
+
+The guided prompt is deterministic apart from project-specific fields
+(`project`, `mode`, `root`, provider, and model). It uses the same structure
+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.
+
+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. 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`.
+- `--apply-output` writes accepted fenced architecture-doc blocks from
+  `state/docs-review-output.md` into canonical `architecture/` docs and
+  completes the local review marker.
+
+For most users, stick with `--guided`.
+
 If you do not chain straight into a first session from `init`, open one later:
 
 ```bash
@@ -172,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 \
@@ -198,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
 
@@ -225,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
@@ -244,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
@@ -265,6 +373,10 @@ This command updates the `Current session` block in `CLAUDE.md` and creates
 `sessions/active/<lane-id>/session.yaml`, `wip.md`, and `handoff.md` for the
 next session number. It also updates `sessions/active/index.yaml`.
 
+If no completed docs-review marker exists under `state/docs-review.json`,
+`start-session` prints a non-blocking warning that starter docs are not a
+comprehensive architecture review.
+
 ### `vibecompass list-sessions`
 
 ```text
@@ -332,6 +444,74 @@ memory. It creates missing files with managed markers, replaces existing
 managed regions, preserves content outside markers, and warns instead of
 overwriting existing unmarked files.
 
+### `vibecompass docs-review`
+
+```text
+vibecompass docs-review --guided [options]
+```
+
+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
+- `--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`
+- `--complete`: mark accepted docs-review changes as completed in local state
+- `--llm <name>`: preferred LLM/provider to record for the review (e.g. `claude`, `codex`, `gemini`)
+- `--model <name>`: model name/version to record for the review
+- `--anthropic-env-var <name>`: env var for local Anthropic runtime; defaults to `ANTHROPIC_API_KEY`
+- `--max-tokens <number>`: local Anthropic output budget, 1024–32000; defaults to 16000
+
+Plain `--guided` does not call an AI itself; it prints a review prompt your
+chosen LLM runs. `--submit-hosted`, `--run-local`, and `--apply-output` are
+explicit alternative steps.
+
+Project-mode requirements:
+
+- `local-only` — `--guided` can use any external LLM; `--run-local` requires a supported local provider key
+- `local-primary` — hosted sync binding preferred for hosted submission; local provider key accepted for `--run-local`
+- `hosted-only` — hosted sync binding required
+
+`--run-local --provider anthropic` always uses local Anthropic regardless of
+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`. 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`.
+
+`--apply-output` looks for accepted architecture docs in fenced blocks:
+
+````md
+```vibecompass-architecture-doc path=architecture/domain/feature/component.md
+---
+domain: Platform
+feature: Example
+component: Backend
+status: In progress
+---
+
+## Description
+Accepted review content.
+```
+````
+
+Only `architecture/*.md` paths are writable through this apply step.
+
+`vibecompass docs-review --complete` updates the marker in
+`state/docs-review.json` to `status: "completed"` once the docs have
+landed, preserving the recorded `llm` / `model` so future sessions know
+what reviewed the architecture.
+
 ### Prompt commands
 
 These are the default prompt commands used by the scaffolded workflow files:
@@ -340,19 +520,22 @@ These are the default prompt commands used by the scaffolded workflow files:
 - `join as reviewer`: reviewer role trigger
 - `review handoff`: reviewer reads the selected lane's latest `wip.md`, `handoff.md`, latest finalized note, and relevant diffs before appending findings
 - `address review`: builder reads the latest reviewer feedback in the selected lane's `wip.md` / `handoff.md`, responds inline, applies accepted changes, and refreshes the builder handoff
+- `close session`: builder runs the close-out checklist and ends with `vibecompass close-session --session <lane-id>`; `end session` is accepted as a synonym
 
 They are prompt commands for AI-tool behavior, not package CLI commands.
 Reviewer handback ends when the reviewer has updated the selected lane's
 `wip.md` and `handoff.md`; there is no extra reviewer-exit step. The builder
 remains in builder role, uses `address review` until findings are resolved or
-explicitly deferred, and then runs `vibecompass close-session --session
-<lane-id>` using the workflow defaults recorded in `project.yaml`.
+explicitly deferred, and then uses the `close session` prompt to run
+`vibecompass close-session --session <lane-id>` using the workflow defaults
+recorded in `project.yaml`.
 
 ## JavaScript API
 
 ```js
 import {
   initializeProjectMemory,
+  preflightDocsReview,
   startProjectSession,
   closeProjectSession,
   syncAgentInstructionFiles,

package/package.json

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