@popoverai/dotrequirements 0.30.1 → 0.31.0

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/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/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

package/dist/schema/browser.js

@@ -25,6 +25,11 @@ ValidationError, validateKey, validateMetadata, validatePrefix, validateRequirem
 // Title semantics (pure TypeScript - browser-safe): the document title and
 // the markdown's leading H1 are the same thing (DOC-TITLE-3)
 export { composeMarkdownWithTitle, effectiveTitle, splitLeadingH1, } from "./title-markdown.js";
+// NOTE: parser.ts and resolver.ts are excluded because they use Node.js 'fs' module.
+// Use parser-core.ts functions above for browser/Convex environments.
+// Dependency-free; shared with the Convex mutations so both halves of the
+// attachments compare-and-set use one predicate (see attachment-lists.ts).
+export { attachmentListsEqual } from "./attachment-lists.js";
 // Scenario building (pure TypeScript - browser-safe, used by Convex Node actions)
 export { buildScenarioFromRequirements, requirementTreeToScenario, } from "./scenario.js";
 //# sourceMappingURL=browser.js.map

package/dist/schema/file-writer.d.ts

@@ -27,6 +27,23 @@ export type PrefixDirective =
  | "keep"
 /** Remove it — the authoritative side has no prefix. */
  | "clear";
+/**
+ * What this write does to `document.attachments` (ATTACH-10) — the same
+ * three readings the prefix has, for the same reason: an absent cloud list is
+ * not self-interpreting.
+ */
+export type AttachmentsDirective = 
+/** The cloud has attachments; the file takes the list. */
+{
+    set: Array<{
+        url: string;
+        title?: string;
+    }>;
+}
+/** Leave whatever the file says. */
+ | "keep"
+/** Remove them — the authoritative side has none. */
+ | "clear";
 /**
  * The frontmatter fields sync owns and rewrites on every write
  * (DOC-HEADER-14.1). `pulledAt` is owned too but never passed: it always
@@ -37,6 +54,10 @@ export interface OwnedFrontmatter {
     documentId: string;
     /** Editor hint for new requirement keys — see PrefixDirective. */
     defaultPrefix: PrefixDirective;
+    /** The document's attached links — see AttachmentsDirective. Absent means
+     * "keep": a caller that doesn't think about attachments must not clear
+     * them. */
+    attachments?: AttachmentsDirective;
     /** The cloud version this content is at. */
     version: number;
 }

package/dist/schema/file-writer.js

@@ -43,6 +43,13 @@ export function writeRequirementsFile(filePath, owned, body) {
         frontmatter.deleteIn(["document", "defaultPrefix"]);
     else if (owned.defaultPrefix !== "keep")
         frontmatter.setIn(["document", "defaultPrefix"], owned.defaultPrefix.set);
+    const attachments = owned.attachments ?? "keep";
+    if (attachments === "clear")
+        frontmatter.deleteIn(["document", "attachments"]);
+    else if (attachments !== "keep")
+        frontmatter.setIn(["document", "attachments"], 
+        // Omit absent titles rather than writing `title: null` into the file.
+        attachments.set.map((a) => a.title === undefined ? { url: a.url } : { url: a.url, title: a.title }));
     // SYNC-TITLE-1.2: `document.title` is a recognized-but-retired field — the
     // title lives in the body as its leading H1 — so a rewrite drops it rather
     // than carrying it forward as if it were one of the user's own fields.

package/dist/schema/index.d.ts

@@ -4,10 +4,11 @@
  * This module provides types, validation, parsing, and building utilities
  * for the Markdown requirements format.
  */
+export { attachmentListsEqual } from "./attachment-lists.js";
 export { buildRequirementMarkdown, buildRequirementsFile, buildRequirementsMarkdown, } from "./builder.js";
 export type { ConvexRequirement } from "./conversions.js";
 export { buildMetadata, constructKey, convexToRequirements, extractRequirementKeys, groupByRoot, parseKey, requirementsToConvex, } from "./conversions.js";
-export type { OwnedFrontmatter, PrefixDirective } from "./file-writer.js";
+export type { AttachmentsDirective, OwnedFrontmatter, PrefixDirective, } from "./file-writer.js";
 export { writeRequirementsFile } from "./file-writer.js";
 export type { ExtractedRequirementBlock } from "./parser.js";
 export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementsFile, parseRequirementsFromFile, parseRootLine, splitRequirementFenceContent, } from "./parser.js";

package/dist/schema/index.js

@@ -4,6 +4,7 @@
  * This module provides types, validation, parsing, and building utilities
  * for the Markdown requirements format.
  */
+export { attachmentListsEqual } from "./attachment-lists.js";
 // Building
 export { buildRequirementMarkdown, buildRequirementsFile, buildRequirementsMarkdown, } from "./builder.js";
 export { buildMetadata, constructKey, convexToRequirements, extractRequirementKeys, groupByRoot, parseKey, requirementsToConvex, } from "./conversions.js";

package/dist/schema/schemas.d.ts

@@ -86,14 +86,44 @@ export declare const MetadataSchema: z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         title: z.ZodOptional<z.ZodString>;
         defaultPrefix: z.ZodOptional<z.ZodString>;
