@aglyn/plugins-ai 1.0.0-beta.237 → 1.0.0-beta.239

package/src/lib/runtime/ai-dataset-generation.js

@@ -0,0 +1,127 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { AI_ROUTING_TABLE } from "../providers/routing.js";
+import { AI_DATASET_LIMITS, AI_DATASET_LIST_SEPARATOR, AI_DATASET_TOOL, AI_DATASET_TOOL_NAME, checkAiDataset } from "../tools/ai-dataset-tool.js";
+import { runValidatedGeneration } from "./ai-doctrine.js";
+/**
+ * A SITE'S DATASETS (AGL-3616): the typed fields and first records of one
+ * dataset a site plan created, through the doctrine's generation call and the
+ * strict `submit_dataset` tool. The data plugin's writer stores what it
+ * answers; nothing here writes.
+ *
+ * Routed as `job.products`, the row a store's first products are proposed on
+ * (no thinking, a structured list from a brief, held to the storefront claim
+ * rules): one dataset of a dozen records is the same work. Its answer is held
+ * to a ceiling of its own under that row's. The rules are cached and
+ * byte-identical; the site's words, the dataset and the pages that show it
+ * ride in the user turn.
+ */ /** The step a dataset is routed as. */ export const AI_DATASET_STEP = 'job.products';
+/**
+ * One dataset's answer ceiling: twelve fields and twelve records of a few
+ * sentences each, written as JSON, about 9,000 characters at three a token
+ * with room; under the routing row's.
+ */ export const AI_DATASET_MAX_TOKENS = Math.min(4000, AI_ROUTING_TABLE[AI_DATASET_STEP].maxTokens);
+/** The generation kind a dataset is asked under, which the doctrine scopes. */ export const AI_DATASET_KIND = 'dataset';
+/** The rules for one dataset. Byte-identical on every request. */ export const AI_DATASET_INSTRUCTIONS = [
+    {
+        text: 'You design one dataset of a new website: a list of like things — a menu, a team, services, portfolio pieces, events, questions and answers — kept as records the owner edits in one place, which the site’s pages list.\n\n' + `Answer by calling ${AI_DATASET_TOOL_NAME} exactly once. A reply in prose cannot be used.\n\n` + 'Rules:\n' + [
+            'Keep the planned fields, in order and named exactly as planned; the pages around the dataset already name them. Add a field only where the records clearly need it.',
+            'Type each field: text for words, including a date or a time written the way a visitor reads it; number or integer only for a figure a visitor compares; boolean for yes or no; list for a few short tags. The first field names each record and is text.',
+            `Write ${AI_DATASET_LIMITS.recordsMin} to ${AI_DATASET_LIMITS.recordsMax} records, as many as the brief supports: what the business actually offers, in its own words where the brief gives them, otherwise plain and general enough to be true of it.`,
+            'Never invent a fact: no price, date, address, phone number, award, credential, client or number the brief does not give, and no review, testimonial, rating or quote from anyone. Leave a value "" rather than make one up.',
+            'Never give a person a name the brief does not give: a team member the brief does not name is their role, such as "Head chef".',
+            'Never say anything cures, treats, heals or prevents anything, and never promise a health, financial or legal result.',
+            `Values are plain text with no links, markup, emoji or square brackets, at most ${AI_DATASET_LIMITS.valueMax} characters each; a description is one to three sentences.`,
+            'Write in the language of the brief.'
+        ].map((rule)=>`- ${rule}`).join('\n'),
+        cacheBreakpoint: true
+    }
+];
+/** The user turn: the site's words, the dataset, and where it is shown. */ export function aiDatasetPrompt(input) {
+    return [
+        'Brief:',
+        input.brief.trim(),
+        `Dataset: “${input.name}” — ${input.why.trim() || 'the site’s structured content'}`,
+        `Planned fields: ${input.fields.length ? input.fields.map((field)=>`“${field}”`).join(', ') : '(none: choose them)'}`,
+        input.shownIn.length ? `Listed on: ${input.shownIn.join('; ')}.` : 'Listed on the site’s pages.',
+        input.recordPages ? 'Each record also gets a page of its own, so give each one enough to read: a sentence or two describing it.' : 'Each record is shown as a card, so keep its values short.'
+    ].join('\n');
+}
+/** Design one dataset. It writes nothing to the site. */ export function generateAiDataset(input) {
+    var _input_maxTokens;
+    const row = AI_ROUTING_TABLE[AI_DATASET_STEP];
+    return runValidatedGeneration(AI_DATASET_KIND, _extends({
+        step: AI_DATASET_STEP
+    }, input.settings ? {
+        settings: input.settings
+    } : {}, input.model ? {
+        model: input.model
+    } : {}, {
+        instructions: AI_DATASET_INSTRUCTIONS,
+        messages: [
+            {
+                role: 'user',
+                content: aiDatasetPrompt(input)
+            }
+        ],
+        tool: AI_DATASET_TOOL,
+        maxTokens: (_input_maxTokens = input.maxTokens) != null ? _input_maxTokens : AI_DATASET_MAX_TOKENS
+    }, row.thinking ? {
+        thinking: row.thinking
+    } : {}, row.effort ? {
+        effort: row.effort
+    } : {}, input.signal ? {
+        signal: input.signal
+    } : {}, input.provider ? {
+        provider: input.provider
+    } : {}, {
+        check: (answer)=>checkAiDataset(answer, {
+                planned: input.fields,
+                merchantWords: input.merchantWords
+            })
+    }));
+}
+/** A designed dataset as the data plugin's `dataset` writer takes it: values by field name. */ export function aiDatasetDraftContent(name, dataset, options) {
+    const records = dataset.records.map((values)=>{
+        const record = {};
+        dataset.fields.forEach((field, column)=>{
+            var _values_column;
+            const value = ((_values_column = values[column]) != null ? _values_column : '').trim();
+            if (!value) return;
+            if (field.type === 'list') {
+                record[field.name] = value.split(AI_DATASET_LIST_SEPARATOR.trim()).map((part)=>part.trim()).filter(Boolean);
+            } else if (field.type === 'number' || field.type === 'integer') {
+                record[field.name] = value.replace(/,/g, '');
+            } else {
+                record[field.name] = value;
+            }
+        });
+        return record;
+    });
+    return _extends({
+        name,
+        fields: dataset.fields.map((field)=>({
+                name: field.name,
+                type: field.type
+            })),
+        records
+    }, options.recordPages && dataset.fields[0] ? {
+        pageAddressFrom: dataset.fields[0].name
+    } : {});
+}
+
+//# sourceMappingURL=ai-dataset-generation.js.map

