@popoverai/dotrequirements 0.21.0 → 0.22.0

package/README.md

@@ -276,6 +276,14 @@ await finalize({ showTestedList: true }); // Include tested requirements
 await finalize({ showSummary: false, showUntestedList: false }); // Quiet mode
 ```
 
+**Attribution:** tag cloud coverage rows with the name of the framework that produced them:
+
+```typescript
+await finalize({ context: 'Vitest' });
+```
+
+The Coverage tab uses this label to show which tool produced each result. Any string works — useful when you have multiple test suites (`"Vitest — unit"`, `"Vitest — integration"`).
+
 By default, only untested requirements are shown. See the [test harness docs](https://docs.dotrequirements.io/tools/test-harness) for all options.
 
 ### Setup with Jest

package/dist/cli.js

@@ -90,6 +90,7 @@ program
     .description('Aggregate test tracking data and generate coverage report')
     .option('--push', 'Push coverage to DotRequirements Cloud')
     .option('-q, --quiet', 'Output only coverage percentage (for scripting)')
+    .option('--context <label>', 'Attribution label identifying the reporter (e.g. "Vitest", "pytest")')
     .action(wrapCommand(finalizeCommand));
 program
     .command('report')

package/dist/commands/finalize.d.ts

@@ -1,6 +1,7 @@
 interface FinalizeOptions {
     push?: boolean;
     quiet?: boolean;
+    context?: string;
 }
 export declare function finalizeCommand(options: FinalizeOptions): Promise<void>;
 export {};

package/dist/commands/finalize.js

@@ -31,6 +31,7 @@ export async function finalizeCommand(options) {
         showTestedList: true,
         showUntestedList: true,
         showCloudStatus: !options.quiet,
+        context: options.context,
     });
     if (options.quiet) {
         // In quiet mode, just output the coverage percent for scripting

package/dist/commands/mcp-setup.js

@@ -5,7 +5,7 @@ import { join } from 'path';
 import prompts from 'prompts';
 import { loadTemplate } from '../utils/templates.js';
 import { brand } from '../utils/brand.js';
-import { getContextFileName, getContextFilePath, findDotrequirementsSection, appendOrUpdateSection, } from '../utils/context-file.js';
+import { getContextFileName, findGitRoot, findDotrequirementsSection, appendOrUpdateSection, buildNoGitRepoMessage, } from '../utils/context-file.js';
 /**
  * Load the context file section template
  */
@@ -16,12 +16,17 @@ function loadContextFileSection() {
  * Install workflow guidance to the appropriate context file for a platform
  */
 async function installContextFileSection(platform) {
-    const contextFilePath = await getContextFilePath(platform);
-    if (!contextFilePath) {
-        console.error(`\n❌ Could not determine context file path for ${platform}`);
+    const fileName = getContextFileName(platform);
+    if (!fileName) {
+        console.error(`\n❌ Unknown platform: ${platform}`);
         return;
     }
-    const fileName = getContextFileName(platform);
+    const gitRoot = await findGitRoot();
+    if (!gitRoot) {
+        console.log('\n' + buildNoGitRepoMessage(fileName) + '\n');
+        return;
+    }
+    const contextFilePath = join(gitRoot, fileName);
     const sectionContent = loadContextFileSection();
     // Check if file exists and has existing section
     let existingSection = null;

package/dist/harness/cache.d.ts

@@ -39,17 +39,22 @@ export interface LookupCache {
 /**
  * Structure of the coverage.json cache (for cloud deduplication)
  */
+/** Attribution tuple used for debounce keying (COVERAGE-DEBOUNCE-2). */
+export interface CoverageTuple {
+    requirementKey: string;
+    context?: string;
+    branch?: string;
+}
+export interface CoverageCacheEntry {
+    testRunId: string;
+    timestamp: number;
+    tuples: CoverageTuple[];
+    /** Legacy field retained for backward-compat reads of pre-attribution caches. */
+    requirementKeys?: string[];
+}
 export interface CoverageCache {
-    current: {
-        testRunId: string;
-        timestamp: number;
-        requirementKeys: string[];
-    } | null;
-    previous: {
-        testRunId: string;
-        timestamp: number;
-        requirementKeys: string[];
-    } | null;
+    current: CoverageCacheEntry | null;
+    previous: CoverageCacheEntry | null;
 }
 /**
  * Find the nearest .requirements directory by walking up from startDir
@@ -123,16 +128,16 @@ export declare function readTrackingEntries(requirementsDir: string): TrackingEn
  * Delete the tracking file after finalize
  */
 export declare function deleteTrackingFile(requirementsDir: string): void;
-/**
- * Read the coverage cache for cloud deduplication
- */
 export declare function readCoverageCache(requirementsDir: string): CoverageCache;
 /**
- * Update the coverage cache after reporting
+ * Update the coverage cache after reporting. Accepts either attribution tuples
+ * (new) or bare requirement keys (legacy; converted to tuples with no context/branch).
  */
-export declare function updateCoverageCache(requirementsDir: string, testRunId: string, requirementKeys: string[]): void;
+export declare function updateCoverageCache(requirementsDir: string, testRunId: string, tuples: CoverageTuple[] | string[]): void;
+export declare const COVERAGE_DEBOUNCE_WINDOW_MS: number;
 /**
- * Check if a requirement needs reporting based on coverage cache
+ * Check if an attribution tuple needs reporting based on the coverage cache.
+ * Returns true if no matching tuple was reported within the debounce window.
  */
-export declare function needsReporting(requirementKey: string, cache: CoverageCache): boolean;
+export declare function needsReporting(tupleOrKey: CoverageTuple | string, cache: CoverageCache): boolean;
 //# sourceMappingURL=cache.d.ts.map

package/dist/harness/cache.js

@@ -288,6 +288,30 @@ export function deleteTrackingFile(requirementsDir) {
 /**
  * Read the coverage cache for cloud deduplication
  */
+/**
+ * Normalize a cache entry read from disk. Migrates legacy `requirementKeys`
+ * arrays into the tuple shape (context/branch undefined) so downstream code
+ * can treat both shapes uniformly.
+ */
+function normalizeEntry(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    if (Array.isArray(raw.tuples)) {
+        return {
+            testRunId: raw.testRunId,
+            timestamp: raw.timestamp,
+            tuples: raw.tuples,
+        };
+    }
+    if (Array.isArray(raw.requirementKeys)) {
+        return {
+            testRunId: raw.testRunId,
+            timestamp: raw.timestamp,
+            tuples: raw.requirementKeys.map((requirementKey) => ({ requirementKey })),
+        };
+    }
+    return null;
+}
 export function readCoverageCache(requirementsDir) {
     const cacheDir = getCacheDir(requirementsDir);
     const coveragePath = path.join(cacheDir, COVERAGE_FILE);
@@ -296,45 +320,58 @@ export function readCoverageCache(requirementsDir) {
     }
     try {
         const content = fs.readFileSync(coveragePath, 'utf-8');
-        return JSON.parse(content);
+        const raw = JSON.parse(content);
+        return {
+            current: normalizeEntry(raw?.current),
+            previous: normalizeEntry(raw?.previous),
+        };
     }
     catch {
         return { current: null, previous: null };
     }
 }
 /**
- * Update the coverage cache after reporting
+ * Update the coverage cache after reporting. Accepts either attribution tuples
+ * (new) or bare requirement keys (legacy; converted to tuples with no context/branch).
  */
-export function updateCoverageCache(requirementsDir, testRunId, requirementKeys) {
+export function updateCoverageCache(requirementsDir, testRunId, tuples) {
     const cacheDir = getCacheDir(requirementsDir, true);
     const coveragePath = path.join(cacheDir, COVERAGE_FILE);
+    const normalized = tuples.map((t) => typeof t === 'string' ? { requirementKey: t } : t);
     const existing = readCoverageCache(requirementsDir);
     const newCache = {
         current: {
             testRunId,
             timestamp: Date.now(),
-            requirementKeys,
+            tuples: normalized,
         },
         previous: existing.current,
     };
     fs.writeFileSync(coveragePath, JSON.stringify(newCache, null, 2));
 }
+export const COVERAGE_DEBOUNCE_WINDOW_MS = 4 * 60 * 60 * 1000; // 4 hours — must match server-side in testCoverage/mutations.ts
+function tuplesMatch(a, b) {
+    return (a.requirementKey === b.requirementKey &&
+        a.context === b.context &&
+        a.branch === b.branch);
+}
 /**
- * Check if a requirement needs reporting based on coverage cache
+ * Check if an attribution tuple needs reporting based on the coverage cache.
+ * Returns true if no matching tuple was reported within the debounce window.
  */
-export function needsReporting(requirementKey, cache) {
-    const STALENESS_THRESHOLD_MS = 4 * 60 * 60 * 1000; // 4 hours
+export function needsReporting(tupleOrKey, cache) {
+    const tuple = typeof tupleOrKey === 'string' ? { requirementKey: tupleOrKey } : tupleOrKey;
     // If no current run, everything needs reporting
     if (!cache.current) {
         return true;
     }
-    // If requirement wasn't in current run, it needs reporting
-    if (!cache.current.requirementKeys.includes(requirementKey)) {
+    // If the tuple wasn't in the current cached run, it needs reporting
+    if (!cache.current.tuples.some((t) => tuplesMatch(t, tuple))) {
         return true;
     }
     // If current run is stale (>4 hours old), needs reporting
     const age = Date.now() - cache.current.timestamp;
-    if (age > STALENESS_THRESHOLD_MS) {
+    if (age > COVERAGE_DEBOUNCE_WINDOW_MS) {
         return true;
     }
     // Otherwise, skip reporting (already reported recently)

package/dist/harness/finalize.d.ts

@@ -24,6 +24,11 @@ export interface FinalizeOptions {
     showUntestedList?: boolean;
     /** Whether to show cloud reporting status messages (defaults to true) */
     showCloudStatus?: boolean;
+    /**
+     * Attribution label identifying the reporter (e.g. "Vitest", "Jest", "pytest").
+     * When omitted, rows are recorded with context absent per COVERAGE-CONTEXT-1.2.
+     */
+    context?: string;
 }
 export interface FinalizeResult {
     /** Number of unique requirements exercised */

package/dist/harness/finalize.js

@@ -10,6 +10,7 @@
  * Implements: HARNESS-FINALIZE-1, HARNESS-FINALIZE-2, HARNESS-FINALIZE-3, HARNESS-FINALIZE-4
  */
 import { execSync } from 'child_process';
+import { randomUUID } from 'crypto';
 import { findRequirementsDir, findProjectRoot, getTestRunId, cleanupTestRunId, readTrackingEntries, deleteTrackingFile, readLookupCache, readCoverageCache, updateCoverageCache, needsReporting, } from './cache.js';
 import { getProjectInfo } from '../utils/project-settings.js';
 /**
@@ -40,6 +41,26 @@ function getCurrentBranch(cwd) {
         return 'unknown';
     }
 }
+/**
+ * Return the git-blame author email for a specific file:line, or undefined
+ * if unavailable (not a git repo, file untracked, git unavailable, etc.).
+ *
+ * COVERAGE-CONTEXT-2: "last reported by" attribution.
+ */
+function getLineAuthor(cwd, file, line) {
+    try {
+        const output = execSync(`git blame -L ${line},${line} --porcelain -- "${file}"`, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+        });
+        const match = output.match(/^author-mail\s+<([^>]+)>/m);
+        return match?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Print local coverage report to console
  *
@@ -112,7 +133,7 @@ const CONVEX_URL = 'https://data.dotrequirements.io';
  * HARNESS-FINALIZE-2: Cloud reporting with error tolerance
  * HARNESS-FINALIZE-3: Coverage records include requirement, file, line, branch
  */
-async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatus) {
+async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatus, context) {
     try {
         // Get project info from .requirements/project-settings.json
         const projectInfo = getProjectInfo(projectRoot);
@@ -125,24 +146,34 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
         }
         const { projectId, projectSecret } = projectInfo.credentials;
         const requirementsDir = findRequirementsDir(projectRoot);
-        // Get all tracked requirement keys
+        const branch = getCurrentBranch(projectRoot);
+        // Build the full set of tuples for this run, one per tracked requirement
         const requirementKeys = Array.from(aggregated.keys());
-        // Use coverage cache for deduplication
+        const allTuples = requirementKeys.map((key) => ({
+            requirementKey: key,
+            context,
+            branch,
+        }));
+        // Local debounce (COVERAGE-DEBOUNCE-1): only report tuples not recently cached.
+        // Server-side debounce is a backstop (COVERAGE-DEBOUNCE-4) — this layer just
+        // prevents unnecessary HTTP calls.
         const coverageCache = readCoverageCache(requirementsDir);
-        const keysToReport = requirementKeys.filter(key => needsReporting(key, coverageCache));
-        if (keysToReport.length === 0) {
+        const tuplesToReport = allTuples.filter((tuple) => needsReporting(tuple, coverageCache));
+        if (tuplesToReport.length === 0) {
             if (showCloudStatus) {
                 console.log('\n✓ Coverage unchanged since last run (skipping cloud report)');
             }
-            // Still update the cache
-            updateCoverageCache(requirementsDir, testRunId, requirementKeys);
+            // Still update the cache so the window continues tracking
+            updateCoverageCache(requirementsDir, testRunId, allTuples);
             return { sent: false, count: 0 };
         }
-        const branch = getCurrentBranch(projectRoot);
+        // Deterministic runId for this finalize invocation (COVERAGE-CONTEXT-4)
+        const runId = randomUUID();
+        // Cache git-blame lookups per file:line to avoid redundant subprocess spawns
+        const userCache = new Map();
         // Build coverage payload
-        // HARNESS-FINALIZE-3: Include requirement path, test file, line, branch
-        const coverage = keysToReport.map(key => {
-            const entries = aggregated.get(key);
+        const coverage = tuplesToReport.map((tuple) => {
+            const entries = aggregated.get(tuple.requirementKey);
             // Use the first access location
             const firstEntry = entries[0];
             const location = firstEntry.callerLocation;
@@ -159,10 +190,23 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
                     testFile = location;
                 }
             }
+            // COVERAGE-CONTEXT-2: git blame on the requirement() call line
+            let user;
+            if (testFile && testLine !== undefined) {
+                const cacheKey = `${testFile}:${testLine}`;
+                if (userCache.has(cacheKey)) {
+                    user = userCache.get(cacheKey);
+                }
+                else {
+                    user = getLineAuthor(projectRoot, testFile, testLine);
+                    userCache.set(cacheKey, user);
+                }
+            }
             return {
-                requirementKey: key,
+                requirementKey: tuple.requirementKey,
                 testFile,
                 testLine,
+                user,
             };
         });
         // Send to Convex
@@ -185,6 +229,8 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
                         slug: projectId,
                     },
                     branch,
+                    context,
+                    runId,
                     coverage,
                 },
                 format: 'json',
@@ -218,11 +264,11 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
             }
         }
         if (showCloudStatus) {
-            console.log(`\n✓ Reported ${keysToReport.length} requirement(s) to cloud (branch: ${branch})`);
+            console.log(`\n✓ Reported ${tuplesToReport.length} requirement(s) to cloud (branch: ${branch})`);
         }
-        // Update coverage cache
-        updateCoverageCache(requirementsDir, testRunId, requirementKeys);
-        return { sent: true, count: keysToReport.length };
+        // Update coverage cache with the full tuple set (includes those not reported this run)
+        updateCoverageCache(requirementsDir, testRunId, allTuples);
+        return { sent: true, count: tuplesToReport.length };
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
@@ -244,7 +290,7 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
  * HARNESS-FINALIZE-4: Finalize cleans up after itself
  */
 export async function finalize(options = {}) {
-    const { cwd = process.cwd(), reportToCloud: shouldReportToCloud = true, cleanup: shouldCleanup = true, showSummary = true, showTestedList = false, showUntestedList = true, showCloudStatus = true, } = options;
+    const { cwd = process.cwd(), reportToCloud: shouldReportToCloud = true, cleanup: shouldCleanup = true, showSummary = true, showTestedList = false, showUntestedList = true, showCloudStatus = true, context, } = options;
     // Priority 1: Use environment variable (cross-process persistence from globalSetup)
     let projectRoot = process.env.DOTREQUIREMENTS_PROJECT_ROOT || null;
     // Priority 2: Find from cwd
@@ -309,7 +355,7 @@ export async function finalize(options = {}) {
     // HARNESS-FINALIZE-2, HARNESS-FINALIZE-3: Report to cloud
     let cloudResult = { sent: false, count: 0 };
     if (shouldReportToCloud) {
-        cloudResult = await reportToConvex(projectRoot, testRunId, aggregated, showCloudStatus);
+        cloudResult = await reportToConvex(projectRoot, testRunId, aggregated, showCloudStatus, context);
     }
     // HARNESS-FINALIZE-4: Clean up tracking data
     if (shouldCleanup && !cloudResult.error) {

package/dist/templates/context-file-section.md

@@ -21,7 +21,7 @@ requirements, so your plan should too.
 ### Requirements Syntax
 
 ```dotrequirements
