@popoverai/dotrequirements 0.20.4 → 0.21.1

package/dist/cli.js

@@ -6,6 +6,9 @@ import { pullCommand } from './commands/pull.js';
 import { pushCommand } from './commands/push.js';
 import { testCommand } from './commands/test.js';
 import { browserTestCommand } from './commands/browsertest.js';
+import { prepareCommand } from './commands/prepare.js';
+import { finalizeCommand } from './commands/finalize.js';
+import { reportCommand } from './commands/report.js';
 import { mcpCommand } from './commands/mcp.js';
 import { mcpSetupCommand } from './commands/mcp-setup.js';
 import { loadEnvFile } from './utils/env.js';
@@ -77,6 +80,23 @@ program
     .option('--json', 'Output results as JSON')
     .option('--useAgent', 'Encourage Claude to use the Agent tool for multi-step tasks')
     .action(wrapCommand(browserTestCommand));
+program
+    .command('prepare')
+    .description('Parse requirements and build lookup cache for multi-language test tracking')
+    .option('-q, --quiet', 'Suppress output (for scripting)')
+    .action(wrapCommand(prepareCommand));
+program
+    .command('finalize')
+    .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)')
+    .action(wrapCommand(finalizeCommand));
+program
+    .command('report')
+    .description('Display coverage report from most recent test run')
+    .option('-f, --format <format>', 'Output format: console, json, markdown', 'console')
+    .option('-r, --requirement <id>', 'Filter to specific requirement and its children')
+    .action(wrapCommand(reportCommand));
 program
     .command('mcp')
     .description('Start the MCP (Model Context Protocol) server for AI assistant integration')

package/dist/commands/finalize.d.ts

@@ -0,0 +1,7 @@
+interface FinalizeOptions {
+    push?: boolean;
+    quiet?: boolean;
+}
+export declare function finalizeCommand(options: FinalizeOptions): Promise<void>;
+export {};
+//# sourceMappingURL=finalize.d.ts.map

package/dist/commands/finalize.js

@@ -0,0 +1,40 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { finalize } from '../harness/finalize.js';
+import { findRequirementsDir, isCacheStale } from '../harness/cache.js';
+import { findProjectRoot } from '../utils/project-settings.js';
+export async function finalizeCommand(options) {
+    // Warn if cache is stale before finalizing
+    if (!options.quiet) {
+        const projectRoot = findProjectRoot(process.cwd());
+        if (projectRoot) {
+            const requirementsDir = findRequirementsDir(projectRoot);
+            if (requirementsDir) {
+                const lookupPath = path.join(requirementsDir, '.cache', 'lookup.json');
+                try {
+                    const cacheStat = fs.statSync(lookupPath);
+                    if (isCacheStale(requirementsDir, cacheStat.mtimeMs)) {
+                        console.error('Warning: Cache may be stale — requirements have changed since last prepare. Run "dotrequirements prepare" to rebuild.\n');
+                    }
+                }
+                catch {
+                    // Ignore — finalize will handle missing cache
+                }
+            }
+        }
+    }
+    const result = await finalize({
+        cwd: process.cwd(),
+        reportToCloud: options.push ?? false,
+        cleanup: true,
+        showSummary: !options.quiet,
+        showTestedList: true,
+        showUntestedList: true,
+        showCloudStatus: !options.quiet,
+    });
+    if (options.quiet) {
+        // In quiet mode, just output the coverage percent for scripting
+        console.log(result.coveragePercent.toFixed(1));
+    }
+}
+//# sourceMappingURL=finalize.js.map

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/commands/prepare.d.ts

@@ -0,0 +1,6 @@
+interface PrepareOptions {
+    quiet?: boolean;
+}
+export declare function prepareCommand(options: PrepareOptions): Promise<void>;
+export {};
+//# sourceMappingURL=prepare.d.ts.map

package/dist/commands/prepare.js

