@odla-ai/brand 0.1.0

package/README.md

@@ -0,0 +1,68 @@
+# @odla-ai/brand
+
+A conversational brand-book builder for odla apps — document and image uploads onto [odla-db](https://odla.ai/docs/packages/db) file storage, agent-driven color exploration with human-gated palette proposals, a zero-dependency OKLCH/WCAG color engine, and a token compiler that turns an approved brand book into [@odla-ai/ui](https://odla.ai/docs/packages/ui) design tokens. The conversation itself rides [@odla-ai/chat](https://odla.ai/docs/packages/chat).
+
+```sh
+npm i @odla-ai/brand
+```
+
+> **Agentic experiment.** This package is built and maintained by AI agents working from bounded runbooks with human review. Review its documented guarantees before relying on it.
+
+## The shape
+
+The package is a **schema + rules + an agent skill + a color engine + a token compiler + a route factory** — not a service you run.
+
+- **Proposals are the only door to the palette.** The agent explores colors (deterministic OKLCH math: harmonies, ramps, ΔEOK dedupe, WCAG contrast) and writes every candidate as an open `brand_proposal`. A human accepts or rejects; `resolve_proposal` is instructed to fire only on explicit user confirmation. Accepted proposals become `brand_palette` rows with full provenance.
+- **Vision happens in the model's own turn.** `view_asset` fetches uploaded bytes worker-side and returns them as image/PDF blocks *inside the tool result* — gated on the model's `toolResultBlocks` catalog capability (`supportsBrandVision`), with a pre-turn attachment fallback for models without it. No AI calls inside any tool handler; every handler is deterministic and testable.
+- **Uploads are worker-mediated.** The odla-db browser client cannot write files, so `createBrandRoutes` proxies multipart uploads onto the app's `$files` storage (content-type allowlist, size cap, unguessable paths) and keeps `brand_asset` rows deny-all so they always match real storage.
+- **Tokens compile to the @odla-ai/ui contract.** `compileBrandTokens` maps swatch roles onto `--ui-*` names — always emitting every required token plus the accent-composing derived set, so a scoped preview island never keeps stale root composites — and `renderTokensCss` emits theme-structured CSS (light, dark, invert). Dark is derived algorithmically and contrast re-tuned per token.
+- **Zero runtime dependencies.** The db client is injected structurally (a real `@odla-ai/db` `AdminDb` satisfies `BrandDb`); `@odla-ai/ai` is a types-only optional peer.
+
+## Quick start
+
+```ts
+import { createBrandRoutes, BRAND_SCHEMA, brandRules } from "@odla-ai/brand";
+import { init } from "@odla-ai/db";
+
+const db = init({ appId, adminToken, endpoint });
+
+// One-time provisioning: POST BRAND_SCHEMA to /schema and brandRules() to
+// /admin/rules (or use the brandIntegration descriptor with the odla CLI).
+
+const routes = createBrandRoutes({
+  db,
+  authorize: async (req) => (await isMember(req)) ? { id: await userId(req), kind: "human" } : null,
+});
+
+export default {
+  async fetch(req: Request): Promise<Response> {
+    return (await routes(req)) ?? new Response("not found", { status: 404 });
+  },
+};
+```
+
+Wire the agent by attaching `brandSkill` to a persona (or let the chat-agent worker route a `brandBotTrigger` dispatch into `dispatchBrandTurn`):
+
+```ts
+import { createBrandPersona, supportsBrandVision } from "@odla-ai/brand";
+
+const spec = inference.catalog[model];
+const persona = createBrandPersona({
+  model,
+  brand: {
+    db, bookId, fileBaseUrl,
+    self: { selfId: botId, kind: "bot" },
+    visionInToolResults: supportsBrandVision(spec),
+  },
+});
+const run = await runAgent(inference, persona, { input: userMessage });
+```
+
+Compile anywhere — worker, script, or browser:
+
+```ts
+import { compileBrandTokens, renderTokensCss } from "@odla-ai/brand";
+
+const { light, dark, warnings } = compileBrandTokens({ swatches });
+const css = renderTokensCss(light, { dark }); // :root / [data-theme="dark"] / media guard
+```