@popoverai/dotrequirements 0.26.2 → 0.27.1

package/dist/commands/review-test.js

@@ -4,14 +4,32 @@ import { DEFAULT_API_BASE_URL, fetchReviewTestFeedback, } from "../requirements/
 import { findRequirementsInFile } from "../requirements/grep.js";
 import { formatRequirementTree, getRequirementTree, loadAllRequirements, } from "../requirements/index.js";
 import { getProjectCredentials } from "../utils/project-settings.js";
-export async function reviewTestCommand(testFilePath) {
+/**
+ * Judgment instructions for local-mode test review. Mirrors the hosted
+ * review's semantic framing: test anatomy (setup, actions, assertions)
+ * checked against requirement anatomy (preconditions, triggers, outcomes).
+ */
+const REVIEW_INSTRUCTIONS = `You are the reviewer. Judge whether the test file below validates what its referenced requirements specify, then report findings under the headings MUST FIX / SHOULD FIX / COULD IMPROVE (semantic gaps are MUST FIX; categorize other findings by their own severity). Focus on gaps and give actionable suggestions.
+
+For each requirement reference, check:
+- **Setup vs preconditions** — does the test establish the state the requirement describes (e.g. "a registered user" backed by actual data, not mocked away)?
+- **Actions vs triggers** — does the test exercise the specified behavior with the specified inputs?
+- **Assertions vs outcomes** — does the test verify the specified outcomes (no tautologies), and does it cover every distinct outcome the requirement lists?
+- Note over-testing (validating behavior the requirement doesn't specify) without treating it as an error.
+- When a test's level doesn't fit its requirement (e.g. a unit test referencing an end-to-end requirement), suggest scoping the reference or a different test level — with specific guidance.`;
+export async function reviewTestCommand(testFilePath, options = {}) {
     const workspaceRoot = process.cwd();
     const fullPath = resolve(workspaceRoot, testFilePath);
-    // CLI-REVIEW-1.5: missing file → error + non-zero exit
+    // CLI-REVIEW-1.5: --source accepts only local|cloud
+    const source = options.source ?? "local";
+    if (source !== "local" && source !== "cloud") {
+        throw new Error(`Invalid --source value: ${options.source}. Expected "local" or "cloud".`);
+    }
+    // CLI-REVIEW-1.3: missing file → error + non-zero exit
     if (!existsSync(fullPath)) {
         throw new Error(`File not found: ${testFilePath}`);
     }
-    // CLI-REVIEW-1.6: must be a test file
+    // CLI-REVIEW-1.4: must be a test file
     if (!/\.(test|spec)\.(js|jsx|ts|tsx)$/.test(testFilePath)) {
         throw new Error(`File must be a test file: *.{test,spec}.{js,jsx,ts,tsx} — got ${testFilePath}`);
     }
@@ -30,6 +48,9 @@ export async function reviewTestCommand(testFilePath) {
     // resolve instead of being dropped.
     const { flattened } = await loadAllRequirements(workspaceRoot);
     const rootToTestedIds = new Map();
+    // CLI-REVIEW-1.2: references whose root resolves to no workspace
+    // requirement are reported as missing (in every mode)
+    const missingIds = [];
     for (const reqId of requirementIds) {
         const dotIndex = reqId.indexOf(".");
         const refRootId = dotIndex > 0 ? reqId.substring(0, dotIndex) : reqId;
@@ -40,7 +61,11 @@ export async function reviewTestCommand(testFilePath) {
             }
             rootToTestedIds.get(req.rootId).add(reqId);
         }
+        else {
+            missingIds.push(reqId);
+        }
     }
+    missingIds.sort();
     const requirements = [];
     for (const [rootId, testedIds] of rootToTestedIds) {
         const tree = getRequirementTree(flattened, rootId);
@@ -50,7 +75,64 @@ export async function reviewTestCommand(testFilePath) {
             testedIds: Array.from(testedIds).sort(),
         });
     }
-    // CLI-REVIEW-1.6: cloud credentials required
+    if (source === "cloud") {
+        await runCloudReview({
+            workspaceRoot,
+            testFilePath,
+            testFileContents,
+            requirements,
+            missingIds,
+        });
+        return;
+    }
+    emitReviewMaterials({
+        testFilePath,
+        testFileContents,
+        requirements,
+        missingIds,
+    });
+}
+/**
+ * CLI-REVIEW-2: local (default) mode — emit judgment-ready review materials
+ * for the calling agent (typically a dispatched review subagent). No cloud
+ * credentials required.
+ */
+function emitReviewMaterials(params) {
+    const { testFilePath, testFileContents, requirements, missingIds } = params;
+    console.log(`# Test Review Materials for ${testFilePath}\n`);
+    console.log(`## Judgment instructions\n`);
+    console.log(REVIEW_INSTRUCTIONS);
+    // CLI-REVIEW-2.0: resolved requirement trees bundled with the test contents
+    console.log(`\n## Referenced requirements\n`);
+    if (requirements.length === 0) {
+        console.log("(none resolved — the test file references no workspace requirements)");
+    }
+    else {
+        for (const req of requirements) {
+            console.log(`### ${req.id} (tested: ${req.testedIds.join(", ")})\n`);
+            console.log(req.content);
+            console.log("");
+        }
+    }
+    // CLI-REVIEW-1.2: missing references reported in the output
+    if (missingIds.length > 0) {
+        console.log(`## Missing requirement references\n`);
+        console.log(`These references resolve to no requirement in this workspace — flag them in your findings:`);
+        for (const id of missingIds) {
+            console.log(`- ${id}`);
+        }
+        console.log("");
+    }
+    console.log(`## Test file under review (${testFilePath})\n`);
+    console.log(testFileContents);
+}
+/**
+ * CLI-REVIEW-3: --source cloud — send the bundle to the hosted review
+ * endpoint and print the returned feedback. Requires cloud credentials.
+ */
+async function runCloudReview(params) {
+    const { workspaceRoot, testFilePath, testFileContents, requirements, missingIds, } = params;
+    // CLI-REVIEW-3.2: cloud credentials required
     let projectId;
     let projectSecret;
     try {
@@ -62,22 +144,34 @@ export async function reviewTestCommand(testFilePath) {
         throw new Error(`Test review requires cloud credentials. Run \`dotrequirements link\` to connect this project to the cloud.\n` +
             `(${error instanceof Error ? error.message : String(error)})`);
     }
-    // CLI-REVIEW-1.2 / .3 / .4 / .7 / .8: dispatch to the hosted endpoint
+    // CLI-REVIEW-3.0 / .1 / .3: dispatch to the hosted endpoint
     const apiBaseUrl = process.env.DOTREQUIREMENTS_API_URL ?? DEFAULT_API_BASE_URL;
     let feedback;
+    let quotaWarning;
     try {
-        feedback = await fetchReviewTestFeedback({
+        ({ feedback, quotaWarning } = await fetchReviewTestFeedback({
             apiBaseUrl,
             projectId,
             projectSecret,
             testFileContents,
             requirements,
-        });
+        }));
     }
     catch (error) {
         throw new Error(`Test review failed: ${error instanceof Error ? error.message : String(error)}`);
     }
     console.log(`Test Review Results for ${testFilePath}\n`);
     console.log(feedback);
+    // LIMITS-5.2 / 5.2.0: the 80–99% quota warning prints with the result
+    if (quotaWarning) {
+        console.log(`\n⚠ ${quotaWarning}`);
+    }
+    // CLI-REVIEW-1.2: missing references reported in every mode
+    if (missingIds.length > 0) {
+        console.log(`\nMissing requirement references (not in this workspace):`);
+        for (const id of missingIds) {
+            console.log(`- ${id}`);
+        }
+    }
 }
 //# sourceMappingURL=review-test.js.map

package/dist/commands/style-check.d.ts

@@ -1,6 +1,7 @@
 interface StyleCheckOptions {
     keys?: string[];
     model?: string;
+    source?: string;
 }
 export declare function styleCheckCommand(filePath: string, options: StyleCheckOptions): Promise<void>;
 export {};

package/dist/commands/style-check.js

@@ -1,16 +1,45 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { DEFAULT_API_BASE_URL, fetchStyleCheckFeedback, } from "../requirements/cloud-ai.js";
-import { filterRequirementsByKeys } from "../requirements/index.js";
-import { getProjectCredentials } from "../utils/project-settings.js";
+import { DEFAULT_API_BASE_URL, fetchStyleCheckFeedback, getProjectContext, } from "../requirements/cloud-ai.js";
+import { filterRequirementsByKeys, loadAllRequirements, } from "../requirements/index.js";
+import { generateStyleGuideBody } from "../requirements/style-guide.js";
+import { readLocalStyleGuide } from "../requirements/style-guide-file.js";
+import { findProjectRoot, getProjectCredentials, } from "../utils/project-settings.js";
+const CONVEX_URL = "https://data.dotrequirements.io";
+/**
+ * Judgment instructions for test-file style review in local mode. Mirrors the
+ * hosted test-style rubric (PROMPT-STYLE-TESTS-*): requirement() usage,
+ * comment discipline, structure, coverage-comment red flags, and semantic
+ * alignment between test anatomy and requirement anatomy.
+ */
+const TEST_STYLE_INSTRUCTIONS = `You are the reviewer. Judge the test file below against these test-style conventions, then report findings under the headings MUST FIX / SHOULD FIX / COULD IMPROVE (categorize each finding by its own severity; semantic gaps are MUST FIX). Focus on gaps and give actionable suggestions.
+
+- \`requirement()\` is used AS the description parameter of \`test()\`, \`describe()\`, or \`it()\` — flag requirement() calls placed in test bodies, and plain-string descriptions that should reference a requirement.
+- Comments describe what the test implementation does — flag comments that copy requirement text verbatim (the requirement() reference already carries that meaning). Tests need no comments at all.
+- Structured requirements (Given/When/Then trees) are tested with nested describe/it blocks; simple requirements need no extra nesting.
+- Flag comments that document requirement coverage (e.g. "Requirements coverage: AUTH-9.0 ✓") — coverage lives in the harness, not comments; a second source of truth drifts.
+- Test setup should establish the preconditions the referenced requirement describes; actions should exercise the specified behavior with the specified inputs; assertions should verify the specified outcomes (not tautologies like expect(true).toBe(true)). Flag requirements whose distinct outcomes are only partially validated; note over-testing without treating it as an error.
+- When a test's level doesn't fit its requirement (e.g. a unit test referencing an end-to-end requirement), suggest scoping the reference or a different test level — with specific guidance, not generic observations.
+
+The referenced requirement trees are not bundled here; if you need one, read it from \`.requirements/\` or run \`dotreq get <KEY>\`. For a full semantic review of tests against their requirements, \`dotreq review-test <file>\` is the dedicated verb.`;
+const REQUIREMENTS_STYLE_INSTRUCTIONS = `You are the reviewer. Judge the requirements below against the style guide above, then report findings under the headings MUST FIX / SHOULD FIX / COULD IMPROVE (categorize each finding by its own severity). Focus on gaps and give actionable suggestions rather than just listing problems.`;
 export async function styleCheckCommand(filePath, options) {
     const workspaceRoot = process.cwd();
     const fullPath = resolve(workspaceRoot, filePath);
-    // CLI-STYLE-1.5: missing file → error + non-zero exit
+    // CLI-STYLE-1.6: --source accepts only local|cloud
+    const source = options.source ?? "local";
+    if (source !== "local" && source !== "cloud") {
+        throw new Error(`Invalid --source value: ${options.source}. Expected "local" or "cloud".`);
+    }
+    // CLI-STYLE-1.7: --model configures the hosted review only
+    if (options.model && source !== "cloud") {
+        throw new Error(`--model applies to cloud review only. Add --source cloud to choose a review model.`);
+    }
+    // CLI-STYLE-1.4: missing file → error + non-zero exit
     if (!existsSync(fullPath)) {
         throw new Error(`File not found: ${filePath}`);
     }
-    // CLI-STYLE-1.0 / .1 / .6: file-type detection
+    // CLI-STYLE-1.0 / .1 / .5: file-type detection
     const isRequirementsFile = filePath.endsWith(".requirements.md");
     const isTestFile = /\.(test|spec)\.(js|jsx|ts|tsx)$/.test(filePath);
     if (!isRequirementsFile && !isTestFile) {
@@ -35,7 +64,100 @@ export async function styleCheckCommand(filePath, options) {
             scopeNote = `\nNote: Some specified keys were not found in the file: ${missingKeys.join(", ")}`;
         }
     }
-    // CLI-STYLE-1.7: credentials are required
+    const scopeLabel = options.keys && options.keys.length > 0
+        ? ` (${options.keys.join(", ")})`
+        : "";
+    if (source === "cloud") {
+        await runCloudStyleCheck({
+            workspaceRoot,
+            filePath,
+            fileContentsToCheck,
+            fileType,
+            model: options.model,
+            scopeLabel,
+            scopeNote,
+        });
+        return;
+    }
+    await emitStyleMaterials({
+        workspaceRoot,
+        filePath,
+        fileContentsToCheck,
+        fileType,
+        scopeLabel,
+        scopeNote,
+    });
+}
+/**
+ * CLI-STYLE-2: local (default) mode — emit judgment-ready review materials
+ * for the calling agent (typically a dispatched review subagent). No cloud
+ * credentials required.
+ */
+async function emitStyleMaterials(params) {
+    const { workspaceRoot, filePath, fileContentsToCheck, fileType, scopeLabel, scopeNote, } = params;
+    console.log(`# Style Review Materials for ${filePath}${scopeLabel}\n`);
+    if (fileType === "requirements") {
+        // CLI-STYLE-2.0: compose the style guide the same way
+        // create-requirement-document does.
+        // CLI-STYLE-2.0.0: a project STYLE.md, when present, IS the guide.
+        const localStyleGuide = readLocalStyleGuide(workspaceRoot);
+        let guide;
+        if (localStyleGuide?.trim()) {
+            guide = localStyleGuide;
+        }
+        else {
+            // CLI-STYLE-2.0.1: otherwise generate from bundled defaults, workspace
+            // patterns, and cloud custom guidance when linked.
+            let requirements = [];
+            try {
+                const result = await loadAllRequirements(workspaceRoot);
+                requirements = result.flattened;
+            }
+            catch {
+                // No requirements in the workspace yet — defaults still apply
+            }
+            // CLI-STYLE-2.3 / .4: credentials are optional; cloud custom guidance is
+            // silently omitted when unlinked or unreachable.
+            let customStyleGuidance = null;
+            const projectRoot = findProjectRoot(workspaceRoot);
+            if (projectRoot) {
+                try {
+                    const { projectId, projectSecret } = getProjectCredentials(workspaceRoot);
+                    const contextData = await getProjectContext(projectId, projectSecret, CONVEX_URL);
+                    customStyleGuidance = contextData?.requirementsStyleContext ?? null;
+                }
+                catch {
+                    // Unlinked or cloud unavailable — fall through with defaults
+                }
+            }
+            guide = generateStyleGuideBody({ requirements, customStyleGuidance });
+        }
+        console.log(`## Style guide\n`);
+        console.log(guide);
+        console.log(`\n## Judgment instructions\n`);
+        console.log(REQUIREMENTS_STYLE_INSTRUCTIONS);
+    }
+    else {
+        console.log(`## Judgment instructions\n`);
+        console.log(TEST_STYLE_INSTRUCTIONS);
+    }
+    // CLI-STYLE-2.1: the content under review (keys-filtered when --keys given)
+    const heading = fileType === "requirements"
+        ? "Requirements under review"
+        : "Test file under review";
+    console.log(`\n## ${heading} (${filePath})\n`);
+    console.log(fileContentsToCheck);
+    if (scopeNote) {
+        console.log(scopeNote);
+    }
+}
+/**
+ * CLI-STYLE-3: --source cloud — send the file to the hosted review endpoint
+ * and print the returned feedback. Requires cloud credentials.
+ */
+async function runCloudStyleCheck(params) {
+    const { workspaceRoot, filePath, fileContentsToCheck, fileType, model, scopeLabel, scopeNote, } = params;
+    // CLI-STYLE-3.2: credentials are required
     let projectId;
     let projectSecret;
     try {
@@ -47,29 +169,32 @@ export async function styleCheckCommand(filePath, options) {
         throw new Error(`Style check requires cloud credentials. Run \`dotrequirements link\` to connect this project to the cloud.\n` +
             `(${error instanceof Error ? error.message : String(error)})`);
     }
-    // CLI-STYLE-1.4 / .8 / .9: dispatch to the hosted endpoint
+    // CLI-STYLE-3.0 / .1 / .3: dispatch to the hosted endpoint
     const apiBaseUrl = process.env.DOTREQUIREMENTS_API_URL ?? DEFAULT_API_BASE_URL;
     let feedback;
+    let quotaWarning;
     try {
-        feedback = await fetchStyleCheckFeedback({
+        ({ feedback, quotaWarning } = await fetchStyleCheckFeedback({
             apiBaseUrl,
             projectId,
             projectSecret,
             fileContents: fileContentsToCheck,
             fileType,
-            model: options.model,
-        });
+            model,
+        }));
     }
     catch (error) {
         throw new Error(`Style check failed: ${error instanceof Error ? error.message : String(error)}`);
     }
-    const scopeLabel = options.keys && options.keys.length > 0
-        ? ` (${options.keys.join(", ")})`
-        : "";
+    // CLI-STYLE-3.4: hosted feedback arrives severity-categorized
     console.log(`Style Check Results for ${filePath}${scopeLabel}\n`);
     console.log(feedback);
     if (scopeNote) {
         console.log(scopeNote);
     }
+    // LIMITS-5.2 / 5.2.0: the 80–99% quota warning prints with the result
+    if (quotaWarning) {
+        console.log(`\n⚠ ${quotaWarning}`);
+    }
 }
 //# sourceMappingURL=style-check.js.map

package/dist/convex.d.ts

@@ -55,11 +55,9 @@ export declare const api: {
         };
         mutations: {
             createInvite: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+            acceptInvite: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
         };
     };
-    polar: {
-        acceptTeamInvite: import("convex/server").FunctionReference<"action", "public", any, any, string | undefined>;
-    };
     projectSecrets: {
         queries: {
             getOwnSecret: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;

package/dist/convex.js

@@ -61,11 +61,11 @@ export const api = {
         },
         mutations: {
             createInvite: mutation("teamInvites/mutations:createInvite"),
+            // Joins the team and reconciles paid-team seats via a scheduled sync
+            // (POLAR-SEATS-3). Replaced the deleted polar:acceptTeamInvite action.
+            acceptInvite: mutation("teamInvites/mutations:acceptInvite"),
         },
     },
-    polar: {
-        acceptTeamInvite: action("polar:acceptTeamInvite"),
-    },
     projectSecrets: {
         queries: {
             getOwnSecret: query("projectSecrets/queries:getOwnSecret"),

package/dist/requirements/cloud-ai.d.ts

@@ -22,11 +22,23 @@ export interface StyleCheckParams {
     model?: string;
 }
 /**
- * POST to `/api/style-check`. Returns the feedback text on success;
- * throws an Error with the underlying failure reason on a non-OK
- * response or a network error.
+ * Feedback plus the optional LIMITS-5.2 quota warning ("You've used X% of
+ * your AI quota this billing cycle."). The warning is present when the
+ * team is at 80–99% of its AI allowance; callers print it alongside the
+ * feedback so the eventual quota wall never arrives unannounced. Older
+ * servers simply omit the field.
  */
-export declare function fetchStyleCheckFeedback(params: StyleCheckParams): Promise<string>;
+export interface CloudAIFeedback {
+    feedback: string;
+    quotaWarning: string | null;
+}
+/**
+ * POST to `/api/style-check`. Returns the feedback (and any quota warning)
+ * on success; throws an Error with the underlying failure reason on a
+ * non-OK response or a network error — including the LIMITS-5.1
+ * quota-exceeded error, whose message carries the billing-page upgrade link.
+ */
+export declare function fetchStyleCheckFeedback(params: StyleCheckParams): Promise<CloudAIFeedback>;
 export interface ReviewTestParams {
     apiBaseUrl: string;
     projectId: string;
@@ -39,11 +51,12 @@ export interface ReviewTestParams {
     }>;
 }
 /**
- * POST to `/api/review-test`. Returns the feedback text on success;
- * throws an Error with the underlying failure reason on a non-OK
- * response or a network error.
+ * POST to `/api/review-test`. Returns the feedback (and any quota warning)
+ * on success; throws an Error with the underlying failure reason on a
+ * non-OK response or a network error — including the LIMITS-5.1
+ * quota-exceeded error, whose message carries the billing-page upgrade link.
  */
-export declare function fetchReviewTestFeedback(params: ReviewTestParams): Promise<string>;
+export declare function fetchReviewTestFeedback(params: ReviewTestParams): Promise<CloudAIFeedback>;
 export interface ProjectContext {
     projectContext: string | null;
     requirementsStyleContext: string | null;

package/dist/requirements/cloud-ai.js

@@ -14,9 +14,10 @@
  */
 export const DEFAULT_API_BASE_URL = "https://app.dotrequirements.io";
 /**
- * POST to `/api/style-check`. Returns the feedback text on success;
- * throws an Error with the underlying failure reason on a non-OK
- * response or a network error.
+ * POST to `/api/style-check`. Returns the feedback (and any quota warning)
+ * on success; throws an Error with the underlying failure reason on a
+ * non-OK response or a network error — including the LIMITS-5.1
+ * quota-exceeded error, whose message carries the billing-page upgrade link.
  */
 export async function fetchStyleCheckFeedback(params) {
     const response = await fetch(`${params.apiBaseUrl}/api/style-check`, {
@@ -35,12 +36,13 @@ export async function fetchStyleCheckFeedback(params) {
         throw new Error(errorData.error || response.statusText);
     }
     const data = (await response.json());
-    return data.feedback;
+    return { feedback: data.feedback, quotaWarning: data.quotaWarning ?? null };
 }
 /**
- * POST to `/api/review-test`. Returns the feedback text on success;
- * throws an Error with the underlying failure reason on a non-OK
- * response or a network error.
+ * POST to `/api/review-test`. Returns the feedback (and any quota warning)
+ * on success; throws an Error with the underlying failure reason on a
+ * non-OK response or a network error — including the LIMITS-5.1
+ * quota-exceeded error, whose message carries the billing-page upgrade link.
  */
 export async function fetchReviewTestFeedback(params) {
     const response = await fetch(`${params.apiBaseUrl}/api/review-test`, {
@@ -58,7 +60,7 @@ export async function fetchReviewTestFeedback(params) {
         throw new Error(errorData.error || response.statusText);
     }
     const data = (await response.json());
-    return data.feedback;
+    return { feedback: data.feedback, quotaWarning: data.quotaWarning ?? null };
 }
 /**
  * Query Convex for project-level AI context (project description and

package/dist/requirements/style-guide-file.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Filesystem access for the style guide — kept apart from the generator itself.
+ *
+ * `style-guide.ts` is imported by the web app to serve the same primer to chat
+ * agents (REMOTE-MCP-10), which have no repo to read. Everything in that module
+ * must therefore stay free of `node:fs`; the workspace lookups live here, where
+ * only the CLI reaches them. This mirrors the split the schema module already
+ * makes between its node and browser entry points.
+ */
+/**
+ * Conventional location of a project's STYLE.md, relative to the workspace
+ * root. Exported so callers (init, push/pull, tests) can reference one place.
+ */
+export declare const STYLE_MD_PATH = ".requirements/STYLE.md";
+/**
+ * Read `.requirements/STYLE.md` if the workspace has one. Returns the file
+ * contents on success, `null` if the file is absent. Empty / whitespace-only
+ * files are treated as absent so the bundled defaults still apply.
+ */
+export declare function readLocalStyleGuide(workspaceRoot: string): string | null;
+//# sourceMappingURL=style-guide-file.d.ts.map

package/dist/requirements/style-guide-file.js

@@ -0,0 +1,30 @@
+/**
+ * Filesystem access for the style guide — kept apart from the generator itself.
+ *
+ * `style-guide.ts` is imported by the web app to serve the same primer to chat
+ * agents (REMOTE-MCP-10), which have no repo to read. Everything in that module
+ * must therefore stay free of `node:fs`; the workspace lookups live here, where
+ * only the CLI reaches them. This mirrors the split the schema module already
+ * makes between its node and browser entry points.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Conventional location of a project's STYLE.md, relative to the workspace
+ * root. Exported so callers (init, push/pull, tests) can reference one place.
+ */
+export const STYLE_MD_PATH = ".requirements/STYLE.md";
+/**
+ * Read `.requirements/STYLE.md` if the workspace has one. Returns the file
+ * contents on success, `null` if the file is absent. Empty / whitespace-only
+ * files are treated as absent so the bundled defaults still apply.
+ */
+export function readLocalStyleGuide(workspaceRoot) {
+    const fullPath = join(workspaceRoot, STYLE_MD_PATH);
+    if (!existsSync(fullPath)) {
+        return null;
+    }
+    const contents = readFileSync(fullPath, "utf-8");
+    return contents.trim().length > 0 ? contents : null;
+}
+//# sourceMappingURL=style-guide-file.js.map

package/dist/requirements/style-guide.d.ts

@@ -11,37 +11,35 @@
  *
  * If the project has a `.requirements/STYLE.md`, callers can pass its
  * contents via `localStyleGuide` to use that body in place of the bundled
- * defaults. See {@link readLocalStyleGuide} for the lookup helper.
+ * defaults. See `readLocalStyleGuide` in ./style-guide-file.ts (CLI-only —
+ * this module stays free of node:fs so the web can serve the same primer).
  */
 import type { FlattenedRequirement } from "./index.js";
 /**
- * Conventional location of a project's STYLE.md, relative to the workspace
- * root. Exported so callers (init, push/pull, tests) can reference one place.
+ * The only fields the guide reads off a requirement.
+ *
+ * Deliberately narrower than {@link FlattenedRequirement}, which is file-shaped
+ * (`sourceFile`, `documentTitle`). The web serves this same guide from cloud
+ * requirements, which have no file to name (REMOTE-MCP-10) — asking only for
+ * what's used lets both callers pass what they actually have instead of
+ * inventing filenames.
  */
-export declare const STYLE_MD_PATH = ".requirements/STYLE.md";
+export type StyleGuideRequirement = Pick<FlattenedRequirement, "id" | "label" | "path">;
 export interface GenerateStyleGuideParams {
-    /** Flattened view of the workspace's existing requirements, used to
-     * surface label patterns and key-prefix patterns in the output. Pass
-     * an empty array when no requirements exist yet. */
-    requirements: FlattenedRequirement[];
-    /** Project-owner-supplied custom guidance (currently sourced from the
-     * cloud project's `requirementsStyleContext` field). Pass null/undefined
-     * to omit. */
+    /** The existing requirements to discover label and key-prefix patterns from.
+     * Pass an empty array when none exist yet. */
+    requirements: StyleGuideRequirement[];
+    /** Project-owner-supplied custom guidance (sourced from the cloud project's
+     * `requirementsStyleContext` field). Pass null/undefined to omit. */
     customStyleGuidance?: string | null;
-    /** Suggested target path for the new file. Used only in the preamble
-     * and "Next Steps" section. Defaults to a generic example path. */
+    /** Suggested target path for the new file. Used only in the preamble and
+     * "Next Steps" section. Defaults to a generic example path. */
     filePath?: string;
-    /** Project-local STYLE.md contents. When provided and non-empty, this
-     * body replaces the bundled default; callers can fetch it via
-     * {@link readLocalStyleGuide}. */
+    /** Project-local STYLE.md contents. When provided and non-empty, this body
+     * replaces the bundled default. CLI-only — see `readLocalStyleGuide` in
+     * ./style-guide-file.ts. */
     localStyleGuide?: string | null;
 }
-/**
- * Read `.requirements/STYLE.md` if the workspace has one. Returns the file
- * contents on success, `null` if the file is absent. Empty / whitespace-only
- * files are treated as absent so the bundled defaults still apply.
- */
-export declare function readLocalStyleGuide(workspaceRoot: string): string | null;
 /**
  * Build the body of the bundled default style guide. This is the content
  * that lives inside the "# Requirements File Template" preamble — the