@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/model/ai-site-inventory.js

@@ -0,0 +1,145 @@
+/**
+ * @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.
+ */ /**
+ * The site's inventory as a model sees it (AGL-2935): what the site already
+ * has, so a plan reuses before it creates (doctrine rule 7).
+ *
+ * COMPACT by construction (AGL-2937): ids, names, prop shapes and slugs —
+ * never a node tree, never a record's content. A component is its name and
+ * the props an instance fills in; a form is its field names; a dataset its
+ * field names. That is everything a planner needs to decide "reuse this"
+ * and a generator needs to place a reference, and it is a few hundred
+ * tokens where the trees would be tens of thousands.
+ *
+ * CAPPED three times, and the three are different numbers on purpose
+ * (AGL-2937). The reader holds each kind to `AI_SITE_INVENTORY_MAX_PER_KIND`;
+ * the prompt block LISTS only `AI_SITE_INVENTORY_LISTED_PER_KIND` of them and
+ * is held to `AI_SITE_INVENTORY_MAX_CHARS` besides; and the rest are answered
+ * on request, through the lookup tool the generation loop offers beside every
+ * door's own (`tools/ai-inventory-lookup-tool.ts`).
+ *
+ * The listing cap is what a prompt can afford: the block is volatile, so it
+ * is billed at full input rate on every request and every re-ask, and a site
+ * with two hundred components would spend most of a plan's prompt on rows it
+ * will not use. The read cap is what a LOOKUP can answer from, which is a
+ * different question — a search for "pricing card" is worth nothing if the
+ * card was never read. A kind cut by either is named in `truncated`, so the
+ * model is told more exist rather than concluding they do not.
+ *
+ * The shapes live here, apart from the reader (`runtime/site-inventory.ts`),
+ * so the prompt block, the validators and their specs can hold an inventory
+ * without loading the Admin SDK the reader needs.
+ */ /**
+ * Rows per kind the reader holds. Above the listing cap on purpose: the rows
+ * past it are what the lookup tool searches, and a row never read cannot be
+ * found. One projection of a few fields each, so the read is small even at
+ * this cap.
+ */ export const AI_SITE_INVENTORY_MAX_PER_KIND = 200;
+/** Rows per kind the prompt block lists; the rest are found by lookup. */ export const AI_SITE_INVENTORY_LISTED_PER_KIND = 40;
+/** The rendered block's ceiling: 2,000 tokens at four characters a token. */ export const AI_SITE_INVENTORY_MAX_CHARS = 8000;
+export const AI_INVENTORY_KINDS = [
+    'components',
+    'layouts',
+    'templates',
+    'forms',
+    'datasets',
+    'collections',
+    'screens'
+];
+/**
+ * The rows of one kind. The inventory's fields are named after their kinds,
+ * so this is a lookup rather than a switch, and it is the one place that
+ * relies on the correspondence: the prompt block, the lookup tool and their
+ * specs all read a kind through it.
+ */ export function aiInventoryRows(inventory, kind) {
+    return inventory[kind];
+}
+/** The heading one kind's lines are listed under, naming its columns in order. */ export const AI_INVENTORY_KIND_HEADINGS = {
+    components: 'Reusable components (id \u00b7 name \u00b7 props an instance fills)',
+    layouts: 'Layouts (id \u00b7 name)',
+    templates: 'Templates (id \u00b7 name \u00b7 kind)',
+    forms: 'Forms (id \u00b7 name \u00b7 fields)',
+    datasets: 'Datasets (id \u00b7 name \u00b7 fields)',
+    collections: 'Content collections (id \u00b7 name \u00b7 slug)',
+    screens: 'Screens (id \u00b7 name \u00b7 slug)'
+};
+/**
+ * One record as a line, in the order its heading names the columns. The one
+ * renderer: the prompt block and the lookup tool's answer read alike, so a
+ * row found by lookup is the same shape as a row that was listed.
+ */ export function aiInventoryLine(kind, row) {
+    const head = `${row.id} \u00b7 ${row.name}`;
+    switch(kind){
+        case 'components':
+            {
+                const props = Object.entries(row.props).map(([name, type])=>`${name}:${type}`).join(', ');
+                return `${head} \u00b7 ${props || 'no props'}`;
+            }
+        case 'layouts':
+            return head;
+        case 'templates':
+            return `${head} \u00b7 ${row.kind}`;
+        case 'forms':
+            return `${head} \u00b7 ${row.fields.join(', ')}`;
+        case 'datasets':
+            return `${head} \u00b7 ${row.fields.join(', ')}`;
+        case 'collections':
+            return `${head} \u00b7 ${row.slug}`;
+        case 'screens':
+            {
+                const screen = row;
+                return `${head} \u00b7 ${screen.slug}${screen.template ? ' \u00b7 entry template' : ''}`;
+            }
+    }
+}
+/** Every word of a record a lookup searches: its line, which holds them all. */ export function aiInventoryHaystack(kind, row) {
+    return aiInventoryLine(kind, row).toLowerCase();
+}
+/** The addresses a site's home screen is stored under. */ const HOME_SLUGS = new Set([
+    '',
+    'home',
+    'index'
+]);
+/**
+ * The site's home screens, by id (AGL-3056): a screen at the root or at
+ * `home`, as a seeded site stores its first screen, or one named Home. A link
+ * with nowhere to go is sent there, which is why the doctrine names them.
+ */ export function aiHomeScreenIds(inventory) {
+    var _ref;
+    return ((_ref = inventory == null ? void 0 : inventory.screens) != null ? _ref : []).filter((screen)=>!screen.template && (HOME_SLUGS.has(screen.slug.trim().replace(/^\/+|\/+$/g, '').toLowerCase()) || /^home(?:\s?page)?$/i.test(screen.name.trim()))).map((screen)=>screen.id);
+}
+/** A site the org does not own; the inventory is never read for it. */ export class AiInventoryScopeError extends Error {
+    constructor(hostId){
+        super(`host ${hostId} is not a site of the workspace that asked`);
+        this.name = 'AiInventoryScopeError';
+    }
+}
+export function emptyAiSiteInventory(hostId) {
+    return {
+        hostId,
+        components: [],
+        layouts: [],
+        templates: [],
+        forms: [],
+        datasets: [],
+        collections: [],
+        screens: [],
+        theme: null,
+        truncated: []
+    };
+}
+
+//# sourceMappingURL=ai-site-inventory.js.map

