@popoverai/dotrequirements 0.30.1 → 0.31.0

package/dist/sync/attachments.js

@@ -0,0 +1,149 @@
+/**
+ * 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";
+export { attachmentListsEqual };
+/** One entry per URL — legacy cloud rows can hold duplicates from before
+ * the validator, and writing them into frontmatter produces a file our own
+ * parser rejects (invalid_file, requirements and all, in every mode). The
+ * FIRST TITLED occurrence wins the name: keeping strictly the first entry
+ * dropped a later name, contradicting "a name beats no name" below. */
+function dedupeByUrl(list) {
+    const byUrl = new Map();
+    for (const a of list) {
+        const kept = byUrl.get(a.url);
+        if (!kept || (kept.title === undefined && a.title !== undefined)) {
+            byUrl.set(a.url, kept ? { url: a.url, title: a.title } : a);
+        }
+    }
+    return [...byUrl.values()];
+}
+/**
+ * Union with the name rule: cloud order first (stable for the web), repo-only
+ * URLs appended in file order; per shared URL, a name beats no name and the
+ * repo's name wins a tie.
+ */
+function merge(local, cloud) {
+    const localByUrl = new Map(local.map((a) => [a.url, a]));
+    const merged = cloud.map((c) => {
+        const l = localByUrl.get(c.url);
+        const title = l?.title ?? c.title;
+        return title === undefined ? { url: c.url } : { url: c.url, title };
+    });
+    const cloudUrls = new Set(cloud.map((a) => a.url));
+    for (const l of local) {
+        if (!cloudUrls.has(l.url))
+            merged.push(l);
+    }
+    return merged;
+}
+/**
+ * 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 function attachmentSyncNeeded(attachments, mode) {
+    if (!attachments)
+        return false;
+    const res = resolveAttachments(attachments.local, attachments.cloud, mode);
+    return res.pushNeeded || res.writeNeeded;
+}
+/**
+ * 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 function cloudAttachmentRemovals(attachments, mode) {
+    if (!attachments)
+        return [];
+    const res = resolveAttachments(attachments.local, attachments.cloud, mode);
+    return attachments.cloud.filter((c) => !res.cloudFinal.some((f) => f.url === c.url));
+}
+export function resolveAttachments(local, cloud, mode) {
+    // The cloud's absence IS "none" — the web shows no attachments. Only the
+    // file has the third state. RESOLUTION runs on deduped views (every
+    // output must be writable to frontmatter our own parser accepts), but the
+    // push/write decisions below compare against the RAW lists — that is what
+    // makes a duplicated legacy row repairable: its deduped resolution
+    // differs from the raw row, so the corrected list gets pushed.
+    const rawCloud = cloud ?? [];
+    const rawLocal = local ?? [];
+    const effCloud = dedupeByUrl(rawCloud);
+    const effLocal = dedupeByUrl(rawLocal);
+    let cloudFinal;
+    let localFinal;
+    switch (mode) {
+        case "repo_wins":
+            // Normalized like merge's output: an entry read from frontmatter can
+            // carry an explicit `title: undefined` key, which only this branch
+            // would otherwise pass through to the wire.
+            cloudFinal =
+                local === undefined
+                    ? effCloud
+                    : local.map((a) => a.title === undefined
+                        ? { url: a.url }
+                        : { url: a.url, title: a.title });
+            localFinal = undefined; // the file is the authority; leave it alone
+            break;
+        case "cloud_wins":
+            cloudFinal = effCloud;
+            localFinal = effCloud;
+            break;
+        case "repo_contributes":
+            cloudFinal = merge(effLocal, effCloud);
+            localFinal = undefined;
+            break;
+        case "cloud_contributes":
+            cloudFinal = effCloud;
+            localFinal = merge(effLocal, effCloud);
+            break;
+        default: {
+            // bare: both sides converge on the union.
+            const merged = merge(effLocal, effCloud);
+            cloudFinal = merged;
+            localFinal = merged;
+        }
+    }
+    // The raw-vs-resolved comparison is what makes a duplicated legacy row
+    // repairable — but ONLY modes that legitimately write the cloud may run
+    // that repair: under cloud authority the mode's promise is that the repo
+    // never overwrites the cloud, and firing a push there rewrote the row
+    // unconsented (round 9). Cloud-authority modes compare deduped-to-deduped,
+    // which is stable: the duplicated row shows in diff and is cleaned up the
+    // next time any pushing mode runs.
+    const cloudWriting = mode === "bare" || mode === "repo_wins" || mode === "repo_contributes";
+    return {
+        cloudFinal,
+        localFinal,
+        pushNeeded: !attachmentListsEqual(cloudWriting ? rawCloud : effCloud, cloudFinal),
+        writeNeeded: localFinal !== undefined && !attachmentListsEqual(rawLocal, localFinal),
+    };
+}
+//# sourceMappingURL=attachments.js.map

package/dist/sync/compare.js

@@ -3,6 +3,7 @@
  * reads no disk and makes no network calls. `dotreq diff` renders its result,
  * `dotreq sync` acts on it, CI asserts on it.
  */
