@vibecompass/vibecompass 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.9.1 - 2026-06-14
+
+- Make local docs-review prompts self-contained by printing the accepted output file, root-scoped apply command, and same-version `npx` fallback the agent should run after user acceptance.
+
 ## 0.9.0 - 2026-06-14
 
 - Add explicit local folder sources for non-Git projects: `project.yaml.repos[]` may use `source: local` plus `path`, and `init` accepts `--repo-local <id=path>`.

package/README.md

@@ -16,32 +16,64 @@ Full docs: https://vibecompass.dev/developers
 
 ## Install
 
-Run without installing:
+Most people can run VibeCompass without installing it globally:
 
 ```bash
-npx -y @vibecompass/vibecompass --help
+npx -y @vibecompass/vibecompass@latest --help
 ```
 
-Or install in a project:
+Or install it globally if you want the shorter `vibecompass` command:
 
 ```bash
-npm install @vibecompass/vibecompass
+npm install -g @vibecompass/vibecompass@latest
 ```
 
 Requires Node.js 20+.
 
 ## Quick Start
 
-Create project memory:
+### Easiest path: ask your AI coding tool
+
+Open Claude Code, Codex, Cursor, or Copilot in the project folder you want
+VibeCompass to remember, then paste:
+
+```text
+VibeCompass is project memory for vibe coding. Use the npm package
+@vibecompass/vibecompass@latest.
+
+Please set it up in this project:
+1. Run the needed VibeCompass commands with npx.
+2. Initialize project memory with guided setup.
+3. If this folder is not a Git repo, use a local folder source.
+4. Start a named session lane for this setup work.
+5. Tell me which files changed and what I should review.
+
+Do not ask me to paste secret tokens into chat.
+```
+
+After setup, start a fresh AI session in the same project and type:
+
+```text
+docs review
+```
+
+That asks the AI to inspect your code and create the first real architecture
+docs. The package prints the output file and the exact apply command when the
+docs are ready for you to accept.
+
+### Terminal path
+
+Run this from your project folder:
 
 ```bash
-npx -y @vibecompass/vibecompass init --guided
+npx -y @vibecompass/vibecompass@latest init --guided
 ```
 
-For a folder that is not a Git repo, use an explicit local source:
+If the folder is not a Git repo, use a local folder source:
 
 ```bash
-npx -y @vibecompass/vibecompass init \
+npx -y @vibecompass/vibecompass@latest init \
+  --root .compass \
   --name "My Project" \
   --mode local-primary \
   --repo-local app=.
@@ -50,13 +82,13 @@ npx -y @vibecompass/vibecompass init \
 Check what to do next:
 
 ```bash
-npx -y @vibecompass/vibecompass status --root .compass
+npx -y @vibecompass/vibecompass@latest status --root .compass
 ```
 
 Start a builder session:
 
 ```bash
-npx -y @vibecompass/vibecompass start-session \
+npx -y @vibecompass/vibecompass@latest start-session \
   --root .compass \
   --id feature-lane \
   --working-on "Build the next feature"
@@ -65,13 +97,13 @@ npx -y @vibecompass/vibecompass start-session \
 Generate evidence-backed architecture docs:
 
 ```bash
-npx -y @vibecompass/vibecompass docs-review --root .compass --guided
+npx -y @vibecompass/vibecompass@latest docs-review --root .compass --guided
 ```
 
 Close the session:
 
 ```bash
-npx -y @vibecompass/vibecompass close-session \
+npx -y @vibecompass/vibecompass@latest close-session \
   --root .compass \
   --session feature-lane \
   --title "Feature Lane" \
@@ -83,25 +115,25 @@ npx -y @vibecompass/vibecompass close-session \
 
 ```bash
 # Create or inspect project memory
-vibecompass init --guided
-vibecompass status --root .compass
+npx -y @vibecompass/vibecompass@latest init --guided
+npx -y @vibecompass/vibecompass@latest status --root .compass
 
 # Session workflow
-vibecompass start-session --root .compass --id auth-flow --working-on "Auth flow"
-vibecompass list-sessions --root .compass
-vibecompass switch-session auth-flow --root .compass
-vibecompass close-session --root .compass --session auth-flow --title "Auth Flow" --completed "Built auth" --next-step "Review"
+npx -y @vibecompass/vibecompass@latest start-session --root .compass --id auth-flow --working-on "Auth flow"
+npx -y @vibecompass/vibecompass@latest list-sessions --root .compass
+npx -y @vibecompass/vibecompass@latest switch-session auth-flow --root .compass
+npx -y @vibecompass/vibecompass@latest close-session --root .compass --session auth-flow --title "Auth Flow" --completed "Built auth" --next-step "Review"
 
 # Agent instruction files