package/src/lib/model/ai-site-inventory.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/model/ai-site-inventory.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\n/**\n * The site's inventory as a model sees it (AGL-2935): what the site already\n * has, so a plan reuses before it creates (doctrine rule 7).\n *\n * COMPACT by construction (AGL-2937): ids, names, prop shapes and slugs —\n * never a node tree, never a record's content. A component is its name and\n * the props an instance fills in; a form is its field names; a dataset its\n * field names. That is everything a planner needs to decide \"reuse this\"\n * and a generator needs to place a reference, and it is a few hundred\n * tokens where the trees would be tens of thousands.\n *\n * CAPPED three times, and the three are different numbers on purpose\n * (AGL-2937). The reader holds each kind to `AI_SITE_INVENTORY_MAX_PER_KIND`;\n * the prompt block LISTS only `AI_SITE_INVENTORY_LISTED_PER_KIND` of them and\n * is held to `AI_SITE_INVENTORY_MAX_CHARS` besides; and the rest are answered\n * on request, through the lookup tool the generation loop offers beside every\n * door's own (`tools/ai-inventory-lookup-tool.ts`).\n *\n * The listing cap is what a prompt can afford: the block is volatile, so it\n * is billed at full input rate on every request and every re-ask, and a site\n * with two hundred components would spend most of a plan's prompt on rows it\n * will not use. The read cap is what a LOOKUP can answer from, which is a\n * different question — a search for \"pricing card\" is worth nothing if the\n * card was never read. A kind cut by either is named in `truncated`, so the\n * model is told more exist rather than concluding they do not.\n *\n * The shapes live here, apart from the reader (`runtime/site-inventory.ts`),\n * so the prompt block, the validators and their specs can hold an inventory\n * without loading the Admin SDK the reader needs.\n */\n\n/**\n * Rows per kind the reader holds. Above the listing cap on purpose: the rows\n * past it are what the lookup tool searches, and a row never read cannot be\n * found. One projection of a few fields each, so the read is small even at\n * this cap.\n */\nexport const AI_SITE_INVENTORY_MAX_PER_KIND = 200\n\n/** Rows per kind the prompt block lists; the rest are found by lookup. */\nexport const AI_SITE_INVENTORY_LISTED_PER_KIND = 40\n\n/** The rendered block's ceiling: 2,000 tokens at four characters a token. */\nexport const AI_SITE_INVENTORY_MAX_CHARS = 8_000\n\nexport type AiInventoryKind =\n  | 'components'\n  | 'layouts'\n  | 'templates'\n  | 'forms'\n  | 'datasets'\n  | 'collections'\n  | 'screens'\n\nexport const AI_INVENTORY_KINDS: readonly AiInventoryKind[] = [\n  'components',\n  'layouts',\n  'templates',\n  'forms',\n  'datasets',\n  'collections',\n  'screens',\n]\n\n/**\n * A reusable component's declared props as an instance may fill them: prop\n * name → its declared type (`text`, `image`, `href`, `number`, `boolean`, …).\n */\nexport type AiComponentPropTypes = Record<string, string>\n\nexport interface AiInventoryComponent {\n  id: string\n  name: string\n  /** The props an instance fills in: name → declared type. */\n  props: AiComponentPropTypes\n  /**\n   * The facts in square brackets each prop's default shows until a page sets\n   * its own, by prop name (AGL-3056): what a page placing the component still\n   * asks the member to fill. Read for the member's note, never listed in a\n   * prompt; absent when no default holds one.\n   */\n  bracketedDefaults?: Record<string, string[]>\n}\n\nexport interface AiInventoryLayout {\n  id: string\n  name: string\n  /** The layout this one nests inside, when it nests. */\n  parentId: string | null\n}\n\nexport interface AiInventoryTemplate {\n  id: string\n  name: string\n  kind: string\n}\n\nexport interface AiInventoryForm {\n  id: string\n  name: string\n  fields: string[]\n}\n\nexport interface AiInventoryDataset {\n  id: string\n  name: string\n  fields: string[]\n}\n\nexport interface AiInventoryCollection {\n  id: string\n  name: string\n  slug: string\n}\n\nexport interface AiInventoryScreen {\n  id: string\n  name: string\n  slug: string\n  layoutId: string | null\n  /** A collection's entry template rather than a page of its own. */\n  template: boolean\n}\n\n/**\n * The site's one theme, as a planner and the email rule read it: a short\n * description, the light scheme's colors by palette path, and the families\n * the theme loads.\n */\nexport interface AiInventoryTheme {\n  summary: string[]\n  colors: Record<string, string>\n  fonts: string[]\n}\n\nexport interface AiSiteInventory {\n  hostId: string\n  components: AiInventoryComponent[]\n  layouts: AiInventoryLayout[]\n  templates: AiInventoryTemplate[]\n  forms: AiInventoryForm[]\n  datasets: AiInventoryDataset[]\n  collections: AiInventoryCollection[]\n  screens: AiInventoryScreen[]\n  theme: AiInventoryTheme | null\n  /** Kinds with more records than are listed. */\n  truncated: AiInventoryKind[]\n}\n\n/** One inventory record, whatever kind it is. */\nexport type AiInventoryRow =\n  | AiInventoryComponent\n  | AiInventoryLayout\n  | AiInventoryTemplate\n  | AiInventoryForm\n  | AiInventoryDataset\n  | AiInventoryCollection\n  | AiInventoryScreen\n\n/**\n * The rows of one kind. The inventory's fields are named after their kinds,\n * so this is a lookup rather than a switch, and it is the one place that\n * relies on the correspondence: the prompt block, the lookup tool and their\n * specs all read a kind through it.\n */\nexport function aiInventoryRows(\n  inventory: AiSiteInventory,\n  kind: AiInventoryKind,\n): readonly AiInventoryRow[] {\n  return inventory[kind]\n}\n\n/** The heading one kind's lines are listed under, naming its columns in order. */\nexport const AI_INVENTORY_KIND_HEADINGS: Readonly<Record<AiInventoryKind, string>> = {\n  components: 'Reusable components (id \\u00b7 name \\u00b7 props an instance fills)',\n  layouts: 'Layouts (id \\u00b7 name)',\n  templates: 'Templates (id \\u00b7 name \\u00b7 kind)',\n  forms: 'Forms (id \\u00b7 name \\u00b7 fields)',\n  datasets: 'Datasets (id \\u00b7 name \\u00b7 fields)',\n  collections: 'Content collections (id \\u00b7 name \\u00b7 slug)',\n  screens: 'Screens (id \\u00b7 name \\u00b7 slug)',\n}\n\n/**\n * One record as a line, in the order its heading names the columns. The one\n * renderer: the prompt block and the lookup tool's answer read alike, so a\n * row found by lookup is the same shape as a row that was listed.\n */\nexport function aiInventoryLine(kind: AiInventoryKind, row: AiInventoryRow): string {\n  const head = `${row.id} \\u00b7 ${row.name}`\n  switch (kind) {\n    case 'components': {\n      const props = Object.entries((row as AiInventoryComponent).props)\n        .map(([name, type]) => `${name}:${type}`)\n        .join(', ')\n      return `${head} \\u00b7 ${props || 'no props'}`\n    }\n    case 'layouts':\n      return head\n    case 'templates':\n      return `${head} \\u00b7 ${(row as AiInventoryTemplate).kind}`\n    case 'forms':\n      return `${head} \\u00b7 ${(row as AiInventoryForm).fields.join(', ')}`\n    case 'datasets':\n      return `${head} \\u00b7 ${(row as AiInventoryDataset).fields.join(', ')}`\n    case 'collections':\n      return `${head} \\u00b7 ${(row as AiInventoryCollection).slug}`\n    case 'screens': {\n      const screen = row as AiInventoryScreen\n      return `${head} \\u00b7 ${screen.slug}${screen.template ? ' \\u00b7 entry template' : ''}`\n    }\n  }\n}\n\n/** Every word of a record a lookup searches: its line, which holds them all. */\nexport function aiInventoryHaystack(kind: AiInventoryKind, row: AiInventoryRow): string {\n  return aiInventoryLine(kind, row).toLowerCase()\n}\n\n/** The addresses a site's home screen is stored under. */\nconst HOME_SLUGS = new Set(['', 'home', 'index'])\n\n/**\n * The site's home screens, by id (AGL-3056): a screen at the root or at\n * `home`, as a seeded site stores its first screen, or one named Home. A link\n * with nowhere to go is sent there, which is why the doctrine names them.\n */\nexport function aiHomeScreenIds(inventory: AiSiteInventory | null): string[] {\n  return (inventory?.screens ?? [])\n    .filter(\n      (screen) =>\n        !screen.template &&\n        (HOME_SLUGS.has(screen.slug.trim().replace(/^\\/+|\\/+$/g, '').toLowerCase()) ||\n          /^home(?:\\s?page)?$/i.test(screen.name.trim())),\n    )\n    .map((screen) => screen.id)\n}\n\n/** A site the org does not own; the inventory is never read for it. */\nexport class AiInventoryScopeError extends Error {\n  constructor(hostId: string) {\n    super(`host ${hostId} is not a site of the workspace that asked`)\n    this.name = 'AiInventoryScopeError'\n  }\n}\n\nexport function emptyAiSiteInventory(hostId: string): AiSiteInventory {\n  return {\n    hostId,\n    components: [],\n    layouts: [],\n    templates: [],\n    forms: [],\n    datasets: [],\n    collections: [],\n    screens: [],\n    theme: null,\n    truncated: [],\n  }\n}\n"],"names":["AI_SITE_INVENTORY_MAX_PER_KIND","AI_SITE_INVENTORY_LISTED_PER_KIND","AI_SITE_INVENTORY_MAX_CHARS","AI_INVENTORY_KINDS","aiInventoryRows","inventory","kind","AI_INVENTORY_KIND_HEADINGS","components","layouts","templates","forms","datasets","collections","screens","aiInventoryLine","row","head","id","name","props","Object","entries","map","type","join","fields","slug","screen","template","aiInventoryHaystack","toLowerCase","HOME_SLUGS","Set","aiHomeScreenIds","filter","has","trim","replace","test","AiInventoryScopeError","Error","hostId","emptyAiSiteInventory","theme","truncated"],"mappings":"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"}

