@caelo-cms/shared 0.11.0 → 0.11.2

package/dist/version.d.ts

@@ -19,7 +19,7 @@
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
  * follow standard SemVer.
  */
-export declare const CAELO_VERSION = "0.11.0";
+export declare const CAELO_VERSION = "0.11.2";
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
  * `CALEO_VERSION` (typo of "Caelo"). New code should import
@@ -31,7 +31,7 @@ export declare const CAELO_VERSION = "0.11.0";
  *
  * @deprecated use CAELO_VERSION
  */
-export declare const CALEO_VERSION = "0.11.0";
+export declare const CALEO_VERSION = "0.11.2";
 /**
  * Parsed shape — major/minor/patch + optional pre-release tag.
  * Stable interface for callers that need to feature-gate (rare —

package/dist/version.js

@@ -20,7 +20,7 @@
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
  * follow standard SemVer.
  */
-export const CAELO_VERSION = "0.11.0";
+export const CAELO_VERSION = "0.11.2";
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
  * `CALEO_VERSION` (typo of "Caelo"). New code should import

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caelo-cms/shared",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "private": false,
   "license": "MPL-2.0",
   "description": "Shared Zod schemas + types + the two-pass HTML composer used by every Caelo CMS workspace package. Stable enough for plugin authors and embedders to depend on directly.",

package/src/__tests__/redos-hardening.test.ts

