@cogenta/agents-builtin 0.3.2 → 0.5.0

package/dist/theme-creator/read-sandbox-tool.d.ts

@@ -0,0 +1,57 @@
+import { type ToolDefinition } from '@cogenta/agents';
+import { z } from 'zod';
+/**
+ * What was missing for a theme to be *adjusted* rather than only created.
+ *
+ * The sandbox tools could write a file and render the result, but never read
+ * one back. Inside a single generation run that is survivable — the agent
+ * still has its own transcript, so it knows what it wrote. Across a second
+ * conversation turn ("make it darker", "put the grid on two columns") it is
+ * fatal: the agent is handed a theme it has never seen, and its only options
+ * are to guess or to rewrite the whole thing from scratch, throwing away
+ * every decision the operator just approved.
+ *
+ * Two tools, because listing and reading are genuinely different questions
+ * and a model asked to "read the theme" should not have to guess filenames:
+ * `theme.list_sandbox_files` answers "what is in here", and
+ * `theme.read_sandbox_file` answers "what does this one say".
+ *
+ * Both are read-only (`sideEffects: false`) and confined to one sandbox
+ * directory — the same directory `theme.write_sandbox_file` already writes
+ * to, with the same host-side path-escape guard in `@cogenta/cli`, which is
+ * where the real filesystem lives.
+ */
+export interface ReadSandboxToolsOptions {
+    readonly listFiles: (input: {
+        readonly sandboxId: string;
+    }) => Promise<readonly string[]>;
+    readonly readFile: (input: {
+        readonly sandboxId: string;
+        readonly path: string;
+    }) => Promise<string>;
+    /** A theme file that is genuinely enormous is truncated rather than allowed to crowd out the rest of the conversation. */
+    readonly maxFileChars?: number;
+}
+declare const ListInputSchema: z.ZodObject<{
+    sandboxId: z.ZodString;
+}, z.core.$strip>;
+export type ListSandboxFilesInput = z.infer<typeof ListInputSchema>;
+declare const ListOutputSchema: z.ZodObject<{
+    files: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ListSandboxFilesOutput = z.infer<typeof ListOutputSchema>;
+declare const ReadInputSchema: z.ZodObject<{
+    sandboxId: z.ZodString;
+    path: z.ZodString;
+}, z.core.$strip>;
+export type ReadSandboxFileInput = z.infer<typeof ReadInputSchema>;
+declare const ReadOutputSchema: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ReadSandboxFileOutput = z.infer<typeof ReadOutputSchema>;
+export declare function createListSandboxFilesTool(options: Pick<ReadSandboxToolsOptions, 'listFiles'>): ToolDefinition<ListSandboxFilesInput, ListSandboxFilesOutput>;
+export declare function createReadSandboxFileTool(options: Pick<ReadSandboxToolsOptions, 'readFile' | 'maxFileChars'>): ToolDefinition<ReadSandboxFileInput, ReadSandboxFileOutput>;
+export {};
+//# sourceMappingURL=read-sandbox-tool.d.ts.map

package/dist/theme-creator/read-sandbox-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-sandbox-tool.d.ts","sourceRoot":"","sources":["../../src/theme-creator/read-sandbox-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACjE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAA;IACzF,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE;QACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;QAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KACtB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACrB,0HAA0H;IAC1H,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAID,QAAA,MAAM,eAAe;;iBAA6C,CAAA;AAClE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAEnE,QAAA,MAAM,gBAAgB;;iBAA2C,CAAA;AACjE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAErE,QAAA,MAAM,eAAe;;;iBAInB,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAElE,QAAA,MAAM,gBAAgB;;;;iBAIpB,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAEpE,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,WAAW,CAAC,GAClD,cAAc,CAAC,qBAAqB,EAAE,sBAAsB,CAAC,CAe/D;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,UAAU,GAAG,cAAc,CAAC,GAClE,cAAc,CAAC,oBAAoB,EAAE,qBAAqB,CAAC,CAsB7D"}

package/dist/theme-creator/read-sandbox-tool.js

@@ -0,0 +1,55 @@
+import { defineTool } from '@cogenta/agents';
+import { z } from 'zod';
+const DEFAULT_MAX_FILE_CHARS = 24_000;
+const ListInputSchema = z.object({ sandboxId: z.string().min(1) });
+const ListOutputSchema = z.object({ files: z.array(z.string()) });
+const ReadInputSchema = z.object({
+    sandboxId: z.string().min(1),
+    /** Sandbox-relative, exactly as `theme.list_sandbox_files` returned it. */
+    path: z.string().min(1),
+});
+const ReadOutputSchema = z.object({
+    path: z.string(),
+    content: z.string(),
+    truncated: z.boolean().optional(),
+});
+export function createListSandboxFilesTool(options) {
+    return defineTool({
+        name: 'theme.list_sandbox_files',
+        version: '1.0.0',
+        description: `Lists every file currently in a theme sandbox, as sandbox-relative paths. Call it first when you are changing a theme you did not write in this conversation — you cannot correct a file whose name you had to guess, and a theme's stylesheet can be called anything.`,
+        input: ListInputSchema,
+        output: ListOutputSchema,
+        permissions: ['theme.write_sandbox'],
+        sideEffects: false,
+        reversible: false,
+        cost: 'low',
+        async execute(input) {
+            return { files: [...(await options.listFiles({ sandboxId: input.sandboxId }))] };
+        },
+    });
+}
+export function createReadSandboxFileTool(options) {
+    const limit = options.maxFileChars ?? DEFAULT_MAX_FILE_CHARS;
+    return defineTool({
+        name: 'theme.read_sandbox_file',
+        version: '1.0.0',
+        description: `Returns the current contents of one file in a theme sandbox. Read a file before changing it: a write replaces the whole file, so editing from memory — or from what you assume a previous run wrote — silently drops everything you did not happen to reproduce. When a request asks to adjust part of a theme, read the file, change that part, and write the whole corrected file back.`,
+        input: ReadInputSchema,
+        output: ReadOutputSchema,
+        permissions: ['theme.write_sandbox'],
+        sideEffects: false,
+        reversible: false,
+        cost: 'low',
+        async execute(input) {
+            const content = await options.readFile({ sandboxId: input.sandboxId, path: input.path });
+            const truncated = content.length > limit;
+            return {
+                path: input.path,
+                content: truncated ? `${content.slice(0, limit)}\n/* …truncated */` : content,
+                truncated,
+            };
+        },
+    });
+}
+//# sourceMappingURL=read-sandbox-tool.js.map

package/dist/theme-creator/read-sandbox-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-sandbox-tool.js","sourceRoot":"","sources":["../../src/theme-creator/read-sandbox-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAuB,MAAM,iBAAiB,CAAA;AACjE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAkCvB,MAAM,sBAAsB,GAAG,MAAM,CAAA;AAErC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;AAGlE,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAA;AAGjE,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,2EAA2E;IAC3E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACxB,CAAC,CAAA;AAGF,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAA;AAGF,MAAM,UAAU,0BAA0B,CACxC,OAAmD;IAEnD,OAAO,UAAU,CAAC;QAChB,IAAI,EAAE,0BAA0B;QAChC,OAAO,EAAE,OAAO;QAChB,WAAW,EAAE,wQAAwQ;QACrR,KAAK,EAAE,eAAe;QACtB,MAAM,EAAE,gBAAgB;QACxB,WAAW,EAAE,CAAC,qBAAqB,CAAC;QACpC,WAAW,EAAE,KAAK;QAClB,UAAU,EAAE,KAAK;QACjB,IAAI,EAAE,KAAK;QACX,KAAK,CAAC,OAAO,CAAC,KAAK;YACjB,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;QAClF,CAAC;KACF,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,OAAmE;IAEnE,MAAM,KAAK,GAAG,OAAO,CAAC,YAAY,IAAI,sBAAsB,CAAA;IAC5D,OAAO,UAAU,CAAC;QAChB,IAAI,EAAE,yBAAyB;QAC/B,OAAO,EAAE,OAAO;QAChB,WAAW,EAAE,2XAA2X;QACxY,KAAK,EAAE,eAAe;QACtB,MAAM,EAAE,gBAAgB;QACxB,WAAW,EAAE,CAAC,qBAAqB,CAAC;QACpC,WAAW,EAAE,KAAK;QAClB,UAAU,EAAE,KAAK;QACjB,IAAI,EAAE,KAAK;QACX,KAAK,CAAC,OAAO,CAAC,KAAK;YACjB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;YACxF,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,KAAK,CAAA;YACxC,OAAO;gBACL,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC,OAAO;gBAC7E,SAAS;aACV,CAAA;QACH,CAAC;KACF,CAAC,CAAA;AACJ,CAAC"}

package/dist/theme-creator/theme-spec.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The structure and composition of a Cogenta theme, as one standing
+ * specification handed to the model in the system prompt's own
+ * `<specification>` section (`assembleContext`, `@cogenta/agents`).
+ *
+ * **Why this file exists.** Every fact below already existed — scattered
+ * across `theme.write_sandbox_file`'s tool `description`, a 311-line
+ * `identity.md` no admin flow ever loads, and the contract D docs. A live
+ * report ("I attach a screenshot and what comes back is nowhere near it")
+ * traced back to that scattering: a tool description is read as API
+ * reference for one call, not as standing knowledge about what is being
+ * built, and the writer agent's actual system prompt was a one-sentence role
+ * plus ten bullets. The tool description keeps only what belongs to the
+ * tool (its arguments and what it rejects); everything about what a theme
+ * *is* lives here.
+ *
+ * **The palette rule reversed, deliberately.** The previous brief told the
+ * model "colour/font/spacing VALUES are not invented here — reference
+ * --cogenta-*". Those custom properties are generated exclusively from the
+ * *site's* skin (`theme-wiring.ts`'s `computeEffectiveStyles`), so a theme
+ * asked to reproduce a specific design was structurally repainted in
+ * whatever palette the site already had — the single largest cause of "far
+ * from the screenshot", and no amount of layout accuracy could compensate.
+ * A theme's own stylesheet is emitted *after* the skin stylesheet
+ * (`joinStyles`, `theme-render.ts`), so a theme can and should carry its own
+ * design palette. The namespaced pattern below keeps the site's brand colours
+ * reachable rather than simply overwriting `--cogenta-*` at `:root`, which
+ * would silently disable the operator's own colour controls.
+ */
+export declare const COGENTA_THEME_SPECIFICATION: string;
+//# sourceMappingURL=theme-spec.d.ts.map