+        attachments: z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            url: string;
+            title?: string | undefined;
+        }, {
+            url: string;
+            title?: string | undefined;
+        }>, "many">>>, {
+            url: string;
+            title?: string | undefined;
+        }[] | undefined, {
+            url: string;
+            title?: string | undefined;
+        }[] | null | undefined>, {
+            url: string;
+            title?: string | undefined;
+        }[] | undefined, {
+            url: string;
+            title?: string | undefined;
+        }[] | null | undefined>;
     }, "strip", z.ZodTypeAny, {
         id?: string | undefined;
         title?: string | undefined;
         defaultPrefix?: string | undefined;
+        attachments?: {
+            url: string;
+            title?: string | undefined;
+        }[] | undefined;
     }, {
         id?: string | undefined;
         title?: string | undefined;
         defaultPrefix?: string | undefined;
+        attachments?: {
+            url: string;
+            title?: string | undefined;
+        }[] | null | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
     version?: number | undefined;
@@ -103,6 +133,10 @@ export declare const MetadataSchema: z.ZodObject<{
         id?: string | undefined;
         title?: string | undefined;
         defaultPrefix?: string | undefined;
+        attachments?: {
+            url: string;
+            title?: string | undefined;
+        }[] | undefined;
     } | undefined;
 }, {
     version?: number | undefined;
@@ -112,6 +146,10 @@ export declare const MetadataSchema: z.ZodObject<{
         id?: string | undefined;
         title?: string | undefined;
         defaultPrefix?: string | undefined;
+        attachments?: {
+            url: string;
+            title?: string | undefined;
+        }[] | null | undefined;
     } | undefined;
 }>;
 export type Metadata = z.infer<typeof MetadataSchema>;
@@ -175,14 +213,44 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             title: z.ZodOptional<z.ZodString>;
             defaultPrefix: z.ZodOptional<z.ZodString>;
+            attachments: z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+                url: z.ZodString;
+                title: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                url: string;
+                title?: string | undefined;
+            }, {
+                url: string;
+                title?: string | undefined;
+            }>, "many">>>, {
+                url: string;
+                title?: string | undefined;
+            }[] | undefined, {
+                url: string;
+                title?: string | undefined;
+            }[] | null | undefined>, {
+                url: string;
+                title?: string | undefined;
+            }[] | undefined, {
+                url: string;
+                title?: string | undefined;
+            }[] | null | undefined>;
         }, "strip", z.ZodTypeAny, {
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            attachments?: {
+                url: string;
+                title?: string | undefined;
+            }[] | undefined;
         }, {
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            attachments?: {
+                url: string;
+                title?: string | undefined;
+            }[] | null | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
         version?: number | undefined;
@@ -192,6 +260,10 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            attachments?: {
+                url: string;
+                title?: string | undefined;
+            }[] | undefined;
         } | undefined;
     }, {
         version?: number | undefined;
@@ -201,6 +273,10 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            attachments?: {
+                url: string;
+                title?: string | undefined;
+            }[] | null | undefined;
         } | undefined;
     }>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
@@ -212,14 +288,44 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             title: z.ZodOptional<z.ZodString>;
             defaultPrefix: z.ZodOptional<z.ZodString>;
+            attachments: z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+                url: z.ZodString;
+                title: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                url: string;
+                title?: string | undefined;
+            }, {
+                url: string;
+                title?: string | undefined;
+            }>, "many">>>, {
+                url: string;
+                title?: string | undefined;
+            }[] | undefined, {
+                url: string;
+                title?: string | undefined;
+            }[] | null | undefined>, {
+                url: string;
+                title?: string | undefined;
+            }[] | undefined, {
+                url: string;
+                title?: string | undefined;
+            }[] | null | undefined>;
         }, "strip", z.ZodTypeAny, {
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            attachments?: {
+                url: string;
+                title?: string | undefined;
+            }[] | undefined;
         }, {
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            attachments?: {
+                url: string;
+                title?: string | undefined;
+            }[] | null | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
         version?: number | undefined;
@@ -229,6 +335,10 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            attachments?: {
+                url: string;
+                title?: string | undefined;
+            }[] | undefined;
         } | undefined;
     }, {
         version?: number | undefined;
@@ -238,6 +348,10 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            attachments?: {
+                url: string;
+                title?: string | undefined;
+            }[] | null | undefined;
         } | undefined;
     }>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
@@ -249,14 +363,44 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             title: z.ZodOptional<z.ZodString>;
             defaultPrefix: z.ZodOptional<z.ZodString>;