@@ -69,6 +69,7 @@ describe("renderTemplate sections (S4, epic #1107 tokenizer)", () => {
     pages: new Map(),
     media: new Map(),
     siteLanguage: "en",
+    homePageId: null,
   }).forPage(null);
   const navField = { name: "nav_items", kind: "list" as const, listType: "links" };
   const entry = (n: number, label: string, href: string) => ({

package/src/ai-tools-add-module-modes.test.ts

@@ -71,7 +71,7 @@ describe("addModuleToolInput modes (issue #159)", () => {
   it("TOLERATES a moduleId call carrying authoring keys (incl. structural html) — placement-only, handler surfaces the ignored-authoring info", () => {
     // §1A/§11 — a valid placement must never fail over an extra authoring
     // field. moduleId + html passes; the tool handler (not the schema)
-    // reports that html was not applied and points at edit_module.
+    // reports that html was not applied and points at update_modules_many.
     const r = addModuleToolInput.safeParse({
       ...BASE,
       moduleId: "11111111-1111-4111-8111-111111111102",

package/src/ai-tools.test.ts

@@ -1,24 +1,21 @@
 // SPDX-License-Identifier: MPL-2.0
 
 import { describe, expect, it } from "bun:test";
-import {
-  chatPublishInput,
-  chatSendMessageInput,
-  editModuleToolInput,
-  siteMemoryProposeToolInput,
-} from "./ai-tools.js";
+import { chatPublishInput, chatSendMessageInput, siteMemoryProposeToolInput } from "./ai-tools.js";
+import { moduleUpdateSchema } from "./content.js";
 
 const UUID = "11111111-1111-4111-8111-111111111111";
 const UUID_2 = "22222222-2222-4222-8222-222222222222";
 
-describe("editModuleToolInput", () => {
+// The per-item shape of update_modules_many (the module-edit tool extends it).
+describe("moduleUpdateSchema (update_modules_many item)", () => {
   it("accepts a minimal valid edit", () => {
-    const r = editModuleToolInput.safeParse({ moduleId: UUID, html: "<p>x</p>" });
+    const r = moduleUpdateSchema.safeParse({ moduleId: UUID, html: "<p>x</p>" });
     expect(r.success).toBe(true);
   });
 
   it("rejects unknown keys (.strict)", () => {
-    const r = editModuleToolInput.safeParse({
+    const r = moduleUpdateSchema.safeParse({
       moduleId: UUID,
       html: "<p>x</p>",
       pageId: UUID_2,
@@ -27,22 +24,12 @@ describe("editModuleToolInput", () => {
   });
 
   it("rejects oversized html", () => {
-    const r = editModuleToolInput.safeParse({
+    const r = moduleUpdateSchema.safeParse({
       moduleId: UUID,
       html: "x".repeat(300_000),
     });
     expect(r.success).toBe(false);
   });
-
-  // e2e-livedit run 40351690739 — `{moduleId}` alone reached the op.
-  it("refuses an edit that changes nothing, naming what to pass", () => {
-    for (const input of [{ moduleId: UUID }, { moduleId: UUID, bindThemeLiterals: false }]) {
-      const r = editModuleToolInput.safeParse(input);
-      expect(r.success).toBe(false);
-      if (!r.success) expect(r.error.issues[0]?.message).toContain("edit_module changes nothing");
-    }
-    expect(editModuleToolInput.safeParse({ moduleId: UUID, kind: "hero" }).success).toBe(true);
-  });
 });
 
 describe("siteMemoryProposeToolInput", () => {

package/src/ai-tools.ts

@@ -17,15 +17,14 @@ import {
   contentInstanceDeleteSchema,
   contentInstanceUpdateSchema,
   forkPlacementContentSchema,
-  MODULE_CSS_MAX,
-  MODULE_HTML_MAX,
-  MODULE_JS_MAX,
   type ModuleField,
   moduleFieldSchema,
+  pageShortTitleSchema,
   pageTypeSlugSchema,
   setPlacementContentSchema,
   slugSchema,
 } from "./content.js";
+import type { SourceLanguage } from "./escaped-line-breaks.js";
 import { LIST_ITEM_ATTR_RE } from "./lists/item-attr.js";
 import { pluginPreviewSelectionSchema } from "./plugin-preview.js";
 import { redirectTargetPathSchema } from "./redirect-target.js";
@@ -71,9 +70,10 @@ function stripSurroundingQuotes(v: unknown): unknown {
  * is handled in one place instead of refused per tool.
  *
  * @param schema - the string schema (length caps, min) the decoded value must satisfy.
+ * @param language - the grammar of the value (`html`, `css`, `js`).
  */
-export function sourceTextArg<T extends z.ZodType<string>>(schema: T) {
-  return z.preprocess(decodeSourceTextTransport, schema);
+export function sourceTextArg<T extends z.ZodType<string>>(schema: T, language: SourceLanguage) {
+  return z.preprocess((value) => decodeSourceTextTransport(value, language), schema);
 }
 
 export const positionInputSchema = z.preprocess(
@@ -87,63 +87,6 @@ export const positionInputSchema = z.preprocess(
   ]),
 );
 
-export const editModuleToolInput = z
-  .object({
-    moduleId: z.string().uuid(),
-    displayName: z.string().min(1).max(128).optional(),
-    /**
-     * v0.12.0 — rewrite the module's purpose. Optional; passing it
-     * updates the `list_modules` catalog your future self will read.
-     */
-    description: z.string().max(1000).optional(),
-    /** v0.12.0 — re-classify the module's role tag. */
-    kind: z.enum(["chrome", "hero", "content", "cta", "utility"]).optional(),
-    /**
-     * v0.12.3 (issue #106) — re-classify the module's stable `type` (the
-     * class a parent's `allowedModuleTypes` whitelist matches against,
-     * e.g. `button`). Rarely needed; usually derived from displayName at
-     * create time. Set it to make this module satisfy a parent's allowlist.
-     */
-    type: slugSchema.optional(),
-    html: sourceTextArg(z.string().max(MODULE_HTML_MAX)).optional(),
-    css: sourceTextArg(z.string().max(MODULE_CSS_MAX)).optional(),
-    js: sourceTextArg(z.string().max(MODULE_JS_MAX)).optional(),
-    /**
-     * v0.4.0 — module field schema. Each field declares one substitution
-     * slot referenced in the module HTML as `{{name}}`. Page placements
-     * fill these via `set_page_module_content`. Optional on edits — pass
-     * to replace the declared schema.
-     */
-    fields: z.array(moduleFieldSchema).max(64).optional(),
-    /** issue #164 slice 2 — see addModuleToolInput.bindThemeLiterals. */
-    bindThemeLiterals: z.boolean().optional(),
-  })
-  .strict()
-  // e2e-livedit run 40351690739: a call with only a (placeholder)
-  // moduleId reached the op and came back as a bare "module not found".
-  // An edit that changes nothing is refused before any lookup, with the
-  // fields that make it one.
-  .refine((v) => Object.keys(v).some((k) => k !== "moduleId" && k !== "bindThemeLiterals"), {
-    message:
-      "edit_module changes nothing: pass what to change (html, css, js, fields, displayName, description, kind or type). list_modules shows the modules; add_module creates a new one.",
-  });
-
-/**
- * v0.4.0 — `set_page_module_content` AI tool. Fills the content values for
- * a module placement on a specific page. Page-bound + branch-isolated per
- * chat until publish (unlike `edit_module` which is global + immediate).
- */
-export const setPageModuleContentToolInput = z
-  .object({
-    pageId: z.string().uuid(),
-    blockName: z.string().min(1).max(64),
-    position: z.number().int().nonnegative(),
-    /** Map of module field name → value. Fully replaces existing values. */
-    contentValues: z.record(z.string(), z.unknown()),
-  })
-  .strict();
-export type SetPageModuleContentToolInput = z.infer<typeof setPageModuleContentToolInput>;
-
 export const siteMemoryProposeToolInput = z
   .object({
     slot: z.enum(["purpose", "brand-voice", "tone", "banned-phrases", "instructions", "glossary"]),
@@ -218,9 +161,9 @@ export const addModuleToolInput = z
     description: z.string().max(1000).optional(),
     kind: z.enum(["chrome", "hero", "content", "cta", "utility"]).optional(),
     type: slugSchema.optional(),
-    html: sourceTextArg(z.string().min(1).max(50_000)).optional(),
-    css: sourceTextArg(z.string().max(50_000)).optional(),
-    js: sourceTextArg(z.string().max(50_000)).optional(),
+    html: sourceTextArg(z.string().min(1).max(50_000), "html").optional(),
+    css: sourceTextArg(z.string().max(50_000), "css").optional(),
+    js: sourceTextArg(z.string().max(50_000), "js").optional(),
     fields: z.array(moduleFieldSchema).max(64).optional(),
     bindThemeLiterals: z.boolean().optional(),
     /**
@@ -233,8 +176,8 @@ export const addModuleToolInput = z
      * stores the values as the minted module's `fields[].default` —
      * which requires explicit `fields` (moduleize field names are
      * unknowable up front) and is rejected for `moduleId` reuse (a
-     * shared module renders its stored defaults; edit_module changes
-     * them).
+     * shared module renders its stored defaults; update_modules_many
+     * changes them).
      */
     values: z.record(z.string(), z.unknown()).optional(),
   })
@@ -245,7 +188,7 @@ export const addModuleToolInput = z
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           message:
-            "Reusing a module on a layout renders the module's STORED field defaults — `values` has nothing to bind to. Drop `values` (the chrome shows the module as-is), or change the shared copy via edit_module.",
+            "Reusing a module on a layout renders the module's STORED field defaults — `values` has nothing to bind to. Drop `values` (the chrome shows the module as-is), or change the shared copy via update_modules_many.",
         });
       } else if (input.fields === undefined || input.fields.length === 0) {
         ctx.addIssue({
@@ -269,7 +212,7 @@ export const addModuleToolInput = z
     // (§1A/§11), so we do NOT reject a moduleId call that also carries authoring
     // fields. Those fields are not applied here; the tool HANDLER surfaces an
     // INFO for any ignored field whose value DIFFERS from the module's stored
-    // one, pointing at edit_module — so a dropped change is never silent (§2).
+    // one, pointing at update_modules_many — so a dropped change is never silent (§2).
     if (input.moduleId !== undefined) return;
     if (input.displayName === undefined || input.html === undefined) {
       ctx.addIssue({
@@ -361,44 +304,6 @@ export const deleteContentInstanceToolInput = contentInstanceDeleteSchema;
 export const setPlacementContentToolInput = setPlacementContentSchema;
 export const forkPlacementContentToolInput = forkPlacementContentSchema;
 
-export const AI_TOOLS = [
-  "edit_module",
-  "site_memory_propose",
-  "add_module",
-  "create_page",
-  // audit #3 — page metadata (name/title/slug/template/status) is one tool for
-  // 1..200 pages: `update_pages_many`. The former rename_page / set_page_title
-  // / change_page_slug were single-field wrappers over the same pages.update.
-  "update_pages_many",
-  // audit #4 — one delete tool for 1..200 pages, disposition per page.
-  // The former singular delete_page folded in (n=1 is a one-item array).
-  "delete_pages_many",
-  // one remove-module tool routed by target (page|layout).
-  "remove_module_from",
-  "update_theme",
-  "set_template_layout",
-  "create_layout",
-  "set_site_defaults",
-  "duplicate_page",
-  "repoint_page_template",
-  "move_module",
-  "reorder_module",
-  "set_nav_menu",
-  "add_plugin_to_page",
-  // v0.12.0 — content_instances + placement binding
-  "list_content_instances",
-  "get_content_instance",
-  "create_content_instance",
-  "set_content_instance_values",
-  "delete_content_instance",
-  "set_placement_content",
-  "fork_placement_content",
-  // issue #299 — bulk-first build path (§11)
-  "build_page",
-  "create_content_instances",
-  "set_page_module_content_many",
-] as const;
-export type AiToolName = (typeof AI_TOOLS)[number];
 export type AddPluginToPageToolInput = z.infer<typeof addPluginToPageToolInput>;
 export type ListContentInstancesToolInput = z.infer<typeof listContentInstancesToolInput>;
 export type GetContentInstanceToolInput = z.infer<typeof getContentInstanceToolInput>;
@@ -473,7 +378,7 @@ export const CHAT_MAX_ATTACHMENTS = 4;
  * `position` / `field` (#917) — plus `item` / `key` for an entry of a
  * local list field (epic #1107) — name the placement field the text
  * comes from when the preview marked it, so the AI can address it in
- * `set_page_module_content` without inspecting the page first.
+ * `set_page_module_content_many` without inspecting the page first.
  * `listItem` is the `data-caelo-list-item` of the list entry the element
  * sits in (epic #1107, `docs/lists.md` §13): the chip then names that
  * entry — of a shared list, or of a module's own list — not just the
@@ -676,8 +581,8 @@ export const createTemplateToolInput = z
   .object({
     slug: slugInputSchema,
     displayName: z.string().min(1).max(256),
-    html: sourceTextArg(z.string().min(1).max(2_000_000)),
-    css: sourceTextArg(z.string().max(2_000_000)).default(""),
+    html: sourceTextArg(z.string().min(1).max(2_000_000), "html"),
+    css: sourceTextArg(z.string().max(2_000_000), "css").default(""),
     layoutId: z.string().uuid().optional(),
     /** Epic #1107 — the page type (slug) this template serves; omit for the site default. */
     pageType: pageTypeSlugSchema.optional(),
@@ -728,8 +633,8 @@ export const createLayoutToolInput = z
   .object({
     slug: slugInputSchema,
     displayName: z.string().min(1).max(200),
-    html: sourceTextArg(z.string().min(1).max(50_000)),
-    css: sourceTextArg(z.string().max(50_000)).optional(),
+    html: sourceTextArg(z.string().min(1).max(50_000), "html"),
+    css: sourceTextArg(z.string().max(50_000), "css").optional(),
     blocks: z
       .array(
         z
@@ -765,8 +670,9 @@ export const duplicatePageToolInput = z
   .object({
     sourcePageId: z.string().uuid(),
     newSlug: slugInputSchema,
-    newName: z.string().min(1).max(256).optional(),
     newTitle: z.string().min(1).max(256).optional(),
+    /** #1142 — the copy's breadcrumb label; omitted = newTitle when given, else the source's. */
+    newShortTitle: pageShortTitleSchema.optional(),
     targetTemplateId: z.string().uuid().optional(),
     /** Where the copy sits: a parent page id, or null for the top level.
      *  Omitted = next to the source (same parent). */
@@ -794,32 +700,50 @@ export const repointPageTemplateToolInput = z
   })
   .strict();
 
-export const moveModuleToolInput = z
-  .object({
-    pageId: z.string().uuid(),
-    moduleId: z.string().uuid(),
-    toBlockName: z.string().min(1).max(80),
-    /** "top" | "bottom" | a 0-based index inside the destination block. */
-    position: positionInputSchema,
-  })
-  .strict();
+/**
+ * `move_module` position: `top` | `bottom` | a 0-based index in the target
+ * block, plus `up` / `down` (one slot within the module's CURRENT block).
+ * Same quote-stripping + numeric-string coercion as `positionInputSchema`.
+ */
+export const movePositionInputSchema = z.preprocess(
+  stripSurroundingQuotes,
+  z.union([
+    z.enum(["top", "bottom", "up", "down"]),
+    z.preprocess(
+      (v) => (typeof v === "string" && /^\d+$/.test(v) ? Number.parseInt(v, 10) : v),
+      z.number().int().min(0).max(1000),
+    ),
+  ]),
+);
 
-export const reorderModuleToolInput = z
+/**
+ * `move_module` — moves a placement to `toBlockName` (omitted = the block it
+ * is in now, i.e. a reorder) at `position`. `up` / `down` only make sense
+ * inside the current block; the handler refuses them with another block.
+ */
+export const moveModuleToolInput = z
   .object({
     pageId: z.string().uuid(),
     moduleId: z.string().uuid(),
     /**
-     * `up` / `down` shift one slot. An integer is an absolute 0-based
-     * target position within the same block.
+     * #1195 — which placement of `moduleId` to move when the page holds it
+     * more than once: its block and 0-based position there. Needed only
+     * then; the error names the placements.
      */
-    direction: z.union([z.enum(["up", "down"]), z.number().int().min(0).max(1000)]),
+    fromBlockName: z.string().min(1).max(80).optional(),
+    fromPosition: z.preprocess(
+      (v) => (typeof v === "string" && /^\d+$/.test(v) ? Number.parseInt(v, 10) : v),
+      z.number().int().min(0).max(1000).optional(),
+    ),
+    toBlockName: z.string().min(1).max(80).optional(),
+    position: movePositionInputSchema,
   })
   .strict();
 
 /**
  * P7 — `find_media`. Searches the media library by alt-text /
  * filename / mime. Each row carries the media UUID (what
- * `set_theme_asset` / `set_media_alt` require) plus a pre-resolved
+ * `set_theme_asset` / `set_media_alt_many` require) plus a pre-resolved
  * variant URL. The AI's only media-inventory surface — the `## Media`
  * system-prompt block was removed by the context diet (#300), so every
  * asset lookup ("an image of a sunlit office") goes through this tool.
@@ -864,7 +788,7 @@ export const regenerateMediaVariantsToolInput = z
 export type RegenerateMediaVariantsToolInput = z.infer<typeof regenerateMediaVariantsToolInput>;
 
 /**
- * P7 — `set_media_alt`. AI may improve a11y on an existing asset
+ * P7 — one item of `set_media_alt_many`. AI may improve a11y on an existing asset
  * without a human round-trip (e.g. when the editor uploaded an image
  * with the default alt and the AI reads its content). Updates only
  * the alt field on `media_assets`.
@@ -894,7 +818,7 @@ export const setNotFoundPageToolInput = z.object({ pageId: z.string().uuid().nul
 export type SetNotFoundPageToolInput = z.infer<typeof setNotFoundPageToolInput>;
 
 /**
- * 0181 — `set_media_source`. AI records an asset's provenance (source
+ * 0181 — one item of `set_media_source_many`. AI records an asset's provenance (source
  * kind + origin detail) and licence when known. All fields but the
  * assetId are optional; the op COALESCEs so omitted fields stay
  * unchanged.
@@ -910,7 +834,7 @@ export const setMediaSourceToolInput = z
 export type SetMediaSourceToolInput = z.infer<typeof setMediaSourceToolInput>;
 
 /**
- * P8 — `set_page_seo`. Manual / panel writes to the per-page SEO
+ * P8 — one item of `set_page_seo_many`. Manual / panel writes to the per-page SEO
  * sidecar. AI calls this only on explicit user intent
  * ("set the home meta description to ..."). Doesn't bump fingerprints
  * (autofilled_at / optimized_at).
@@ -931,7 +855,7 @@ export const setPageSeoToolInput = z
 export type SetPageSeoToolInput = z.infer<typeof setPageSeoToolInput>;
 
 /**
- * P8 — `autofill_page_seo` (and, per item, `autofill_page_seo_many`).
+ * P8 — one item of `autofill_page_seo_many`.
  * Fill-once. Refuses when the page's SEO was already autofilled. The AI
  * calls it before a page's first Stage; staging and production builds
  * refuse pages without a meta description (deploy/missing-seo.ts).
@@ -945,22 +869,6 @@ export const autofillPageSeoToolInput = z
   .strict();
 export type AutofillPageSeoToolInput = z.infer<typeof autofillPageSeoToolInput>;
 
-/**
- * P8 — `optimize_page_seo`. Explicit re-optimization. Always allowed.
- * Takes optional context (keyword analysis / intent shifts / branding
- * changes). The AI can call this across N pages in one chat turn —
- * the resulting changes batch into one Publish-pill confirm.
- */
-export const optimizePageSeoToolInput = z
-  .object({
-    pageId: z.string().uuid(),
-    metaDescription: z.string().min(1).max(320),
-    ogImageAssetId: z.string().uuid().nullable().optional(),
-    context: z.string().max(4000).optional(),
-  })
-  .strict();
-export type OptimizePageSeoToolInput = z.infer<typeof optimizePageSeoToolInput>;
-
 /**
  * P8 AI-first review pass — bulk variants. Per CLAUDE.md §11, bulk
  * tools save round-trips when the AI knows it has N changes to make
@@ -980,7 +888,7 @@ export type FindRedirectsToolInput = z.infer<typeof findRedirectsToolInput>;
 
 export const bulkCreateRedirectsToolInput = z
   .object({
-    redirects: z
+    items: z
       .array(
         z
           .object({
@@ -1032,7 +940,7 @@ export type BulkDeleteRedirectsToolInput = z.infer<typeof bulkDeleteRedirectsToo
 
 export const bulkOptimizeSeoToolInput = z
   .object({
-    updates: z
+    items: z
       .array(
         z
           .object({
@@ -1049,7 +957,6 @@ export const bulkOptimizeSeoToolInput = z
   .strict();
 export type BulkOptimizeSeoToolInput = z.infer<typeof bulkOptimizeSeoToolInput>;
 
-export type EditModuleToolInput = z.infer<typeof editModuleToolInput>;
 export type SiteMemoryProposeToolInput = z.infer<typeof siteMemoryProposeToolInput>;
 export type CreateTemplateToolInput = z.infer<typeof createTemplateToolInput>;
 // v0.10.22 — `UpdateThemeToolInput` removed alongside `update_theme` tool.
@@ -1067,7 +974,6 @@ export type SetSiteDefaultsToolInput = z.infer<typeof setSiteDefaultsToolInput>;
 export type DuplicatePageToolInput = z.infer<typeof duplicatePageToolInput>;
 export type RepointPageTemplateToolInput = z.infer<typeof repointPageTemplateToolInput>;
 export type MoveModuleToolInput = z.infer<typeof moveModuleToolInput>;
-export type ReorderModuleToolInput = z.infer<typeof reorderModuleToolInput>;
 // v0.10.22 — `SetNavMenuToolInput` removed alongside `set_nav_menu` tool.
 
 /**

package/src/bug-intake.test.ts

@@ -9,6 +9,7 @@
 
 import { describe, expect, it } from "bun:test";
 import {
+  BUG_REPORT_KIND_BEFORE_1192,
   bugIntakeReport,
   bugIntakeSigningString,
   computeBugFingerprint,
@@ -32,7 +33,7 @@ describe("computeBugFingerprint", () => {
   });
 
   it("keeps different tools and different quoted field names apart", async () => {
-    expect(await auto("boom", "build_page")).not.toBe(await auto("boom", "edit_module"));
+    expect(await auto("boom", "build_page")).not.toBe(await auto("boom", "update_modules_many"));
     expect(await auto('Invalid input at "page.slug"')).not.toBe(
       await auto('Invalid input at "page.title"'),
     );
@@ -152,3 +153,49 @@ describe("bugIntakeReport", () => {
     expect(parsed.success).toBe(false);
   });
 });
+
+describe("bugIntakeReport kind (#1192)", () => {
+  const base = {
+    protocolVersion: 1,
+    reportId: "7f3c2b9e-1d4a-4e8b-9c0f-2a1b3c4d5e6f",
+    caeloVersion: "0.10.55",
+    fingerprint: "a".repeat(64),
+    source: "ai",
+    severity: "degraded",
+    blockedTask: false,
+    suspectedTool: null,
+    title: "t",
+    whatHappened: "w",
+    expected: "e",
+    evidence: null,
+  } as const;
+
+  it("parses a report without kind, as an install from before #1192 sends it, as a defect", () => {
+    expect(BUG_REPORT_KIND_BEFORE_1192).toBe("defect");
+    const parsed = bugIntakeReport.parse(base);
+    expect(parsed.kind).toBe("defect");
+    expect(parsed.severity).toBe("degraded");
+  });
+
+  it("round-trips a suggestion, which carries no severity", () => {
+    const sent = { ...base, kind: "suggestion", severity: null };
+    const parsed = bugIntakeReport.parse(sent);
+    expect(parsed).toEqual(sent);
+    expect(bugIntakeReport.parse(JSON.parse(JSON.stringify(parsed)))).toEqual(sent);
+  });
+
+  it("refuses a defect without severity, a graded suggestion and an auto-captured suggestion", () => {
+    const issues = (r: unknown) =>
+      bugIntakeReport.safeParse(r).error?.issues.map((i) => `${i.path.join(".")}: ${i.message}`);
+    expect(issues({ ...base, kind: "defect", severity: null })).toEqual([
+      "severity: a defect needs a severity",
+    ]);
+    expect(issues({ ...base, kind: "suggestion" })).toEqual([
+      "severity: a suggestion has no severity; send null",
+    ]);
+    expect(issues({ ...base, source: "auto", kind: "suggestion", severity: null })).toEqual([
+      "kind: an auto-captured report is always a defect",
+    ]);
+    expect(issues({ ...base, kind: "feature" })?.[0]).toStartWith("kind:");
+  });
+});

package/src/bug-intake.ts

@@ -60,7 +60,41 @@ export const bugIntakeRegisterRequest = z
   .strict();
 export type BugIntakeRegisterRequest = z.infer<typeof bugIntakeRegisterRequest>;
 
-/** `POST /v1/reports` — one redacted bug report (signed). */
+/**
+ * What a report is about (#1192).
+ *   defect     — something in Caelo misbehaved: a tool contradicted its
+ *                description, a render contradicted stored state, a call
+ *                failed. Auto captures and provider errors are always this.
+ *   suggestion — nothing misbehaved, but Caelo lacks something the AI needed:
+ *                a capability, a tool, a docs page. Filed by the AI only.
+ * The intake keeps the two apart end to end: own title prefix and label, own
+ * daily issue cap, and matching never puts one kind into the other's cluster.
+ */
+export const bugReportKind = z.enum(["defect", "suggestion"]);
+export type BugReportKind = z.infer<typeof bugReportKind>;
+
+/**
+ * The kind of a report that names none. Contract rule (#1192): installs
+ * released before `kind` existed send no kind, and everything they could
+ * file was a defect, so a missing kind IS `defect`. This is a protocol rule,
+ * not a guess: it holds for every protocol-1 report, and the intake applies
+ * the same rule to the records it stored before #1192.
+ */
+export const BUG_REPORT_KIND_BEFORE_1192: BugReportKind = "defect";
+
+/** How badly a defect hurt the task. Defects only: a suggestion has no severity. */
+export const bugReportSeverity = z.enum(["blocking", "degraded", "cosmetic"]);
+export type BugReportSeverity = z.infer<typeof bugReportSeverity>;
+
+/**
+ * `POST /v1/reports` — one redacted bug report (signed).
+ *
+ * `kind` is optional on the wire only for the contract rule above; parsing
+ * always yields one. `severity` is set for a defect and `null` for a
+ * suggestion (nothing broke, so there is nothing to grade), and an
+ * auto-captured report is always a defect. A report that breaks either is
+ * refused, not repaired: it came from a broken client.
+ */
 export const bugIntakeReport = z
   .object({
     protocolVersion: z.literal(BUG_INTAKE_PROTOCOL_VERSION),
@@ -69,7 +103,8 @@ export const bugIntakeReport = z
     caeloVersion: z.string().min(1).max(64),
     fingerprint: fingerprintSchema,
     source: z.enum(["ai", "auto"]),
-    severity: z.enum(["blocking", "degraded", "cosmetic"]),
+    kind: bugReportKind.default(BUG_REPORT_KIND_BEFORE_1192),
+    severity: bugReportSeverity.nullable(),
     blockedTask: z.boolean(),
     suspectedTool: z.string().max(200).nullable(),
     title: z.string().min(1).max(BUG_INTAKE_LIMITS.title),
@@ -77,7 +112,27 @@ export const bugIntakeReport = z
     expected: z.string().min(1).max(BUG_INTAKE_LIMITS.expected),
     evidence: z.string().max(BUG_INTAKE_LIMITS.evidence).nullable(),
   })
-  .strict();
+  .strict()
+  .superRefine((r, ctx) => {
+    if (r.kind === "defect" && r.severity === null) {
+      ctx.addIssue({ code: "custom", path: ["severity"], message: "a defect needs a severity" });
+    }
+    if (r.kind === "suggestion" && r.severity !== null) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["severity"],
+        message: "a suggestion has no severity; send null",
+      });
+    }
+    if (r.kind === "suggestion" && r.source === "auto") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["kind"],
+        message: "an auto-captured report is always a defect",
+      });
+    }
+  });
+/** A parsed report: `kind` is always present. */
 export type BugIntakeReport = z.infer<typeof bugIntakeReport>;
 
 /**