package/dist/theme-creator/theme-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-spec.d.ts","sourceRoot":"","sources":["../../src/theme-creator/theme-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,2BAA2B,QA+NhC,CAAA"}

package/dist/theme-creator/theme-spec.js

@@ -0,0 +1,254 @@
+/**
+ * The structure and composition of a Cogenta theme, as one standing
+ * specification handed to the model in the system prompt's own
+ * `<specification>` section (`assembleContext`, `@cogenta/agents`).
+ *
+ * **Why this file exists.** Every fact below already existed — scattered
+ * across `theme.write_sandbox_file`'s tool `description`, a 311-line
+ * `identity.md` no admin flow ever loads, and the contract D docs. A live
+ * report ("I attach a screenshot and what comes back is nowhere near it")
+ * traced back to that scattering: a tool description is read as API
+ * reference for one call, not as standing knowledge about what is being
+ * built, and the writer agent's actual system prompt was a one-sentence role
+ * plus ten bullets. The tool description keeps only what belongs to the
+ * tool (its arguments and what it rejects); everything about what a theme
+ * *is* lives here.
+ *
+ * **The palette rule reversed, deliberately.** The previous brief told the
+ * model "colour/font/spacing VALUES are not invented here — reference
+ * --cogenta-*". Those custom properties are generated exclusively from the
+ * *site's* skin (`theme-wiring.ts`'s `computeEffectiveStyles`), so a theme
+ * asked to reproduce a specific design was structurally repainted in
+ * whatever palette the site already had — the single largest cause of "far
+ * from the screenshot", and no amount of layout accuracy could compensate.
+ * A theme's own stylesheet is emitted *after* the skin stylesheet
+ * (`joinStyles`, `theme-render.ts`), so a theme can and should carry its own
+ * design palette. The namespaced pattern below keeps the site's brand colours
+ * reachable rather than simply overwriting `--cogenta-*` at `:root`, which
+ * would silently disable the operator's own colour controls.
+ */
+export const COGENTA_THEME_SPECIFICATION = `
+A Cogenta theme is a small ES module package that turns a page's stored
+content into HTML, plus the CSS that makes that HTML look like a design. It
+runs server-side, per request. It has no build step: files are loaded with a
+plain \`import()\`, so there is no JSX, no TypeScript compilation, no bundler.
+
+## The files
+
+A complete theme is three things. None is optional if the theme is meant to
+look like anything.
+
+1. \`theme.config.{js,mjs,ts}\` — the contract D manifest.
+2. \`theme.render.{js,mjs,ts}\` — \`renderPage\` and \`renderChrome\`.
+3. At least one \`.css\` file — any name, any number. Every \`.css\` at the
+   theme root is picked up automatically and concatenated in filename order.
+
+\`.tsx\` and \`.jsx\` are refused: nothing transforms JSX here. Write
+\`h(tag, attrs, ...children)\` calls instead, whichever extension you choose.
+
+## theme.config.*
+
+\`export default defineTheme({...})\` from '@cogenta/theme-kit', with exactly
+these fields:
+
+- \`name\`: string
+- \`version\`: exact semver, e.g. '1.0.0'
+- \`engine\`: a semver RANGE, e.g. '^1.0.0' — never prose
+- \`blocks\`: a semver RANGE too, e.g. '^1.0.0' — the block-vocabulary
+  version, NEVER a list of block names
+- \`implements\`: string[] — the block \`_type\` names \`renderPage\` really
+  handles, e.g. ['hero','collectionList','prose']
+- \`collections\`: string[] or '*'
+- \`runtime\`: exactly one of 'static' | 'server' | 'edge'
+- \`tokens\`: a STRING path, e.g. './theme.tokens.json' — never inline data
+
+## theme.render.*
+
+A real ES module exporting two functions, both building markup with \`h()\`
+from '@cogenta/theme-kit'. \`h(tag, attrs, ...children)\` returns an
+HtmlElement tree; the pipeline calls \`serialize()\` on what you return, and
+it understands only that tree or a plain string.
+
+\`renderChrome(input)\` returns \`{ header, footer }\` as HTML **strings**.
+\`input\` is \`{ site: {name,url,locales,defaultLocale}, locale, homeHref,
+headerNav: [{label,href}], footerNav, brandingHtml, tagline?, social?,
+footerNote?, headerAction? }\`.
+
+\`renderPage(page, ctx, entries)\`:
+- \`page\`: \`{ title, blocks: Array<{_key, _type, ...fields}> }\` — the real
+  saved contract B blocks.
+- \`ctx\`: \`{ site, locale, url, t(key,vals), image(mediaId,opts),
+  link(target), content: {entry,byPath,list} }\`.
+- \`entries\`: fetched \`collectionList\` results, keyed by \`block._key\`.
+
+Design freedom is total, like a WordPress theme: fetch whatever you need
+through \`ctx.content\`, place it anywhere, invent your own block types. A
+page's \`blocks\` list is one available data source, never a required
+structure. The shared vocabulary (hero, prose, mediaFigure, featureGrid, cta,
+gallery, quote, faq, stats, logos, collectionList, embed, testimonial,
+pricingTable, accordion, statCounter, logoStrip) exists so content already
+composed with those still shows something — implementing all of them is never
+required. But a block type you do not specifically style must still render
+plainly rather than vanish: never drop content a page actually has.
+
+There is no access to token VALUES from render code. \`ctx.theme.tokens\` does
+not exist. Render code emits semantic HTML with class names; CSS does the
+rest.
+
+## The CSS, and where colour actually comes from
+
+This is where a design succeeds or fails. Markup structure alone renders as
+unstyled text, every time.
+
+Two stylesheets reach the page, in this order: the **site skin** first, then
+**this theme's CSS**. Later wins at equal specificity, so a theme can define
+its own design language and does not merely decorate the site's.
+
+The site skin publishes these custom properties on \`:root\`:
+\`--cogenta-color-bg/fg/accent/accent-fg/muted/muted-fg/border\`,
+\`--cogenta-font-sans/serif/mono\`,
+\`--cogenta-font-size-xs/sm/md/lg/xl/2xl/3xl\`, \`--cogenta-space-unit\`,
+\`--cogenta-radius-sm/md/lg\`, \`--cogenta-shadow-sm/md\`.
+
+**Own your palette.** When the request describes or shows a specific design,
+that design's colours, type and spacing are the point — reproducing them is
+the job. Define them as your own namespaced custom properties, derived from
+what the request actually shows, and build every rule on those:
+
+\`\`\`css
+:root {
+  --t-bg: #0e1013;
+  --t-surface: #171a1f;
+  --t-fg: #f2f4f7;
+  --t-muted-fg: #98a1ad;
+  --t-accent: #3ddc84;
+  --t-accent-fg: #06210f;
+  --t-border: #262b33;
+  --t-radius: 14px;
+  --t-display: "Fraunces", Georgia, serif;
+  --t-body: "Inter", system-ui, sans-serif;
+  --t-step: 8px;
+}
+\`\`\`
+
+Prefix them with something short and specific to the theme. Do **not**
+redefine \`--cogenta-*\` at \`:root\`: those are the operator's own colour
+controls in the Appearance screen, and overwriting them silently disables
+that feature. When a value should follow the site's brand instead of the
+design, read the site variable directly, or use it as the fallback:
+\`color: var(--cogenta-color-accent, var(--t-accent));\`.
+
+Literal colours are allowed and expected in a theme's own stylesheet.
+**Gradients are not** — flat, structured surfaces only, no
+\`linear-gradient\`/\`radial-gradient\` anywhere. Use flat fills, borders and
+spacing to build hierarchy.
+
+Google Fonts may be pulled with an \`@import\` at the very top of a CSS file;
+always give a real fallback stack.
+
+## Light and dark
+
+Themes are expected to work in both. The site stamps \`data-theme="dark"\` or
+\`data-theme="light"\` on the root element when a visitor chooses explicitly,
+and stamps nothing on the default "system" setting — where only
+\`prefers-color-scheme\` separates them. Define the complete palette on bare
+\`:root\`, then redefine only the tokens in two more blocks:
+
+\`\`\`css
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) { --t-bg: #0e1013; --t-fg: #f2f4f7; }
+}
+:root[data-theme="dark"] { --t-bg: #0e1013; --t-fg: #f2f4f7; }
+:root[data-theme="light"] { --t-bg: #ffffff; --t-fg: #14171c; }
+\`\`\`
+
+Never give a colour its only definition inside a media or \`[data-theme]\`
+block — it then never applies in the unstamped state, and the page renders
+one theme's text on the other theme's background.
+
+A theme that deliberately commits to a single look may skip those blocks, but
+must still paint background and text colours explicitly.
+
+## Two things the page always has
+
+The host page template injects both on every page, whatever the theme, so
+every theme must account for them:
+
+1. **A "Skip to content" link**, \`.cg-skip-link\`, placed before your header
+   markup (WCAG 2.4.1). Style it off-screen until focus — never
+   \`display: none\`, which removes it from the tab order and defeats its
+   purpose. Without a rule for it, it renders as a plain visible link at the
+   very top of every page:
+
+\`\`\`css
+.cg-skip-link { position: absolute; left: 1rem; top: -4rem; z-index: 50;
+  padding: .6em 1.1em; background: var(--t-accent); color: var(--t-accent-fg);
+  border-radius: 999px; text-decoration: none; transition: top 160ms ease; }
+.cg-skip-link:focus-visible { top: 1rem; }
+\`\`\`
+
+2. **The light/dark toggle script.** The host injects the script; a theme only
+   ever places the button, via \`renderThemeToggle()\` from
+   '@cogenta/theme-kit', inside its own \`renderChrome\` markup. Never inject
+   the script yourself, and never write client JavaScript of your own —
+   themes are zero-JS apart from that one host-provided toggle.
+
+## A theme displays the site's content. It never contains content.
+
+This is the rule that separates a theme from a mockup, and breaking it
+produces something that looks finished and is unusable.
+
+Everything a visitor reads — article titles, excerpts, dates, menu labels,
+page copy — comes from the site's database at render time, through the page
+you were handed and through \`ctx.content\`. A theme that hardcodes three
+article cards in \`renderPage\` produces a site whose owner cannot edit those
+articles from the admin, cannot translate them, cannot add a fourth, and
+cannot delete the one that is wrong. It is not a shortcut; it is a site that
+does not work.
+
+Concretely, and without exception:
+
+- **Never invent posts, titles, excerpts, author names, dates or prices.** If
+  a list should show articles, fetch them:
+  \`const posts = await ctx.content.list({ collection: 'article', limit: 6 })\`
+  and render what comes back — however many that is, including none.
+- **Never write \`href="#"\`.** A link goes where the content says it goes:
+  \`ctx.link({ collection: entry.collection, id: entry.id })\` for an entry,
+  \`input.headerNav\`/\`input.footerNav\` in \`renderChrome\` for navigation.
+  A \`#\` is a dead link shipped to a real visitor.
+- **Never hardcode display text.** Labels a theme itself owns ("Read more",
+  "Next") go through \`ctx.t('readMore', { default: 'Read more' })\`, so a
+  site in another language is not stuck with English baked into its layout.
+- **An empty list renders as an empty state**, not as invented filler. A site
+  with no articles yet must show that honestly.
+
+A design shows three cards; the theme's job is a card *component* and a grid
+that renders however many entries exist. Design the container, never the
+contents.
+
+**The preview you get back is sample data.** \`theme.preview_sandbox\` renders
+your theme against a fixed demo page so you can see structure and styling —
+those titles and excerpts are scaffolding for the preview, not content to
+copy into your code. If you find yourself typing a title you saw in a
+preview, that is the mistake this section exists to prevent.
+
+## Images
+
+A photograph the request calls for is a real \`url()\` or \`<img>\`, resolved
+through \`ctx.image(mediaId)\` for uploaded media or pointing at a real asset
+path. A flat colour block standing in for a photo the brief asked for is a
+failure to deliver the design, not a simplification.
+
+## What "matching a design" means here
+
+Colour is the easiest half and the least of it. When a reference is given,
+reproduce, in this order of importance: the **layout skeleton** (how the page
+divides into regions, what is full-bleed vs contained, the grid and column
+counts), the **spacing rhythm and density**, the **typographic scale and
+pairing** (display vs body face, weights, letter-spacing, how large the
+biggest thing actually is relative to body text), the **shape language**
+(corner radius, borders, elevation, how flat or how carved), and only then
+the palette. A theme with the right palette and the wrong skeleton does not
+resemble the reference; the reverse mostly does.
+`.trim();
+//# sourceMappingURL=theme-spec.js.map

