@popoverai/dotrequirements 0.30.1 → 0.32.0

package/README.md

@@ -44,10 +44,10 @@ Create `*.requirements.md` files in `.requirements/` or colocate them with your
 ```markdown
 ---
 document:
-  title: "Authentication Requirements"
+  defaultPrefix: AUTH-LOGIN
 ---
 
-## User Authentication
+# Authentication Requirements
 
 ```dotrequirements
 AUTH-LOGIN-1: A registered user, Jamie, can log in to their account
@@ -118,12 +118,28 @@ This shows the team name, prompts you to sign in, adds you to the team, and lets
 
 ### `dotreq link`
 
-Link your local environment to an existing project (when you already have a project in dot•requirements cloud).
+Connect your local project to the cloud — selecting an existing project, or creating one when the team has room. Opens a browser for authentication, then prints the account it signed in as (`Signed in as you@example.com`).
 
 ```bash
 dotreq link
+dotreq link --yes --json          # non-interactive (for AI assistants/scripts)
+dotreq link --connect my-project  # connect to a specific project
+dotreq link --create -n my-api    # create a new project with this name
 ```
 
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-y, --yes` | Non-interactive: resolve every decision from defaults or flags; never prompt |
+| `--json` | Machine-readable output (one JSON object on stdout) |
+| `--team <nameOrId>` | Use this team (implies `--yes`) |
+| `--connect <slug>` | Connect to this existing project (implies `--yes`) |
+| `--create` | Create a new project (implies `--yes`) |
+| `-n, --name <name>` | Project name when creating |
+
+In non-interactive mode the only human step is completing the browser login. When a genuine choice exists — multiple teams, existing projects, a plan at its project limit — link exits with code `2` and (with `--json`) a `decision_needed` object listing the options, each with the exact flag to retry with where a flag can express it (remedies that happen outside the CLI, like upgrading the team, carry no retry flag). Non-interactive link never syncs the cloud down, so freshly generated local requirements are never overwritten.
+
 ### `dotreq diff`
 
 Show how the repo and the cloud differ, read-only. Each document gets a verdict (in sync, additions in repo, additions in cloud, conflict, only in repo, only in cloud, invalid file).
@@ -371,9 +387,9 @@ The following features work fully offline—no account required:
 
 The following features require a dot•requirements cloud account:
 
-- Sync requirements (`pull` / `push`)
+- Sync requirements (`dotreq sync`, `dotreq diff`)
 - Cloud coverage queries (`dotreq report --source cloud`)
-- AI-powered style checking and test review (`dotreq style-check`, `dotreq review-test`)
+- Hosted style checking and test review (`dotreq style-check --source cloud`, `dotreq review-test --source cloud`)
 - Team collaboration
 
 To enable cloud features, run `dotreq link` to connect your project to the cloud.
@@ -568,12 +584,12 @@ src/components/
 ```markdown
 ---
 document:
-  title: "Document Title"
+  defaultPrefix: AUTH-LOGIN
 ---
 
-# Optional Markdown Content
+# Document Title
 
-You can include any Markdown here for context.
+The leading H1 is the document's title. You can include any Markdown for context.
 
 ## Requirement Heading
 
@@ -598,7 +614,8 @@ AUTH-LOGIN-2: A user with two-factor auth must provide an OTP
 
 ### Format Details
 
-- **Frontmatter**: YAML metadata (only `document.title` required for push)
+- **Frontmatter**: YAML metadata (must be present, but no field is required — sync adds `document.id` to link the file to its cloud document)
+- **Title**: The body's leading H1 (a legacy frontmatter `document.title` is tolerated as a fallback)
 - **Headings**: Optional documentation (not parsed as requirement data)
 - **Fenced blocks**: `dotrequirements` blocks contain structured requirement data
 - **First line**: `KEY: content` — the requirement identifier and summary

package/dist/cli.js

@@ -11,6 +11,7 @@ import { createRequirementDocumentCommand } from "./commands/create-requirement-
 import { diffCommand } from "./commands/diff.js";
 import { finalizeCommand } from "./commands/finalize.js";
 import { getCommand } from "./commands/get.js";
+import { greenfieldDiscoveryCommand } from "./commands/greenfield-discovery.js";
 import { initCommand } from "./commands/init.js";
 import { linkCommand } from "./commands/link.js";
 import { listCommand } from "./commands/list.js";