+            attachments: z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+                url: z.ZodString;
+                title: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                url: string;
+                title?: string | undefined;
+            }, {
+                url: string;
+                title?: string | undefined;
+            }>, "many">>>, {
+                url: string;
+                title?: string | undefined;
+            }[] | undefined, {
+                url: string;
+                title?: string | undefined;
+            }[] | null | undefined>, {
+                url: string;
+                title?: string | undefined;
+            }[] | undefined, {
+                url: string;
+                title?: string | undefined;
+            }[] | null | undefined>;
         }, "strip", z.ZodTypeAny, {
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            attachments?: {
+                url: string;
+                title?: string | undefined;
+            }[] | undefined;
         }, {
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            attachments?: {
+                url: string;
+                title?: string | undefined;
+            }[] | null | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
         version?: number | undefined;
@@ -266,6 +410,10 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            attachments?: {
+                url: string;
+                title?: string | undefined;
+            }[] | undefined;
         } | undefined;
     }, {
         version?: number | undefined;
@@ -275,6 +423,10 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            attachments?: {
+                url: string;
+                title?: string | undefined;
+            }[] | null | undefined;
         } | undefined;
     }>;
 }, z.ZodTypeAny, "passthrough">>;

package/dist/schema/schemas.js

@@ -147,6 +147,24 @@ export const MetadataSchema = z.object({
         id: z.string().optional(), // Cloud document link - filled by push when creating
         title: z.string().optional(), // Legacy fallback — the body's leading H1 is the title
         defaultPrefix: z.string().optional(), // Editor hint for new requirement keys
+        // ATTACH-10: links attached to the document (a Miro board, a reference
+        // page). Round-trips through sync — the cloud stores them as document
+        // metadata, the file carries them here.
+        // A bare `attachments:` key parses as YAML null and means the same as
+        // an explicit empty list — "this document has none" — which is the
+        // natural hand-edit for removing every entry. Absent stays undefined
+        // (the file takes no position; see sync/attachments.ts).
+        attachments: z
+            .array(z.object({
+            url: z.string(),
+            title: z.string().optional(),
+        }))
+            .nullable()
+            .optional()
+            .transform((a) => (a === null ? [] : a))
+            .refine((a) => a === undefined || new Set(a.map((x) => x.url)).size === a.length, {
+            message: "attachments list the same url more than once — remove the duplicate entry",
+        }),
     })
         .optional(),
 });

package/dist/sync/attachments.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Attachment resolution, outside the document verdict (ATTACH-10.2).
+ *
+ * Attachments are a small named-link set, not additive body content: three
+ * review rounds showed that routing them through the body's verdict matrix
+ * broke a different cell each round — a name difference freezing the whole
+ * document, planning a destructive body publish, or --repo-wins wiping
+ * attachments a pre-feature file never mentioned. So they resolve here, by
+ * their own rule, and the body syncs as if they didn't exist.
+ *
+ * The rule, per URL:
+ * - Additive modes union the two sides. Removals don't propagate (as
+ *   everywhere in additive sync); a contributes mode only changes the
+ *   receiving side.
+ * - Names: a name beats no name; when both sides name the same URL
+ *   differently, the REPO wins — it is the hand-authored side, and
+ *   ATTACH-10.1 promises frontmatter edits propagate (decided 2026-08-20).
+ * - Authority modes make that side's list the outcome — except that a file
+ *   with NO attachments key has no opinion: absence cannot distinguish "the
+ *   user removed everything" from "this file predates attachments", so it
+ *   never clears anything, even under --repo-wins. An explicit
+ *   `attachments: []` (or a bare `attachments:` key) is how a file says
+ *   "none".
+ */
+import { attachmentListsEqual } from "../schema/attachment-lists.js";
+import type { SyncMode } from "./plan.js";
+import type { Attachment } from "./types.js";
+export { attachmentListsEqual };
+export interface AttachmentsResolution {
+    /** The list the cloud should end with. */
+    cloudFinal: Attachment[];
+    /** The list the file should end with (undefined = leave the file alone). */
+    localFinal: Attachment[] | undefined;
+    /** The cloud's list differs from cloudFinal — a push is needed. */
+    pushNeeded: boolean;
+    /** The file's effective list differs from localFinal — a write is needed. */
+    writeNeeded: boolean;
+}
+/**
+ * Does this document need attachment work its body action won't do? The
+ * sync command's "already in sync" gate asks this — the resolver, not the
+ * raw `differ` flag, because four of five modes deliberately leave one side
+ * alone (a no-key file under repo_contributes is a permanent no-op, not
+ * pending work).
+ */
+export declare function attachmentSyncNeeded(attachments: {
+    local: Attachment[] | undefined;
+    cloud: Attachment[];
+} | undefined, mode: SyncMode): boolean;
+/**
+ * The cloud attachments a sync under this mode removes. Removals ride
+ * authority ungated — like requirement blocks dropped from a file's body,
+ * and unlike whole documents (SYNC-MODE-4 gates only those); the docs
+ * promise attachments never hold up the rest of the spec, and a link is
+ * re-pasteable. This names them for the post-run report (ATTACH-10.3.1.0).
+ * Only authority can remove (union never shrinks), so this is empty
+ * outside --repo-wins.
+ */
+export declare function cloudAttachmentRemovals(attachments: {
+    local: Attachment[] | undefined;
+    cloud: Attachment[];
+} | undefined, mode: SyncMode): Attachment[];
+export declare function resolveAttachments(local: Attachment[] | undefined, cloud: Attachment[] | undefined, mode: SyncMode): AttachmentsResolution;
+//# sourceMappingURL=attachments.d.ts.map