@vibecompass/vibecompass 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.9.2 - 2026-06-14
+
+- Clarify docs-review acceptance gates so agents state when no architecture docs have been applied yet and only report completion after apply succeeds.
+- Render local folder repo sources correctly in generated agent files instead of showing `null`.
+- Fix false agent-file drift in `status` after `sync-agents` when managed files are already current.
+
+## 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,69 @@ 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. If you run docs review, continue until either architecture docs are applied
+   or you are waiting for my explicit coverage-plan approval. Do not call docs
+   review done just because the marker was created.
+6. Tell me which files changed, whether docs were actually applied, and what I
+   should review next.
+
+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. If it asks you to approve a coverage plan, approve it or ask for changes;
+the package prints the output file and exact apply command after the accepted
+docs are ready.
+
+### 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 +87,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 +102,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 +120,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 +183,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 +199,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.2",
   "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`.',
@@ -1714,7 +1722,7 @@ function renderReviewPrompt(options) {
     '- Prioritize entry points, user-flow/gating relationships, data ownership, external integrations, jobs/async boundaries, auth/security boundaries, and test surfaces.',
     '- Mark each proposed doc as `comprehensive`, `partial`, or `initial`, with the reason and blindspots.',
     '- Emit the accepted plan as one `vibecompass-coverage-plan version=1` JSON fence before architecture-doc blocks.',
-    '- Ask for user acceptance before emitting fenced architecture-doc blocks.',
+    '- Ask for user acceptance before emitting fenced architecture-doc blocks. When you stop for acceptance, state plainly that no architecture docs have been applied yet.',
     '',
     'Stage 3 — Bounded doc generation:',
     '- Generate only accepted docs, one complete fenced block per architecture path.',
@@ -1724,8 +1732,10 @@ 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`.',
-    '- Surface any parser warnings, especially oversized docs, so the user can decide whether to compact or accept the 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.`,
+    '- Only report docs-review as applied after the apply command succeeds. Surface any parser warnings, especially oversized docs, so the user can decide whether to compact or accept the output.',
     '',
     '## Architecture Doc Contract',
     'When creating or updating architecture docs, use the existing VibeCompass structure:',
@@ -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/generators/agent-files/markers.js

@@ -46,7 +46,8 @@ export function applyManagedBlock(existingContent, generatedContent, options = {
   }
 
   const before = existingContent.slice(0, startIndex);
-  const after = existingContent.slice(endIndex + END_MARKER.length);
+  const rawAfter = existingContent.slice(endIndex + END_MARKER.length);
+  const after = rawAfter.trim() === '' ? '' : rawAfter;
   const beforeSeparator = before === '' || before.endsWith('\n') ? '' : '\n';
   const afterSeparator = after === '' || after.startsWith('\n') ? '' : '\n';
 

package/src/generators/agent-files/template.js

@@ -63,7 +63,7 @@ function renderProjectSnapshot(context) {
   }
 
   for (const repo of context.repos) {
-    lines.push(`- Repo \`${repo.id}\`: ${repo.remote}`);
+    lines.push(`- Repo \`${repo.id}\`: ${formatRepoDescriptor(repo)}`);
   }
 
   const domainCount = context.domains.length;
@@ -82,6 +82,18 @@ function renderProjectSnapshot(context) {
   return lines.length > 0 ? lines : ['- No project details recorded yet.'];
 }
 
+function formatRepoDescriptor(repo) {
+  if (repo?.source === 'local' || repo?.path) {
+    return `local folder ${repo.path ?? '.'}`;
+  }
+
+  if (repo?.remote) {
+    return repo.remote;
+  }
+
+  return 'source not recorded';
+}
+
 function renderDecisionLine(decision) {
   return `D-${String(decision.decision_id).padStart(3, '0')} — ${decision.title}`;
 }

package/src/scaffold.js

@@ -459,11 +459,11 @@ ${repoLines}
 }
 
 function formatRepoDescriptor(repo) {
-  if (repo.source === 'local') {
+  if (repo.source === 'local' || repo.path) {
     return `local folder ${repo.path}`;
   }
 
-  return repo.remote;
+  return repo.remote ?? 'source not recorded';
 }
 
 function generateArchitectureGuide(projectConfig) {

package/src/status.js

@@ -281,7 +281,7 @@ async function readAgentFileStatus(rootDir, toolingRootDir) {
       results: result.results.map((item) => ({
         format: item.format,
         relativePath: item.relativePath,
-        status: item.status,
+        status: item.changed || item.warning ? item.status : 'current',
         warning: item.warning,
         changed: item.changed,
         conflicts: item.conflicts ?? [],

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 --output ${outputPath}`;
+  const npxApplyCommand = `npx -y @vibecompass/vibecompass@${PACKAGE_VERSION} docs-review --root ${rootRelativePath} --apply-output --output ${outputPath}`;
 
   return `# VibeCompass Workflow — docs review
 
@@ -109,11 +113,11 @@ Turn starter project memory into evidence-backed architecture docs under \`archi
    - produce a coverage plan before reading broad source bodies
    - read targeted source files only when the coverage plan needs evidence
 3. Run \`vibecompass docs-review --guided --llm <tool-name> --model <model-name>\` to record the review marker and print the canonical docs-review contract. Use the current AI tool name and model when known.
-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.
+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. If you stop here for user approval, state clearly that no architecture docs have been applied yet.
 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. Only report docs-review as applied after this command succeeds. 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