package/src/lib/model/ai-site-job.d.ts

@@ -0,0 +1,247 @@
+/**
+ * @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 { type AiBuildPlan, type AiBuildPlanCreateKind } from './ai-build-plan';
+/**
+ * What a site scaffold is (AGL-2911): the inputs a `site` job is admitted
+ * with, the plans a scaffold can build, and what one is estimated to cost
+ * before it starts.
+ *
+ * A scaffold is the one job kind that builds a whole site rather than one
+ * record: a plan of four to eight screens, the layout they render inside,
+ * the contact form they place, a palette suggestion, and — where the email
+ * step is loaded — a welcome email. It builds each of those through the job
+ * kind that already owns it, so this module describes what a scaffold may
+ * ask for and refuses the rest at confirmation, before a credit is spent,
+ * naming what to make first.
+ *
+ * ── The estimate is the guard rail ───────────────────────────────────────
+ *
+ * A scaffold is tens of model calls, where every other kind is a few, so the
+ * member reads what it will cost before they confirm the plan that spends
+ * it. The figure is the machine's own nominal credits per step multiplied by
+ * the passes the plan implies — an estimate, and said to be one wherever it
+ * is shown.
+ *
+ * This module imports nothing at runtime, so the doors, the step, the batch
+ * card and the plan proposal read one vocabulary.
+ */
+/** How many pages a scaffold builds: enough to be a site, few enough to read. */
+export declare const AI_SITE_PAGES: {
+    readonly min: 4;
+    readonly max: 8;
+};
+/**
+ * The most sections one scaffolded page may hold. The plan model allows more
+ * for a page job, which builds one page; a scaffold builds eight, and each
+ * section is a pass of its own.
+ */
+export declare const AI_SITE_MAX_SECTIONS = 8;
+/**
+ * Sections a page is assumed to hold before a plan names them, for the
+ * estimate a member reads when they ask for a scaffold. A declared
+ * assumption, not a measurement: the plan's own section counts replace it
+ * the moment the plan exists.
+ */
+export declare const AI_SITE_NOMINAL_SECTIONS = 5;
+/**
+ * The credits one pass is held against: the machine's
+ * `AI_JOB_STEP_RESERVE_CREDITS`, declared here so the estimate stays a pure
+ * number the console computes without the Admin SDK. `ai-site-job.spec.ts`
+ * holds the two equal.
+ */
+export declare const AI_SITE_PASS_CREDITS = 50;
+/** The longest a scaffold's scalar inputs may run; they are names, not copy. */
+export declare const AI_SITE_INPUT_MAX_CHARS = 120;
+/** The sites one agency batch may generate for in one request. */
+export declare const AI_SITE_BATCH_MAX = 25;
+/**
+ * The sites a plan must hold before the org Sites page offers the batch at
+ * all: the Agency and Advanced bands, which the plan's `hostLimit` is what
+ * distinguishes.
+ */
+export declare const AI_SITE_BATCH_MIN_HOST_LIMIT = 25;
+export interface AiSiteJobInputs {
+    /** What the business is, in a few words: the brief's subject. */
+    businessType: string;
+    /**
+     * Who the site is for, in a few words (AGL-2918); empty when nobody said.
+     * The plan step puts it in front of the model on a line of its own, as it
+     * does every other scalar here, so it narrows the pages a plan proposes
+     * without a prompt of its own.
+     */
+    audience: string;
+    /**
+     * The starter site whose shape the person liked (AGL-2918), by its
+     * `STARTER_TEMPLATES` id; empty when they picked none.
+     *
+     * A hint carried as the id rather than the starter, because an id is what
+     * the guided start's list, this door and the plan's line all agree on
+     * without any of them loading a catalog of node maps. Unrecognized ids are
+     * admitted for the same reason an unrecognized business type is: it is a
+     * few words in a brief, not a lookup.
+     */
+    starter: string;
+    /** How many pages the member asked for. */
+    pages: number;
+    /** The per-site variables an agency batch varies; empty when none was given. */
+    businessName: string;
+    city: string;
+    brand: string;
+    /** Whether the scaffold also drafts a welcome email. */
+    welcomeEmail: boolean;
+    /**
+     * Where the contact form's submissions go (AGL-2918); `null` where nobody
+     * said, which is every job created before the question existed and every
+     * door that does not ask it.
+     *
+     * The one setting a new site owner actually needs made, and the one thing
+     * about a contact form a model cannot know: whether a submission is a note
+     * to read or a lead to chase is a decision about how the business runs. So
+     * an answer BINDS the form step rather than hinting to it, and `null`
+     * leaves the model's own proposal standing, exactly as it stood before.
+     */
+    submissions: AiSiteSubmissions | null;
+    /** The batch this job was created under (AGL-2911); `null` for a single site. */
+    batchId: string | null;
+}
+/**
+ * Where a site's contact form sends what a visitor writes.
+ *
+ * Two, not three. The form step's own vocabulary has a third — a mailing
+ * list — which it can only answer with a note, because the stored routing has
+ * no place for a list; offering it as a question would be asking somebody to
+ * pick an outcome the platform then explains it cannot store.
+ */
+export declare const AI_SITE_SUBMISSIONS: readonly ["inbox", "lead"];
+export type AiSiteSubmissions = (typeof AI_SITE_SUBMISSIONS)[number];
+/**
+ * What each answer to "where do submissions go" is called, and what it means.
+ *
+ * Here rather than beside the guided start's own questions, because it is not
+ * only the guided start that asks: the agency batch asks the same thing of a
+ * whole run (AGL-2918), and two surfaces wording one decision two ways is two
+ * decisions. `ai-site-job.spec.ts` holds the list to {@link AI_SITE_SUBMISSIONS}.
+ */
+export declare const AI_SITE_SUBMISSION_CHOICES: ReadonlyArray<{
+    id: AiSiteSubmissions;
+    label: string;
+    blurb: string;
+}>;
+/**
+ * Which kind of email a scaffold's email unit is (AGL-2918), carried on the
+ * derived job as `inputs.emailType`. The email step names the kind on the one
+ * line it puts above the brief, and a scaffold was naming none.
+ *
+ * A key of the email step's own `AI_EMAIL_TYPES`, held here because neither
+ * step may import the other: a scaffold delegates by job kind, and a
+ * deployment that scaffolds is not necessarily one that has loaded the email
+ * step. `ai-job-email-step.spec.ts` holds this key to that catalog.
+ *
+ * `reply` and not `welcome`. The five kinds a member picks are campaigns
+ * somebody sends to an audience, and this is an answer to one person who
+ * wrote in through the site; the nearest, `welcome`, is a label about signing
+ * up, and a kind that misdescribes the email is worse than an absent one
+ * because it is the first thing the model is told.
+ */
+export declare const AI_SITE_EMAIL_TYPE = "reply";
+/** Where a job's inputs say submissions go, or `null` where they do not say. */
+export declare function aiSiteSubmissions(inputs: Readonly<Record<string, unknown>> | null | undefined): AiSiteSubmissions | null;
+/** A scaffold's inputs, or the sentence the door refuses them with. */
+export declare function parseAiSiteJobInputs(inputs: Readonly<Record<string, unknown>> | null | undefined): AiSiteJobInputs | string;
+/**
+ * What the site itself is, as a step that is NOT the scaffold reads it off a
+ * job's inputs (AGL-2918).
+ *
+ * A scaffold delegates unit by unit under a job derived from its own — a page
+ * job, a form job — and the derived job carries the scaffold's inputs. So the
+ * two answers that describe the site rather than one record of it are
+ * readable by every delegated step, and a step that wants them does not have
+ * to know it was delegated to.
+ *
+ * Lenient where {@link parseAiSiteJobInputs} is strict, because it reads the
+ * inputs of jobs that are not scaffolds: a page job started from the Screens
+ * page has no `businessType` and no `pages`, and that is not an error here —
+ * it is a site nobody described, and the answer is two empty strings.
+ */
+export interface AiSiteWords {
+    /** What kind of site it is; empty when the job's inputs do not say. */
+    about: string;
+    /** Who it is for; empty when the job's inputs do not say. */
+    audience: string;
+}
+/** Whether either half of {@link AiSiteWords} says anything. */
+export declare function aiSiteWordsSaidAnything(words: AiSiteWords): boolean;
+/** What a job's inputs say the site is, read defensively and trimmed to the input ceiling. */
+export declare function aiSiteWords(inputs: Readonly<Record<string, unknown>> | null | undefined): AiSiteWords;
+/**
+ * What a scaffold builds for itself: the layout its pages render inside, the
+ * form they place, and the palette suggestion a member applies in the Theme
+ * section. Anything else a plan asks to create is a job of its own.
+ */
+export declare const AI_SITE_CREATE_KINDS: readonly AiBuildPlanCreateKind[];
+/** The creations a scaffold cannot build, in the order the plan lists them, each named once. */
+export declare function aiSitePlanPrerequisites(plan: AiBuildPlan): Array<{
+    kind: AiBuildPlanCreateKind;
+    name: string;
+}>;
+/**
+ * Why a scaffold cannot build a plan of this SHAPE — the page band, a page's
+ * sections, its addresses, its navigation — in a sentence a member reads;
+ * `null` when the shape is one it builds. The plan step holds a plan to it
+ * with a re-ask (AGL-3030), and the doors hold a confirmed plan to it again
+ * through `aiSitePlanRefusal`.
+ */
+export declare function aiSitePlanShapeRefusal(plan: AiBuildPlan): string | null;
+/**
+ * Why a scaffold cannot build this plan, in a sentence a member reads when
+ * confirming it; `null` when it can.
+ */
+export declare function aiSitePlanRefusal(plan: AiBuildPlan): string | null;
+/** What the estimate counts a plan in: whether a welcome email follows, and the creations the job builds. */
+export interface AiPlanPassOptions {
+    welcomeEmail?: boolean;
+    /** The creation kinds the job builds itself; a scaffold's when absent. */
+    creates?: readonly AiBuildPlanCreateKind[];
+}
+/**
+ * The passes a plan implies: one per section of every screen, one more per
+ * screen for its search listing and its draft, and one for each thing the
+ * plan creates that the job builds. What the estimate is counted in.
+ */
+export declare function aiPlanPasses(plan: AiBuildPlan, options?: AiPlanPassOptions): number;
+/**
+ * About what a plan costs to build, in credits. An ESTIMATE: the nominal
+ * credits the machine holds per step, times the passes the plan implies.
+ * What each pass actually costs is its model's tokens, recorded on the job
+ * as it runs.
+ */
+export declare function aiPlanCreditEstimate(plan: AiBuildPlan, options?: AiPlanPassOptions): number;
+/**
+ * About what a job of this kind costs to build from its plan (AGL-3031): a
+ * page job counts the layout, forms and components it builds before its
+ * page, and every other kind counts what a scaffold would. The figure the
+ * proposal shows beside Confirm, and the hold a confirmation takes.
+ */
+export declare function aiJobPlanCreditEstimate(kind: string, plan: AiBuildPlan): number;
+/**
+ * About what a scaffold of this many pages costs, before a plan names its
+ * sections: the same arithmetic on the nominal section count, plus the plan
+ * step that proposes it. Shown where a member asks for a scaffold.
+ */
+export declare function aiSiteCreditEstimate(pages: number, options?: {
+    welcomeEmail?: boolean;
+}): number;