@@ -0,0 +1,20 @@
+import { prepare } from '../harness/prepare.js';
+export async function prepareCommand(options) {
+    const result = prepare({
+        cwd: process.cwd(),
+        logWarnings: !options.quiet,
+    });
+    if (!options.quiet) {
+        console.log(`Parsed ${result.filesProcessed} file(s), loaded ${result.requirementsLoaded} requirement(s) into cache.`);
+        if (result.parseErrors.length > 0) {
+            console.log(`\n⚠️  ${result.parseErrors.length} file(s) had parse errors (skipped):`);
+            for (const err of result.parseErrors) {
+                console.log(`  - ${err.file}: ${err.error}`);
+            }
+        }
+        console.log('\nCache written to .requirements/.cache/lookup.json');
+        console.log('Tracking initialized at .requirements/.cache/tracking.jsonl');
+        console.log('\nRun your tests, then run "dotrequirements finalize" to generate coverage report.');
+    }
+}
+//# sourceMappingURL=prepare.js.map

package/dist/commands/report.d.ts

@@ -0,0 +1,7 @@
+interface ReportOptions {
+    format?: 'console' | 'json' | 'markdown';
+    requirement?: string;
+}
+export declare function reportCommand(options: ReportOptions): Promise<void>;
+export {};
+//# sourceMappingURL=report.d.ts.map

package/dist/commands/report.js

@@ -0,0 +1,152 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { findProjectRoot } from '../utils/project-settings.js';
+import { findRequirementsDir, readTrackingEntries, isCacheStale, } from '../harness/cache.js';
+function buildCoverageEntries(lookup, entries, filterKey) {
+    // Aggregate tracking by key
+    const locationsByKey = new Map();
+    for (const entry of entries) {
+        if (!locationsByKey.has(entry.requirementKey)) {
+            locationsByKey.set(entry.requirementKey, new Set());
+        }
+        locationsByKey.get(entry.requirementKey).add(entry.callerLocation);
+    }
+    const results = [];
+    for (const [key, req] of Object.entries(lookup.requirements)) {
+        // Skip alias entries to avoid double-counting
+        if (req.isAlias)
+            continue;
+        // Filter if requested
+        if (filterKey && key !== filterKey && !key.startsWith(filterKey + '.')) {
+            continue;
+        }
+        // Collect locations from both the numeric key and any alias keys that map to the same id
+        const locations = new Set();
+        const keyLocations = locationsByKey.get(key);
+        if (keyLocations)
+            keyLocations.forEach(l => locations.add(l));
+        // Also check if tracking data was written using a label path
+        for (const [aliasKey, aliasReq] of Object.entries(lookup.requirements)) {
+            if (aliasReq.isAlias && aliasReq.id === req.id) {
+                const aliasLocations = locationsByKey.get(aliasKey);
+                if (aliasLocations)
+                    aliasLocations.forEach(l => locations.add(l));
+            }
+        }
+        results.push({
+            key,
+            label: req.label || null,
+            content: req.content,
+            tested: locations.size > 0,
+            locations: Array.from(locations),
+        });
+    }
+    return results;
+}
+function formatConsole(coverage) {
+    const tested = coverage.filter(c => c.tested).length;
+    const total = coverage.length;
+    const pct = total > 0 ? ((tested / total) * 100).toFixed(1) : '0.0';
+    let out = `\n=== Requirements Coverage Report ===\n`;
+    out += `\nTotal: ${total} | Tested: ${tested} | Untested: ${total - tested} | Coverage: ${pct}%\n`;
+    const testedEntries = coverage.filter(c => c.tested);
+    if (testedEntries.length > 0) {
+        out += '\n✓ Tested:\n';
+        for (const c of testedEntries) {
+            const preview = c.content.length > 60 ? c.content.substring(0, 60) + '...' : c.content;
+            out += `  ${c.key}: ${preview}\n`;
+            for (const loc of c.locations) {
+                out += `    ← ${loc}\n`;
+            }
+        }
+    }
+    const untestedEntries = coverage.filter(c => !c.tested);
+    if (untestedEntries.length > 0) {
+        out += '\n✗ Untested:\n';
+        for (const c of untestedEntries) {
+            const preview = c.content.length > 60 ? c.content.substring(0, 60) + '...' : c.content;
+            out += `  ${c.key}: ${preview}\n`;
+        }
+    }
+    out += '\n====================================\n';
+    return out;
+}
+function formatJson(coverage) {
+    const tested = coverage.filter(c => c.tested).length;
+    const total = coverage.length;
+    return JSON.stringify({
+        summary: {
+            total,
+            tested,
+            untested: total - tested,
+            coveragePercent: total > 0 ? parseFloat(((tested / total) * 100).toFixed(1)) : 0,
+        },
+        requirements: coverage,
+    }, null, 2);
+}
+function formatMarkdown(coverage) {
+    const tested = coverage.filter(c => c.tested).length;
+    const total = coverage.length;
+    const pct = total > 0 ? ((tested / total) * 100).toFixed(1) : '0.0';
+    let out = `# Requirements Coverage Report\n\n`;
+    out += `**Coverage:** ${tested}/${total} (${pct}%)\n\n`;
+    out += `| Requirement | Status | Locations |\n`;
+    out += `|---|---|---|\n`;
+    for (const c of coverage) {
+        const status = c.tested ? '✓' : '✗';
+        const locs = c.locations.join(', ') || '-';
+        const preview = c.content.length > 40 ? c.content.substring(0, 40) + '...' : c.content;
+        out += `| ${c.key}: ${preview} | ${status} | ${locs} |\n`;
+    }
+    return out;
+}
+export async function reportCommand(options) {
+    const projectRoot = findProjectRoot(process.cwd());
+    if (!projectRoot) {
+        throw new Error('Could not find .requirements directory. Run "dotrequirements init" to initialize your project.');
+    }
+    const requirementsDir = findRequirementsDir(projectRoot);
+    const cacheDir = path.join(requirementsDir, '.cache');
+    const lookupPath = path.join(cacheDir, 'lookup.json');
+    if (!fs.existsSync(lookupPath)) {
+        throw new Error('No lookup cache found. Run "dotrequirements prepare" first to build the cache.');
+    }
+    // Read lookup cache
+    const lookupContent = fs.readFileSync(lookupPath, 'utf-8');
+    const lookup = JSON.parse(lookupContent);
+    // Warn if cache is stale (requirements changed since last prepare)
+    try {
+        const cacheStat = fs.statSync(lookupPath);
+        if (isCacheStale(requirementsDir, cacheStat.mtimeMs)) {
+            console.error('Warning: Cache may be stale — requirements have changed since last prepare. Run "dotrequirements prepare" to rebuild.\n');
+        }
+    }
+    catch {
+        // Ignore stat errors
+    }
+    // Read tracking entries
+    const trackingPath = path.join(cacheDir, 'tracking.jsonl');
+    const trackingExists = fs.existsSync(trackingPath);
+    const entries = readTrackingEntries(requirementsDir);
+    if (!trackingExists) {
+        console.error('Warning: No tracking data found. Run your tests first, or run "dotrequirements prepare" to start a new tracking session.\n');
+    }
+    else if (entries.length === 0) {
+        console.error('Warning: Tracking file is empty — no requirements were tracked during tests.\n');
+    }
+    const coverage = buildCoverageEntries(lookup, entries, options.requirement);
+    const format = options.format || 'console';
+    switch (format) {
+        case 'json':
+            console.log(formatJson(coverage));
+            break;
+        case 'markdown':
+            console.log(formatMarkdown(coverage));
+            break;
+        case 'console':
+        default:
+            console.log(formatConsole(coverage));
+            break;
+    }
+}
+//# sourceMappingURL=report.js.map

