@vibecompass/vibecompass 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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>`.
+- Keep blank Git remotes invalid, but report an actionable `--repo-local` hint when `--repo <id=remote>` resolves to an empty value.
+- Update guided init, starter docs, status, scanning, and read-model output so local-source roots validate and render cleanly.
+- Bump docs-review to `VibeCompass Docs Review Prompt v3`, requiring first-pass docs to include a user journey, project/system map, and core journey-facing feature summaries.
+- Add `vibecompass-project-map version=1` support inside `architecture/overview/project-shape.md`, including nested-fence parsing so generated overview docs can round-trip the machine-readable journey map block.
+
 ## 0.8.0 - 2026-06-12
 
 - Add named sync targets (D-236): `connect-hosted --target <name>` binds one project root to multiple hosted environments (for example `dev` on localhost and `prod` on vibecompass.dev).

package/README.md

@@ -16,38 +16,79 @@ 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
+```
+
+If the folder is not a Git repo, use a local folder source:
+
+```bash
+npx -y @vibecompass/vibecompass@latest init \
+  --root .compass \
+  --name "My Project" \
+  --mode local-primary \
+  --repo-local app=.
 ```
 
 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"
@@ -56,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" \
@@ -74,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
@@ -137,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
@@ -153,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.8.0",
+  "version": "0.9.1",
   "description": "Local-first project-memory core for VibeCompass",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -568,6 +568,11 @@ export function parseCliArgs(argv) {
         parsed.repos.push({ id, remote });
         break;
       }