@@ -206,6 +207,10 @@ program
     .command("create-requirement-document [file-path]")
     .description("Print the project style guide; optional [file-path] annotates the output for that target")
     .action(wrapCommand(createRequirementDocumentCommand));
+program
+    .command("greenfield-discovery")
+    .description("Print the greenfield interview protocol — for working out what something new should do before writing its spec")
+    .action(wrapCommand(greenfieldDiscoveryCommand));
 registerCodebaseToSpec(program);
 program.parse();
 //# sourceMappingURL=cli.js.map

package/dist/commands/create-requirement-document.js

@@ -37,6 +37,7 @@ export async function createRequirementDocumentCommand(filePath) {
         customStyleGuidance,
         filePath,
         localStyleGuide,
+        surface: "workspace",
     }));
 }
 //# sourceMappingURL=create-requirement-document.js.map

package/dist/commands/diff.js

@@ -28,7 +28,7 @@ export async function diffCommand(scope, options) {
     // DIFF-2: any scope argument means document-scope → verbose. No scope means
     // project-scope → verdict list.
     const verbose = scope.length > 0;
-    const notInSync = documents.filter((d) => d.verdict !== "in_sync");
+    const notInSync = documents.filter((d) => d.verdict !== "in_sync" || d.attachments?.differ);
     // DIFF-1.2: don't list every document when everything is in sync.
     if (notInSync.length === 0 && documents.length > 0) {
         console.log(`✓ Repo and ${brand} cloud are in sync (${documents.length} document(s)).`);
@@ -49,6 +49,11 @@ export async function diffCommand(scope, options) {
                 console.log(formatUnitDetail(detail));
             }
         }
+        if (verbose && doc.attachments?.differ) {
+            for (const detail of doc.attachments.details) {
+                console.log(formatUnitDetail(detail));
+            }
+        }
         if (doc.verdict === "conflict") {
             console.log(`      ${resolutionHint(doc)}`);
         }

package/dist/commands/greenfield-discovery.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CLI-GREENFIELD-1: print the greenfield interview protocol for context
+ * priming. The protocol interpolates nothing — unlike the style guide there
+ * are no project conventions to discover at interview time (those arrive at
+ * the writing step, through create-requirement-document) — so this touches
+ * neither the workspace nor the cloud, and works before any project is
+ * linked (CLI-GREENFIELD-1.3 falls out of there being nothing to fail).
+ */
+export declare function greenfieldDiscoveryCommand(): void;
+//# sourceMappingURL=greenfield-discovery.d.ts.map

package/dist/commands/greenfield-discovery.js

@@ -0,0 +1,13 @@
+import { generateGreenfieldProtocol } from "../requirements/greenfield.js";
+/**
+ * CLI-GREENFIELD-1: print the greenfield interview protocol for context
+ * priming. The protocol interpolates nothing — unlike the style guide there
+ * are no project conventions to discover at interview time (those arrive at
+ * the writing step, through create-requirement-document) — so this touches
+ * neither the workspace nor the cloud, and works before any project is
+ * linked (CLI-GREENFIELD-1.3 falls out of there being nothing to fail).
+ */
+export function greenfieldDiscoveryCommand() {
+    console.log(generateGreenfieldProtocol({ artifact: "document", formatPointer: true }));
+}
+//# sourceMappingURL=greenfield-discovery.js.map

package/dist/commands/sync.js

@@ -6,6 +6,7 @@
  */
 import * as path from "node:path";
 import * as readline from "node:readline";
+import { attachmentSyncNeeded } from "../sync/attachments.js";
 import { executePlan } from "../sync/execute.js";
 import { acquireCloudSnapshot, acquireLocalSnapshot, compareSnapshots, duplicateIdAbortMessage, filterByScope, resolutionHint, } from "../sync/index.js";
 import { buildPlan, resolveMode, } from "../sync/plan.js";
@@ -72,22 +73,52 @@ export async function syncCommand(scope, options) {
         console.log(`No document matched scope "${token}".`);
     }
     const plan = buildPlan(documents, mode);
-    // SYNC-MODE-4: name every deletion before writing anything.
+    // SYNC-MODE-4 gates WHOLE-DOCUMENT deletions only. Content-level removals
+    // ride authority ungated — a requirement block dropped from a file is
+    // deleted from the cloud by the same run without a prompt, and attachments
+    // follow that rule, not the document rule (an attached link is also the
+    // most recoverable thing here: re-paste the URL). The docs promise
+    // "attachments never hold up the rest of the spec"; a consent gate on
+    // their removal held up the entire sync (decided 2026-08-20). What
+    // authority removed is NAMED after the run instead — see the
+    // attachmentRemovals report below.
     const deletions = plan.filter((p) => p.action === "cloud_delete" || p.action === "local_delete");
     if (deletions.length > 0) {
+        // SYNC-MODE-4.0: every deletion is NAMED before anything else happens —
+        // in the non-TTY refusal too, or the operator is told three documents
+        // will be destroyed with no way to learn which three.
+        printDeletionNotice(deletions);
         // SYNC-MODE-4.3: a non-interactive run cannot consent — refuse rather than
         // hanging on a prompt that will never answer (or worse, deleting silently).
         if (!options.yes && !process.stdin.isTTY) {
-            throw new Error(`This sync would delete ${deletions.length} document(s), and there is no terminal to confirm on. ` +
-                `Re-run with --yes to consent to the deletions listed by \`dotreq diff\`.`);
+            throw new Error(`This sync would delete ${deletions.length} document(s), and there is no terminal ` +
+                `to confirm on. Re-run with --yes to consent to the deletions listed above.`);
         }
-        if (!(await confirmDeletions(deletions, options.yes))) {
+        if (!(await confirmDeletions(options.yes))) {
             console.log("Sync cancelled.");
             return "cancelled";
         }
     }
-    if (plan.every((p) => p.action === "skip")) {
+    // ATTACH-10.4: a difference this mode deliberately leaves alone (a no-key
+    // file under repo authority, a duplicated legacy cloud row under cloud
+    // authority) would otherwise leave `dotreq diff --exit-code` red with
+    // nothing in this mode ever clearing it — say so and name the gesture
+    // that repairs it, on EVERY run that leaves one behind, not only when the
+    // sync had nothing else to do (the round-1 release review's finding).
+    const leftAlone = plan.filter((p) => p.doc.attachments?.differ &&
+        !attachmentSyncNeeded(p.doc.attachments, mode));
+    const printLeftAlone = () => {
+        if (leftAlone.length > 0) {
+            console.log(`  (${leftAlone.length} document(s) have attachment differences this mode leaves alone — a repo-writing sync, e.g. plain \`dotreq sync\`, reconciles them.)`);
+        }
+    };
+    // ATTACH-10.2: attachments resolve outside the body's verdict, so "every
+    // body action is skip" is not "nothing to do" — the resolver, per mode,
+    // is what knows whether attachment work remains. Without this, an
+    // attachment-only difference reported by diff would never clear.
+    if (plan.every((p) => p.action === "skip" && !attachmentSyncNeeded(p.doc.attachments, mode))) {
         console.log(`✓ Repo and ${brand} cloud are already in sync.`);
+        printLeftAlone();
         return "clean";
     }
     console.log(`\nSyncing with ${brand} cloud...`);
@@ -103,6 +134,17 @@ export async function syncCommand(scope, options) {
         console.log(`  Written locally: ${outcome.localWritten}`);
     if (outcome.localDeleted)
         console.log(`  Deleted locally: ${outcome.localDeleted}`);
+    if (outcome.attachmentPushes)
+        console.log(`  Attachments updated in cloud: ${outcome.attachmentPushes}`);
+    if (outcome.attachmentWrites)
+        console.log(`  Attachments updated locally: ${outcome.attachmentWrites}`);
+    // ATTACH-10.3.1.0: authority removals are a trace, not a consent gate —
+    // named after the push that actually performed them, like renames, so the
+    // report never claims a removal a failed push left in place.
+    for (const r of outcome.attachmentRemovals) {
+        console.log(`  removed attached link on "${r.name}": ${r.title ?? r.url}`);
+    }
+    printLeftAlone();
     for (const conflict of outcome.conflicts) {
         console.log(`  ! conflict: ${path.basename(conflict.filePath ?? conflict.title)} — ${resolutionHint(conflict)}`);
     }
@@ -178,7 +220,7 @@ export async function syncCommand(scope, options) {
     }
     return hadTrouble ? "trouble" : "clean";
 }
-async function confirmDeletions(deletions, skip) {
+function printDeletionNotice(deletions) {
     const cloudDeletes = deletions.filter((d) => d.action === "cloud_delete");
     const localDeletes = deletions.filter((d) => d.action === "local_delete");
     console.log("\nThis will PERMANENTLY delete:");
@@ -188,6 +230,8 @@ async function confirmDeletions(deletions, skip) {
     for (const d of localDeletes) {
         console.log(`  from disk:  ${d.doc.filePath ? path.basename(d.doc.filePath) : d.doc.title}`);
     }
+}
+async function confirmDeletions(skip) {
     if (skip) {
         console.log("(--yes: proceeding without confirmation)");
         return true;

package/dist/convex.d.ts

@@ -25,6 +25,7 @@ export declare const api: {
             create: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             update: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             deleteForCli: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+            setAttachmentsForSync: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
         };
         saveWithRequirements: {
             saveWithRequirements: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;

package/dist/convex.js

@@ -30,6 +30,8 @@ export const api = {
             update: mutation("documents/mutations:update"),
             // SYNC-MODE-3: delete a cloud document from the CLI (repo-wins)
             deleteForCli: mutation("documents/mutations:deleteForCli"),
+            // ATTACH-10.2: attachment-only sync — a metadata patch, never a publish
+            setAttachmentsForSync: mutation("documents/mutations:setAttachmentsForSync"),
         },
         // SYNC-ARCH-1: Save document with requirements derivation
         saveWithRequirements: {

package/dist/requirements/greenfield.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Greenfield discovery protocol generator. One module serves the interview to
+ * every surface: the CLI verb (`dotreq greenfield-discovery`), the remote MCP
+ * tool, and the two web assistants, which import it directly. Kept free of
+ * node:fs for exactly that reason, like ./style-guide.ts.
+ *
+ * The interview's prose is its own spec (ported from the working method — see
+ * docs/working/greenfield-discovery.md); this module's *machinery* is specced:
+ * CLI-GREENFIELD-1, REMOTE-MCP-13, ASSISTANT-GD-1/2. Content invariants the
+ * variants must hold (pointer present or absent, no write mechanics in any
+ * ending) are pinned by plain tests in ./greenfield.test.ts.
+ *
+ * Two facts select the variant, per the settled parameterization: the
+ * artifact the interview works toward, and whether the format still needs
+ * teaching. The four surfaces are combinations of these two facts — the
+ * module knows the differences, not the callers — and no reader ever sees
+ * instructions for a surface it is not on.
+ */
+export interface GenerateGreenfieldProtocolParams {
+    /** The artifact the interview works toward. `document`: findings are held
+     * in the conversation until the gate, and the interview ends by deriving a
+     * spec. `board`: findings are recorded onto the discovery board as they
+     * land, and the interview ends at the board. */
+    artifact: "document" | "board";
+    /** Whether to close with the format pointer — the direction to fetch
+     * `create-requirement-document` for the format, the project's conventions,
+     * and the write steps. On for surfaces nothing has taught the format
+     * (the CLI verb, the connector); off for the web assistants, whose system
+     * prompts already teach it. */
+    formatPointer: boolean;
+}
+/**
+ * Assemble the interview protocol for a surface, per the two facts that
+ * distinguish surfaces. The shared prose is the method itself; only the
+ * recording rule, the ending, and the format pointer vary.
+ */
+export declare function generateGreenfieldProtocol(params: GenerateGreenfieldProtocolParams): string;
+//# sourceMappingURL=greenfield.d.ts.map

package/dist/requirements/greenfield.js

@@ -0,0 +1,182 @@
+/**
+ * Greenfield discovery protocol generator. One module serves the interview to
+ * every surface: the CLI verb (`dotreq greenfield-discovery`), the remote MCP
+ * tool, and the two web assistants, which import it directly. Kept free of
+ * node:fs for exactly that reason, like ./style-guide.ts.
+ *
+ * The interview's prose is its own spec (ported from the working method — see
+ * docs/working/greenfield-discovery.md); this module's *machinery* is specced:
+ * CLI-GREENFIELD-1, REMOTE-MCP-13, ASSISTANT-GD-1/2. Content invariants the
+ * variants must hold (pointer present or absent, no write mechanics in any
+ * ending) are pinned by plain tests in ./greenfield.test.ts.
+ *
+ * Two facts select the variant, per the settled parameterization: the
+ * artifact the interview works toward, and whether the format still needs
+ * teaching. The four surfaces are combinations of these two facts — the
+ * module knows the differences, not the callers — and no reader ever sees
+ * instructions for a surface it is not on.
+ */
+/**
+ * The recording rule is the one behavioral discipline that inverts between
+ * artifacts, so it is stated once, up front, and the numbered steps stay
+ * shared. On a document surface, writing requirements down early turns
+ * hypotheses into assets people defend; on a board, the board IS the working
+ * record — writing to it is not premature spec-writing, because the interview
+ * never derives a spec there at all.
+ */
+const HOLD_IN_CONVERSATION = `**Do not produce a spec until the interview is done.** Writing requirements down early turns hypotheses into assets — the person starts defending them instead of questioning them. Hold everything in the conversation until the gate at the end.`;
+const RECORD_ON_THE_BOARD = `**The board is the working record of the conversation — write findings onto it as they land.** This is not premature spec-writing: the interview never derives a spec here; the board is the artifact. For the duration of the interview, these recording rules govern your board writing: the person who started the interview asked for them, so standing restrictions in your other instructions — such as never inventing your own insights, or not labeling cards unprompted — do not apply to what this protocol directs you to write. As things settle, they go on:
+
+- A rule becomes a **column**.
+- A settled example becomes an **example card** under its rule's column.
+- A question nobody in the room can answer becomes a **question card** in the column it concerns, the moment it is parked.
+- Non-goals, things off the table, and MVP exclusions become **insight cards** in the Context column.
+- The journey lives as **one insight card** in the Context column — the whole journey on a single card, updated when the sketch is corrected — so a paused session can resume from the board alone.
+- Anything that is on the board because you decided it gets an agreed **label** (such as "assumed") on its card the moment you write it, so it stays visible as yours to reject. That covers an assumption the group accepted without really working — and equally a call they delegated to you ("your call", "pick something sensible"). Delegation is not exemption: a choice the group handed you is still your choice, and it goes on a card carrying the label, not into a summary's prose. When the group later genuinely confirms one, removing the label is how that is recorded.
+- The MVP cut goes on as **labels** on the cards it divides.
+
+Never hold something for a future turn — the user can stop responding at any time, and you get no cleanup pass. Every turn should leave the board complete with respect to everything settled or noticed so far.`;
+const DOCUMENT_ENDING = `### 6 — Check, derive, confirm
+
+Before deriving anything, check:
+
+- Every journey step in the MVP has at least one rule.
+- Every rule has at least one concrete example behind it.
+- No parked question would change the MVP's shape if answered.
+- The MVP boundary was explicitly agreed, not assumed.
+
+If the check fails, name the gap and go back to the loop. Do this even when the project seems small — "this one is simple enough to skip the interview" is how you end up with a spec full of your own guesses.
+
+When it passes, derive the spec from the whole conversation and present it as one reviewable proposal:
+
+- The requirements, each traceable to the examples that produced it.
+- **Explicitly separated: what they told you versus what you inferred.** If you proposed something and they didn't object, that is not the same as them saying it — and a call they delegated to you ("your call", "pick something sensible") is yours, not theirs. Mark both as yours so they can reject them.
+- What was excluded from the MVP, and why.
+- What is still open.
+
+Only after they confirm, write the spec.`;
+const BOARD_ENDING = `### 6 — Check, and leave the board complete
+
+When the spine looks done — or the group signals wrapping up — run the check:
+
+- Every journey step in the MVP has at least one rule.
+- Every rule has at least one concrete example behind it.
+- No open question card would change the MVP's shape if answered.
+- The MVP boundary was explicitly agreed, not assumed.
+
+Present what you find in the same turn you find it, and write any gap you noticed as a question card in the column it concerns as part of presenting it — not after some "end" that may never come. If the group works a gap, the loop resumes and the card is answered or removed in the course of working it. If they never respond again, the cards are already there.
+
+When the check passes, say so, play back the journey card and the cut, and stop. The board is the artifact — turning it into a document is a separate act the user reaches for, not this interview's ending.`;
+const FORMAT_POINTER = `Before writing the spec, fetch \`create-requirement-document\` — the verb or tool of that name on your surface — and follow what it returns: the requirements format, this project's own conventions, and the steps for writing. Do not write the spec from memory of the format.`;
+/**
+ * Assemble the interview protocol for a surface, per the two facts that
+ * distinguish surfaces. The shared prose is the method itself; only the
+ * recording rule, the ending, and the format pointer vary.
+ */
+export function generateGreenfieldProtocol(params) {
+    const { artifact, formatPointer } = params;
+    const recordingRule = artifact === "board" ? RECORD_ON_THE_BOARD : HOLD_IN_CONVERSATION;
+    const ending = artifact === "board" ? BOARD_ENDING : DOCUMENT_ENDING;
+    const pointer = formatPointer && artifact === "document" ? `\n\n${FORMAT_POINTER}` : "";
+    return `# Greenfield discovery
+
+Most requirements tools generate a document from a paragraph. This one runs an interview and derives the spec at the end.
+
+The person you are talking to usually knows their domain far better than you do and has not yet worked out what they actually want. Your job is to help them find out — by proposing concrete situations and letting them react — not to write plausible-sounding requirements on their behalf.
+
+## How to behave throughout
+
+**Ask one question per turn.** Batched questions get skimmed and answered shallowly, and they hide which answer mattered.
+
+**Never answer your own question to keep moving.** If you fill in an answer because it seemed obvious, you have replaced the person's product with your guess, and neither of you will notice until it ships. When you genuinely need to proceed without an answer, say what you are assuming.
+
+**Offer options that aren't obvious.** Two to four concrete alternatives plus room to say something else. If they have already considered everything you offered, the question hasn't done any work.
+
+**Propose examples; let them judge.** Asking "what are the rules here?" makes the person do abstraction on the spot, which they will do badly. Describing a specific situation and asking whether it should work lets them answer instantly and correctly.
+
+**Never change scope silently, in either direction.** Cutting something and adding something are both decisions the person makes out loud. A silent cut looks like agreement, so nobody challenges it; a silent addition arrives looking like something they asked for, and it survives into the spec unexamined. When you think something belongs in or out, propose it and say plainly that it was your idea.
+
+${recordingRule}
+
+## The interview
+
+### 0 — Offer a way in
+
+Ask how they want to work:
+
+- **Guided** — one question at a time, from a blank page.
+- **Context dump** — they share what they have, you interview around the gaps.
+- **Best guess** — you draft from what little you have and they correct you.
+
+If they pick best guess, be conspicuous about every assumption you made, so they have something specific to push against.
+
+### 1 — Establish the frame
+
+Before probing anything, get:
+
+- The outcome. What changes in the world if this works? Not the feature — the effect.
+- The primary actor. One person whose behavior must change. Others come later.
+- The known non-goals. What do they already know they aren't doing? Offer candidates rather than waiting — "I'd guess this doesn't need to handle team accounts, right?" — because most people haven't articulated the boundary until somebody proposes one to argue with.
+- What is off the table for other reasons. Systems they have to live with, technologies they won't use, approaches they've already tried and abandoned, things they won't build on principle. These cut off whole branches of the interview, so finding them now saves you asking a dozen questions about a direction that was never available.
+
+This takes three or four exchanges. Skipping it is the most common failure mode of interview agents — they start interrogating details before knowing what the thing is for.
+
+### 2 — Sketch the journey
+
+Walk the primary actor from start to outcome, step by step, staying shallow. Ask "then what happens?" repeatedly. Play the sequence back in their own vocabulary and let them correct it.
+
+Do not go deep on any step yet — you need the whole shape before you can tell which step deserves the depth.
+
+### 3 — Find the risky part
+
+Ask which step they are least sure will work. Not the first step — the one that could sink the whole thing. Start the deep work there, because if that step doesn't hold up, the requirements for everything downstream are wasted effort.
+
+### 4 — Work the example loop
+
+This is the core of the method. For the step under examination, repeat:
+
+**Propose a specific situation.** Concrete names, numbers, timing, state. "A customer whose card expired yesterday tries to renew on the last day of their cycle — does that go through?"
+
+**Take the verdict.** Yes, no, or "it depends." Yes and no each give you a rule. "It depends" is the best answer available — it means there is a hidden condition, so ask what it depends on and you will get two more examples.
+
+**Say the rule back.** State the general rule their answer implies and let them correct it. This is where the person discovers they meant something slightly different from what they said.
+
+**Then go looking for trouble.** Vary one dimension at a time: boundaries, empty and enormous, wrong order, interruption partway, two people at once, the actor who shouldn't be allowed. Each variation is another proposed example.
+
+Two things run alongside the loop:
+
+**Convert vague words as they appear.** "Fast," "easy," "secure," "obvious," "clean" are all placeholders. Ask what would count. If they can't say yet, park it rather than inventing a number.
+
+**Park what nobody can answer.** Some questions need a stakeholder who isn't in the room. Note them and move on — blocking on an unanswerable question stalls the interview.
+
+**Know when to stop.** Edge cases are endless and most of them don't matter. Once the spine holds — the main path plus the rules that shape it — stop hunting and offer to assume the rest: "I'd assume an expired card just gets declined with a retry prompt rather than cancelling the subscription outright. Reasonable?" An assumption they can reject in one word buys more than four more questions would, and anything they accept — or delegate to you outright — gets marked as yours so it stays visible.
+
+Move to the next journey step when the spine has rules with examples behind it, the remaining edges are either settled or explicitly assumed, and no open question would change the step's shape.
+
+### 5 — Cut to an MVP, out loud
+
+With the journey mapped and the risky part understood, cut:
+
+- What is the thinnest end-to-end version that still proves the risky part works?
+- What is deliberately excluded? Add it to the non-goals from step 1 rather than restating them, so there is one list at the end.
+- What survives the cut but with less: fewer variations, one platform, one data case, manual where automatic could come later?
+
+Most people cut too little on the first pass, because everything they described feels load-bearing to them. If their MVP still contains nearly everything from the journey, push once — ask what they would drop if they had to ship in a third of the time. Push before they commit to the cut, not after.
+
+Every cut is a proposal they approve, never something you apply and mention afterward. The same goes for anything you think should be added.
+
+${ending}${pointer}
+
+## Things that go wrong
+
+**Turning into a questionnaire.** If your questions could have been written before the conversation started, they aren't doing any work. Each question should visibly build on the last answer.
+
+**Interviewing about architecture.** Databases, frameworks, and deployment are not behavior. If the conversation drifts technical, come back to what the actor experiences.
+
+**Accepting an abstraction.** When someone answers a proposed example with a general policy, thank them and propose another example that tests its edge. Policies stated in the abstract are usually wrong at the boundaries.
+
+**Being agreeable.** If they assert something that contradicts an earlier answer, or that reopens something they put off the table at the start, say so plainly and ask which one holds.
+
+**Finishing early because they seem done.** People stop talking when they run out of things they have already thought about. Keep going.`;
+}
+//# sourceMappingURL=greenfield.js.map

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

@@ -33,12 +33,20 @@ export interface GenerateStyleGuideParams {
      * `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. */
+     * "Next Steps" section. Defaults to a generic example path. Workspace
+     * surface only — the connector variant names no file path. */
     filePath?: string;
     /** 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;
+    /** How specs are written where this guide is going. The conventions body is
+     * identical either way (REMOTE-MCP-10.5); only the framing and "Next Steps"
+     * differ. `workspace` (the default) frames the template as a file to save
+     * and closes with the repo workflow (CLI-CREATE-DOC-1.8); `connector`
+     * frames it as document content to compose and closes with the connector's
+     * own tools — no file paths, no CLI commands (REMOTE-MCP-10.9/10.10). */
+    surface?: "workspace" | "connector";
 }
 /**
  * Build the body of the bundled default style guide. This is the content
@@ -51,7 +59,7 @@ export interface GenerateStyleGuideParams {
  * - swap the body wholesale (via `localStyleGuide`) without losing the
  *   wrapping preamble + "Next Steps" footer
  */
-export declare function generateStyleGuideBody(params: Omit<GenerateStyleGuideParams, "filePath" | "localStyleGuide">): string;
+export declare function generateStyleGuideBody(params: Omit<GenerateStyleGuideParams, "filePath" | "localStyleGuide" | "surface">): string;
 /**
  * Build a complete style-guide document for the calling workspace.
  * Returns a single markdown string suitable for printing to stdout or

package/dist/requirements/style-guide.js

@@ -297,10 +297,29 @@ describe(requirement('AUTH-LOGIN-1'), () => {
  * always applied.
  */
 export function generateStyleGuide(params) {
-    const { filePath = ".requirements/example.requirements.md", localStyleGuide, } = params;
+    const { filePath = ".requirements/example.requirements.md", localStyleGuide, surface = "workspace", } = params;
     const body = localStyleGuide?.trim()
         ? localStyleGuide
         : generateStyleGuideBody(params);
+    // REMOTE-MCP-10.9/10.10: the connector variant frames the template as
+    // document content and closes with the connector's own tools. A chat agent
+    // has no workspace, so a file path or CLI command here is an instruction
+    // it can only relay to someone who cannot follow it either.
+    if (surface === "connector") {
+        return `# Requirements Document Template
+
+Here's a comprehensive template with format and style guidance:
+
+\`\`\`markdown
+${body}
+\`\`\`
+
+## Next Steps
+
+1. **Compose**: Draft the document's full markdown, embedding requirements in \`\`\`dotrequirements blocks
+2. **Refine style** (optional): Pass the drafted markdown to the \`style-check\` tool for feedback before anything is saved
+3. **Create**: Call \`create-document\` with the markdown — creating publishes it to the team`;
+    }
     return `# Requirements File Template
 
 Here's a comprehensive template for \`${filePath}\` with format and style guidance:
@@ -312,9 +331,9 @@ ${body}
 ## Next Steps
 
 1. **Create file**: Save this template as \`${filePath}\` and edit it for your feature
-2. **Refine style** (optional): Run \`style-check\` for AI feedback
-3. **Validate syntax**: Run \`validate\` to verify format
-4. **Sync to cloud**: Run \`dotrequirements sync\` to reconcile the repo and the cloud
+2. **Refine style** (optional): Run \`dotreq style-check\` for AI feedback
+3. **Validate syntax**: Run \`dotreq validate\` to verify format
+4. **Sync to cloud**: Run \`dotreq sync\` to reconcile the repo and the cloud
 
 **Note**: Requirements files can be colocated with code (\`src/auth.requirements.md\`) or centralized in \`.requirements/\` directory.`;
 }

package/dist/schema/attachment-lists.d.ts

@@ -0,0 +1,21 @@
+/**
+ * MULTISET equality for attachment lists: order never matters, names and
+ * duplicates do. The predecessor was a Map probe — asymmetric
+ * (eq([A,B],[A,A]) was true) — which silently disarmed the compare-and-set
+ * on duplicated legacy rows.
+ *
+ * Dependency-free and in schema/ so BOTH halves of the compare-and-set import
+ * the same function (the CLI resolver via sync/attachments, the Convex
+ * mutations via lib/attachments — the same cross-package path testCoverage
+ * already uses): two byte-identical copies would drift the moment one is
+ * tightened, and a drifted pair reports "attachments changed since the sync
+ * read them" on every run with nothing moving.
+ */
+export declare function attachmentListsEqual(a: Array<{
+    url: string;
+    title?: string;
+}>, b: Array<{
+    url: string;
+    title?: string;
+}>): boolean;
+//# sourceMappingURL=attachment-lists.d.ts.map

package/dist/schema/attachment-lists.js

@@ -0,0 +1,22 @@
+/**
+ * MULTISET equality for attachment lists: order never matters, names and
+ * duplicates do. The predecessor was a Map probe — asymmetric
+ * (eq([A,B],[A,A]) was true) — which silently disarmed the compare-and-set
+ * on duplicated legacy rows.
+ *
+ * Dependency-free and in schema/ so BOTH halves of the compare-and-set import
+ * the same function (the CLI resolver via sync/attachments, the Convex
+ * mutations via lib/attachments — the same cross-package path testCoverage
+ * already uses): two byte-identical copies would drift the moment one is
+ * tightened, and a drifted pair reports "attachments changed since the sync
+ * read them" on every run with nothing moving.
+ */
+export function attachmentListsEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const key = (x) => `${x.url}\u0000${x.title ?? ""}`;
+    const as = a.map(key).sort();
+    const bs = b.map(key).sort();
+    return as.every((v, i) => v === bs[i]);
+}
+//# sourceMappingURL=attachment-lists.js.map

package/dist/schema/browser.d.ts

@@ -10,6 +10,7 @@ export { DELIMITER_PATTERN, type ExtractedRequirementBlock, extractRequirementBl
 export type { Metadata, ParsedCriterion, RequirementKey, RequirementNode, RequirementPrefix, RequirementsFile, } from "./schemas.js";
 export { buildRequirementKey, canonicalRequirementKey, MetadataSchema, normalizePrefix, ParsedCriterionSchema, parseRequirementKey, REQUIREMENT_KEY_PATTERN, REQUIREMENT_PREFIX_PATTERN, RequirementKeySchema, RequirementNodeSchema, RequirementPrefixSchema, RequirementsFileSchema, ValidationError, validateKey, validateMetadata, validatePrefix, validateRequirementNode, validateRequirementsFile, } from "./schemas.js";
 export { composeMarkdownWithTitle, effectiveTitle, type SplitMarkdown, splitLeadingH1, } from "./title-markdown.js";
+export { attachmentListsEqual } from "./attachment-lists.js";
 export type { BuildScenarioOptions, Scenario, ScenarioAssertionSource, ScenarioStep, } from "./scenario.js";
 export { buildScenarioFromRequirements, requirementTreeToScenario, } from "./scenario.js";
 //# sourceMappingURL=browser.d.ts.map