-vibecompass sync-agents --root .compass
+npx -y @vibecompass/vibecompass@latest sync-agents --root .compass
 
 # Architecture docs review
-vibecompass docs-review --root .compass --guided
-vibecompass docs-review --root .compass --apply-output
+npx -y @vibecompass/vibecompass@latest docs-review --root .compass --guided
+npx -y @vibecompass/vibecompass@latest docs-review --root .compass --apply-output
 
 # Rerun docs review from an archived architecture-doc slate
-vibecompass docs-review --root .compass --rebuild --path architecture
-vibecompass docs-review --root .compass --rebuild --apply --stale-policy archive --path architecture
+npx -y @vibecompass/vibecompass@latest docs-review --root .compass --rebuild --path architecture
+npx -y @vibecompass/vibecompass@latest docs-review --root .compass --rebuild --apply --stale-policy archive --path architecture
 ```
 
 ## What It Creates
@@ -146,13 +178,13 @@ Use hosted sync when you want browser review, team workflows, or hosted
 docs-review proposals:
 
 ```bash
-vibecompass connect-hosted \
+npx -y @vibecompass/vibecompass@latest connect-hosted \
   --root .compass \
   --sync-api-url https://vibecompass.dev \
   --sync-project-id vc_proj_example \
   --sync-credential-env-var VIBECOMPASS_SYNC_TOKEN
 
-vibecompass push --root .compass
+npx -y @vibecompass/vibecompass@latest push --root .compass
 ```
 
 ### Multiple environments
@@ -162,16 +194,16 @@ production) so you never have to rebind:
 
 ```bash
 # add targets once — the first one becomes the default
-vibecompass connect-hosted --root .compass --target dev \
+npx -y @vibecompass/vibecompass@latest connect-hosted --root .compass --target dev \
   --sync-api-url http://localhost:3000 --sync-project-id vc_proj_dev \
   --sync-credential-env-var VIBECOMPASS_SYNC_TOKEN
-vibecompass connect-hosted --root .compass --target prod \
+npx -y @vibecompass/vibecompass@latest connect-hosted --root .compass --target prod \
   --sync-api-url https://vibecompass.dev --sync-project-id vc_proj_prod \
   --sync-credential-env-var VIBECOMPASS_SYNC_TOKEN_PROD
 
 # then pick per command, or switch the default
-vibecompass push --root .compass --sync-target prod
-vibecompass sync-target prod --root .compass
+npx -y @vibecompass/vibecompass@latest push --root .compass --sync-target prod
+npx -y @vibecompass/vibecompass@latest sync-target prod --root .compass
 ```
 
 Tip: if you already have a single (flat) binding, add it as your first named

package/package.json

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

package/src/docs-review.js

@@ -6,6 +6,7 @@ import { sha256Text } from './hash.js';
 import { writeStateManifest } from './manifest.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 import { readSyncCursor, resolveSyncBinding } from './sync-binding.js';
+import { PACKAGE_VERSION } from './version.js';
 
 const DOCS_REVIEW_PROMPT_VERSION = 'VibeCompass Docs Review Prompt v3';
 const ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES = 12000;
@@ -1683,6 +1684,10 @@ function renderApplyOutputMessage(options) {
 }
 
 function renderReviewPrompt(options) {
+  const outputPath = path.join(options.rootDir, 'state', 'docs-review-output.md');
+  const applyCommand = `vibecompass docs-review --root ${shellQuote(options.rootDir)} --apply-output --output ${shellQuote(outputPath)}`;
+  const npxApplyCommand = `npx -y @vibecompass/vibecompass@${PACKAGE_VERSION} docs-review --root ${shellQuote(options.rootDir)} --apply-output --output ${shellQuote(outputPath)}`;
+
   return [
     `# ${DOCS_REVIEW_PROMPT_VERSION}`,
     '',