package/src/lib/runtime/ai-dataset-generation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/runtime/ai-dataset-generation.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { AiStepKind } from '../providers/catalog'\nimport type { AiProvider } from '../providers/contract'\nimport { AI_ROUTING_TABLE, type AiPluginSettings } from '../providers/routing'\nimport {\n  AI_DATASET_LIMITS,\n  AI_DATASET_LIST_SEPARATOR,\n  AI_DATASET_TOOL,\n  AI_DATASET_TOOL_NAME,\n  checkAiDataset,\n  type AiDataset,\n} from '../tools/ai-dataset-tool'\nimport { runValidatedGeneration, type AiValidatedGeneration } from './ai-doctrine'\nimport type { AiSystemBlock } from './ai-runtime'\n\n/**\n * A SITE'S DATASETS (AGL-3616): the typed fields and first records of one\n * dataset a site plan created, through the doctrine's generation call and the\n * strict `submit_dataset` tool. The data plugin's writer stores what it\n * answers; nothing here writes.\n *\n * Routed as `job.products`, the row a store's first products are proposed on\n * (no thinking, a structured list from a brief, held to the storefront claim\n * rules): one dataset of a dozen records is the same work. Its answer is held\n * to a ceiling of its own under that row's. The rules are cached and\n * byte-identical; the site's words, the dataset and the pages that show it\n * ride in the user turn.\n */\n\n/** The step a dataset is routed as. */\nexport const AI_DATASET_STEP: AiStepKind = 'job.products'\n\n/**\n * One dataset's answer ceiling: twelve fields and twelve records of a few\n * sentences each, written as JSON, about 9,000 characters at three a token\n * with room; under the routing row's.\n */\nexport const AI_DATASET_MAX_TOKENS = Math.min(4_000, AI_ROUTING_TABLE[AI_DATASET_STEP].maxTokens)\n\n/** The generation kind a dataset is asked under, which the doctrine scopes. */\nexport const AI_DATASET_KIND = 'dataset'\n\n/** The rules for one dataset. Byte-identical on every request. */\nexport const AI_DATASET_INSTRUCTIONS: AiSystemBlock[] = [\n  {\n    text:\n      'You design one dataset of a new website: a list of like things — a menu, a team, services, portfolio pieces, events, questions and answers — kept as records the owner edits in one place, which the site’s pages list.\\n\\n' +\n      `Answer by calling ${AI_DATASET_TOOL_NAME} exactly once. A reply in prose cannot be used.\\n\\n` +\n      'Rules:\\n' +\n      [\n        'Keep the planned fields, in order and named exactly as planned; the pages around the dataset already name them. Add a field only where the records clearly need it.',\n        'Type each field: text for words, including a date or a time written the way a visitor reads it; number or integer only for a figure a visitor compares; boolean for yes or no; list for a few short tags. The first field names each record and is text.',\n        `Write ${AI_DATASET_LIMITS.recordsMin} to ${AI_DATASET_LIMITS.recordsMax} records, as many as the brief supports: what the business actually offers, in its own words where the brief gives them, otherwise plain and general enough to be true of it.`,\n        'Never invent a fact: no price, date, address, phone number, award, credential, client or number the brief does not give, and no review, testimonial, rating or quote from anyone. Leave a value \"\" rather than make one up.',\n        'Never give a person a name the brief does not give: a team member the brief does not name is their role, such as \"Head chef\".',\n        'Never say anything cures, treats, heals or prevents anything, and never promise a health, financial or legal result.',\n        `Values are plain text with no links, markup, emoji or square brackets, at most ${AI_DATASET_LIMITS.valueMax} characters each; a description is one to three sentences.`,\n        'Write in the language of the brief.',\n      ]\n        .map((rule) => `- ${rule}`)\n        .join('\\n'),\n    cacheBreakpoint: true,\n  },\n]\n\nexport interface AiDatasetPromptInput {\n  /** The site's words: the brief and its answers, as a unit's brief carries them. */\n  brief: string\n  /** The dataset as the plan named it, and why it has one. */\n  name: string\n  why: string\n  /** The field names the plan gave it. */\n  fields: readonly string[]\n  /** The sections that list it, by page: \"Menu › Our dishes (12 items)\". */\n  shownIn: readonly string[]\n  /** Whether each record also gets a page of its own. */\n  recordPages: boolean\n}\n\n/** The user turn: the site's words, the dataset, and where it is shown. */\nexport function aiDatasetPrompt(input: AiDatasetPromptInput): string {\n  return [\n    'Brief:',\n    input.brief.trim(),\n    `Dataset: “${input.name}” — ${input.why.trim() || 'the site’s structured content'}`,\n    `Planned fields: ${input.fields.length ? input.fields.map((field) => `“${field}”`).join(', ') : '(none: choose them)'}`,\n    input.shownIn.length ? `Listed on: ${input.shownIn.join('; ')}.` : 'Listed on the site’s pages.',\n    input.recordPages\n      ? 'Each record also gets a page of its own, so give each one enough to read: a sentence or two describing it.'\n      : 'Each record is shown as a card, so keep its values short.',\n  ].join('\\n')\n}\n\nexport interface GenerateAiDatasetInput extends AiDatasetPromptInput {\n  /** What a claim or a price may be quoted from: the brief and the site's answers. */\n  merchantWords: string\n  settings?: AiPluginSettings\n  model?: string\n  maxTokens?: number\n  signal?: AbortSignal\n  provider?: AiProvider\n}\n\n/** Design one dataset. It writes nothing to the site. */\nexport function generateAiDataset(input: GenerateAiDatasetInput): Promise<AiValidatedGeneration<AiDataset>> {\n  const row = AI_ROUTING_TABLE[AI_DATASET_STEP]\n  return runValidatedGeneration(AI_DATASET_KIND, {\n    step: AI_DATASET_STEP,\n    ...(input.settings ? { settings: input.settings } : {}),\n    ...(input.model ? { model: input.model } : {}),\n    instructions: AI_DATASET_INSTRUCTIONS,\n    messages: [{ role: 'user', content: aiDatasetPrompt(input) }],\n    tool: AI_DATASET_TOOL,\n    maxTokens: input.maxTokens ?? AI_DATASET_MAX_TOKENS,\n    ...(row.thinking ? { thinking: row.thinking } : {}),\n    ...(row.effort ? { effort: row.effort } : {}),\n    ...(input.signal ? { signal: input.signal } : {}),\n    ...(input.provider ? { provider: input.provider } : {}),\n    check: (answer) => checkAiDataset(answer, { planned: input.fields, merchantWords: input.merchantWords }),\n  }) as Promise<AiValidatedGeneration<AiDataset>>\n}\n\n/** A designed dataset as the data plugin's `dataset` writer takes it: values by field name. */\nexport function aiDatasetDraftContent(\n  name: string,\n  dataset: AiDataset,\n  options: { recordPages: boolean },\n): Record<string, unknown> {\n  const records = dataset.records.map((values) => {\n    const record: Record<string, unknown> = {}\n    dataset.fields.forEach((field, column) => {\n      const value = (values[column] ?? '').trim()\n      if (!value) return\n      if (field.type === 'list') {\n        record[field.name] = value.split(AI_DATASET_LIST_SEPARATOR.trim()).map((part) => part.trim()).filter(Boolean)\n      } else if (field.type === 'number' || field.type === 'integer') {\n        record[field.name] = value.replace(/,/g, '')\n      } else {\n        record[field.name] = value\n      }\n    })\n    return record\n  })\n  return {\n    name,\n    fields: dataset.fields.map((field) => ({ name: field.name, type: field.type })),\n    records,\n    // A record page shows each record at an address made from its name.\n    ...(options.recordPages && dataset.fields[0] ? { pageAddressFrom: dataset.fields[0].name } : {}),\n  }\n}\n"],"names":["AI_ROUTING_TABLE","AI_DATASET_LIMITS","AI_DATASET_LIST_SEPARATOR","AI_DATASET_TOOL","AI_DATASET_TOOL_NAME","checkAiDataset","runValidatedGeneration","AI_DATASET_STEP","AI_DATASET_MAX_TOKENS","Math","min","maxTokens","AI_DATASET_KIND","AI_DATASET_INSTRUCTIONS","text","recordsMin","recordsMax","valueMax","map","rule","join","cacheBreakpoint","aiDatasetPrompt","input","brief","trim","name","why","fields","length","field","shownIn","recordPages","generateAiDataset","row","step","settings","model","instructions","messages","role","content","tool","thinking","effort","signal","provider","check","answer","planned","merchantWords","aiDatasetDraftContent","dataset","options","records","values","record","forEach","column","value","type","split","part","filter","Boolean","replace","pageAddressFrom"],"mappings":"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"}

package/src/lib/runtime/ai-doctrine-validators.d.ts

@@ -747,8 +747,53 @@ export declare function detectPlanSplitLists(plan: AiBuildPlan, inventory: AiSit
  * creation before the rules read the plan, when exactly one creation matches
  * it with case, spaces and punctuation ignored. Two that match, or none, are
  * left for the rules to ask about.
+ *
+ * So is a creation named without its prefix — `Contact form` in a section's
+ * uses for the "Contact form" the plan creates — where the name is no record
+ * the site has (AGL-3660). A re-asked plan told to place its form "by id"
+ * can answer with the form's bare name, which is no reference at all.
+ */
+export declare function aiSettlePlanRefs(plan: AiBuildPlan, inventory?: AiSiteInventory | null): AiBuildPlan;
+/**
+ * What customers say, which no dataset of the site's holds: a review, a
+ * testimonial, a rating, a quote (AGL-3616). A job never writes them for the
+ * people who did not, so a dataset of them is one nothing can seed.
+ */
+export declare const AI_DATASET_SAID_NAME: RegExp;
+/**
+ * A plan that creates more datasets than this job may make is settled in
+ * code, never re-asked (AGL-3616). The live eval of 2026-10-10 refused a
+ * dental practice's plan four times over for a fourth dataset, and a food
+ * bank's re-ask for one broke a layout rule its first answer had kept.
+ *
+ * A dataset of what customers say (`AI_DATASET_SAID_NAME`, in its name or a
+ * field) is let go first, whatever the cap: both of those plans made one of
+ * testimonials, which nothing may seed.
+ *
+ * The datasets kept are the most useful: the ones the most sections list,
+ * a record template counting double, plan order breaking ties. Each one let
+ * go leaves the plan whole — its `new:` reference comes off every section,
+ * a record template of it becomes a page of its own, and a section that
+ * listed it shows fewer items than rule 8 binds, so its items are written
+ * out on the page. Where the job may create no dataset at all, rule 7 still
+ * asks, as it does for any creation.
+ */
+export declare function aiSettlePlanDatasets(plan: AiBuildPlan, capabilities?: AiPlanCapabilities | null): AiBuildPlan;
+/**
+ * A form's dataset, settled in code before the rules read the plan
+ * (AGL-3616, Zach 2026-10-10: Aglyn AI's forms write to its datasets).
+ *
+ *  - A `writesTo` that names nothing the form can write to comes off: a
+ *    `new:` of no dataset this plan creates, an id the inventory does not
+ *    hold, or a dataset this job may not create. The form is then the
+ *    form it always was, its submissions in the Inbox. A dataset the
+ *    inventory holds, named by its name rather than its id, is given its id.
+ *  - A dataset this plan creates for a form holds the people who send it:
+ *    no page lists it and none is its record template, so its `new:` comes
+ *    off every section and record that named it, and a section that listed
+ *    it shows fewer items than rule 8 binds.
  */
-export declare function aiSettlePlanRefs(plan: AiBuildPlan): AiBuildPlan;
+export declare function aiSettlePlanFormDatasets(plan: AiBuildPlan, inventory: AiSiteInventory | null, capabilities?: AiPlanCapabilities | null): AiBuildPlan;
 /**
  * A page that names no layout, on a site where only one layout can frame it,
  * is put in that layout before the rules read the plan (2026-10-07). The
@@ -760,6 +805,37 @@ export declare function aiSettlePlanRefs(plan: AiBuildPlan): AiBuildPlan;
  * so the rule still asks.
  */
 export declare function aiSettlePlanLayouts(plan: AiBuildPlan, inventory: AiSiteInventory | null, capabilities?: AiPlanCapabilities | null): AiBuildPlan;
+/** The contact form a plan is given when a section collects answers and the plan makes no form. */
+export declare const AI_PLAN_SETTLED_FORM: {
+    readonly name: "Contact form";
+    readonly why: "Visitors need a way to reach the owner, and the site has no saved form for it.";
+    readonly fields: readonly ["name", "email", "message"];
+};
+/**
+ * A section that collects answers and places no saved form is given one
+ * before the rules read the plan (AGL-3660), rather than failing the build.
+ * A production guided start for a ceramic artist's portfolio (2026-10-09,
+ * five pages, 94 credits refunded) planned a section that asks for
+ * commissions on its work page without placing the contact form the plan
+ * made for its Contact page; the answer and its re-ask both did, and rule 3
+ * failed the whole site for one section.
+ *
+ * The section places, in order of preference:
+ * 1. the form whose name best matches it, among those the plan creates and
+ *    the site has, preferring one the plan already places — so a guided
+ *    start, which makes one form, places that same form again rather than a
+ *    second one;
+ * 2. where there is no form at all and this job may create one, a form the
+ *    plan now creates: named for the `new:` reference the section already
+ *    holds when it names a form it never declared, the contact form
+ *    otherwise.
+ *
+ * Nothing is taken out of the plan: the section keeps its name, its other
+ * uses and its items. Where the site has no form and the job may create none,
+ * rule 3 asks for nothing (AGL-3596), and neither does this. A section whose
+ * uses are already full is left for the rule to ask about.
+ */
+export declare function aiSettlePlanForms(plan: AiBuildPlan, inventory: AiSiteInventory | null, capabilities?: AiPlanCapabilities | null): AiBuildPlan;
 /**
  * Rule 2 (plan): every screen declares a layout, no section is a copy of a
  * layout region, and no section places a layout, which frames a whole screen

package/src/lib/runtime/ai-doctrine-validators.js

@@ -23,7 +23,7 @@ import { FREE_AI_TASTE_CREDITS_PER_MONTH } from "../plan-entitlements.js";
 import { REUSABLE_INSTANCE_COMPONENT_ID, REUSABLE_INSTANCE_PROP_VALUES_KEY } from "@aglyn/aglyn/app-utils/reusable-component-keys";
 import { parseBreakpointSpan } from "@aglyn/shared-data-enums/breakpoint-span";
 import { renderEmailHtml } from "@aglyn/shared-util-email/email-render";
-import { AI_BUILD_PLAN_CREATION_NOUNS, AI_BUILD_PLAN_EMBED_HOST_NAMES, AI_PLAN_ASKS_FOR_VIDEO, aiEmbedHostOf, aiEmbedVideoKey, aiPlanCreateFor, aiPlanSlugKey, aiPlanUndeclaredRefs, isAiPlanNewRef } from "../model/ai-build-plan.js";
+import { AI_BUILD_PLAN_CREATION_NOUNS, AI_BUILD_PLAN_EMBED_HOST_NAMES, AI_BUILD_PLAN_LIMITS, AI_PLAN_ASKS_FOR_VIDEO, aiEmbedHostOf, aiEmbedVideoKey, AI_PLAN_DATASET_ITEM_OP, aiPlanCreateFor, aiPlanFormDatasetNames, aiPlanItemFor, aiPlanSlugKey, aiPlanUndeclaredRefs, isAiPlanNewRef } from "../model/ai-build-plan.js";
 import { aiCreationNoun, aiPlanCanPlaceForm, aiPlanUncreatable, aiPlanUncreatableKind } from "../model/ai-plan-capabilities.js";
 import { aiFreeSiteSectionsWithin, aiSiteHomeMinSections, aiSitePlanIsHome } from "../model/ai-site-job.js";
 import { AI_INSTANCE_REF_PROP, validateAiNodeTree } from "./ai-node-tree.js";
@@ -279,12 +279,15 @@ function listNames(ids, tree) {
     const index = indexShapes(tree);
     /**
    * A compiled picture card (AGL-3660): a Stack that opens with its picture,
-   * in a cell of a grid — or that cell, holding only the card.
+   * in a cell of a grid — or that cell, holding only the card. A storefront's
+   * icon column (AGL-3676), a Stack that opens with its library icon, is the
+   * compiler's the same way: no model writes an Icon on a page.
    */ const card = (id)=>{
         var _node_nodes, _tree_nodes_first;
         const node = id === undefined ? undefined : tree.nodes[id];
         const first = node == null ? void 0 : (_node_nodes = node.nodes) == null ? void 0 : _node_nodes[0];
-        return (node == null ? void 0 : node.componentId) === 'muiStack' && first !== undefined && ((_tree_nodes_first = tree.nodes[first]) == null ? void 0 : _tree_nodes_first.componentId) === 'image';
+        const opens = first === undefined ? undefined : (_tree_nodes_first = tree.nodes[first]) == null ? void 0 : _tree_nodes_first.componentId;
+        return (node == null ? void 0 : node.componentId) === 'muiStack' && (opens === 'image' || opens === 'icon');
     };
     const pictureCard = (id)=>{
         var _node_props, _node_nodes, _index_visits_find, _tree_nodes_parentId;
@@ -3286,11 +3289,18 @@ const FORM_SECTION_NAME = /\bform\b|\bsign[- ]?up\b|\bsubscribe\b|\bnewsletter\b
  * creation before the rules read the plan, when exactly one creation matches
  * it with case, spaces and punctuation ignored. Two that match, or none, are
  * left for the rules to ask about.
- */ export function aiSettlePlanRefs(plan) {
+ *
+ * So is a creation named without its prefix — `Contact form` in a section's
+ * uses for the "Contact form" the plan creates — where the name is no record
+ * the site has (AGL-3660). A re-asked plan told to place its form "by id"
+ * can answer with the form's bare name, which is no reference at all.
+ */ export function aiSettlePlanRefs(plan, inventory = null) {
     if (!plan.create.length) return plan;
+    const kinds = inventoryKinds(inventory);
     const resolve = (ref)=>{
-        if (!isAiPlanNewRef(ref) || aiPlanCreateFor(plan, ref)) return ref;
-        const key = creationKey(ref.slice('new:'.length));
+        if (!ref || kinds.has(ref) || aiPlanCreateFor(plan, ref)) return ref;
+        const key = creationKey(isAiPlanNewRef(ref) ? ref.slice('new:'.length) : ref);
+        if (!key) return ref;
         const matches = plan.create.filter((entry)=>creationKey(entry.name) === key);
         return matches.length === 1 ? `new:${matches[0].name}` : ref;
     };
@@ -3314,6 +3324,135 @@ const FORM_SECTION_NAME = /\bform\b|\bsign[- ]?up\b|\bsubscribe\b|\bnewsletter\b
         screens
     }) : plan;
 }
+/**
+ * What customers say, which no dataset of the site's holds: a review, a
+ * testimonial, a rating, a quote (AGL-3616). A job never writes them for the
+ * people who did not, so a dataset of them is one nothing can seed.
+ */ export const AI_DATASET_SAID_NAME = /\b(reviews?|testimonials?|ratings?|quotes?|stars?|endorsements?)\b/i;
+/**
+ * A plan that creates more datasets than this job may make is settled in
+ * code, never re-asked (AGL-3616). The live eval of 2026-10-10 refused a
+ * dental practice's plan four times over for a fourth dataset, and a food
+ * bank's re-ask for one broke a layout rule its first answer had kept.
+ *
+ * A dataset of what customers say (`AI_DATASET_SAID_NAME`, in its name or a
+ * field) is let go first, whatever the cap: both of those plans made one of
+ * testimonials, which nothing may seed.
+ *
+ * The datasets kept are the most useful: the ones the most sections list,
+ * a record template counting double, plan order breaking ties. Each one let
+ * go leaves the plan whole — its `new:` reference comes off every section,
+ * a record template of it becomes a page of its own, and a section that
+ * listed it shows fewer items than rule 8 binds, so its items are written
+ * out on the page. Where the job may create no dataset at all, rule 7 still
+ * asks, as it does for any creation.
+ */ export function aiSettlePlanDatasets(plan, capabilities = null) {
+    var _ref, _entry_left;
+    const entry = capabilities == null ? void 0 : capabilities.create.dataset;
+    if (!(entry == null ? void 0 : entry.allowed)) return plan;
+    const cap = Math.min((_ref = capabilities == null ? void 0 : capabilities.datasetsMax) != null ? _ref : Infinity, (_entry_left = entry.left) != null ? _entry_left : Infinity);
+    const datasets = plan.create.filter((one)=>one.kind === 'dataset');
+    // A dataset a form writes to holds what visitors send (AGL-3616): its
+    // fields may well be a rating or a quote request, and nothing seeds it.
+    const forForms = aiPlanFormDatasetNames(plan);
+    const said = (one)=>!forForms.has(one.name.trim().toLowerCase()) && (AI_DATASET_SAID_NAME.test(one.name) || one.fields.some((field)=>AI_DATASET_SAID_NAME.test(field)));
+    if (!datasets.some(said) && (!Number.isFinite(cap) || datasets.length <= cap)) return plan;
+    const named = (ref, name)=>!!ref && isAiPlanNewRef(ref) && ref.slice('new:'.length).trim().toLowerCase() === name.trim().toLowerCase();
+    // A form's dataset counts as much as a record template: the form the
+    // person asked for is built around it.
+    const score = (name)=>(forForms.has(name.trim().toLowerCase()) ? 2 : 0) + plan.screens.reduce((total, screen)=>{
+            var _screen_record;
+            return total + (named((_screen_record = screen.record) == null ? void 0 : _screen_record.dataset, name) ? 2 : 0) + screen.sections.filter((section)=>section.uses.some((ref)=>named(ref, name))).length;
+        }, 0);
+    const ranked = datasets.filter((one)=>!said(one)).map((one, index)=>({
+            name: one.name,
+            index,
+            score: score(one.name)
+        })).sort((a, b)=>b.score - a.score || a.index - b.index);
+    const kept = new Set(ranked.slice(0, Math.max(0, cap)).map((one)=>one.name.trim().toLowerCase()));
+    const dropped = new Set(datasets.map((one)=>one.name.trim().toLowerCase()).filter((name)=>!kept.has(name)));
+    const isDropped = (ref)=>[
+            ...dropped
+        ].some((name)=>named(ref, name));
+    return _extends({}, plan, {
+        create: plan.create.filter((one)=>one.kind !== 'dataset' || !dropped.has(one.name.trim().toLowerCase()))// A form whose dataset was let go sends its submissions to the Inbox only.
+        .map((one)=>one.kind === 'form' && isDropped(one.writesTo) ? withoutWritesTo(one) : one),
+        screens: plan.screens.map((screen)=>_extends({}, screen, {
+                record: screen.record && isDropped(screen.record.dataset) ? null : screen.record,
+                sections: screen.sections.map((section)=>section.uses.some(isDropped) ? _extends({}, section, {
+                        uses: section.uses.filter((ref)=>!isDropped(ref)),
+                        items: Math.min(section.items, AI_TYPED_LIST_MIN_ITEMS - 1)
+                    }) : section)
+            }))
+    });
+}
+/** A creation with no `writesTo`, as a plan that never said one reads. */ function withoutWritesTo(creation) {
+    const rest = _extends({}, creation);
+    delete rest.writesTo;
+    return rest;
+}
+/**
+ * A form's dataset, settled in code before the rules read the plan
+ * (AGL-3616, Zach 2026-10-10: Aglyn AI's forms write to its datasets).
+ *
+ *  - A `writesTo` that names nothing the form can write to comes off: a
+ *    `new:` of no dataset this plan creates, an id the inventory does not
+ *    hold, or a dataset this job may not create. The form is then the
+ *    form it always was, its submissions in the Inbox. A dataset the
+ *    inventory holds, named by its name rather than its id, is given its id.
+ *  - A dataset this plan creates for a form holds the people who send it:
+ *    no page lists it and none is its record template, so its `new:` comes
+ *    off every section and record that named it, and a section that listed
+ *    it shows fewer items than rule 8 binds.
+ */ export function aiSettlePlanFormDatasets(plan, inventory, capabilities = null) {
+    var _ref;
+    if (!plan.create.some((one)=>one.kind === 'form' && one.writesTo)) return plan;
+    const held = (_ref = inventory == null ? void 0 : inventory.datasets) != null ? _ref : [];
+    const creatable = !capabilities || capabilities.create.dataset.allowed;
+    let changed = false;
+    const create = plan.create.map((one)=>{
+        if (one.kind !== 'form' || !one.writesTo) return one;
+        const ref = one.writesTo.trim();
+        if (isAiPlanNewRef(ref)) {
+            var _aiPlanCreateFor, _aiPlanItemFor;
+            if (creatable && ((_aiPlanCreateFor = aiPlanCreateFor(plan, ref)) == null ? void 0 : _aiPlanCreateFor.kind) === 'dataset') return one;
+            // A build's dataset item, which the data plugin's operation makes.
+            if (((_aiPlanItemFor = aiPlanItemFor(plan, ref)) == null ? void 0 : _aiPlanItemFor.op) === AI_PLAN_DATASET_ITEM_OP) return one;
+        } else {
+            if (held.some((row)=>row.id === ref)) return one;
+            const byName = held.find((row)=>aiNamesMatch(row.name, ref));
+            if (byName) {
+                changed = true;
+                return _extends({}, one, {
+                    writesTo: byName.id
+                });
+            }
+        }
+        changed = true;
+        return withoutWritesTo(one);
+    });
+    const settled = _extends({}, plan, {
+        create
+    });
+    const forForms = aiPlanFormDatasetNames(settled);
+    const listsOne = (ref)=>isAiPlanNewRef(ref) && forForms.has(ref.slice('new:'.length).trim().toLowerCase());
+    const screens = plan.screens.map((screen)=>{
+        const record = screen.record && listsOne(screen.record.dataset) ? null : screen.record;
+        const sections = screen.sections.map((section)=>section.uses.some(listsOne) ? _extends({}, section, {
+                uses: section.uses.filter((ref)=>!listsOne(ref)),
+                items: Math.min(section.items, AI_TYPED_LIST_MIN_ITEMS - 1)
+            }) : section);
+        if (record === screen.record && sections.every((section, index)=>section === screen.sections[index])) return screen;
+        changed = true;
+        return _extends({}, screen, {
+            record,
+            sections
+        });
+    });
+    return changed ? _extends({}, settled, {
+        screens
+    }) : plan;
+}
 /**
  * A page that names no layout, on a site where only one layout can frame it,
  * is put in that layout before the rules read the plan (2026-10-07). The
@@ -3366,6 +3505,140 @@ const FORM_SECTION_NAME = /\bform\b|\bsign[- ]?up\b|\bsubscribe\b|\bnewsletter\b
             }))
     });
 }
+/** Every saved form a plan could place, the plan's own creations first. */ function planFormChoices(plan, inventory) {
+    var _ref;
+    return [
+        ...plan.create.filter((entry)=>entry.kind === 'form').map((entry)=>({
+                ref: `new:${entry.name}`,
+                name: entry.name,
+                created: true
+            })),
+        ...((_ref = inventory == null ? void 0 : inventory.forms) != null ? _ref : []).map((form)=>({
+                ref: form.id,
+                name: form.name,
+                created: false
+            }))
+    ];
+}
+/** The form a plan's own words would name for a section's reference, so placements count alike. */ function formChoiceKey(ref, plan) {
+    const created = isAiPlanNewRef(ref) ? aiPlanCreateFor(plan, ref) : undefined;
+    return created ? `new:${created.name}` : ref;
+}
+/**
+ * The form a section that collects answers places: the one whose name shares
+ * the most words with the section's ("Commission inquiry" → "Commission
+ * inquiry form"), then the one the plan already places most, then the plan's
+ * own creation over a form the site has. `null` when there is none.
+ */ function bestPlanForm(section, choices, placed) {
+    var _ranked_;
+    const words = new Set(nameTokens(section.name).filter((word)=>word !== 'form'));
+    const score = (choice)=>nameTokens(choice.name).filter((word)=>word !== 'form' && words.has(word)).length;
+    const ranked = [
+        ...choices
+    ].sort((a, b)=>{
+        var _placed_get, _placed_get1;
+        return score(b) - score(a) || ((_placed_get = placed.get(b.ref)) != null ? _placed_get : 0) - ((_placed_get1 = placed.get(a.ref)) != null ? _placed_get1 : 0) || Number(b.created) - Number(a.created);
+    });
+    return (_ranked_ = ranked[0]) != null ? _ranked_ : null;
+}
+/** The contact form a plan is given when a section collects answers and the plan makes no form. */ export const AI_PLAN_SETTLED_FORM = {
+    name: 'Contact form',
+    why: 'Visitors need a way to reach the owner, and the site has no saved form for it.',
+    fields: [
+        'name',
+        'email',
+        'message'
+    ]
+};
+/**
+ * A section that collects answers and places no saved form is given one
+ * before the rules read the plan (AGL-3660), rather than failing the build.
+ * A production guided start for a ceramic artist's portfolio (2026-10-09,
+ * five pages, 94 credits refunded) planned a section that asks for
+ * commissions on its work page without placing the contact form the plan
+ * made for its Contact page; the answer and its re-ask both did, and rule 3
+ * failed the whole site for one section.
+ *
+ * The section places, in order of preference:
+ * 1. the form whose name best matches it, among those the plan creates and
+ *    the site has, preferring one the plan already places — so a guided
+ *    start, which makes one form, places that same form again rather than a
+ *    second one;
+ * 2. where there is no form at all and this job may create one, a form the
+ *    plan now creates: named for the `new:` reference the section already
+ *    holds when it names a form it never declared, the contact form
+ *    otherwise.
+ *
+ * Nothing is taken out of the plan: the section keeps its name, its other
+ * uses and its items. Where the site has no form and the job may create none,
+ * rule 3 asks for nothing (AGL-3596), and neither does this. A section whose
+ * uses are already full is left for the rule to ask about.
+ */ export function aiSettlePlanForms(plan, inventory, capabilities = null) {
+    if (!aiPlanCanPlaceForm(inventory, capabilities)) return plan;
+    const kinds = inventoryKinds(inventory);
+    const unbound = (current)=>sectionPaths(current).filter(({ section })=>FORM_SECTION_NAME.test(section.name) && section.uses.length < AI_BUILD_PLAN_LIMITS.uses && !section.uses.some((ref)=>refKind(ref, current, kinds) === 'form'));
+    const first = unbound(plan);
+    if (!first.length) return plan;
+    let next = plan;
+    if (!planFormChoices(next, inventory).length) {
+        if (capabilities && !capabilities.create.form.allowed) return plan;
+        // A form the section already names and the plan never declared is the form it meant.
+        const named = first.flatMap(({ section })=>section.uses).find((ref)=>isAiPlanNewRef(ref) && !aiPlanCreateFor(next, ref) && !aiPlanItemFor(next, ref));
+        const taken = new Set(next.create.map((entry)=>entry.name.toLowerCase()));
+        const name = named ? named.slice('new:'.length).trim() : taken.has(AI_PLAN_SETTLED_FORM.name.toLowerCase()) ? 'Get in touch form' : AI_PLAN_SETTLED_FORM.name;
+        next = _extends({}, next, {
+            create: [
+                ...next.create,
+                {
+                    kind: 'form',
+                    name,
+                    why: AI_PLAN_SETTLED_FORM.why,
+                    duplicateOf: null,
+                    fields: [
+                        ...AI_PLAN_SETTLED_FORM.fields
+                    ]
+                }
+            ]
+        });
+    }
+    const choices = planFormChoices(next, inventory);
+    const placed = new Map();
+    for (const { section } of sectionPaths(next)){
+        for (const ref of section.uses){
+            var _placed_get;
+            if (refKind(ref, next, kinds) !== 'form') continue;
+            const key = formChoiceKey(ref, next);
+            placed.set(key, ((_placed_get = placed.get(key)) != null ? _placed_get : 0) + 1);
+        }
+    }
+    const settle = new Map();
+    for (const { section, path } of unbound(next)){
+        const form = bestPlanForm(section, choices, placed);
+        if (form) settle.set(path, form.ref);
+    }
+    if (!settle.size) return next;
+    return _extends({}, next, {
+        screens: next.screens.map((screen, screenIndex)=>_extends({}, screen, {
+                sections: screen.sections.map((section, sectionIndex)=>{
+                    const ref = settle.get(`screens[${screenIndex}].sections[${sectionIndex}]`);
+                    if (!ref) return section;
+                    // The undeclared reference the form was named for now names it; any other stays.
+                    const uses = section.uses.some((use)=>formChoiceKey(use, next) === ref) ? section.uses : [
+                        ...section.uses,
+                        ref
+                    ];
+                    return _extends({}, section, {
+                        uses
+                    });
+                })
+            }))
+    });
+}
+/** The forms a section that collects answers can place, as the re-ask names them. */ function planFormChoicesText(plan, inventory) {
+    const choices = planFormChoices(plan, inventory);
+    if (!choices.length) return 'Plan one in create as a form, and put new:<its name> in the section\'s uses.';
+    return `Put one of these in the section's uses: ${choices.map((choice)=>choice.created ? choice.ref : `${choice.ref} (${choice.name})`).join(', ')}.`;
+}
 /**
  * Rule 2 (plan): every screen declares a layout, no section is a copy of a
  * layout region, and no section places a layout, which frames a whole screen
@@ -3426,6 +3699,7 @@ const FORM_SECTION_NAME = /\bform\b|\bsign[- ]?up\b|\bsubscribe\b|\bnewsletter\b
             rule: 3,
             code: 'plan-form-not-placed',
             message: 'A section collects answers without a form. Reuse a form from the Forms page, or plan one there, and place it by id.',
+            detail: planFormChoicesText(plan, inventory),
             paths: unbound.map((entry)=>entry.path)
         }
     ] : [];