@avocadostudio-ai/orchestrator-core 0.3.3 → 0.4.0

package/dist/chat/chat-pipeline.js

@@ -4,6 +4,7 @@ import { GENERATING_IMAGE_PLACEHOLDER, SEARCHING_IMAGE_PLACEHOLDER, isGenerating
 import { siteCapabilitiesSchema, isBatchAddRequest, isDuplicateBlockRequest, isBlockCatalogQuery, isInfoQuery, isAdviceQuery, adviceResponse, isContentQuery, isPageListQuery, requestsPlanFirst, plannerMessageWithPendingContext, buildSiteContextBlock, infoResponse } from "../nlp/intent-detection.js";
 import { isLikelyClarificationFollowUp } from "../nlp/intent-helpers.js";
 import { versions, pendingClarificationBySession, chatHistoryBySession, continuationChainBySession, imageSourcePreferenceBySession, getSessionDraft, getPage, setPage, pushUndo, bumpVersion, pushRecentEdit, pushVersionEntry, pushChatHistory, schedulePersistState, removePage } from "../state/session-state.js";
+import { getSiteAssets } from "../state/site-assets.js";
 import { loadPendingPlan, savePendingPlan, clearPendingPlan } from "../durable/pending-plan-store.js";
 import { toErrorDetail, isNoEffectiveChangeError, isAlreadyCurrentError, classifyGuardrailError, formatValidationError, isRepairEligibleCategory, buildDeterministicRepairFeedback, validateOperations, applyOpsAtomically, isStructuralOperation, pickFocusBlockId, pickUpdatedSlug } from "../ops/ops-engine.js";
 import { evaluateDestructiveActions } from "../ops/destructive-action-gate.js";
@@ -336,12 +337,26 @@ export async function runChatPipeline(ctx, body, options) {
     }
     const sanitizedMessage = sanitizeMessageForPlanning(body.message ?? "");
     const pageDirectory = buildPageDirectory(body.session);
+    /*
+     * The site's documents ride along with the page list.
+     *
+     * Without them "link the winter menu" has no referent: the planner knows the
+     * pages and the block schemas and nothing about the fifteen PDFs the site
+     * hosts, so it writes a path that looks right and is not — which is exactly
+     * how a link to a misspelled filename gets into a page. `undefined` when the
+     * site cannot enumerate its documents, in which case the block simply omits
+     * the section rather than claiming the site has none.
+     */
+    const siteDocuments = await getSiteAssets();
     const siteContextBlock = buildSiteContextBlock({
         sitePurpose: body.sitePurpose,
         siteHosting: body.siteHosting,
         businessContext: body.businessContext,
         siteContext: body.siteContext,
-        pageDirectory: pageDirectory || undefined
+        pageDirectory: pageDirectory || undefined,
+        ...(siteDocuments?.length
+            ? { documents: siteDocuments.map((d) => ({ path: d.path, ...(d.name ? { name: d.name } : {}) })) }
+            : {})
     });
     // Site context is now passed to the LLM system prompt (cacheable) instead of the user message.
     let plannerMessage = plannerMessageWithPendingContext(body.session, sanitizedMessage);

package/dist/chat/prompts.d.ts

@@ -65,3 +65,8 @@ export declare function buildPlannerSystemPromptSegments(opts: PlannerPromptOpti
     stable: string;
     dynamic: string;
 };
+/**
+ * The subset of the corrections above that is true of THIS site's catalogue.
+ * Returns one prompt line per surviving correction, or an empty array.
+ */
+export declare function propNameCorrectionLines(effectiveBlockTypes: string[]): string[];

package/dist/chat/prompts.js

@@ -4,6 +4,7 @@
  * Eliminates duplication between OpenAI and Anthropic planner modules.
  * Provider-specific extensions are injected via the `provider` option.
  */
+import { blockAcceptsProp, blockListItemAcceptsKey } from "@avocadostudio-ai/shared";
 // ---------------------------------------------------------------------------
 // Intent parser
 // ---------------------------------------------------------------------------
@@ -154,7 +155,13 @@ const ANTHROPIC_IMAGE_TOOL_LINES = [
     "When using image.generate, write the returned imageUrl into the relevant imageUrl field and set imageAlt from the returned alt text.",
 ];
 const BLOCK_NAME_PRIVACY_OPENAI = "Never mention internal block IDs (b_hero_*, b_featuregrid_*, etc.), prop names (imageUrl, imageAlt), or system settings in summary_for_user or change_log. Use human-friendly descriptions instead (e.g. 'Update the Hero image' not 'Update imageUrl on b_hero_123').";
-const BLOCK_NAME_PRIVACY_ANTHROPIC = "Never mention internal block IDs (b_hero_*, b_featuregrid_*, etc.), prop names (imageUrl, imageAlt), or system settings in summary_for_user, change_log, or suggested_next_actions. Also avoid raw block type names like 'RichText', 'FeatureGrid', 'CardGrid', 'FAQAccordion' — use natural descriptions instead: 'text section', 'features grid', 'card grid', 'FAQ section'. Exception: 'Hero', 'CTA', and 'Testimonials' are fine as-is since users understand these terms.";
+/*
+ * Stated as a rule about identifiers rather than as a list of our block names:
+ * a site with its own catalogue has its own CamelCase type names, and an
+ * allowlist of ours neither covers them nor describes them. The test is whether
+ * the word reads as English to someone who has never seen the schema.
+ */
+const BLOCK_NAME_PRIVACY_ANTHROPIC = "Never mention internal block IDs (b_hero_*, b_featuregrid_*, etc.), prop names (imageUrl, imageAlt), or system settings in summary_for_user, change_log, or suggested_next_actions. Also avoid raw block type names — they are schema identifiers, not words users know. Describe the section by what it is: a type named 'RichText' is a 'text section', 'FeatureGrid' a 'features grid', 'FAQAccordion' an 'FAQ section', 'heroSplit' or 'PageHeader' just 'the hero' or 'the page header'. The test is whether the word reads as ordinary English rather than as a name from a schema; where it does — 'Hero', 'CTA', 'Testimonials', 'Gallery' — using it as-is is fine.";
 // ---------------------------------------------------------------------------
 // Full planner prompt — composed from section builders.
 // Each section becomes a ## HEADER in the emitted prompt so the LLM can
@@ -168,16 +175,18 @@ function joinSections(sections) {
 }
 function buildFullPlannerSegments(opts) {
     const hasNativeTools = opts.provider === "anthropic" || opts.provider === "gemini";
-    // Stable sections — depend only on provider (fixed for a given planner) and
-    // static rule constants. These bytes are identical across requests and are
-    // the part Anthropic caches. IMAGES is here too; it depends on hasNativeTools
-    // but that's stable per provider.
+    // Stable sections — the part Anthropic caches. "Stable" means stable across
+    // *requests*, not constant: IMAGES varies with hasNativeTools and OPERATION
+    // CATALOG with the site's block catalogue, and both are fixed for a given
+    // provider and site. Two sites with different catalogues get two cache
+    // entries, which is the correct trade — a prompt that tells the model the
+    // wrong prop names caches beautifully and edits the wrong field.
     const stableSections = [
         sectionRole(),
         sectionOutputContract(),
         sectionIntentDecisionTree(),
         sectionVoice(opts, hasNativeTools),
-        sectionOperationCatalog(),
+        sectionOperationCatalog(opts),
         sectionSchemaDiscipline(),
         sectionImages(hasNativeTools),
     ];
@@ -241,14 +250,88 @@ function sectionVoice(opts, hasNativeTools) {
     if (hasNativeTools) {
         lines.push("For edit_plan intent: summary_for_user must be ONE short sentence (max ~20 words) describing what the plan will do. Do NOT elaborate, explain why, or describe the content being added — let change_log carry the detail. Bad: 'Updated the hero heading with a punchier tone.' Good: 'Will add a **text section** about blueberry varieties after the features grid.'", "change_log coverage is MANDATORY: emit exactly one change_log entry per op, in the same order as ops[], describing what that specific op does. If ops has N entries, change_log must have N entries — never cluster multiple ops into one entry, never skip an op, never leave an op undescribed. The user reads change_log to decide whether to approve; a missing entry is a silent bait-and-switch.", "change_log entries should add specific detail NOT already in summary_for_user — e.g. list the actual content, items, or values being set. Do not paraphrase the summary.");
     }
-    lines.push("In summary_for_user, use simple markdown for readability: **bold** for key terms or labels, and bullet lists (- item) when listing multiple items, recommendations, or observations. Keep it scannable — avoid walls of text.", "When rewriting text, return plain text unless the prop is a rich-text prop (see below) or the user explicitly asks for markdown formatting. Do not wrap the entire rewrite in **bold** markers.", RULE_RICH_TEXT_PROPS, "For copy in German or similar long-compound languages, insert soft hyphen opportunities in long compounds where helpful for responsive line wrapping. Use the Unicode soft hyphen character (U+00AD), never HTML entities like ­ or ­.", opts.provider !== "openai" ? BLOCK_NAME_PRIVACY_ANTHROPIC : BLOCK_NAME_PRIVACY_OPENAI, "", "### suggested_next_actions", "2-4 short imperative phrases the user could type next (max 6 words each). Each MUST be a logical follow-up to the specific change just made — not a generic action. NEVER suggest 'Open /X' or any navigation to a page that the current plan is creating, duplicating, or otherwise still pending — the page won't exist until the user approves the plan, and there is no special navigation chip handler (suggestions are sent verbatim as the next chat command). Suggest plan refinements instead (e.g. 'Use a punchier hero headline', 'Add a card grid for spotlights', 'Drop the FAQ section'). Ask yourself: 'what would the user likely want to do next given THIS edit?' When the plan contains exactly one update_props op that changes a text field, the first 1-2 suggestions MUST be refinements of that same field (e.g. 'Make it shorter', 'Try a bolder tone', 'Revert to previous'). For example, after rewriting stats labels, suggest refining the same section ('Make the numbers bigger', 'Add a stat about X') — not unrelated actions like 'Change title' or 'Add a Testimonials section'. For needs_clarification, suggest the most likely concrete answers. Omit suggested_next_actions entirely if no contextual follow-up is obvious. Every suggestion must be an action the user can perform inside this editor — restricted to the block types in blockContracts / blockCatalogue (Hero, FeatureGrid, Testimonials, FAQAccordion, CTA, Card, CardGrid, RichText, TwoColumn, Banner, Carousel, Embed, Footer, Gallery, Quote, SiteHeader, Stats, Table, Tabs, Video) or SEO/site-config edits. NEVER suggest unsupported features: no forms, no email capture, no contact forms, no subscribe boxes, no newsletter signups, no popups/modals, no chat widgets, no live video, no payment/checkout — these require custom code the editor cannot produce. Never suggest actions outside the editor's scope such as A/B testing, analytics, performance monitoring, user research, or marketing strategy.");
+    lines.push("In summary_for_user, use simple markdown for readability: **bold** for key terms or labels, and bullet lists (- item) when listing multiple items, recommendations, or observations. Keep it scannable — avoid walls of text.", "When rewriting text, return plain text unless the prop is a rich-text prop (see below) or the user explicitly asks for markdown formatting. Do not wrap the entire rewrite in **bold** markers.", RULE_RICH_TEXT_PROPS, "For copy in German or similar long-compound languages, insert soft hyphen opportunities in long compounds where helpful for responsive line wrapping. Use the Unicode soft hyphen character (U+00AD), never HTML entities like ­ or ­.", opts.provider !== "openai" ? BLOCK_NAME_PRIVACY_ANTHROPIC : BLOCK_NAME_PRIVACY_OPENAI, "", "### suggested_next_actions", "2-4 short imperative phrases the user could type next (max 6 words each). Each MUST be a logical follow-up to the specific change just made — not a generic action. NEVER suggest 'Open /X' or any navigation to a page that the current plan is creating, duplicating, or otherwise still pending — the page won't exist until the user approves the plan, and there is no special navigation chip handler (suggestions are sent verbatim as the next chat command). Suggest plan refinements instead (e.g. 'Use a punchier hero headline', 'Add a card grid for spotlights', 'Drop the FAQ section'). Ask yourself: 'what would the user likely want to do next given THIS edit?' When the plan contains exactly one update_props op that changes a text field, the first 1-2 suggestions MUST be refinements of that same field (e.g. 'Make it shorter', 'Try a bolder tone', 'Revert to previous'). For example, after rewriting stats labels, suggest refining the same section ('Make the numbers bigger', 'Add a stat about X') — not unrelated actions like 'Change title' or 'Add a Testimonials section'. For needs_clarification, suggest the most likely concrete answers. Omit suggested_next_actions entirely if no contextual follow-up is obvious. Every suggestion must be an action the user can perform inside this editor — restricted to the block types listed in blockContracts / blockCatalogue for THIS site, or SEO/site-config edits. Never suggest adding a section this site has no block for; the catalogue is the whole list, not a sample of a larger one. NEVER suggest unsupported features: no forms, no email capture, no contact forms, no subscribe boxes, no newsletter signups, no popups/modals, no chat widgets, no live video, no payment/checkout — these require custom code the editor cannot produce. Never suggest actions outside the editor's scope such as A/B testing, analytics, performance monitoring, user research, or marketing strategy.");
+    return lines;
+}
+/*
+ * Prop-name corrections the model actually needs, and the reason they are not
+ * written as prose.
+ *
+ * Models reach for the obvious English word — `heading` for a section title,
+ * `question`/`answer` for an FAQ entry, `testimonial` for a quote — and several
+ * of Avocado's built-in blocks chose a different name. Telling the model so is
+ * worth real accuracy, and the line that did it read: "use 'title' not
+ * 'heading' for section titles (except Hero which uses 'heading')".
+ *
+ * That is a fact about Avocado's own catalogue stated as a fact about section
+ * titles. A site that brings its own blocks and names a text prop `heading` was
+ * being instructed, in the system prompt, to emit a prop its schema does not
+ * have. It is the same mistake the plan normalizer was fixed for in 0.3.3 — the
+ * normalizer no longer *creates* the wrong prop name, but nothing had stopped
+ * the prompt from *asking* for it, so the bug simply moved one layer up.
+ *
+ * So each correction now names the block type it is about, and is emitted only
+ * when the registry confirms it is still true: the type is in this site's
+ * catalogue, it really does reject the wrong key, and it really does accept the
+ * right one. A site that registers its own `Hero` with a `title` prop gets no
+ * line about Hero; a site with no FAQAccordion gets no line about `q`/`a`.
+ */
+const PROP_NAME_CORRECTIONS = [
+    { type: "Hero", wrong: "title", right: "heading", what: "the headline" },
+    { type: "FeatureGrid", wrong: "heading", right: "title", what: "the section title" },
+    { type: "CardGrid", wrong: "heading", right: "title", what: "the section title" },
+    { type: "Testimonials", wrong: "heading", right: "title", what: "the section title" },
+    { type: "FAQAccordion", wrong: "heading", right: "title", what: "the section title" },
+    { type: "CTA", wrong: "title", right: "heading", what: "the headline" },
+];
+const LIST_ITEM_CORRECTIONS = [
+    { type: "FAQAccordion", list: "items", wrong: "question", right: "q" },
+    { type: "FAQAccordion", list: "items", wrong: "answer", right: "a" },
+    { type: "Testimonials", list: "items", wrong: "testimonial", right: "quote" },
+];
+/**
+ * The subset of the corrections above that is true of THIS site's catalogue.
+ * Returns one prompt line per surviving correction, or an empty array.
+ */
+export function propNameCorrectionLines(effectiveBlockTypes) {
+    const present = new Set(effectiveBlockTypes);
+    const lines = [];
+    for (const c of PROP_NAME_CORRECTIONS) {
+        if (!present.has(c.type))
+            continue;
+        if (blockAcceptsProp(c.type, c.wrong))
+            continue;
+        if (!blockAcceptsProp(c.type, c.right))
+            continue;
+        lines.push(`${c.type} names ${c.what} '${c.right}', not '${c.wrong}'.`);
+    }
+    for (const c of LIST_ITEM_CORRECTIONS) {
+        if (!present.has(c.type))
+            continue;
+        if (blockListItemAcceptsKey(c.type, c.list, c.wrong))
+            continue;
+        if (!blockListItemAcceptsKey(c.type, c.list, c.right))
+            continue;
+        lines.push(`${c.type} \`${c.list}\` entries use '${c.right}', not '${c.wrong}'.`);
+    }
     return lines;
 }
-function sectionOperationCatalog() {
+function sectionOperationCatalog(opts) {
+    /*
+     * The universal rule first, so it governs even when no correction below
+     * applies: a prop name is a property of one block type's schema, never of the
+     * English word for the thing it holds.
+     */
+    const corrections = propNameCorrectionLines(opts.effectiveBlockTypes);
+    const addBlockPropRule = "add_block: use the exact prop names blockContracts lists for THAT block type. A prop name is a fact about one block's schema, not about the kind of content it holds — never carry a prop name across from another block type, and never infer one from the English word for the field ('heading', 'question', 'subtitle'). If blockContracts does not list a prop, the block does not have it: omit it rather than inventing a plausible name." +
+        (corrections.length > 0
+            ? ` Corrections for blocks on this site that models routinely get wrong: ${corrections.join(" ")}`
+            : "") +
+        " Always populate block.props with REAL content matching the user's request (headlines, body copy, list items grounded in the user's topic) — never emit add_block with empty or missing props; the system falls back to demo template defaults if you omit props, and that template will mislead the user. Placement: set `afterBlockId` to the id of the block the new section should follow — e.g. to add a section 'below the hero' / 'under the hero' / 'after the hero', set afterBlockId to the hero block's id from the pageOutline. Honor any position the user names ('below the hero', 'above the footer', 'after the pricing'). Omit afterBlockId only when no position is implied — it then appends at the very end of the page.";
     return [
         "## OPERATION CATALOG",
         "update_props: blockId is required and must target an existing block id (b_*). Never use a page route/path as blockId or path. Use blockId values from the pageOutline — never invent block IDs. Set patch to changed props only; use existing prop keys for the target block type. Emit keys in this exact order: op, pageSlug (if present), blockId, patch.",
-        "add_block: use exact prop names from blockContracts. Always populate block.props with REAL content matching the user's request (headlines, body copy, list items grounded in the user's topic) — never emit add_block with empty or missing props. The system will fall back to demo template defaults (e.g. 'Key features / Fast setup / Safe edits / Live updates') if you omit props, and that template will mislead the user. Common mistakes: use 'title' not 'heading' for section titles (except Hero which uses 'heading'), use 'q'/'a' not 'question'/'answer' for FAQ items, use 'quote' not 'testimonial' for Testimonials items. Placement: set `afterBlockId` to the id of the block the new section should follow — e.g. to add a section 'below the hero' / 'under the hero' / 'after the hero', set afterBlockId to the hero block's id from the pageOutline. Honor any position the user names ('below the hero', 'above the footer', 'after the pricing'). Omit afterBlockId only when no position is implied — it then appends at the very end of the page.",
+        addBlockPropRule,
         "remove_block: delete an ENTIRE block/section from the page (blockId required, no listKey). Use this — NOT remove_item — whenever the user removes a whole section, INCLUDING when they pick it by POSITION or TYPE: 'delete the second card grid', 'remove the first feature grid', 'hide the third section', 'remove the FAQ', 'get rid of the testimonials'. For 'remove ALL the <type>' / 'delete every <type>', emit one remove_block per matching block. remove_item is ONLY for deleting ONE entry inside a block's list and is signalled by an item word scoped INTO a container ('remove the last card IN the grid', 'delete a question FROM the FAQ'). A bare '[the Nth] <block-or-section-noun>' with no into-container preposition is ALWAYS a remove_block — never remove an item to satisfy it.",
         "add_item / update_item / remove_item / move_item: edit ONE entry inside a block's list prop (e.g. FeatureGrid `features`, FAQAccordion `items`, Testimonials `items`, CardGrid `cards`). Required on every item op: pageSlug, blockId, listKey. Address the target entry by its stable `itemId` (the item's `id` field) WHEN the block's full props are in your context — never guess or invent an itemId you cannot see. Otherwise use the 0-based `index`; the system resolves it against the current page state, so an index is safe too. add_item: supply `item` with the entry's props (do NOT invent an `id`, one is assigned); optional `afterItemId` (or `afterIndex`) positions it, omit ⇒ append. update_item: `patch` is a merge-patch over that entry's fields. move_item: `afterItemId` (or `afterIndex`) sets the new position, omit ⇒ move to front. When changing SEVERAL entries of one list in a single plan, replacing the whole list with one update_props op is also fine.",
         "update_page_meta: set SEO metadata (title, description, ogImage) on a page. Patch is merge-patch: only supplied keys update. Set a field to empty string to clear it.",

package/dist/checks/field-walk.d.ts

@@ -1,5 +1,5 @@
 import type { BlockManifest, PageDoc } from "@avocadostudio-ai/shared";
-import type { FieldEntry } from "./types.ts";
+import type { FieldEntry, LinkEntry } from "./types.ts";
 export declare function walkPageFields(page: PageDoc, manifest: BlockManifest): FieldEntry[];
 /**
  * Readable text inside a field value.
@@ -23,3 +23,20 @@ export declare function fieldText(value: unknown): string;
  * has two of anything else.
  */
 export declare function groupByBlock(fields: FieldEntry[]): Map<string, FieldEntry[]>;
+/**
+ * Every link on the page, from the two places links live.
+ *
+ * The first is a `link`- or `url`-kind prop, which is what every link-aware
+ * rule already walked. The second is prose — a markdown or ProseMirror link
+ * inside a richtext body — which none of them did, and which on a content page
+ * is where most of the links are. A live site's Bistro section carries four
+ * menu-PDF links written exactly that way; not one was ever inspected, and the
+ * one pointing at a misspelled filename had been wrong for months with nothing
+ * able to see it.
+ *
+ * A prose link is attributed to the field that contains it. That is honest
+ * about what we can offer — the panel can open the body, but there is no
+ * editable path for a span inside it — and `inProse` lets a rule word its
+ * finding accordingly instead of pretending otherwise.
+ */
+export declare function walkPageLinks(page: PageDoc, manifest: BlockManifest): LinkEntry[];

package/dist/checks/field-walk.js

@@ -1,3 +1,4 @@
+import { linksInRichText } from "@avocadostudio-ai/shared";
 /*
  * Flatten a page's block props into located, kind-tagged fields.
  *
@@ -150,3 +151,48 @@ export function groupByBlock(fields) {
     }
     return byBlock;
 }
+/**
+ * Every link on the page, from the two places links live.
+ *
+ * The first is a `link`- or `url`-kind prop, which is what every link-aware
+ * rule already walked. The second is prose — a markdown or ProseMirror link
+ * inside a richtext body — which none of them did, and which on a content page
+ * is where most of the links are. A live site's Bistro section carries four
+ * menu-PDF links written exactly that way; not one was ever inspected, and the
+ * one pointing at a misspelled filename had been wrong for months with nothing
+ * able to see it.
+ *
+ * A prose link is attributed to the field that contains it. That is honest
+ * about what we can offer — the panel can open the body, but there is no
+ * editable path for a span inside it — and `inProse` lets a rule word its
+ * finding accordingly instead of pretending otherwise.
+ */
+export function walkPageLinks(page, manifest) {
+    const out = [];
+    for (const field of walkPageFields(page, manifest)) {
+        const located = {
+            blockId: field.blockId,
+            blockType: field.blockType,
+            ...(field.blockLabel ? { blockLabel: field.blockLabel } : {}),
+            path: field.path,
+            ...(field.label ? { label: field.label } : {})
+        };
+        if (field.kind === "link" || field.kind === "url" || field.kind === "file") {
+            if (typeof field.value === "string" && field.value.trim() !== "") {
+                out.push({ ...located, value: field.value, inProse: false });
+            }
+            continue;
+        }
+        /*
+         * Only richtext. A `text` prop holding something that looks like markdown
+         * is a string that happens to contain brackets, and treating it as prose
+         * would invent links out of product copy.
+         */
+        if (field.kind !== "richtext")
+            continue;
+        for (const href of linksInRichText(field.value)) {
+            out.push({ ...located, value: href, inProse: true });
+        }
+    }
+    return out;
+}

package/dist/checks/rules-draft.js

@@ -1,4 +1,4 @@
-import { IMAGE_PLACEHOLDER, isKnownRoute, parseLink, toAltPath } from "@avocadostudio-ai/shared";
+import { IMAGE_PLACEHOLDER, isKnownRoute, normalizeLinkPath, parseLink, toAltPath } from "@avocadostudio-ai/shared";
 import { fieldText, groupByBlock } from "./field-walk.js";
 /*
  * The eleven-ish draft-tier rules. Each is a pure function; none does IO.
@@ -253,35 +253,98 @@ const thinContent = {
 // ---------------------------------------------------------------------------
 // Links, images, leftovers
 // ---------------------------------------------------------------------------
+/** A link's evidence, which points at the field the link was written in. */
+function linkEvidence(link) {
+    return {
+        source: "draft",
+        blockId: link.blockId,
+        blockType: link.blockType,
+        ...(link.blockLabel ? { blockLabel: link.blockLabel } : {}),
+        path: link.path,
+        excerpt: link.value
+    };
+}
+/*
+ * One finding per link, and a link written in prose needs a key that separates
+ * it from its neighbours: three PDF links in one body all sit at the same
+ * field path, so keying on the path alone collapses them into one finding and
+ * two broken links go unreported.
+ */
+function linkKey(link) {
+    const base = link.path === "" ? link.blockId : `${link.blockId}:${link.path}`;
+    return link.inProse ? `${base}#${link.value}` : base;
+}
 const internalLinkDead = {
     id: "seo.internal-link-dead",
     agent: "seo",
     severity: "warning",
     run: (ctx) => {
         const known = new Set(ctx.site.slugs);
-        return ctx.fields
+        return ctx.links
             /*
-             * `link` is the kind that means "navigation target"; `url` is still
-             * accepted because a custom block's manifest may declare either, and a
-             * dead link is a dead link whichever way it was tagged. `parseLink`
-             * screens out mailto/tel/anchors/external and the default "/", so only a
-             * real route reaches `isKnownRoute` — the same matcher the editor's link
-             * field uses inline, so the panel and the field cannot disagree.
+             * `ctx.links` already carries both sources — `link`/`url`/`file` props
+             * and hrefs written into prose. It used to read `ctx.fields` and so saw
+             * only the first, which meant the links a content page actually has, the
+             * ones inside its bodies, were never checked.
+             *
+             * `parseLink` screens out mailto/tel/anchors/external, the default "/",
+             * and now documents: a `.pdf` path is `kind: "file"` and is not a route,
+             * so it is not this rule's business. `fileLinkUnknown` below answers the
+             * question that *is* right for a file.
              */
-            .filter((f) => f.kind === "link" || f.kind === "url")
+            .filter((link) => {
+            const parsed = parseLink(link.value);
+            return parsed.kind === "page" && parsed.path?.startsWith("/") === true;
+        })
             /*
              * Absolute routes only, as before. A bare "pricing" is a relative link
              * and broken from any page but the root, but flagging it is a separate
              * judgement call from this rule's, and one that would light up existing
              * sites without warning.
              */
-            .filter((f) => parseLink(f.value).path?.startsWith("/") === true)
-            .filter((f) => !isKnownRoute(String(f.value), known))
-            .map((field) => ({
-            key: field.path === "" ? field.blockId : `${field.blockId}:${field.path}`,
+            .filter((link) => !isKnownRoute(link.value, known))
+            .map((link) => ({
+            key: linkKey(link),
             title: `Link points at a page that does not exist`,
-            detail: String(field.value),
-            evidence: evidenceFor(field, String(field.value))
+            detail: link.inProse ? `${link.value} — written in ${link.label ?? link.path}` : link.value,
+            evidence: linkEvidence(link)
+        }));
+    }
+};
+/*
+ * A link to a document the site does not have.
+ *
+ * This is the rule that pays for the `file` kind. A menu PDF is linked by
+ * hand-typed path, nothing renders a 404 until a customer clicks it, and the
+ * filename is usually long and often misspelled — one live site links
+ * `/downloads/AadventureArenaBerm-Gruppen-DE.pdf`, and whether that is the real
+ * filename or a typo for it is not a question anyone has been able to ask.
+ *
+ * It runs only when the site can enumerate its documents. `ctx.site.assets`
+ * undefined means it cannot, and then this rule returns nothing rather than
+ * reporting every document on the site as missing — the same discipline as
+ * `resolveLink`, where "we did not check" must not read as "it is not there".
+ */
+const fileLinkUnknown = {
+    id: "content.file-link-unknown",
+    agent: "seo",
+    severity: "error",
+    run: (ctx) => {
+        const assets = ctx.site.assets;
+        if (!assets)
+            return [];
+        const known = new Set(assets.map((a) => normalizeLinkPath(a.path)));
+        return ctx.links
+            .filter((link) => {
+            const parsed = parseLink(link.value);
+            return parsed.kind === "file" && parsed.path?.startsWith("/") === true;
+        })
+            .filter((link) => !known.has(normalizeLinkPath(parseLink(link.value).path ?? "")))
+            .map((link) => ({
+            key: linkKey(link),
+            title: "Link points at a document the site does not have",
+            detail: link.inProse ? `${link.value} — written in ${link.label ?? link.path}` : link.value,
+            evidence: linkEvidence(link)
         }));
     }
 };
@@ -370,6 +433,7 @@ export const DRAFT_RULES = [
     headingOrder,
     thinContent,
     internalLinkDead,
+    fileLinkUnknown,
     altMissing,
     unfinished
 ];

package/dist/checks/run-checks.d.ts

@@ -1,6 +1,6 @@
 import type { BlockManifest, PageDoc, SiteConfig } from "@avocadostudio-ai/shared";
 import type { CheckRunRecord, CheckRunTrigger, DurableStore } from "../durable/types.ts";
-import type { CheckRule } from "./types.ts";
+import type { CheckRule, SiteAsset } from "./types.ts";
 /**
  * The fingerprint: identity of a problem, not of an occurrence of it.
  *
@@ -24,6 +24,16 @@ export type RunChecksArgs = {
      * page's title as unique, nor every link into them as dead.
      */
     slugs?: string[];
+    /**
+     * The documents the site holds, when the caller could list them.
+     *
+     * Omitted — not `[]` — when it could not. `content.file-link-unknown` is
+     * silent without this, because a site that cannot enumerate its assets has no
+     * grounds to call any of its own document links broken. Filling it is the
+     * caller's job because listing assets is IO, and every rule in this directory
+     * is a pure function by construction.
+     */
+    assets?: SiteAsset[];
     rules?: CheckRule[];
     store?: DurableStore;
     runId?: string;

package/dist/checks/run-checks.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { getDurableStore } from "../durable/durable-store-singleton.js";
 import { NEUTRAL_PAGE_WEIGHT, impactFor } from "../durable/finding-impact.js";
-import { walkPageFields } from "./field-walk.js";
+import { walkPageFields, walkPageLinks } from "./field-walk.js";
 import { computePageWeights } from "./page-weight.js";
 import { DRAFT_RULES } from "./rules-draft.js";
 /**
@@ -25,7 +25,10 @@ export async function runDraftChecks(args) {
     const site = {
         slugs: args.pages.map((p) => p.slug),
         pages: args.pages.map((p) => ({ slug: p.slug, title: p.title, ...(p.meta ? { meta: p.meta } : {}) })),
-        config: args.siteConfig ?? {}
+        config: args.siteConfig ?? {},
+        // Present only when the caller could enumerate the site's documents.
+        // Passing `[]` where it could not would make every file link report broken.
+        ...(args.assets ? { assets: args.assets } : {})
     };
     const wanted = args.slugs ? new Set(args.slugs) : null;
     const scanned = args.pages.filter((p) => (wanted ? wanted.has(p.slug) : true));
@@ -41,8 +44,11 @@ export async function runDraftChecks(args) {
      * pages reuse their entry rather than being walked a second time.
      */
     const fieldsBySlug = new Map();
-    for (const page of args.pages)
+    const linksBySlug = new Map();
+    for (const page of args.pages) {
         fieldsBySlug.set(page.slug, walkPageFields(page, args.manifest));
+        linksBySlug.set(page.slug, walkPageLinks(page, args.manifest));
+    }
     const weights = computePageWeights({ pages: site.pages, fieldsBySlug, config: site.config });
     await store.startCheckRun({
         id: runId,
@@ -62,7 +68,8 @@ export async function runDraftChecks(args) {
                 page,
                 site,
                 manifest: args.manifest,
-                fields: fieldsBySlug.get(page.slug) ?? []
+                fields: fieldsBySlug.get(page.slug) ?? [],
+                links: linksBySlug.get(page.slug) ?? []
             };
             for (const rule of rules) {
                 // One rule throwing must not cost the run every other rule's findings —

package/dist/checks/session-runner.js

@@ -1,6 +1,7 @@
 import { buildBlockManifest } from "@avocadostudio-ai/shared";
 import { getSessionDraft, getSiteConfig } from "../state/session-state.js";
 import { runDraftChecks } from "./run-checks.js";
+import { getSiteAssets } from "../state/site-assets.js";
 /*
  * Binds the pure rules engine to session state.
  *
@@ -10,6 +11,8 @@ import { runDraftChecks } from "./run-checks.js";
  * the HTTP action and the triggers below run identical code.
  */
 export async function runChecksForSession(args) {
+    // `undefined` when the site cannot list its documents — see `site-assets.ts`.
+    const assets = await getSiteAssets();
     return runDraftChecks({
         scopeKey: args.scopeKey,
         pages: [...getSessionDraft(args.scopeKey).values()],
@@ -19,6 +22,7 @@ export async function runChecksForSession(args) {
         manifest: buildBlockManifest(),
         siteConfig: getSiteConfig(args.scopeKey),
         trigger: args.trigger,
+        ...(assets ? { assets } : {}),
         ...(args.slugs?.length ? { slugs: args.slugs } : {})
     });
 }

package/dist/checks/types.d.ts

@@ -22,6 +22,37 @@ export type FieldEntry = {
      */
     container: string;
 };
+/**
+ * One link on the page, wherever it was written.
+ *
+ * Separate from `FieldEntry` because most links are not fields. A `link`-kind
+ * prop is one source; the other — and on a content-heavy page much the larger —
+ * is prose: `[Menükarte](/downloads/menu-de.pdf)` inside a richtext body. Every
+ * link-aware rule read declared fields only, so those were never checked.
+ *
+ * A prose link has no editable path of its own, which is why `path` points at
+ * the *field that contains it* and `inProse` says so. A finding can still send
+ * you to the right control; it just cannot highlight the link itself.
+ */
+export type LinkEntry = {
+    blockId: string;
+    blockType: string;
+    blockLabel?: string;
+    /** The field the link is in — its own path for a link field, the containing field for a prose link. */
+    path: string;
+    label?: string;
+    /** The href as written. */
+    value: string;
+    /** True when this came out of a richtext body rather than from a link field. */
+    inProse: boolean;
+};
+/** A document the site can link to. Empty is not the same as absent — see `assets`. */
+export type SiteAsset = {
+    path: string;
+    name?: string;
+    contentType?: string;
+    size?: number;
+};
 /** The other pages, for the rules that cannot be answered from one page. */
 export type SiteView = {
     slugs: string[];
@@ -29,6 +60,17 @@ export type SiteView = {
         meta?: PageDoc["meta"];
     }>;
     config: SiteConfig;
+    /**
+     * The documents the site holds, when it can enumerate them.
+     *
+     * `undefined` and `[]` mean different things and rules must keep them apart:
+     * undefined is "this site cannot list its assets", under which no rule may
+     * conclude a file link is broken; `[]` is "it listed them, and there are
+     * none", under which every file link is broken and saying so is correct.
+     * A site answers this by implementing `getMedia`; most do not, and for those
+     * the file rules stay silent rather than reporting every document on the site.
+     */
+    assets?: SiteAsset[];
 };
 export type CheckContext = {
     scopeKey: string;
@@ -37,6 +79,8 @@ export type CheckContext = {
     manifest: BlockManifest;
     /** Every field on the page, already flattened. Rules should not re-walk. */
     fields: FieldEntry[];
+    /** Every link on the page — from link fields and from prose alike. */
+    links: LinkEntry[];
 };
 /**
  * What a rule returns.