+import { attachmentListsEqual } from "./attachments.js";
 import { normalizeProse, requirementUnitMap, segmentBody, } from "./segment.js";
 /** Whitespace-only normalization for the fast-path body equality check. */
 function normalizeBody(body) {
@@ -184,6 +185,81 @@ function proseLabel(text) {
         ? `${firstLine.slice(0, 40)}…`
         : firstLine || "(prose)";
 }
+function attachmentLabel(url) {
+    return url.length > 60 ? `${url.slice(0, 60)}…` : url;
+}
+/**
+ * Describe attachment differences for `dotreq diff` (ATTACH-10.2). Display
+ * only: attachments never touch the document's verdict — they resolve by
+ * their own rule in sync/attachments.ts. The directional verdicts here name
+ * which side holds the difference, for the reader.
+ */
+function describeAttachments(local, cloud) {
+    const details = [];
+    const localByUrl = new Map((local ?? []).map((a) => [a.url, a]));
+    const cloudByUrl = new Map((cloud ?? []).map((a) => [a.url, a]));
+    for (const [url, a] of localByUrl) {
+        const c = cloudByUrl.get(url);
+        if (!c) {
+            details.push({
+                unit: attachmentLabel(url),
+                verdict: "additions_in_repo",
+                note: "attachment",
+            });
+        }
+        else if ((a.title ?? "") !== (c.title ?? "")) {
+            details.push({
+                unit: attachmentLabel(url),
+                verdict: (a.title ?? "") === "" ? "additions_in_cloud" : "additions_in_repo",
+                note: "attachment name",
+            });
+        }
+    }
+    for (const url of cloudByUrl.keys()) {
+        if (!localByUrl.has(url)) {
+            details.push({
+                unit: attachmentLabel(url),
+                verdict: "additions_in_cloud",
+                note: "attachment",
+            });
+        }
+    }
+    // Duplicate entries collapse in the URL-keyed maps above, so a
+    // duplicated row would flag `differ` with no detail line beneath it —
+    // a not-in-sync header over nothing. Count per URL and say so.
+    const countBy = (list) => {
+        const counts = new Map();
+        for (const a of list ?? [])
+            counts.set(a.url, (counts.get(a.url) ?? 0) + 1);
+        return counts;
+    };
+    const localCounts = countBy(local);
+    const cloudCounts = countBy(cloud);
+    for (const [url, n] of cloudCounts) {
+        // Both-sides URLs only: a cloud-only duplicated URL already gets the
+        // first loop's addition line, and a second line with the same label
+        // double-reports one link (round 10). No local twin — the frontmatter
+        // schema rejects duplicates, so such a file is invalid_file before it
+        // reaches this comparison.
+        const localN = localCounts.get(url);
+        if (n > 1 && localN !== undefined && n !== localN) {
+            details.push({
+                unit: attachmentLabel(url),
+                verdict: "additions_in_cloud",
+                note: "duplicated entry",
+            });
+        }
+    }
+    // `differ` is THE predicate every consumer gates on (the sync command's
+    // gate resolves it further by mode; the executor's residual path trusts
+    // it) — so it is computed by the same set-equality the resolver uses,
+    // not from these display details: the URL-keyed maps above collapse
+    // duplicate entries that the length-aware comparison still sees.
+    return {
+        differ: !attachmentListsEqual(local ?? [], cloud ?? []),
+        details,
+    };
+}
 /** Compare one document across surfaces. */
 function compareDocument(local, cloud) {
     const base = {
@@ -194,9 +270,17 @@ function compareDocument(local, cloud) {
     };
     const diverges = attributesDiverge(local, cloud);
     const body = local.body ?? "";
+    const attach = describeAttachments(local.attachments, cloud.attachments);
+    const attachments = {
+        local: local.attachments,
+        cloud: cloud.attachments ?? [],
+        differ: attach.differ,
+        details: attach.details,
+    };
     // Fast path: whitespace-identical bodies with matching attributes.
+    // Attachments deliberately don't gate this — they resolve on their own.
     if (!diverges && normalizeBody(body) === normalizeBody(cloud.body)) {
-        return { ...base, verdict: "in_sync" };
+        return { ...base, verdict: "in_sync", attachments };
     }
     // SYNC-FAIL-4.2: cloud bodies reach the snapshot as stored markdown, never
     // re-parsed, so a document saved before today's grammar can still be
@@ -211,21 +295,21 @@ function compareDocument(local, cloud) {
         classified = classifyBodies(body, cloud.body);
     }
     catch {
-        return { ...base, verdict: "conflict" };
+        // `attachments` rides along like every other return: without it the
+        // residual sync and verbose diff silently drop this document's links.
+        return { ...base, verdict: "conflict", attachments };
     }
     const { verdict: bodyVerdict, details } = classified;
-    let verdict;
-    if (diverges) {
-        // A changed single-valued attribute is never additive → conflict.
-        verdict = "conflict";
-    }
-    else {
-        verdict = bodyVerdict;
-    }
+    // ATTACH-10.2: the verdict is the BODY's verdict. Attachments never move
+    // it — a name difference could otherwise freeze the document
+    // (skip_conflict) or, worse, plan a destructive body publish over a
+    // colleague's unpublished work, from someone naming a link in frontmatter.
+    const verdict = diverges ? "conflict" : bodyVerdict;
     return {
         ...base,
         verdict,
         details: verdict === "in_sync" ? undefined : details,
+        attachments,
     };
 }
 /**

package/dist/sync/execute.d.ts

@@ -16,6 +16,17 @@ export interface SyncOutcome {
     cloudDeleted: number;
     localWritten: number;
     localDeleted: number;
+    /** ATTACH-10.2: attachment-only operations, outside the body actions. */
+    attachmentPushes: number;
+    attachmentWrites: number;
+    /** ATTACH-10.3.1.0: cloud attachments a push removed on the file's
+     * authority. Recorded only after the push succeeded — the report's trace
+     * must never claim a removal a refused or failed push left in place. */
+    attachmentRemovals: Array<{
+        name: string;
+        url: string;
+        title?: string;
+    }>;
     conflicts: DocumentComparison[];
     invalid: DocumentComparison[];
     errors: Array<{

package/dist/sync/execute.js

@@ -14,6 +14,7 @@ import { getConvexUrl } from "../config.js";
 import { api } from "../convex.js";
 import { parseFilesForPushIndividually, WEB_APP_URL } from "../push/core.js";
 import { composeMarkdownWithTitle, splitLeadingH1, writeRequirementsFile, } from "../schema/index.js";
+import { cloudAttachmentRemovals, resolveAttachments } from "./attachments.js";
 import { resolveLocalPath } from "./local-files.js";
 import { publishToCloud } from "./publish.js";
 function emptyOutcome() {
@@ -23,6 +24,9 @@ function emptyOutcome() {
         cloudDeleted: 0,
         localWritten: 0,
         localDeleted: 0,
+        attachmentPushes: 0,
+        attachmentWrites: 0,
+        attachmentRemovals: [],
         conflicts: [],
         invalid: [],
         errors: [],
@@ -59,7 +63,7 @@ export async function executePlan(plan, cloud, auth, workspaceRoot, mode) {
                     outcome.invalid.push(doc);
                     break;
                 case "cloud_write":
-                    await cloudWrite(auth, doc, cloudById, outcome);
+                    await cloudWrite(auth, doc, cloudById, outcome, mode);
                     break;
                 case "cloud_delete":
                     await cloudDelete(client, auth, doc, outcome);
@@ -71,6 +75,12 @@ export async function executePlan(plan, cloud, auth, workspaceRoot, mode) {
                     localDelete(doc, outcome);
                     break;
             }
+            // ATTACH-10.2: attachments resolve outside the body's verdict, so a
+            // body action may not have carried them — cover the residue. cloud_write
+            // pushed cloudFinal and wrote back localFinal; local_write wrote
+            // localFinal; deletes moot the question. Everything else (skip,
+            // skip_conflict, and the un-pushed side of local_write) lands here.
+            await syncResidualAttachments(client, auth, doc, action, outcome, mode);
         }
         catch (err) {
             outcome.errors.push({ name, error: errorDisplayMessage(err) });
@@ -78,6 +88,79 @@ export async function executePlan(plan, cloud, auth, workspaceRoot, mode) {
     }
     return outcome;
 }
+/**
+ * Attachment-only operations for whatever the body action didn't cover.
+ * The push goes through setAttachmentsForSync — a metadata patch, never the
+ * publish path, so naming a link cannot displace anyone's working document.
+ */
+async function syncResidualAttachments(client, auth, doc, action, outcome, mode) {
+    if (!doc.attachments?.differ || !doc.documentId)
+        return;
+    // A conflicted document is reported as left alone, with a resolution hint
+    // — rewriting its frontmatter or its cloud list would falsify that report
+    // for someone mid-resolution. Deletes and invalid files moot the question.
+    if (action === "cloud_delete" ||
+        action === "local_delete" ||
+        action === "invalid" ||
+        action === "skip_conflict") {
+        return;
+    }
+    const res = resolveAttachments(doc.attachments.local, doc.attachments.cloud, mode);
+    if (res.pushNeeded && action !== "cloud_write") {
+        if (!auth.projectSlug) {
+            throw new Error("Cannot sync attachments without project credentials.");
+        }
+        await client.mutation(api.documents.mutations.setAttachmentsForSync, {
+            projectAuth: {
+                projectSlug: auth.projectSlug,
+                projectSecret: auth.projectSecret,
+            },
+            target: { type: "project", slug: auth.projectSlug },
+            documentId: doc.documentId,
+            attachments: res.cloudFinal,
+            // Compare-and-set: the resolution was computed from the snapshot's
+            // cloud list; if the cloud moved since (a paste in the web app while
+            // this run sat at a prompt), replaying our list would delete it. The
+            // mutation refuses instead, and the next run resolves fresh.
+            expectAttachments: doc.attachments.cloud,
+        });
+        outcome.attachmentPushes++;
+        for (const removed of cloudAttachmentRemovals(doc.attachments, mode)) {
+            outcome.attachmentRemovals.push({
+                name: doc.title,
+                url: removed.url,
+                title: removed.title,
+            });
+        }
+    }
+    if (res.writeNeeded &&
+        res.localFinal !== undefined &&
+        action !== "local_write" &&
+        action !== "cloud_write" &&
+        doc.filePath) {
+        const { parsedFiles } = parseFilesForPushIndividually([doc.filePath]);
+        const parsed = parsedFiles[0];
+        if (!parsed)
+            return;
+        // The writer drops the legacy frontmatter `document.title`
+        // (SYNC-TITLE-1.2) — same compensation cloudWrite makes: an H1-less
+        // legacy body gets its title materialized as the leading H1, or an
+        // attachment-only write would leave the file untitled and the next
+        // compare would flag a phantom title conflict.
+        let body = parsed.markdownContent;
+        const legacyTitle = parsed.metadata.document?.title;
+        if (legacyTitle && splitLeadingH1(body).title === null) {
+            body = composeMarkdownWithTitle(legacyTitle, body);
+        }
+        writeRequirementsFile(doc.filePath, {
+            documentId: doc.documentId,
+            defaultPrefix: "keep",
+            attachments: { set: res.localFinal },
+            version: (parsed.metadata.version ?? 0) + 1,
+        }, body);
+        outcome.attachmentWrites++;
+    }
+}
 /**
  * Servers throw ConvexError({kind, message}) for expected failures; production
  * redacts the Error message to "Server Error" but preserves error.data.
@@ -89,7 +172,7 @@ function errorDisplayMessage(err) {
         return data.message;
     return err instanceof Error ? err.message : String(err);
 }
-async function cloudWrite(auth, doc, cloudById, outcome) {
+async function cloudWrite(auth, doc, cloudById, outcome, mode) {
     if (!auth.projectSlug || !doc.filePath) {
         throw new Error("Cannot write to the cloud without project credentials.");
     }
@@ -109,6 +192,7 @@ async function cloudWrite(auth, doc, cloudById, outcome) {
     if (meta?.title && splitLeadingH1(parsed.markdownContent).title === null) {
         parsed.markdownContent = composeMarkdownWithTitle(meta.title, parsed.markdownContent);
     }
+    const attachmentsRes = resolveAttachments(meta?.attachments, meta?.id ? cloudById.get(meta.id)?.attachments : undefined, mode);
     // SYNC-CLI-EDIT-2: the push goes to the web app, which writes it into the
     // working document Quinn may have open and publishes a copy printed from it.
     // Convex cannot do that job — the conversion needs the BlockNote schema.
@@ -124,9 +208,43 @@ async function cloudWrite(auth, doc, cloudById, outcome) {
         title: meta?.title,
         markdownContent: parsed.markdownContent,
         defaultPrefix: meta?.defaultPrefix,
+        // ATTACH-10.2: the push carries the RESOLVED list (sync/attachments.ts)
+        // — union in additive modes, authority as declared, a file with no
+        // attachments key having no opinion — or nothing at all when the
+        // cloud's list already is the resolution.
+        attachments: attachmentsRes.pushNeeded
+            ? attachmentsRes.cloudFinal
+            : undefined,
+        // Compare-and-set whenever the push replaces the list: the cloud copy
+        // the resolution was computed against. A link pasted mid-sync makes the
+        // publish refuse (dry-run first, so nothing is destroyed) instead of
+        // silently replaying the stale list over it.
+        expectAttachments: attachmentsRes.pushNeeded
+            ? meta?.id
+                ? (cloudById.get(meta.id)?.attachments ?? [])
+                : []
+            : undefined,
         runMarker: parsed.metadata.ctsRun,
     });
     const documentId = saveResult.documentId;
+    // ATTACH-10.3.1.0: the publish above is the push that removes cloud
+    // attachments under repo authority — trace them now that it has landed.
+    // Named by file, like every other per-document line here: doc.title is
+    // pinned to the OLD cloud title, so a push that renames the H1 and drops
+    // a link in one edit would print the removal against a title that no
+    // longer exists (round-2 release review).
+    if (attachmentsRes.pushNeeded) {
+        const cloudBefore = meta?.id
+            ? (cloudById.get(meta.id)?.attachments ?? [])
+            : [];
+        for (const removed of cloudAttachmentRemovals({ local: meta?.attachments, cloud: cloudBefore }, mode)) {
+            outcome.attachmentRemovals.push({
+                name: path.basename(doc.filePath),
+                url: removed.url,
+                title: removed.title,
+            });
+        }
+    }
     // The server accepted the publish and told us something after it did not
     // finish. Reported rather than dropped: the push DID land, so this is not a
     // failure, but "synced" on its own would claim more than happened.
@@ -217,6 +335,11 @@ async function cloudWrite(auth, doc, cloudById, outcome) {
             defaultPrefix: meta?.defaultPrefix
                 ? { set: meta.defaultPrefix }
                 : "keep",
+            // The file adopts its side of the resolution — cloud-held names it
+            // lacked, for one (ATTACH-10.2).
+            attachments: attachmentsRes.writeNeeded && attachmentsRes.localFinal !== undefined
+                ? { set: attachmentsRes.localFinal }
+                : "keep",
             version: (parsed.metadata.version ?? 0) + 1,
         }, contentToWriteBack);
         // Counted only once the rewrite actually happened: reporting it before a
@@ -265,9 +388,19 @@ function localWrite(doc, cloudById, usedPaths, requirementsDir, outcome, mode) {
         : mode === "cloud_wins"
             ? "clear"
             : "keep";
+    // ATTACH-10.0/10.2: the file adopts its side of the attachment resolution
+    // — cloud's list plus the file's own additions in additive modes, the
+    // cloud's exactly under cloud authority. An explicit empty list is written
+    // as `attachments: []` (present key = an opinion); no write happens when
+    // the file already agrees.
+    const attachRes = resolveAttachments(doc.attachments?.local, cloudDoc.attachments, mode);
+    const attachments = attachRes.writeNeeded && attachRes.localFinal !== undefined
+        ? { set: attachRes.localFinal }
+        : "keep";
     const changed = writeRequirementsFile(filePath, {
         documentId: cloudDoc.documentId,
         defaultPrefix,
+        attachments,
         version: cloudDoc.version,
     }, cloudDoc.body);
     if (changed)

package/dist/sync/publish.d.ts

@@ -21,6 +21,16 @@ export interface PublishParams {
     /** Legacy frontmatter title, used only as the server's H1-less fallback. */
     title?: string;
     defaultPrefix?: string;
+    /** document.attachments from the file's frontmatter (ATTACH-10.1). */
+    attachments?: Array<{
+        url: string;
+        title?: string;
+    }>;
+    /** Compare-and-set: the cloud attachments the sync read them against. */
+    expectAttachments?: Array<{
+        url: string;
+        title?: string;
+    }>;
     runMarker?: string;
 }
 /**

package/dist/sync/render.js

@@ -33,6 +33,13 @@ export function resolutionHint(doc) {
 }
 /** One line per document: glyph, name, verdict. */
 export function formatVerdictLine(doc) {
+    // ATTACH-10.2: attachments resolve outside the verdict, so a document can
+    // be in sync while its attachments differ — say so rather than reporting
+    // "in sync" over a real difference. (Diff is mode-independent, like the
+    // body verdicts: whether a sync would act on it depends on the mode.)
+    if (doc.verdict === "in_sync" && doc.attachments?.differ) {
+        return `  ~ ${displayName(doc).padEnd(40)} attachments differ`;
+    }
     return `  ${GLYPH[doc.verdict]} ${displayName(doc).padEnd(40)} ${verdictLabel(doc.verdict)}`;
 }
 /** Verbose, one-level-unfolded detail for a document (DIFF-2). */

package/dist/sync/snapshot.js

@@ -32,6 +32,7 @@ export function readLocalDocument(filePath) {
     let documentId;
     let title;
     let defaultPrefix;
+    let attachments;
     let frontmatterError;
     const split = splitFrontmatter(raw);
     if (split) {
@@ -56,6 +57,24 @@ export function readLocalDocument(filePath) {
                     title = d.title;
                 if (typeof d.defaultPrefix === "string")
                     defaultPrefix = d.defaultPrefix;
+                // ATTACH-10.1: attachments from frontmatter. Shape-filtered here for
+                // the same reason as the fields above; a malformed entry is caught by
+                // validateMetadata below and flags the file rather than half-syncing.
+                // A present-but-empty key (`attachments:` or `attachments: []`) is an
+                // explicit "none" — the tri-state the resolver needs: only a file
+                // with NO key has no opinion (sync/attachments.ts).
+                if (d.attachments === null) {
+                    attachments = [];
+                }
+                else if (Array.isArray(d.attachments)) {
+                    attachments = d.attachments
+                        .filter((a) => !!a && typeof a === "object" && !Array.isArray(a))
+                        .filter((a) => typeof a.url === "string")
+                        .map((a) => ({
+                        url: a.url,
+                        title: typeof a.title === "string" ? a.title : undefined,
+                    }));
+                }
             }
         }
         if (rawMeta !== undefined && !frontmatterError) {
@@ -83,7 +102,14 @@ export function readLocalDocument(filePath) {
     // frontmatter title stands only when the body has none (SYNC-TITLE-1.1);
     // with neither, the document is untitled (SYNC-TITLE-1.4).
     const derivedTitle = splitLeadingH1(body).title ?? title;
-    return { filePath, documentId, title: derivedTitle, defaultPrefix, body };
+    return {
+        filePath,
+        documentId,
+        title: derivedTitle,
+        defaultPrefix,
+        attachments,
+        body,
+    };
 }
 /**
  * Build the local snapshot from the workspace, or from an explicit set of file
@@ -113,6 +139,7 @@ export async function acquireCloudSnapshot(auth) {
             documentId: d.documentId,
             title: d.title,
             defaultPrefix: d.defaultPrefix,
+            attachments: d.attachments,
             body: d.markdownContent,
             version: d.version,
             updatedAt: d.updatedAt,

package/dist/sync/types.d.ts

@@ -11,6 +11,11 @@
 export type Verdict = "in_sync" | "additions_in_repo" | "additions_in_cloud" | "conflict" | "only_in_repo" | "only_in_cloud" | "invalid_file";
 /** The user-facing spelling of a verdict — same words, spaced. */
 export declare function verdictLabel(verdict: Verdict): string;
+/** One attached link (ATTACH-10): document metadata that syncs both ways. */
+export interface Attachment {
+    url: string;
+    title?: string;
+}
 /**
  * One document as it exists locally: a `.requirements.md` file. When the file
  * cannot be parsed, `parseError` is set and the other content fields are absent
@@ -22,6 +27,8 @@ export interface LocalDocument {
     documentId?: string;
     title?: string;
     defaultPrefix?: string;
+    /** document.attachments from frontmatter (ATTACH-10). */
+    attachments?: Attachment[];
     /** Frontmatter-stripped markdown body (the comparison unit, SYNC-ARCH-1). */
     body?: string;
     parseError?: string;
@@ -33,6 +40,8 @@ export interface CloudDocument {
     documentId: string;
     title: string;
     defaultPrefix?: string;
+    /** The document's attached links (ATTACH-10). */
+    attachments?: Attachment[];
     /** Published markdownContent (SYNC-ARCH-1). */
     body: string;
     version: number;
@@ -75,6 +84,20 @@ export interface DocumentComparison {
     error?: string;
     /** Unit-level breakdown, populated for verbose diff of non-in-sync documents. */
     details?: UnitDetail[];
+    /**
+     * ATTACH-10.2: attachments never contribute to `verdict` — they resolve by
+     * their own rule (sync/attachments.ts), so a name difference can neither
+     * freeze the body's sync nor plan a body write. This carries what that
+     * resolution needs: both sides' lists (`local` undefined = the file has no
+     * attachments key = no opinion) and display details for `dotreq diff`.
+     */
+    attachments?: {
+        local: Attachment[] | undefined;
+        cloud: Attachment[];
+        /** True when the two sides' lists differ (set semantics, names count). */
+        differ: boolean;
+        details: UnitDetail[];
+    };
 }
 export interface ComparisonResult {
     documents: DocumentComparison[];