+      case '--repo-local': {
+        const [id, repoPath] = splitAssignment(value, '--repo-local');
+        parsed.repos.push({ id, source: 'local', path: repoPath });
+        break;
+      }
       case '--repo-branch': {
         const [id, defaultBranch] = splitAssignment(value, '--repo-branch');
         parsed.repoBranches.set(id, defaultBranch);
@@ -1461,6 +1466,11 @@ function writeWarnings(io, warnings = []) {
 function splitAssignment(value, flagName) {
   const separatorIndex = value.indexOf('=');
   if (separatorIndex <= 0 || separatorIndex === value.length - 1) {
+    if (flagName === '--repo' && separatorIndex > 0 && separatorIndex === value.length - 1) {
+      throw new Error(
+        '--repo remote resolved to empty. For a non-Git folder, use --repo-local <id=path> instead of --repo <id=remote>.',
+      );
+    }
     throw new Error(`${flagName} expects id=value.`);
   }
 
@@ -1495,7 +1505,8 @@ function usageText() {
     '  --placement <workspace-root|dedicated-memory-repo|primary-repo>',
     '                                        Optional explicit placement pattern',
     '  --guided                             Ask placement and setup questions interactively',
-    '  --repo <id=remote>                   Repeatable repo descriptor',
+    '  --repo <id=remote>                   Repeatable Git-backed repo descriptor',
+    '  --repo-local <id=path>               Repeatable local folder source for non-Git projects',
     '  --repo-branch <id=branch>            Optional per-repo default branch',
     '  --sync-api-url <url>                 Optional hosted sync api_url',
     '  --sync-project-id <id>               Optional hosted sync project_id',

package/src/docs-review.js

@@ -6,8 +6,9 @@ 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 v2';
+const DOCS_REVIEW_PROMPT_VERSION = 'VibeCompass Docs Review Prompt v3';
 const ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES = 12000;
 const COVERAGE_PLAN_OUTPUT_VERSION = 1;
 const COVERAGE_PLAN_STATUSES = new Set(['accepted', 'deferred', 'missing']);
@@ -785,13 +786,13 @@ function extractAnthropicText(body) {
 
 function parseArchitectureDocBlocks(source) {
   const blocks = [];
-  const pattern = /^```vibecompass-architecture-doc\s+path=([^\s`]+)\s*\n([\s\S]*?)^```[ \t]*$/gm;
+  const pattern = /^(`{3,})vibecompass-architecture-doc\s+path=([^\s`]+)\s*\n([\s\S]*?)^\1[ \t]*$/gm;
   let match;
 
   while ((match = pattern.exec(source)) !== null) {
     blocks.push({
-      path: normalizeBlockPath(match[1]),
-      content: match[2].replace(/\n$/, ''),
+      path: normalizeBlockPath(match[2]),
+      content: match[3].replace(/\n$/, ''),
     });
   }
 
@@ -829,8 +830,8 @@ function parseDecisionRecommendationBlocks(source) {
 }
 
 function countMalformedArchitectureDocFences(source) {
-  const fencePattern = /^```vibecompass-architecture-doc\b.*$/gm;
-  const acceptedOpeningPattern = /^```vibecompass-architecture-doc\s+path=[^\s`]+\s*$/;
+  const fencePattern = /^`{3,}vibecompass-architecture-doc\b.*$/gm;
+  const acceptedOpeningPattern = /^`{3,}vibecompass-architecture-doc\s+path=[^\s`]+\s*$/;
   let count = 0;
   let match;
 
@@ -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`.',
@@ -1705,24 +1713,28 @@ function renderReviewPrompt(options) {
     'Stage 1 — Evidence inventory:',
     '- Build a compact repo inventory from file paths, manifests/config files, route/job/test directories, and existing architecture frontmatter before reading large file bodies.',
     '- Mine finalized session notes for decision candidates and product constraints, but cap proposed decisions to the five highest-value architecture choices.',
-    '- Identify candidate domains, features, components, and ownership boundaries with concrete `repo:path` evidence.',
+    '- Identify candidate domains, features, components, ownership boundaries, user journey entry points, feature-to-feature relationships, and system-layer connections with concrete `repo:path` evidence.',
     '- Do not fetch or summarize broad source bodies until the coverage plan says a file is needed.',
     '',
     'Stage 2 — Coverage plan:',
     '- Propose the smallest useful architecture-doc set that will let future agents understand the project and retrieve targeted context.',
-    '- Prioritize entry points, data ownership, external integrations, jobs/async boundaries, auth/security boundaries, and test surfaces.',
+    '- The minimum useful set must cover: user journey, project/system map (frontend/backend/API/data/integration structure and connections), and summaries of the core journey-facing features.',
+    '- 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.',
     '',
     'Stage 3 — Bounded doc generation:',
     '- Generate only accepted docs, one complete fenced block per architecture path.',
+    '- Ensure `architecture/overview/project-shape.md` includes a concise system map plus one `vibecompass-project-map version=1` JSON fence that lists journey-facing features and supported relationships.',
     '- Keep docs concise and retrieval-oriented: explain contracts, flows, invariants, and ownership; do not rewrite source code or produce file-by-file walkthroughs.',
     `- Soft size budget: keep each generated architecture doc under ${ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES} bytes unless the extra detail is necessary and called out in Blindspots or Retrieval guidance.`,
     '- 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',
@@ -1746,18 +1758,46 @@ function renderReviewPrompt(options) {
     '',
     '## Review Rules',
     '1. Do not delete `architecture/overview/project-shape.md`.',
-    '2. Add evidence-backed component docs alongside the overview.',
-    '3. Update `architecture/overview/project-shape.md` coverage and blindspot sections to summarize what has now been mapped.',
-    '4. Keep all implementation claims source-backed with `repo:path` evidence.',
-    '5. Use only the exact confidence and coverage enum values listed above.',
-    '6. Put uncertainty in `Blindspots`; do not fill gaps with guesses.',
-    '7. Do not append real `D-NNN` decisions without explicit user acceptance. Propose candidate decisions separately.',
-    '8. Do not edit `decisions/INDEX.md` directly unless a canonical decision file was explicitly accepted and appended.',
-    '9. Optimize for future retrieval: project-level docs stay compact; component docs carry focused context for a specific area.',
+    '2. Add or update `architecture/overview/project-shape.md` so it explains the project/system map and includes the accepted `vibecompass-project-map version=1` block.',
+    '3. Add evidence-backed component docs alongside the overview for core journey-facing features and important supporting systems.',
+    '4. Update `architecture/overview/project-shape.md` coverage and blindspot sections to summarize what has now been mapped.',
+    '5. Keep all implementation claims source-backed with `repo:path` evidence.',
+    '6. Use only the exact confidence and coverage enum values listed above.',
+    '7. Put uncertainty in `Blindspots`; do not fill gaps with guesses.',
+    '8. Do not append real `D-NNN` decisions without explicit user acceptance. Propose candidate decisions separately.',
+    '9. Do not edit `decisions/INDEX.md` directly unless a canonical decision file was explicitly accepted and appended.',
+    '10. Optimize for future retrieval: project-level docs stay compact; component docs carry focused context for a specific area.',
+    '',
+    '## Project Map Block',
+    'Include exactly one project-map block inside `architecture/overview/project-shape.md` when the user accepts journey/system mapping output:',
+    '',
+    '```vibecompass-project-map version=1',
+    '{',
+    '  "features": [',
+    '    {',
+    '      "domain": "Domain name matching architecture frontmatter",',
+    '      "feature": "Feature name matching architecture frontmatter",',
+    '      "is_entry_point": true,',
+    '      "summary": "Short user-facing feature summary"',
+    '    }',
+    '  ],',
+    '  "relationships": [',
+    '    {',
+    '      "from": { "domain": "Domain", "feature": "Feature" },',
+    '      "to": { "domain": "Domain", "feature": "Feature" },',
+    '      "kind": "gates | navigates_to | depends_on | writes_to",',
+    '      "label": "Short evidence-backed relationship label"',
+    '    }',
+    '  ]',
+    '}',
+    '```',
+    '',
+    'Only include relationships supported by evidence. Prefer `navigates_to` and `gates` for the main user journey; use `depends_on` and `writes_to` for supporting system relationships. If useful journey links cannot be inferred, state that as a coverage gap rather than inventing links.',
     '',
     '## Output Contract',
     'First provide a concise findings summary with:',
     '- mapped areas',
+    '- user journey and project/system map coverage',
     '- gaps/blindspots',
     '- evidence inventory summary',
     '- coverage plan and proposed architecture docs',
@@ -1791,6 +1831,8 @@ function renderReviewPrompt(options) {
     '<complete markdown file content>',
     '```',
     '',
+    'If the complete markdown file content contains its own fenced block, such as `vibecompass-project-map version=1`, use a longer outer fence for the architecture-doc block (for example four backticks) so the inner fence stays inside the document body.',
+    '',
     'If the review surfaced accepted decision candidates, output each candidate as a separate block without assigning a D-number:',
     '',
     '```vibecompass-decision-recommendation target=decisions/cross-cutting.md',
@@ -1800,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/init.js

@@ -257,13 +257,42 @@ function normalizeInitOptions(options) {
     }
     seenRepoIds.add(repo.id);
 
-    if (typeof repo.remote !== 'string' || repo.remote.trim() === '') {
-      throw new Error(`repo "${repo.id}" requires a non-empty remote.`);
+    const source = typeof repo.source === 'string' && repo.source.trim() !== ''
+      ? repo.source.trim()
+      : null;
+    const pathValue = typeof repo.path === 'string' && repo.path.trim() !== ''
+      ? repo.path.trim()
+      : null;
+    const remote = typeof repo.remote === 'string' ? repo.remote.trim() : '';
+
+    if (source && !['git', 'local'].includes(source)) {
+      throw new Error(`repo "${repo.id}" source must be git or local.`);
+    }
+
+    if (source === 'local' || (!source && !remote && pathValue)) {
+      if (!['local-only', 'local-primary'].includes(preparedOptions.mode)) {
+        throw new Error(`repo "${repo.id}" local sources are supported only in local-only or local-primary mode.`);
+      }
+
+      if (!pathValue) {
+        throw new Error(`repo "${repo.id}" source local requires a non-empty path.`);
+      }
+
+      return {
+        id: repo.id,
+        source: 'local',
+        path: pathValue,
+      };
+    }
+
+    if (!remote) {
+      throw new Error(`repo "${repo.id}" requires a non-empty remote, or use a local repo source with source: local and path.`);
     }
 
     return {
       id: repo.id,
-      remote: repo.remote,
+      ...(source === 'git' ? { source: 'git' } : {}),
+      remote,
       ...(repo.defaultBranch ? { default_branch: repo.defaultBranch } : {}),
     };
   });

package/src/project-memory.js

@@ -34,7 +34,7 @@ const KNOWN_PROJECT_FIELDS = new Set([
   'sync',
   'metadata',
 ]);
-const KNOWN_REPO_FIELDS = new Set(['id', 'remote', 'default_branch']);
+const KNOWN_REPO_FIELDS = new Set(['id', 'source', 'remote', 'path', 'default_branch']);
 const KNOWN_SYNC_FIELDS = new Set([
   'provider',
   'api_url',
@@ -278,8 +278,25 @@ function validateProjectData(data, relativePath) {
         repoIds.push(repo.id);
       }
 
-      if (typeof repo.remote !== 'string' || repo.remote.trim() === '') {
-        errors.push(createError(relativePath, 'project-invalid-repo-remote', `${prefix}.remote must be a non-empty string.`));
+      const source = typeof repo.source === 'string' && repo.source.trim() !== ''
+        ? repo.source.trim()
+        : null;
+      const remote = typeof repo.remote === 'string' ? repo.remote.trim() : '';
+      const sourcePath = typeof repo.path === 'string' ? repo.path.trim() : '';
+
+      if (source && !['git', 'local'].includes(source)) {
+        errors.push(createError(relativePath, 'project-invalid-repo-source', `${prefix}.source must be git or local.`));
+      }
+
+      if (source === 'local' || (!source && !remote && sourcePath)) {
+        if (!['local-only', 'local-primary'].includes(data.mode)) {
+          errors.push(createError(relativePath, 'project-invalid-repo-source', `${prefix}.source local is supported only when mode is local-only or local-primary.`));
+        }
+        if (!sourcePath) {
+          errors.push(createError(relativePath, 'project-invalid-repo-path', `${prefix}.path must be a non-empty string for local sources.`));
+        }
+      } else if (!remote) {
+        errors.push(createError(relativePath, 'project-invalid-repo-remote', `${prefix}.remote must be a non-empty string for Git-backed sources.`));
       }
     }
   }
@@ -336,10 +353,12 @@ function validateProjectData(data, relativePath) {
       repo_ids: repoIds,
       repos: Array.isArray(data.repos)
         ? data.repos
-            .filter((repo) => isPlainObject(repo) && typeof repo.id === 'string' && typeof repo.remote === 'string')
+            .filter((repo) => isPlainObject(repo) && typeof repo.id === 'string')
             .map((repo) => ({
               id: repo.id,
-              remote: repo.remote,
+              source: typeof repo.source === 'string' ? repo.source : (typeof repo.remote === 'string' ? 'git' : 'local'),
+              remote: typeof repo.remote === 'string' ? repo.remote : null,
+              path: typeof repo.path === 'string' ? repo.path : null,
               default_branch: typeof repo.default_branch === 'string' ? repo.default_branch : null,
             }))
         : [],

package/src/read-model.js

@@ -105,7 +105,9 @@ function buildProjectSummary(scanResult, currentManifest, freshness, existingMan
   const extracted = scanResult.project.extracted ?? {};
   const repos = (extracted.repos ?? []).map((repo) => ({
     id: repo.id,
+    source: repo.source,
     remote: repo.remote,
+    path: repo.path,
     default_branch: repo.default_branch,
   }));
 
@@ -451,10 +453,12 @@ function buildRepoAliasMap(repos) {
     aliases.set(repo.id, repo.id);
     aliases.set(repo.id.toLowerCase(), repo.id);
 
-    const remoteName = repo.remote
-      .replace(/\.git$/, '')
-      .split('/')
-      .pop();
+    const remoteName = typeof repo.remote === 'string'
+      ? repo.remote
+          .replace(/\.git$/, '')
+          .split('/')
+          .pop()
+      : null;
 
     if (remoteName) {
       aliases.set(remoteName, repo.id);

package/src/scaffold.js

@@ -206,7 +206,7 @@ function generateContextMarkdown(options) {
   const workflow = resolveWorkflowSettings(options.projectConfig);
   const promptCommands = renderPromptCommandLines({ rootRelativePath }).join('\n');
   const repos = options.projectConfig.repos
-    .map((repo) => `- \`${repo.id}\` → ${repo.remote}`)
+    .map((repo) => `- \`${repo.id}\` → ${formatRepoDescriptor(repo)}`)
     .join('\n');
 
   return `# Project Context — ${projectName}
@@ -348,7 +348,7 @@ automatically by package commands.
 function generateStarterArchitectureDoc(projectConfig) {
   const repos = projectConfig.repos.map((repo) => repo.id);
   const repoLines = projectConfig.repos
-    .map((repo) => `- \`${repo.id}\` — ${repo.remote}${repo.default_branch ? ` (${repo.default_branch})` : ''}`)
+    .map((repo) => `- \`${repo.id}\` — ${formatRepoDescriptor(repo)}${repo.default_branch ? ` (${repo.default_branch})` : ''}`)
     .join('\n');
   const repoEvidence = projectConfig.repos
     .map((repo) => `- \`${repo.id}:/\` — declared repository root`)
@@ -379,7 +379,7 @@ ${repoLines}
 ## Coverage
 Confirmed:
 - Project identity and mode from \`project.yaml\`
-- Declared repository IDs and remotes from \`project.yaml\`
+- Declared repository IDs and source descriptors from \`project.yaml\`
 - Project-memory root layout created by \`vibecompass init\`
 
 Not yet documented:
@@ -425,7 +425,7 @@ Do not copy this example as-is. Allocate real decision IDs from the current cano
 function generateStarterSessionNote(options) {
   const sessionDate = sessionDateFromGeneratedAt(options.generatedAt);
   const projectConfig = options.projectConfig;
-  const repoLines = projectConfig.repos.map((repo) => `- \`${repo.id}\` — ${repo.remote}`).join('\n');
+  const repoLines = projectConfig.repos.map((repo) => `- \`${repo.id}\` — ${formatRepoDescriptor(repo)}`).join('\n');
 
   return `# Session — ${sessionDate}-1 — Project Memory Initialized
 
@@ -458,6 +458,14 @@ ${repoLines}
 `;
 }
 
+function formatRepoDescriptor(repo) {
+  if (repo.source === 'local') {
+    return `local folder ${repo.path}`;
+  }
+
+  return repo.remote;
+}
+
 function generateArchitectureGuide(projectConfig) {
   return `# Architecture
 

package/src/setup.js

@@ -882,12 +882,13 @@ async function promptForRepos(prompter, cwd) {
 
   for (let index = 0; index < repoCount; index += 1) {
     const ordinal = index + 1;
-    const repo = {
-      id: await askInput(prompter, `Repo ${ordinal} id`, {
-        defaultValue: repoCount === 1 ? repoIdDefault : `repo-${ordinal}`,
-      }),
-      remote: await askInput(prompter, `Repo ${ordinal} remote`),
-    };
+    const repoId = await askInput(prompter, `Repo ${ordinal} id`, {
+      defaultValue: repoCount === 1 ? repoIdDefault : `repo-${ordinal}`,
+    });
+    const remote = await askOptionalInput(prompter, `Repo ${ordinal} remote (blank for local folder)`);
+    const repo = remote
+      ? { id: repoId, remote }
+      : { id: repoId, source: 'local', path: '.' };
 
     const defaultBranch = await askOptionalInput(prompter, `Repo ${ordinal} default branch`);
     if (defaultBranch) {

package/src/status.js

@@ -143,7 +143,9 @@ async function readProjectSummary(projectFilePath) {
             .filter((repo) => repo && typeof repo === 'object')
             .map((repo) => ({
               id: typeof repo.id === 'string' ? repo.id : null,
+              source: typeof repo.source === 'string' ? repo.source : (typeof repo.remote === 'string' ? 'git' : 'local'),
               remote: typeof repo.remote === 'string' ? repo.remote : null,
+              path: typeof repo.path === 'string' ? repo.path : null,
               defaultBranch: typeof repo.default_branch === 'string' ? repo.default_branch : null,
             }))
             .filter((repo) => repo.id)

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
 
@@ -99,7 +103,7 @@ When the user says \`docs review\`, run this workflow inside the current Claude
 
 ## Goal
 
-Turn starter project memory into evidence-backed architecture docs under \`architecture/<domain>/<feature>/<component>.md\`, a projected coverage plan, and optional accepted decision recommendations.
+Turn starter project memory into evidence-backed architecture docs under \`architecture/<domain>/<feature>/<component>.md\`, a projected coverage plan, a journey-aware project map, and optional accepted decision recommendations.
 
 ## Steps
 
@@ -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, 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\`. Accepted local decisions may be fenced as \`vibecompass-decision-recommendation target=decisions/domain.md\` blocks without D-numbers.
+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