package/dist/theme-creator/theme-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-spec.js","sourceRoot":"","sources":["../../src/theme-creator/theme-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+N1C,CAAC,IAAI,EAAE,CAAA"}

package/dist/theme-creator/write-sandbox-file-tool.d.ts

@@ -0,0 +1,54 @@
+import { type ToolDefinition } from '@cogenta/agents';
+import { z } from 'zod';
+/**
+ * `theme.write_sandbox_file` (`tools@1.6`, `docs/04-contrats.md`) — fiche 73
+ * task 7. Same shape as `code.propose_patch` (`code.patch`,
+ * `../developer/patch-tool.ts`), on purpose: a real, effectful write with a
+ * real `revert`, `sideEffects: true` + `reversible: true` keeping it inside
+ * `withAutonomy`'s ordinary gate rather than always forcing approval. What
+ * differs is the destination and the meaning of "revert": `code.patch`
+ * opens a pull request nothing merges automatically, this writes straight
+ * into one file of one theme *sandbox* (`<projectRoot>/.cogenta/theme-sandbox
+ * /<id>/`, fiche 73 task 4) — never `themes/`, and so never anything a live
+ * request could resolve. `revert` deletes the file it wrote, the same
+ * "undo the one write this tool made" meaning `deps.patch`'s `revert`
+ * already has, just without a forge in between.
+ *
+ * `writeFile`/`deleteFile` are factory options, not part of the Zod input
+ * schema — the same shape `theme.propose_theme`'s `resolveProvider` and
+ * `code.propose_patch`'s `prClient` already use: this package cannot import
+ * `@cogenta/cli`'s `theme-sandbox.ts` (the dependency arrow runs the other
+ * way — `@cogenta/cli` depends on `@cogenta/agents-builtin`, never the
+ * reverse), so the real filesystem write — and the path-escape guard that
+ * makes it safe to hand a model — lives in `@cogenta/cli` and is threaded in
+ * here as a plain function.
+ */
+export interface WriteSandboxFileToolOptions {
+    readonly writeFile: (input: {
+        readonly sandboxId: string;
+        readonly path: string;
+        readonly content: string;
+    }) => Promise<{
+        readonly path: string;
+        readonly warnings?: readonly string[];
+    }>;
+    readonly deleteFile: (input: {
+        readonly sandboxId: string;
+        readonly path: string;
+    }) => Promise<void>;
+}
+declare const WriteSandboxFileInputSchema: z.ZodObject<{
+    sandboxId: z.ZodString;
+    path: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+export type WriteSandboxFileInput = z.infer<typeof WriteSandboxFileInputSchema>;
+declare const WriteSandboxFileOutputSchema: z.ZodObject<{
+    sandboxId: z.ZodString;
+    path: z.ZodString;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type WriteSandboxFileOutput = z.infer<typeof WriteSandboxFileOutputSchema>;
+export declare function createWriteSandboxFileTool(options: WriteSandboxFileToolOptions): ToolDefinition<WriteSandboxFileInput, WriteSandboxFileOutput>;
+export {};
+//# sourceMappingURL=write-sandbox-file-tool.d.ts.map

package/dist/theme-creator/write-sandbox-file-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-sandbox-file-tool.d.ts","sourceRoot":"","sources":["../../src/theme-creator/write-sandbox-file-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACjE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE;QAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;QAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KACzB,KAAK,OAAO,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC,CAAA;IAC/E,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE;QAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;QAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KACtB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACpB;AAED,QAAA,MAAM,2BAA2B;;;;iBAM/B,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAE/E,QAAA,MAAM,4BAA4B;;;;iBAKhC,CAAA;AACF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAEjF,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GACnC,cAAc,CAAC,qBAAqB,EAAE,sBAAsB,CAAC,CA4F/D"}

package/dist/theme-creator/write-sandbox-file-tool.js

@@ -0,0 +1,109 @@
+import { defineTool } from '@cogenta/agents';
+import { z } from 'zod';
+const WriteSandboxFileInputSchema = z.object({
+    /** An id `theme.propose_theme`-adjacent tooling (or a human) already created — this tool never creates a sandbox itself. */
+    sandboxId: z.string().min(1),
+    /** Sandbox-relative, e.g. `"theme.render.mjs"` — never absolute, never `../`-prefixed. The real escape guard is enforced host-side, in `@cogenta/cli`; this tool has no filesystem of its own to guard. */
+    path: z.string().min(1),
+    content: z.string(),
+});
+const WriteSandboxFileOutputSchema = z.object({
+    sandboxId: z.string(),
+    path: z.string(),
+    /** Present when the file was accepted but contains something worth fixing — a dead `href="#"`, say. Read them: a warning here is a real defect that simply was not worth refusing the write over. */
+    warnings: z.array(z.string()).optional(),
+});
+export function createWriteSandboxFileTool(options) {
+    return defineTool({
+        name: 'theme.write_sandbox_file',
+        version: '1.0.0',
+        description: `Writes one real source file (theme.config.*, theme.render.*, or any other file the theme needs) into a theme sandbox — actual TypeScript/JavaScript code, not tokens. Use this, never theme.propose_theme, whenever the request needs custom layout, custom markup structure, or anything no installed theme package already renders — a fully custom design, not a recolour of an existing one. theme.propose_theme only ever picks an existing installed theme and fills its colour/font/spacing tokens; it cannot change layout or markup. Never writes into themes/ directly, and never touches anything a live request could resolve — deploying the sandbox stays a separate, human-confirmed action.
+
+Full design freedom, like a WordPress theme or a Strapi frontend: renderPage/renderChrome are plain code, not a fixed template — fetch whatever data you want via ctx.content.entry()/list()/byPath() (any collection, not just what a page's own blocks list) and place it anywhere, in any layout, any markup, any CSS. page.blocks is one available data source, never a required structure — a page's blocks can be ignored entirely for a fully bespoke design that queries content directly. There is no closed list of block types either: a custom block type — any name, including one nobody else uses — is fine to invent and handle in renderPage; the shared vocabulary (hero, prose, mediaFigure, featureGrid, cta, gallery, quote, faq, stats, logos, collectionList, embed, testimonial, pricingTable, accordion, statCounter, logoStrip) is only there so existing content composed with those still shows something if this theme chooses to render them — implementing all of them is never required to deploy.
+
+Every write of theme.config.* or theme.render.* is validated for real before it lands — an invalid manifest field, a missing export, or a render function that does not actually produce a real page is rejected with a specific error naming what is wrong; read it and call this tool again with a corrected file. It is normal to need a few tries.
+
+theme.config.* — export default defineTheme({...}) from '@cogenta/theme-kit', EXACTLY these fields:
+  name: string, version: 'X.Y.Z' (exact semver), engine: '^1.0.0' (a semver RANGE, not a description), blocks: '^1.0.0' (also a semver range — the block-vocabulary version this theme supports, NEVER a list of block names), implements: string[] (which block _type names this theme's renderPage actually handles, e.g. ['hero','collectionList','prose']), collections: string[] | '*', runtime: 'static' | 'server' | 'edge' (one of these three literal strings, never an object), tokens: a STRING path to the tokens file, e.g. './theme.tokens.json' (never inline token data — the token VALUES belong in that separate JSON file, shaped like SkinTokens: {color:{bg,fg,accent,accentFg,muted,mutedFg,border}, font:{sans,serif,mono,scale,baseSize}, space:{unit,density}, radius:{sm,md,lg}, motion:{duration,easing,reduced}, shadow:{sm,md}} — nothing more, nothing less).
+
+A real .css file — any file name, any number of files (theme.css, style.css, base.css + blocks.css, whatever fits) — is REQUIRED for any design that is supposed to look like anything: real CSS, plain text, no <style> tags. Every *.css file written into this sandbox is picked up automatically, no naming convention to follow. Without at least one, the page is 100% unstyled HTML — every visual detail (colours, layout, spacing, grid, cards, hero image, typography) comes ONLY from selectors written here targeting the class names theme.render.* emits; nothing renders a design on its own. Read the request's visual reference (screenshot/description) closely and write real, specific CSS for it — layout (flexbox/grid), colours, spacing, typography, imagery — not a token dump. Colour/font/spacing VALUES are not invented here: reference the site's actual skin tokens through the CSS custom properties the site already generates on :root — --cogenta-color-bg/fg/accent/accent-fg/muted/muted-fg/border, --cogenta-font-sans/serif/mono, --cogenta-font-size-xs/sm/md/lg/xl/2xl/3xl, --cogenta-space-unit, --cogenta-radius-sm/md/lg, --cogenta-shadow-sm/md — e.g. "background: var(--cogenta-color-bg); font-family: var(--cogenta-font-serif); padding: calc(var(--cogenta-space-unit) * 2);". A background photo or other imagery is a real url() the theme's own markup or CSS points at (e.g. an uploaded media file resolved through ctx.image() and passed into the render module's markup as a style/background, or a static asset path) — never a placeholder colour standing in for a photo the brief actually asked for.
+
+theme.render.* — a real ES module. renderPage and renderChrome build markup with h() from '@cogenta/theme-kit' (h(tag, attrs, ...children) => HtmlElement, NOT a plain data object — the render pipeline calls serialize() on what these return, which only understands an HtmlElement tree or a plain string). There is no ctx.theme.tokens or any per-request access to skin token VALUES from render code — tokens reach the page only through the CSS custom properties the .css file(s) above read, never as JS values; a render module only ever emits semantic HTML with class names for that CSS to target. Minimal, real, working example:
+
+import { h } from '@cogenta/theme-kit'
+
+export function renderChrome(input) {
+  // input: { site: {name,url,locales,defaultLocale}, locale, homeHref, headerNav: [{label,href}], footerNav, brandingHtml }
+  const nav = (input.headerNav || []).map((l) => \`<a href="\${l.href}">\${l.label}</a>\`).join('')
+  return {
+    header: \`<header class="cg-header"><a href="\${input.homeHref}">\${input.site.name}</a><nav>\${nav}</nav></header>\`,
+    footer: \`<footer class="cg-footer">\${input.site.name}</footer>\`,
+  }
+}
+
+export function renderPage(page, ctx, entries = {}) {
+  // page: { title: string, blocks: Array<{_key, _type, ...fields}> } — the entry's real, saved contract-B blocks.
+  // ctx: { site, locale, url, t(key,vals), image(mediaId,opts), link(target), content: {entry,byPath,list} }
+  // entries: fetched collectionList results, keyed by block._key.
+  const renderedBlocks = page.blocks.map((block) => {
+    if (block._type === 'hero') {
+      return h('section', { class: 'cg-hero' }, [
+        h('h1', { class: 'cg-hero__title' }, block.title || page.title),
+        block.subtitle ? h('p', { class: 'cg-hero__subtitle' }, block.subtitle) : null,
+      ])
+    }
+    if (block._type === 'collectionList') {
+      const items = entries[block._key] || []
+      return h(
+        'section',
+        { class: 'cg-grid' },
+        items.map((entry) =>
+          h('article', { class: 'cg-card' }, [
+            h('h3', {}, String(entry.title ?? '')),
+            h('a', { href: ctx.link({ collection: entry.collection, id: entry.id }) }, ctx.t('readMore', { default: 'Read more' })),
+          ]),
+        ),
+      )
+    }
+    // Any block type not specifically styled still renders, plainly — never drop content the page actually has.
+    return h('section', { class: 'cg-block', 'data-type': block._type }, block.title ? h('h2', {}, String(block.title)) : null)
+  })
+  return h('main', { class: 'cg-main' }, [h('h1', { class: 'cg-page-title' }, page.title), ...renderedBlocks])
+}
+
+Matching .css for the example above (real selectors for the real classes theme.render.* just emitted — this is the part that actually makes it look like anything; call the file whatever you want):
+
+.cg-main { background: var(--cogenta-color-bg); color: var(--cogenta-color-fg); font-family: var(--cogenta-font-sans); }
+.cg-hero { padding: calc(var(--cogenta-space-unit) * 4) calc(var(--cogenta-space-unit) * 2); text-align: center; }
+.cg-hero__title { font-family: var(--cogenta-font-serif); font-size: var(--cogenta-font-size-3xl); }
+.cg-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--cogenta-space-unit); padding: var(--cogenta-space-unit); }
+.cg-card { background: var(--cogenta-color-muted); color: var(--cogenta-color-muted-fg); border-radius: var(--cogenta-radius-md); padding: var(--cogenta-space-unit); box-shadow: var(--cogenta-shadow-sm); }
+@media (max-width: 640px) { .cg-grid { grid-template-columns: 1fr; } }
+
+This example is deliberately generic (it renders whatever block types a real page actually has, defaulting unknown ones to a plain but real block rather than silently dropping them) — adapt the class names, nesting and per-block-type markup freely to match the requested design, but keep using h() to build the tree, keep renderChrome returning { header, footer } as HTML strings, and always write real .css (any file name) that actually styles whatever class names this file ends up using — a theme.render.* with no matching CSS renders as unstyled text, every time, regardless of how good the markup structure is.`,
+        input: WriteSandboxFileInputSchema,
+        output: WriteSandboxFileOutputSchema,
+        permissions: ['theme.write_sandbox'],
+        sideEffects: true,
+        reversible: true,
+        cost: 'low',
+        async execute(input) {
+            const result = await options.writeFile({
+                sandboxId: input.sandboxId,
+                path: input.path,
+                content: input.content,
+            });
+            return {
+                sandboxId: input.sandboxId,
+                path: result.path,
+                ...(result.warnings === undefined || result.warnings.length === 0
+                    ? {}
+                    : { warnings: [...result.warnings] }),
+            };
+        },
+        async revert(receipt) {
+            await options.deleteFile({ sandboxId: receipt.sandboxId, path: receipt.path });
+        },
+    });
+}
+//# sourceMappingURL=write-sandbox-file-tool.js.map

package/dist/theme-creator/write-sandbox-file-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-sandbox-file-tool.js","sourceRoot":"","sources":["../../src/theme-creator/write-sandbox-file-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAuB,MAAM,iBAAiB,CAAA;AACjE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAsCvB,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,4HAA4H;IAC5H,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,2MAA2M;IAC3M,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;CACpB,CAAC,CAAA;AAGF,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,qMAAqM;IACrM,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CACzC,CAAC,CAAA;AAGF,MAAM,UAAU,0BAA0B,CACxC,OAAoC;IAEpC,OAAO,UAAU,CAAC;QAChB,IAAI,EAAE,0BAA0B;QAChC,OAAO,EAAE,OAAO;QAChB,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wmBA+DulB;QACpmB,KAAK,EAAE,2BAA2B;QAClC,MAAM,EAAE,4BAA4B;QACpC,WAAW,EAAE,CAAC,qBAAqB,CAAC;QACpC,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,IAAI;QAChB,IAAI,EAAE,KAAK;QACX,KAAK,CAAC,OAAO,CAAC,KAAK;YACjB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC;gBACrC,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,OAAO,EAAE,KAAK,CAAC,OAAO;aACvB,CAAC,CAAA;YACF,OAAO;gBACL,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;oBAC/D,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;aACxC,CAAA;QACH,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,OAAO;YAClB,MAAM,OAAO,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;QAChF,CAAC;KACF,CAAC,CAAA;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cogenta/agents-builtin",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "The built-in agents shipped with Cogenta — Security, SEO, Content, Performance.",
   "license": "MPL-2.0",
   "type": "module",
@@ -28,8 +28,8 @@
   },
   "dependencies": {
     "zod": "^4.4.3",
-    "@cogenta/agents": "0.5.1",
-    "@cogenta/core": "0.7.0"
+    "@cogenta/core": "0.9.0",
+    "@cogenta/agents": "0.7.0"
   },
   "devDependencies": {
     "typescript": "^7.0.2",