-REQ-ID: Short description of expected behavior
+DOMAIN-1: Short description of expected behavior
   0. -> First criterion or condition
   1. -> Second criterion
     1.0. -> Nested detail under second criterion
@@ -31,6 +31,7 @@ REQ-ID: Short description of expected behavior
 - Criteria: `position. -> content` (optional label before the arrow)
 - Nesting: Indent with 2 spaces, use `x.y` position paths
 - Delimiter: `->` or `→`
+- **Key style**: Use sequential keys with a short domain prefix (`ORCHESTRATOR-1`, `ORCHESTRATOR-2`, ...) rather than semantic keys (`AUTONOMOUS-ADVANCE`). Sequential keys stay stable when a requirement gets reworded, so test references don't break. Call `create_requirement_document` for full key-naming guidance.
 
 ### Test Usage
 

package/dist/templates/example-requirements.js

@@ -18,15 +18,15 @@ document:
 
 This file demonstrates the dotrequirements format. Feel free to edit or delete it.
 
-## HOW-TO: How to use dotrequirements
+## HOWTO-1: How to use dotrequirements
 
 \`\`\`dotrequirements
-HOW-TO: How to use dotrequirements
-  0. → Requirements live here and are referenced by index, like requirement('HOW-TO.0')
-  1. Labels → Anything before the arrow is a label. You can reference a requirement by its index or its label: requirement('HOW-TO.1') == requirement('HOW-TO.labels')
-  2. Labels → Repeated labels can be referenced sequentially: requirement('HOW-TO.labels#2')
-    2.0. Nesting → You can keep nesting. Label references don't need to be nested: requirement('HOW-TO.nesting').
-    2.1. Several words → Reference multi-word labels using kebab-case. Label references are never case sensitive: requirement('HOW-TO.several-words')
+HOWTO-1: How to use dotrequirements
+  0. → Requirements live here and are referenced by index, like requirement('HOWTO-1.0')
+  1. Labels → Anything before the arrow is a label. You can reference a requirement by its index or its label: requirement('HOWTO-1.1') == requirement('HOWTO-1.labels')
+  2. Labels → Repeated labels can be referenced sequentially: requirement('HOWTO-1.labels#2')
+    2.0. Nesting → You can keep nesting. Label references don't need to be nested: requirement('HOWTO-1.nesting').
+    2.1. Several words → Reference multi-word labels using kebab-case. Label references are never case sensitive: requirement('HOWTO-1.several-words')
   3. → While you _can_ write your requirements longhand in this format, there are a number of better ways.
     3.0. MCP → The dotrequirements MCP equips an AI assistant to develop requirements with you
     3.1. Your current tools → Dotrequirements has a composer for Jira, Confluence, and Notion
@@ -36,12 +36,12 @@ HOW-TO: How to use dotrequirements
 
 ---
 
-## USER-AUTH: User authentication flow
+## AUTH-1: User authentication flow
 
 **Implementation notes:** Use bcrypt for password hashing with work factor >= 12.
 
 \`\`\`dotrequirements
-USER-AUTH: User authentication flow
+AUTH-1: User authentication flow
   0. AC → Login form accepts email and password
   1. AC → Invalid credentials show error message
   2. Edge-case → Rate limiting after 5 failed attempts
@@ -71,11 +71,11 @@ import { requirement } from '@popoverai/dotrequirements/test';
 
 test('login with valid credentials', () => {
   // Reference by numeric path
-  const ac = requirement('USER-AUTH.0');
+  const ac = requirement('AUTH-1.0');
   // Returns: "AC: Login form accepts email and password"
 
   // Reference by label
-  const edgeCase = requirement('USER-AUTH.edge-case');
+  const edgeCase = requirement('AUTH-1.edge-case');
   // Returns: "Edge-case: Rate limiting after 5 failed attempts"
 
   // Your test implementation...

package/dist/templates/example-requirements.ts

@@ -19,15 +19,15 @@ document:
 
 This file demonstrates the dotrequirements format. Feel free to edit or delete it.
 
-## HOW-TO: How to use dotrequirements
+## HOWTO-1: How to use dotrequirements
 
 \`\`\`dotrequirements
-HOW-TO: How to use dotrequirements
-  0. → Requirements live here and are referenced by index, like requirement('HOW-TO.0')
-  1. Labels → Anything before the arrow is a label. You can reference a requirement by its index or its label: requirement('HOW-TO.1') == requirement('HOW-TO.labels')
-  2. Labels → Repeated labels can be referenced sequentially: requirement('HOW-TO.labels#2')
-    2.0. Nesting → You can keep nesting. Label references don't need to be nested: requirement('HOW-TO.nesting').
-    2.1. Several words → Reference multi-word labels using kebab-case. Label references are never case sensitive: requirement('HOW-TO.several-words')
+HOWTO-1: How to use dotrequirements
+  0. → Requirements live here and are referenced by index, like requirement('HOWTO-1.0')
+  1. Labels → Anything before the arrow is a label. You can reference a requirement by its index or its label: requirement('HOWTO-1.1') == requirement('HOWTO-1.labels')
+  2. Labels → Repeated labels can be referenced sequentially: requirement('HOWTO-1.labels#2')
+    2.0. Nesting → You can keep nesting. Label references don't need to be nested: requirement('HOWTO-1.nesting').
+    2.1. Several words → Reference multi-word labels using kebab-case. Label references are never case sensitive: requirement('HOWTO-1.several-words')
   3. → While you _can_ write your requirements longhand in this format, there are a number of better ways.
     3.0. MCP → The dotrequirements MCP equips an AI assistant to develop requirements with you
     3.1. Your current tools → Dotrequirements has a composer for Jira, Confluence, and Notion
@@ -37,12 +37,12 @@ HOW-TO: How to use dotrequirements
 
 ---
 
-## USER-AUTH: User authentication flow
+## AUTH-1: User authentication flow
 
 **Implementation notes:** Use bcrypt for password hashing with work factor >= 12.
 
 \`\`\`dotrequirements
-USER-AUTH: User authentication flow
+AUTH-1: User authentication flow
   0. AC → Login form accepts email and password
   1. AC → Invalid credentials show error message
   2. Edge-case → Rate limiting after 5 failed attempts
@@ -72,11 +72,11 @@ import { requirement } from '@popoverai/dotrequirements/test';
 
 test('login with valid credentials', () => {
   // Reference by numeric path
-  const ac = requirement('USER-AUTH.0');
+  const ac = requirement('AUTH-1.0');
   // Returns: "AC: Login form accepts email and password"
 
   // Reference by label
-  const edgeCase = requirement('USER-AUTH.edge-case');
+  const edgeCase = requirement('AUTH-1.edge-case');
   // Returns: "Edge-case: Rate limiting after 5 failed attempts"
 
   // Your test implementation...

package/dist/utils/context-file.d.ts

@@ -35,4 +35,12 @@ export declare function appendOrUpdateSection(filePath: string, sectionContent:
  * Get the full path to the context file for a platform
  */
 export declare function getContextFilePath(platform: string): Promise<string | null>;
+/**
+ * Build a user-facing message explaining that context file installation
+ * was skipped because the current directory is not inside a git repository.
+ *
+ * The MCP server itself is configured separately, so this message is only
+ * about the second step (writing the platform's context file).
+ */
+export declare function buildNoGitRepoMessage(fileName: string): string;
 //# sourceMappingURL=context-file.d.ts.map

package/dist/utils/context-file.js

@@ -91,4 +91,23 @@ export async function getContextFilePath(platform) {
         return null;
     return join(gitRoot, fileName);
 }
+/**
+ * Build a user-facing message explaining that context file installation
+ * was skipped because the current directory is not inside a git repository.
+ *
+ * The MCP server itself is configured separately, so this message is only
+ * about the second step (writing the platform's context file).
+ */
+export function buildNoGitRepoMessage(fileName) {
+    return [
+        `⚠️  Skipped writing ${fileName}: not inside a git repository.`,
+        `   ${fileName} would have been created at the git repo root, but no .git directory was found.`,
+        '',
+        '   To finish setup, either:',
+        '     • run `git init` here, then re-run `dotreq mcp-setup`, or',
+        '     • `cd` into an existing project directory and run `dotreq mcp-setup` there.',
+        '',
+        '   Note: the MCP server itself was configured successfully — only the context file step was skipped.',
+    ].join('\n');
+}
 //# sourceMappingURL=context-file.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Requirements tracking CLI, test harness, and MCP server",
   "type": "module",
   "bin": {