package/dist/harness/cache.d.ts

@@ -32,6 +32,8 @@ export interface LookupCache {
         id: string;
         label: string;
         content: string;
+        /** True if this key is a label-path alias for another entry (e.g. "REQ.given" → "REQ.0") */
+        isAlias?: boolean;
     }>;
 }
 /**
@@ -69,6 +71,11 @@ export declare function findRequirementsFiles(projectRoot: string): string[];
  * Write the lookup cache with all pre-parsed requirements
  */
 export declare function writeLookupCache(requirementsDir: string, requirements: RequirementNode[]): void;
+/**
+ * Check if any source file is newer than the cache file.
+ * Returns true if cache is stale and should be invalidated.
+ */
+export declare function isCacheStale(requirementsDir: string, cacheMtime: number): boolean;
 /**
  * Read the lookup cache, returning null if not found, invalid, or stale.
  * Cache is considered stale if any .requirements.md file is newer than the cache.

package/dist/harness/cache.js

@@ -84,19 +84,37 @@ export function writeLookupCache(requirementsDir, requirements) {
         generatedAt: new Date().toISOString(),
         requirements: {},
     };
-    // Recursively flatten the requirement trees
-    function flatten(node) {
-        lookup.requirements[node.id] = {
+    // Recursively flatten the requirement trees, adding both numeric and label paths
+    function flatten(node, labelPath) {
+        const entry = {
             id: node.id,
             label: node.label,
             content: node.content,
         };
+        // Always add the numeric path (e.g. "AUTH-LOGIN.0")
+        lookup.requirements[node.id] = entry;
+        // Add label path as an alias if it differs from the numeric path
+        if (labelPath && labelPath !== node.id) {
+            lookup.requirements[labelPath] = { ...entry, isAlias: true };
+        }
+        // Track label occurrences for disambiguation (e.g. given#0, given#1)
+        const labelCounts = new Map();
         for (const child of node.children) {
-            flatten(child);
+            let childLabelPath = null;
+            if (child.label && child.label !== 'requirementHeader') {
+                const normalizedLabel = child.label.toLowerCase().replace(/\s+/g, '-');
+                const count = labelCounts.get(normalizedLabel) || 0;
+                labelCounts.set(normalizedLabel, count + 1);
+                const parentPath = labelPath || node.id;
+                childLabelPath = count === 0
+                    ? `${parentPath}.${normalizedLabel}`
+                    : `${parentPath}.${normalizedLabel}#${count}`;
+            }
+            flatten(child, childLabelPath);
         }
     }
     for (const req of requirements) {
-        flatten(req);
+        flatten(req, null);
     }
     fs.writeFileSync(lookupPath, JSON.stringify(lookup, null, 2));
 }
@@ -104,7 +122,7 @@ export function writeLookupCache(requirementsDir, requirements) {
  * Check if any source file is newer than the cache file.
  * Returns true if cache is stale and should be invalidated.
  */