@@ -1694,6 +1699,9 @@ function renderReviewPrompt(options) {
     `- Project mode: ${options.project.mode}`,
     `- Review provider to record: ${options.llm}`,
     `- Review model/version to record: ${options.model}`,
+    `- Accepted output file: ${outputPath}`,
+    `- Apply command after user acceptance: ${applyCommand}`,
+    `- Apply command if the CLI is not installed on PATH: ${npxApplyCommand}`,
     '',
     '## Required Inputs',
     '1. Read `project.yaml`.',
@@ -1724,7 +1732,9 @@ function renderReviewPrompt(options) {
     '- Include only the most important involved files; prefer representative entry points and owned contracts over exhaustive file lists.',
     '',
     'Stage 4 — Apply and verify:',
-    '- After accepted blocks are written to `state/docs-review-output.md`, run `vibecompass docs-review --apply-output`.',
+    `- After the user accepts Stage 2, write the complete accepted fenced output verbatim to \`${outputPath}\`.`,
+    `- Then run \`${applyCommand}\` to validate and apply the accepted blocks.`,
+    `- If \`vibecompass\` is not installed on PATH, run \`${npxApplyCommand}\` instead.`,
     '- Surface any parser warnings, especially oversized docs, so the user can decide whether to compact or accept the output.',
     '',
     '## Architecture Doc Contract',
@@ -1832,10 +1842,14 @@ function renderReviewPrompt(options) {
     '**Context:** Optional supporting context.',
     '```',
     '',
-    'Only include accepted coverage, architecture, and decision-recommendation blocks. After accepted output is applied, `vibecompass docs-review --apply-output` records completion in `state/docs-review.json`.',
+    `Only include accepted coverage, architecture, and decision-recommendation blocks. After user acceptance, save the final accepted output to \`${outputPath}\`, run \`${applyCommand}\` or \`${npxApplyCommand}\`, and report applied paths plus parser warnings.`,
   ].join('\n');
 }
 
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
 function ensureTrailingNewline(value) {
   return value.endsWith('\n') ? value : `${value}\n`;
 }

package/src/workflows/registry.js

@@ -1,3 +1,5 @@
+import { PACKAGE_VERSION } from '../version.js';
+
 export const WORKFLOW_REGISTRY = [
   {
     id: 'session-lifecycle',
@@ -88,6 +90,8 @@ function renderDocsReviewWorkflow(options = {}) {
   const decisionsPath = joinRootRelative(rootRelativePath, 'decisions/');
   const sessionsPath = joinRootRelative(rootRelativePath, 'sessions/');
   const outputPath = joinRootRelative(rootRelativePath, 'state/docs-review-output.md');
+  const applyCommand = `vibecompass docs-review --root ${rootRelativePath} --apply-output`;
+  const npxApplyCommand = `npx -y @vibecompass/vibecompass@${PACKAGE_VERSION} docs-review --root ${rootRelativePath} --apply-output`;
 
   return `# VibeCompass Workflow — docs review
 
@@ -112,8 +116,8 @@ Turn starter project memory into evidence-backed architecture docs under \`archi
 4. Present the evidence inventory, coverage plan, user journey, project/system map, proposed architecture docs, blindspots, token-budget risks, and any decision candidates before generating accepted output.
 5. Draft only output the user accepts. The accepted plan must be fenced as \`vibecompass-coverage-plan version=1\`. Accepted architecture docs must be fenced as \`vibecompass-architecture-doc path=architecture/domain/feature/component.md\` blocks and must include required frontmatter: \`domain\`, \`feature\`, \`component\`, and \`status\`. The accepted \`architecture/overview/project-shape.md\` doc should include exactly one \`vibecompass-project-map version=1\` JSON block with journey-facing features, entry points, and evidence-backed relationships. Accepted local decisions may be fenced as \`vibecompass-decision-recommendation target=decisions/domain.md\` blocks without D-numbers.
 6. Keep each generated architecture doc focused and retrieval-oriented. Soft budget: under 12000 bytes per doc unless the extra detail is necessary and called out in review metadata or retrieval guidance.
-7. Write the accepted fenced blocks to \`${outputPath}\`.
-8. Run \`vibecompass docs-review --apply-output\` to validate and apply the accepted blocks. If accepted docs were written manually outside the output file, run \`vibecompass docs-review --complete\` after confirming the marker should be completed.
+7. Write the accepted fenced blocks verbatim to \`${outputPath}\`.
+8. Run \`${applyCommand}\` to validate and apply the accepted blocks. If \`vibecompass\` is not installed on PATH, run \`${npxApplyCommand}\` instead. If accepted docs were written manually outside the output file, run \`vibecompass docs-review --root ${rootRelativePath} --complete\` after confirming the marker should be completed.
 9. Run \`vibecompass status\` to confirm the docs-review marker is complete and not drifted. Report the applied architecture paths, coverage projection, decision recommendations, parser warnings such as oversized docs or missing review metadata, and any blindspots documented in the accepted docs-review output.
 
 ## Rebuild option