-function isCacheStale(requirementsDir, cacheMtime) {
+export function isCacheStale(requirementsDir, cacheMtime) {
     const projectRoot = path.dirname(requirementsDir);
     const sourceFiles = findRequirementsFiles(projectRoot);
     for (const file of sourceFiles) {

package/dist/harness/finalize.js

@@ -47,7 +47,7 @@ function getCurrentBranch(cwd) {
  */
 function printLocalReport(testedKeys, lookup, options) {
     const { showSummary, showTestedList, showUntestedList } = options;
-    const allKeys = lookup ? Object.keys(lookup.requirements) : [];
+    const allKeys = lookup ? Object.keys(lookup.requirements).filter(k => !lookup.requirements[k].isAlias) : [];
     const untestedKeys = allKeys.filter(key => !testedKeys.includes(key));
     const total = allKeys.length;
     const tested = testedKeys.length;
@@ -278,10 +278,26 @@ export async function finalize(options = {}) {
     const entries = readTrackingEntries(requirementsDir);
     // Aggregate by requirement key
     const aggregated = aggregateEntries(entries);
-    const testedKeys = Array.from(aggregated.keys());
     // Read lookup cache for report
     const lookup = readLookupCache(requirementsDir);
-    const totalRequirements = lookup ? Object.keys(lookup.requirements).length : 0;
+    // Normalize alias keys to canonical numeric keys.
+    // Non-JS consumers may write label paths (e.g. "AUTH-LOGIN.given") to tracking.jsonl.
+    // We resolve those to their canonical numeric key (e.g. "AUTH-LOGIN.0") so that
+    // coverage counting, display, and cloud reporting all use consistent keys.
+    if (lookup) {
+        for (const [key, trackingEntries] of Array.from(aggregated.entries())) {
+            const entry = lookup.requirements[key];
+            if (entry?.isAlias) {
+                const canonicalKey = entry.id;
+                // Merge into canonical key's entries
+                const existing = aggregated.get(canonicalKey) || [];
+                aggregated.set(canonicalKey, [...existing, ...trackingEntries]);
+                aggregated.delete(key);
+            }
+        }
+    }
+    const testedKeys = Array.from(aggregated.keys());
+    const totalRequirements = lookup ? Object.keys(lookup.requirements).filter(k => !lookup.requirements[k].isAlias).length : 0;
     const coveragePercent = totalRequirements > 0
         ? (testedKeys.length / totalRequirements) * 100
         : 0;

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.20.4",
+  "version": "0.21.1",
   "description": "Requirements tracking CLI, test harness, and MCP server",
   "type": "module",
   "bin": {