diff --git a/.agents/skills/starter/SKILL.md b/.agents/skills/starter/SKILL.md deleted file mode 100644 index c721b69..0000000 --- a/.agents/skills/starter/SKILL.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -name: starter -description: 'Conventions and patterns for building Sanity starter templates. Use when creating a new starter, modifying an existing one, or reviewing a starter PR. Covers project structure, env management, shared config packages, formatting, CI workflows, blueprints, typegen, and pnpm workspace patterns. Trigger on: new starter, add a starter, starter conventions, or any task that modifies starter-level configuration.' ---- - -# Starter Conventions - -Every starter in this repo must work as a standalone project when cloned via `sanity init --template`. These conventions keep starters consistent and maintainable. - -## Project Structure - -A starter is a pnpm monorepo at the root level of this repo: - -``` -my-starter/ -├── .github/workflows/ # CI, deploy, etc. (works standalone) -├── .env # dotenv-expand prefix mappings (safe to commit) -├── .env.example # Template for .env.local (committed) -├── .gitignore # Self-contained (no reliance on root) -├── .npmrc # enable-pre-post-scripts=true -├── .oxfmtrc.json # Formatting config -├── AGENT.md # Agent instructions for this starter -├── CLAUDE.md -> AGENT.md # Symlink -├── README.md # Setup instructions for users -├── package.json # Root scripts, engines, packageManager -├── pnpm-workspace.yaml # Workspace + catalog config -├── sanity.blueprint.ts # Infrastructure-as-code (if applicable) -├── skills/ # Starter-specific skills (if applicable) -├── studio/ # Sanity Studio workspace -├── apps/ # Frontend apps, dashboards -├── packages/ # Shared workspace packages -└── functions/ # Sanity Functions (if applicable) -``` - -## Required Files - -Every starter must have: - -| File | Purpose | -| --------------------- | ------------------------------------------------------------------------------ | -| `package.json` | `"type": "module"`, `engines`, `packageManager`, scripts | -| `pnpm-workspace.yaml` | Workspace packages + `catalog:` for shared dep versions | -| `.env.example` | Template with comments, no real values | -| `.gitignore` | Self-contained, covers all starter concerns | -| `.npmrc` | `enable-pre-post-scripts=true` (required for pnpm 10.x) | -| `.oxfmtrc.json` | `semi: false`, `singleQuote: true`, `printWidth: 100`, `bracketSpacing: false` | -| `README.md` | Getting started, prerequisites, project structure | -| `AGENT.md` | Agent context for Claude Code / Cursor / etc. | -| `CLAUDE.md` | Symlink to `AGENT.md` | - -## Environment Variables - -Single root `.env.local` cascades to all workspaces. Never committed. - -- `.env` — dotenv-expand prefix mappings (committed, no secrets) -- `.env.example` — template for users to copy to `.env.local` -- `.env.local` — actual values (gitignored) - -Loading patterns by context: - -| Context | Pattern | -| --------------------------------- | ----------------------------------------------------- | -| Studio CLI (`sanity.cli.ts`) | `process.loadEnvFile(\`${__dirname}/../.env.local\`)` | -| Blueprint (`sanity.blueprint.ts`) | `readFileSync` + manual parse (jiti quirk) | -| Vite apps | `vite: { envDir: '..' }` pointing to root | - -## Shared Config Packages - -Use `packages/@starter/` scope for shared configs: - -- **`@starter/eslint-config`** — flat config array (ESLint v9) -- **`@starter/tsconfig`** — `base.json` with ES2024, bundler resolution, strict mode - -All workspaces extend these. Keeps config DRY without coupling starters to each other. - -## pnpm Catalog - -Centralize shared dependency versions in `pnpm-workspace.yaml`: - -```yaml -catalog: - sanity: ^5.12.0 - '@sanity/client': ^7.16.0 - react: ^19.2 - # ... -``` - -Consumer packages reference as `"sanity": "catalog:"`. Prevents version drift. - -## Typegen - -Enable auto-typegen in `studio/sanity.cli.ts`: - -```ts -typegen: { - enabled: true, - path: ['./src/**/*.{ts,tsx}', '../packages/*/src/**/*.{ts,tsx}'], - generates: '../packages/@starter/sanity-types/sanity.types.ts', -} -``` - -The root `package.json` should have `"pretypecheck": "pnpm run typegen"` so typecheck works in CI and fresh clones where generated types don't exist yet. - -## Scripts - -Root `package.json` delegates to workspaces: - -```json -{ - "dev": "concurrently ... pnpm --filter dev", - "build": "pnpm -r build", - "test": "pnpm -r test", - "lint": "eslint --cache --cache-location node_modules/.cache/eslint/ .", - "format": "oxfmt .", - "format:check": "oxfmt --check .", - "typegen": "pnpm --filter studio typegen", - "pretypecheck": "pnpm run typegen", - "typecheck": "pnpm -r typecheck" -} -``` - -## GitHub Workflows - -Each starter ships its own workflows under `/.github/workflows/` for standalone use (they run when the starter is cloned via `sanity init --template`): - -- **`ci.yml`** — format check, lint, typecheck, validate, and (if it has Functions) build + manifest extract + bundle-size check -- **`deploy.yml`** — deploy Studio, functions, and blueprint on push to main (path-filtered); build the frontend as a guard. The Next.js storefront itself deploys via Vercel (dashboard import), not this workflow. -- **`eval.yml`** — manual triggers for quality evals (if applicable) - -## Wiring a New Starter into the Monorepo - -The starter's own workflows do **not** run in this repo — the root `.github/workflows/ci.yml` runs CI for every starter. Adding a new starter is not complete until you do all of the following (it's easy to forget the root CI job — a starter with green local `pnpm validate` still has **zero** monorepo coverage without it): - -1. **Add a job to the root `.github/workflows/ci.yml`.** Mirror an existing starter job (e.g. `knowledge-base`): a Node 20/22 matrix, `environment: `, `defaults.run.working-directory: `, then `pnpm install` + format check + lint + typecheck + validate (+ functions build, manifest extract, and bundle-size check if it has Functions). Steps that touch the Content Lake read `SANITY_STUDIO_PROJECT_ID`/`SANITY_STUDIO_DATASET` from `${{ vars.SANITY_PROJECT_ID }}` / `${{ vars.SANITY_DATASET }}`. -2. **Create a GitHub Environment** named exactly after the starter (repo Settings → Environments) with: - - vars: `SANITY_PROJECT_ID`, `SANITY_DATASET` (add `SANITY_STACK_ID` if it deploys a blueprint) - - secrets: `SANITY_AUTH_TOKEN` (only if the starter deploys) -3. **Add a row** to the starters table in the root `README.md`. -4. **Husky needs no edit** — the root `.husky/pre-commit` hook auto-discovers each starter by its own `package.json` / `eslint.config.*`, so formatting and lint-fix scope automatically. - -Verify from the starter directory with `pnpm validate` (template compatibility) and confirm the new `` job appears in the PR's checks. - -## Template Validation - -Starters must pass `sanity-template-validate` for compatibility with `sanity init --template`. Add `@sanity/template-validator` as a devDep and a `validate` script. - -## Blueprint Pattern - -If the starter uses Sanity Functions, include `sanity.blueprint.ts` at the starter root: - -- Use `readFileSync` for env loading (not `process.loadEnvFile` — jiti doesn't support it) -- Set `deletionPolicy: 'retain'` on datasets -- Reference robot tokens via `$.resources.` - -## Workspace Package Exports - -Use sub-path exports to maintain clean boundaries: - -```json -{ - "exports": { - ".": "./src/index.ts", - "./core": "./src/core/index.ts", - "./core/types": "./src/core/types.ts" - } -} -``` - -This lets serverless functions import pure utilities without pulling in React. diff --git a/.claude/skills/starter b/.claude/skills/starter deleted file mode 120000 index 48786ee..0000000 --- a/.claude/skills/starter +++ /dev/null @@ -1 +0,0 @@ -../../.agents/skills/starter \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index feb360d..51b9233 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,7 +33,7 @@ Always `cd` into the starter directory first. Each has its own pnpm workspace, l ## Conventions -All starters should follow the patterns documented in the `starter` skill. Run `/starter` or read `.agents/skills/starter/SKILL.md` before creating or modifying a starter. +All starters should follow the patterns documented in the [Conventions](./CONTRIBUTING.md#conventions) section of `CONTRIBUTING.md`. Read it before creating or modifying a starter. ## Adding a New Starter diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2abaec4..9e1a1b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,6 @@ Then customize it: 6. **Env** — update `.env.example` files if your starter needs additional variables 7. **README** — rewrite `README.md` to describe your starter, not the scaffold 8. **AGENT.md** — update with your starter's stack and context -9. **Skills** — add Claude Code skills under `skills/` or remove the placeholder When it's ready, wire it into the monorepo: @@ -33,7 +32,9 @@ The starter must work standalone when cloned via `sanity init --template`. Run ` ## Conventions -All starters share these baseline conventions to keep things consistent for users and maintainers. The full details live in the [starter skill](./.agents/skills/starter/SKILL.md), but the highlights: +All starters share these baseline conventions to keep things consistent for users and maintainers. Every starter must work as a standalone project when cloned via `sanity init --template`. + +The highlights: - **pnpm monorepo** with `catalog:` for shared dep versions - **ESM-first** (`"type": "module"`) @@ -43,6 +44,168 @@ All starters share these baseline conventions to keep things consistent for user - **AGENT.md** with `CLAUDE.md` symlink for AI agent context - **Template validation** via `sanity-template-validate` +The full details follow. + +### Project structure + +A starter is a pnpm monorepo at the root level of this repo: + +``` +my-starter/ +├── .github/workflows/ # CI, deploy, etc. (works standalone) +├── .env # dotenv-expand prefix mappings (safe to commit) +├── .env.example # Template for .env.local (committed) +├── .gitignore # Self-contained (no reliance on root) +├── .npmrc # enable-pre-post-scripts=true +├── .oxfmtrc.json # Formatting config +├── AGENT.md # Agent instructions for this starter +├── CLAUDE.md -> AGENT.md # Symlink +├── README.md # Setup instructions for users +├── package.json # Root scripts, engines, packageManager +├── pnpm-workspace.yaml # Workspace + catalog config +├── sanity.blueprint.ts # Infrastructure-as-code (if applicable) +├── studio/ # Sanity Studio workspace +├── apps/ # Frontend apps, dashboards +├── packages/ # Shared workspace packages +└── functions/ # Sanity Functions (if applicable) +``` + +### Required files + +Every starter must have: + +| File | Purpose | +| --------------------- | ------------------------------------------------------------------------------ | +| `package.json` | `"type": "module"`, `engines`, `packageManager`, scripts | +| `pnpm-workspace.yaml` | Workspace packages + `catalog:` for shared dep versions | +| `.env.example` | Template with comments, no real values | +| `.gitignore` | Self-contained, covers all starter concerns | +| `.npmrc` | `enable-pre-post-scripts=true` (required for pnpm 10.x) | +| `.oxfmtrc.json` | `semi: false`, `singleQuote: true`, `printWidth: 100`, `bracketSpacing: false` | +| `README.md` | Getting started, prerequisites, project structure | +| `AGENT.md` | Agent context for Claude Code / Cursor / etc. | +| `CLAUDE.md` | Symlink to `AGENT.md` | + +### Environment variables + +Single root `.env.local` cascades to all workspaces. Never committed. + +- `.env` — dotenv-expand prefix mappings (committed, no secrets) +- `.env.example` — template for users to copy to `.env.local` +- `.env.local` — actual values (gitignored) + +Loading patterns by context: + +| Context | Pattern | +| --------------------------------- | --------------------------------------------------------- | +| Studio CLI (`sanity.cli.ts`) | `process.loadEnvFile()` pointing at the root `.env.local` | +| Blueprint (`sanity.blueprint.ts`) | `readFileSync` + manual parse (jiti quirk) | +| Vite apps | `vite: { envDir: '..' }` pointing to root | + +### Shared config packages + +Use `packages/@starter/` scope for shared configs: + +- **`@starter/eslint-config`** — flat config array (ESLint v9) +- **`@starter/tsconfig`** — `base.json` with ES2024, bundler resolution, strict mode + +All workspaces extend these. Keeps config DRY without coupling starters to each other. + +### pnpm catalog + +Centralize shared dependency versions in `pnpm-workspace.yaml`: + +```yaml +catalog: + sanity: ^5.12.0 + '@sanity/client': ^7.16.0 + react: ^19.2 + # ... +``` + +Consumer packages reference as `"sanity": "catalog:"`. Prevents version drift. + +### Typegen + +Enable auto-typegen in `studio/sanity.cli.ts`: + +```ts +typegen: { + enabled: true, + path: ['./src/**/*.{ts,tsx}', '../packages/*/src/**/*.{ts,tsx}'], + generates: '../packages/@starter/sanity-types/sanity.types.ts', +} +``` + +The root `package.json` should have `"pretypecheck": "pnpm run typegen"` so typecheck works in CI and fresh clones where generated types don't exist yet. + +### Scripts + +Root `package.json` delegates to workspaces: + +```json +{ + "dev": "concurrently ... pnpm --filter dev", + "build": "pnpm -r build", + "test": "pnpm -r test", + "lint": "eslint --cache --cache-location node_modules/.cache/eslint/ .", + "format": "oxfmt .", + "format:check": "oxfmt --check .", + "typegen": "pnpm --filter studio typegen", + "pretypecheck": "pnpm run typegen", + "typecheck": "pnpm -r typecheck" +} +``` + +### GitHub workflows + +Each starter ships its own workflows under `/.github/workflows/` for standalone use (they run when the starter is cloned via `sanity init --template`): + +- **`ci.yml`** — format check, lint, typecheck, validate, and (if it has Functions) build + manifest extract + bundle-size check +- **`deploy.yml`** — deploy Studio, functions, and blueprint on push to main (path-filtered); build the frontend as a guard. The Next.js storefront itself deploys via Vercel (dashboard import), not this workflow. +- **`eval.yml`** — manual triggers for quality evals (if applicable) + +### Wiring a new starter into the monorepo + +The starter's own workflows do **not** run in this repo — the root `.github/workflows/ci.yml` runs CI for every starter. Adding a new starter is not complete until you do all of the following (it's easy to forget the root CI job — a starter with green local `pnpm validate` still has **zero** monorepo coverage without it): + +1. **Add a job to the root `.github/workflows/ci.yml`.** Mirror an existing starter job (e.g. `knowledge-base`): a Node 20/22 matrix, `environment: `, `defaults.run.working-directory: `, then `pnpm install` + format check + lint + typecheck + validate (+ functions build, manifest extract, and bundle-size check if it has Functions). Steps that touch the Content Lake read `SANITY_STUDIO_PROJECT_ID`/`SANITY_STUDIO_DATASET` from `${{ vars.SANITY_PROJECT_ID }}` / `${{ vars.SANITY_DATASET }}`. +2. **Create a GitHub Environment** named exactly after the starter (repo Settings → Environments) with: + - vars: `SANITY_PROJECT_ID`, `SANITY_DATASET` (add `SANITY_STACK_ID` if it deploys a blueprint) + - secrets: `SANITY_AUTH_TOKEN` (only if the starter deploys) +3. **Add a row** to the starters table in the root `README.md`. +4. **Husky needs no edit** — the root `.husky/pre-commit` hook auto-discovers each starter by its own `package.json` / `eslint.config.*`, so formatting and lint-fix scope automatically. + +Verify from the starter directory with `pnpm validate` (template compatibility) and confirm the new `` job appears in the PR's checks. + +### Template validation + +Starters must pass `sanity-template-validate` for compatibility with `sanity init --template`. Add `@sanity/template-validator` as a devDep and a `validate` script. + +### Blueprint pattern + +If the starter uses Sanity Functions, include `sanity.blueprint.ts` at the starter root: + +- Use `readFileSync` for env loading (not `process.loadEnvFile` — jiti doesn't support it) +- Set `deletionPolicy: 'retain'` on datasets +- Reference robot tokens via `$.resources.` + +### Workspace package exports + +Use sub-path exports to maintain clean boundaries: + +```json +{ + "exports": { + ".": "./src/index.ts", + "./core": "./src/core/index.ts", + "./core/types": "./src/core/types.ts" + } +} +``` + +This lets serverless functions import pure utilities without pulling in React. + ## Lock files Starter lock files are gitignored at the root level. Users generate their own on `pnpm install`. The root lock file (for DX deps) is committed. diff --git a/_scaffold/README.md b/_scaffold/README.md index a1adfee..2a81fc3 100644 --- a/_scaffold/README.md +++ b/_scaffold/README.md @@ -25,7 +25,6 @@ Then customize — see [CONTRIBUTING.md](../CONTRIBUTING.md) for the full checkl | **Bootstrap** | One-command setup: deploy blueprint, deploy schema, extract types, seed sample data | | **CI** | GitHub Actions workflow for type-checking, template validation, and function bundle verification | | **Agent context** | `AGENT.md` + `CLAUDE.md` symlink for AI-assisted development | -| **Skills** | Placeholder for Claude Code skills | ## Running the scaffold locally diff --git a/_scaffold/skills/example/SKILL.md b/_scaffold/skills/example/SKILL.md deleted file mode 100644 index 2add6ef..0000000 --- a/_scaffold/skills/example/SKILL.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -name: example -description: 'Example skill placeholder. Replace this with a real skill for your starter.' ---- - -# Example Skill - -This is a placeholder. Create skills to extend Claude Code with starter-specific workflows. - -## When to use - -Describe when this skill should be triggered. - -## Workflow - -1. Step one -2. Step two -3. Step three diff --git a/agent-ready-content/AGENT.md b/agent-ready-content/AGENT.md index f380aef..bdc8b0d 100644 --- a/agent-ready-content/AGENT.md +++ b/agent-ready-content/AGENT.md @@ -19,7 +19,6 @@ pnpm install && pnpm run bootstrap && pnpm dev - `apps/astro/` — Astro 7: HTML pages + `.md` endpoints + `Accept` middleware (server output) - `packages/schema/` — document types (section, article, code, callout) - `packages/agent-markdown/` — Portable Text serializers, document builders, GROQ queries. Everything defining the markdown output lives here; the apps contribute routing only. -- `skills/agent-ready-content/` — skill for porting the pattern onto an existing project ## Code style diff --git a/agent-ready-content/README.md b/agent-ready-content/README.md index d871827..f58f7a2 100644 --- a/agent-ready-content/README.md +++ b/agent-ready-content/README.md @@ -46,7 +46,6 @@ packages/ schema/ section, article, code, callout document types agent-markdown/ Portable Text serializers, document builders, GROQ queries seed/ Sample content (Keplar, a fictional geospatial API) -skills/ Claude Code skill for porting the pattern to existing projects ``` ## How the markdown routes work @@ -59,7 +58,7 @@ Everything that defines the markdown output lives in `packages/agent-markdown`. ## Adopting the pattern in an existing project -You don't need this starter's content model. [`skills/agent-ready-content/SKILL.md`](skills/agent-ready-content/SKILL.md) walks a coding agent through porting the pattern onto your existing schema: point the queries at your document types, map your custom blocks in the serializers, add the route files for your framework. By hand, budget roughly a day; the serializers for your custom blocks are the only part with real decisions in it. +You don't need this starter's content model. Porting the pattern onto your existing schema comes down to three steps: point the queries in `packages/agent-markdown` at your document types, map your custom blocks in the serializers, and add the route files for your framework (see the Next.js and Astro apps here for both shapes). Budget roughly a day; the serializers for your custom blocks are the only part with real decisions in it. ## Type safety diff --git a/agent-ready-content/skills/agent-ready-content/SKILL.md b/agent-ready-content/skills/agent-ready-content/SKILL.md deleted file mode 100644 index 0a86e50..0000000 --- a/agent-ready-content/skills/agent-ready-content/SKILL.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -name: agent-ready-content -description: > - Port the agent-ready content pattern (markdown routes, content negotiation, - sitemap.md, llms.txt) from the agent-ready-content starter into an existing - Sanity project. Use when someone wants their site's content served as - markdown for AI agents, wants to add llms.txt, wants "Accept: text/markdown" - content negotiation, or asks to make their docs or site agent-readable. ---- - -# Port agent-ready content into an existing project - -You are adapting the agent-ready-content starter's delivery pattern onto a project that already has its own schema and frontend. Do not copy the starter's content model. The pattern has three parts, and they adopt independently: explicit `.md` routes (do this first, it carries the most value), discovery routes (`llms.txt`, `sitemap.md`), and `Accept` header negotiation (optional, needs care with CDNs). - -## Step 1: Map the content model - -Ask for (or read from the project): - -- Which document types should be agent-readable, and which field holds the Portable Text body -- The URL structure of the existing HTML pages (you will mirror it for `.md`) -- Every custom block type inside the Portable Text arrays (code? image? video? embed? table?) - -## Step 2: Copy and adapt packages/agent-markdown - -Copy the package into the project (or its files into a `lib/` directory). Then: - -1. Rewrite `queries.ts` against the project's types and slugs. Keep the two-tier split: navigation queries fetch title/slug/summary only, article queries fetch full content. -2. In `serializers.ts`, write one renderer per custom block type found in step 1. Follow the conventions: GFM alerts for callout-like types, `lang:filename` fences for code, CDN URLs for images. A type without a renderer is silently dropped from the output, so cover all of them. -3. Adapt the builders in `build.ts` to the project's URL structure. Keep the canonical URL line in article output. - -## Step 3: Add routes for the project's framework - -- **Next.js**: copy `apps/next/src/app/md/` handlers, `sitemap.md/route.ts`, `llms.txt/route.ts`, and the `rewrites` block from `next.config.ts`. Adjust segment names to the project's URL structure. -- **Astro**: copy the `.md.ts` endpoint files, `llms.txt.ts`, and `src/middleware.ts`. Header negotiation requires an SSR adapter; skip the middleware for static builds. -- **Other frameworks**: the builders return strings. Any framework that can return a `Response` with a `Content-Type: text/markdown; charset=utf-8` header can serve them. Mirror the rewrite/endpoint split that fits its router. - -## Step 4: Verify - -```bash -curl http://localhost:3000/.md # markdown, correct Content-Type -curl -H "Accept: text/markdown" http://localhost:3000/ # same output -curl http://localhost:3000/llms.txt # H1, blockquote, H2 link lists -``` - -Check that the llms.txt links resolve, that custom blocks appear in the markdown (not silently dropped), and that no stega characters leak into the output (fetch with `stega: false` anywhere visual editing is enabled). - -## Conventions to preserve - -- `requestTagPrefix` on the client plus per-fetch tags (`md.article`, `llms.index`), so adoption is measurable -- Tiered cache headers: 60s/300s articles, 300s/600s navigation routes -- llms.txt links point at `.md` URLs, not HTML pages -- Summaries are the agent's decision surface: if the project's documents lack a summary field, recommend adding one rather than truncating body text - -## References - -Fetch these when you need to verify current APIs instead of trusting this file or your training data. The Learn URLs serve markdown when you append `.md`, which is the pattern you are porting. - -- [llms.txt spec](https://llmstxt.org/index.md): the required file structure (H1, blockquote, H2 link lists, Optional section). Check before changing `buildLlmsTxt`. -- [Markdown Routes with Next.js course](https://www.sanity.io/learn/course/markdown-routes-with-nextjs.md): step-by-step walkthrough of the Next.js half. Known issue: its `portableTextToMarkdown` snippets show a `serializers: {...}` options wrapper; the shipped @portabletext/markdown API takes renderer maps directly (`{types: {...}}`). Trust the installed package's types. -- [@portabletext/markdown](https://www.npmjs.com/package/@portabletext/markdown): renderer signatures for custom block types. -- [Next.js rewrites](https://nextjs.org/docs/app/api-reference/config/next-config-js/rewrites): `beforeFiles` timing and `has` header matching. -- [Astro endpoints](https://docs.astro.build/en/guides/endpoints/) and [middleware](https://docs.astro.build/en/guides/middleware/): `.md.ts` file routing and the `next(path)` rewrite used for header negotiation. -- [Request tags in @sanity/client](https://www.sanity.io/docs/apis-and-sdks/js-client-request-tags): how `requestTagPrefix` and per-fetch tags surface in request logs. diff --git a/agentic-localization/apps/frontend/src/app/[lang]/architecture/page.tsx b/agentic-localization/apps/frontend/src/app/[lang]/architecture/page.tsx index 346ec06..4169d80 100644 --- a/agentic-localization/apps/frontend/src/app/[lang]/architecture/page.tsx +++ b/agentic-localization/apps/frontend/src/app/[lang]/architecture/page.tsx @@ -918,9 +918,9 @@ defineField({

Add this to your project

- This starter includes an agent skill that walks Claude through adding the full - localization setup to any existing Sanity project. Studio-side and frontend-side, step by - step. + The Studio-side and frontend-side pieces of this setup are documented in the starter + repository, so you can port the full localization workflow to an existing Sanity project + step by step.

`, locale switcher | -| `apps/frontend/src/app/[lang]/page.tsx` | Article list filtered by locale | -| `apps/frontend/src/app/[lang]/[slug]/page.tsx` | Article detail with fallback logic | -| `apps/frontend/src/components/LocaleSwitcher.tsx` | Path-based locale switching with cookie persistence | -| `apps/frontend/src/components/FallbackBanner.tsx` | Fallback language notice | -| `apps/frontend/src/components/PortableText.tsx` | Portable Text renderer | - -Visit `/en-US/architecture` in the running frontend for an interactive -architecture overview. - -Do NOT recreate these files — modify the existing ones. - -## If Using a Different Framework - -### Step 1 — Load Reference - -Read `references/shared-setup.md` for the framework-agnostic patterns: Sanity -client setup, GROQ queries, TypeScript types, the fallback content pattern, and -design principles. - -### Step 2 — Adapt the Patterns - -Apply the shared patterns using your framework's conventions: - -| Concern | Next.js (reference) | Astro | SvelteKit | -| --------------- | ---------------------------- | ------------------- | -------------------- | -| Client | `next-sanity` `createClient` | `@sanity/client` | `@sanity/client` | -| Env prefix | `NEXT_PUBLIC_` | `PUBLIC_` | `PUBLIC_` | -| Routing | `app/[lang]/` file-based | `src/pages/[lang]/` | `src/routes/[lang]/` | -| SSR fetch | `server-only` module | Astro frontmatter | `+page.server.ts` | -| Locale redirect | `middleware.ts` | Astro middleware | `hooks.server.ts` | - -### Step 3 — Implement - -Read the Next.js source files listed above for implementation patterns, then -adapt them to your framework. The core logic is the same: - -1. **Locale routing** — path prefix (`/en-US/slug`, `/de-DE/slug`) -2. **Locale switcher** — swap the path segment, persist preference in a cookie -3. **Fallback content** — try target locale, fall back to default, show banner -4. **Dynamic locales** — query `l10n.locale` documents, never hardcode - -### Step 4 — Verify - -1. Dev server starts without errors -2. `/` redirects to `/{defaultLocale}/` -3. Locale switcher changes URL and content -4. Missing translations show fallback banner -5. New locales added in Studio appear automatically - -## Extending This Skill - -To add a framework-specific reference: - -1. Create `references/-setup.md` covering framework-specific routing, - data fetching, and middleware patterns. -2. Add the framework's config file pattern to the adaptation table above. -3. No changes needed to `shared-setup.md` or the workflow steps. - -## Companion Skills - -- **sanity-l10n** — The l10n plugin, prompt assembly, glossaries, style guides, - evals, and serverless functions -- **sanity-best-practices** — General i18n patterns: document-level vs - field-level diff --git a/agentic-localization/skills/add-l10n-frontend/references/nextjs-setup.md b/agentic-localization/skills/add-l10n-frontend/references/nextjs-setup.md deleted file mode 100644 index c0f9bf2..0000000 --- a/agentic-localization/skills/add-l10n-frontend/references/nextjs-setup.md +++ /dev/null @@ -1,72 +0,0 @@ -# Next.js Reference Implementation - -The complete Next.js implementation lives at `apps/frontend/`. Read the source -files directly rather than duplicating code here. - -## Key Files - -| File | Purpose | -| ------------------------------------------------- | ---------------------------------------------------- | -| `apps/frontend/src/sanity/client.ts` | Sanity client via `next-sanity` | -| `apps/frontend/src/sanity/fetch.ts` | Server-only fetch wrapper | -| `apps/frontend/src/sanity/queries.ts` | GROQ queries with `defineQuery()` | -| `apps/frontend/src/sanity/types.ts` | TypeScript interfaces | -| `apps/frontend/src/proxy.ts` | Middleware for locale redirect | -| `apps/frontend/src/app/[lang]/layout.tsx` | Root layout, locale switcher, `generateStaticParams` | -| `apps/frontend/src/app/[lang]/page.tsx` | Article list by locale | -| `apps/frontend/src/app/[lang]/[slug]/page.tsx` | Article detail with fallback | -| `apps/frontend/src/components/LocaleSwitcher.tsx` | Path-swapping locale picker | -| `apps/frontend/src/components/FallbackBanner.tsx` | "Viewing in fallback language" notice | -| `apps/frontend/src/components/PortableText.tsx` | Portable Text renderer | -| `apps/frontend/src/components/ArticleCard.tsx` | Article preview card | - -## Dependencies - -Runtime: `next` (^15), `next-sanity`, `react` (^19), `react-dom` (^19), -`@portabletext/react`, `@sanity/image-url`, `@tailwindcss/typography` - -Dev: `tailwindcss` (^4), `@tailwindcss/postcss`, `postcss`, `typescript`, -`@types/react`, `@types/react-dom` - -## Implementation Notes - -These are patterns to understand, not code to copy: - -### Data fetching - -Uses a `server-only` fetch wrapper (`src/sanity/fetch.ts`), NOT `defineLive()` -or `SanityLive`. The wrapper creates a server client with the read token and -`useCdn: false`. - -### Routing - -Path-based locale prefixes (`/en-US/slug`, `/de-DE/slug`). All pages nest under -`app/[lang]/`. In Next.js 15, `params` is a Promise and must be awaited. - -### Middleware - -Redirects bare paths to `/{preferred locale}`. Reads a `NEXT_LOCALE` cookie set -by the locale switcher; falls back to `en-US` for first-time visitors. - -### Fallback content - -Detail page queries the target locale first. If null and not the default -language, retries with `en-US`. Renders a `FallbackBanner` when showing fallback -content. - -### Locale switcher - -Client component that reads the current locale from the URL path, swaps the -path segment on click, and persists the choice in a `NEXT_LOCALE` cookie. - -### Static generation - -`generateStaticParams` in the layout queries `l10n.locale` documents to generate -a page per locale at build time. - -### Request tags - -The reference client sets `requestTagPrefix: 'kit.agentic-l10n'` — handy -for filtering your own request logs. Change or remove `requestTagPrefix` in -your client config to use whatever tagging scheme you prefer. See -[Request tags](https://www.sanity.io/docs/apis-and-sdks/js-client-request-tags). diff --git a/agentic-localization/skills/add-l10n-frontend/references/shared-setup.md b/agentic-localization/skills/add-l10n-frontend/references/shared-setup.md deleted file mode 100644 index 773b493..0000000 --- a/agentic-localization/skills/add-l10n-frontend/references/shared-setup.md +++ /dev/null @@ -1,86 +0,0 @@ -# Shared Setup — Framework-Agnostic - -Patterns that apply regardless of frontend framework. For the Next.js -implementation, read `apps/frontend/src/` directly. - -## Environment Variables - -| Variable | Description | Framework prefix | -| ---------- | -------------------------------------- | --------------------------------------------------------------------- | -| Project ID | Sanity project ID | `NEXT_PUBLIC_` (Next.js), `PUBLIC_` (Astro/SvelteKit), `VITE_` (Vite) | -| Dataset | Dataset name | Same prefix pattern | -| Read token | Read-only API token (server-side only) | `SANITY_API_READ_TOKEN` (no prefix — never expose to client) | - -## Sanity Client - -For Next.js, use `createClient` from `next-sanity`. For other frameworks, use -`@sanity/client`. See `apps/frontend/src/sanity/client.ts` for the Next.js -version. - -### Request Tags - -The reference client at `apps/frontend/src/sanity/client.ts` sets -`requestTagPrefix: 'kit.agentic-l10n'`, and per-call options take a -`tag: '.'` (e.g. `tag: 'articles.list'`), producing the combined -tag `kit.agentic-l10n.articles.list` — handy for filtering your own -request logs. Change or remove `requestTagPrefix` in your client config to use -whatever tagging scheme you prefer. See -[Request tags](https://www.sanity.io/docs/apis-and-sdks/js-client-request-tags). - -## Key Concepts - -### The `language` field - -A hidden, read-only string injected by the l10n plugin into every localized -document type. Stores a BCP-47 locale code (e.g., `"en-US"`, `"de-DE"`). -Managed by the Studio, not the frontend. - -### The `l10n.locale` document type - -Locales are Sanity documents with `_type: "l10n.locale"`. Each has `code` -(BCP-47), `title` (display name), and `nativeName` (name in the locale's own -language). Query these to build dynamic locale switchers — never hardcode locale -lists. - -### Slug storage - -Slugs are stored as `{ current: "the-slug", _type: "slug" }`. Always project -as `"slug": slug.current` in GROQ queries. - -### Localized document types - -Only types listed in `createL10n({localizedSchemaTypes: [...]})` have the -`language` field. - -## GROQ Query Patterns - -See `apps/frontend/src/sanity/queries.ts` for the complete queries. The key -patterns: - -- **Filter by locale:** `*[_type == "article" && language == $language]` -- **Fetch locales:** `*[_type == "l10n.locale"] | order(title asc)` -- **Single doc by slug + locale:** `*[_type == "article" && slug.current == $slug && language == $language][0]` - -## Fallback Content Pattern - -When a translation is missing for the requested locale: - -1. Query for the document with the requested locale -2. If null AND the locale is not the default language, query the same slug with - the default language (`en-US`) -3. If a fallback is found, render it with a banner indicating the content is in - the default language -4. If still null, show a 404 - -See `apps/frontend/src/app/[lang]/[slug]/page.tsx` for the Next.js -implementation. - -## Design Principles - -1. **Separate concerns** — Keep framework-agnostic Sanity code in `src/sanity/`. - Framework-specific rendering goes in pages/components. -2. **Read-only frontend** — The frontend never mutates Sanity data. No write - tokens, no Studio dependencies. -3. **Dynamic locales** — Always query `l10n.locale` documents instead of - hardcoding. New locales added in the Studio appear automatically. -4. **Type safety** — Use `defineQuery()` (Next.js) or typed fetch wrappers. diff --git a/agentic-localization/skills/sanity-l10n/SKILL.md b/agentic-localization/skills/sanity-l10n/SKILL.md deleted file mode 100644 index 5b05850..0000000 --- a/agentic-localization/skills/sanity-l10n/SKILL.md +++ /dev/null @@ -1,243 +0,0 @@ ---- -name: sanity-l10n -description: 'Work with a Sanity starter that uses structured content (glossaries, style guides, locale metadata) to make AI translation enterprise-grade. Covers prompt assembly, automated stale detection via Sanity Functions, translation quality evals, and the Agent Actions Translate API. Trigger on: customize glossary, add terminology, translation style guide, run evals, deploy functions, prompt assembly, debug translation, extend l10n plugin, Agent Actions Translate, blueprint deploy, stale detection, pre-translation, field-level translation, field translation, internationalizedArray, field workflow, publish gate, field matrix, per-field translate, field approve, review workflow, translate field action. Complements sanity-best-practices (general i18n) and add-l10n-frontend (frontend rendering).' ---- - -# Sanity Agentic Localization - -## Core Principles - -Enterprise translation quality comes from structured metadata, not better -engines. This starter closes the gap between enterprise TMS capabilities and AI -translation APIs. See `docs/I18N_RESEARCH.md` for the full gap analysis. - -1. **Structured content is the medium** — Glossaries, style guides, and locale - rules are Sanity documents. Content teams maintain them in the Studio. Code - queries them at translation time. Every job reuses them. - -2. **Content-aware assembly** — Don't dump all glossary terms into every prompt. - `filterGlossaryByContent()` prunes to terms that actually appear in the - source document. Always include do-not-translate and forbidden terms as - guardrails. - -3. **Prove it** — Translate WITH and WITHOUT context. Measure the delta. If - glossaries don't measurably improve quality, the terms need work. The - strongest entries are brand names that look like common English words (e.g., - "Releases", "Perspectives", "Portable Text"). - -4. **Automate the lifecycle** — Stale detection, change analysis, and - pre-translation happen automatically via Sanity Functions. Editors review - results, not initiate workflows. - -5. **Lean on the platform** — Use Sanity exports, generated types (TypeGen), and - `@sanity/*` utilities. Don't reinvent what the SDK provides. - -## Orientation - -Read `references/architecture.md` for the full project map. Key entry points: - -- `packages/l10n/` — Unified plugin: schemas, prompt assembly, translation UI, - hooks, evals. Sub-path exports keep serverless functions React-free. -- `functions/` — Two Sanity Functions: mark translations stale on publish, - analyze changes + pre-translate. -- `studio/` — Studio workspace with article, person, topic, tag types. -- `apps/translations-dashboard/` — Real-time translation overview (App SDK). -- `apps/frontend/` — Next.js frontend with path-based i18n routing. -- `sanity.blueprint.ts` — Infrastructure-as-code: dataset, robot token, - functions. -- Start here: `packages/l10n/src/promptAssembly.ts` — the core bridge between - structured metadata and the Translate API. - -### Two-Tier Architecture - -The starter supports two complementary translation approaches: - -- **Document-level** (`@sanity/document-internationalization`) — one document per - locale. Used for content types where the entire document is translated (e.g., - articles). Configured via `localizedSchemaTypes` in `createL10n()`. -- **Field-level** (`sanity-plugin-internationalized-array`) — inline - `internationalizedArray*` fields on a single document. Used for types where - only specific fields need translation (e.g., person bios). Auto-detected by - the inspector via schema walk. - -Key field-level entry points: - -- `packages/l10n/src/translations/FieldTranslationContent.tsx` — field x locale - matrix inspector -- `packages/l10n/src/translations/deriveFieldCellStates.ts` — pure state - derivation (6 rules) -- `packages/l10n/src/translations/useFieldTranslateActions.ts` — translation - orchestration (translate, approve, dismiss) -- `packages/l10n/src/core/types.ts` — `FieldWorkflowStateEntry`, - `FieldCellState` types - -## Jobs to Be Done - -### 1. Customize glossaries for my domain - -Replace the Sanity product terms with your own brand terminology. The strongest -glossary entries are brand names that look like common English words — generic -terms like "Dashboard" add little value because models translate them correctly -without help. - -- Read `packages/l10n/evals/fixtures.ts` to see the example glossary entries -- Read `packages/l10n/src/schemas/glossaryEntry.ts` for the 7-field anatomy -- Load `references/customization-guide.md` for detailed guidance -- Do NOT remove fields from glossary entries — each drives branching logic in - prompt assembly - -### 2. Add a content type to the l10n system - -- Add the type name to `localizedSchemaTypes` in `studio/sanity.config.ts` -- Run `pnpm exec sanity schema deploy` from `studio/` -- Update the function event filter in `sanity.blueprint.ts` if the new type - should trigger stale detection -- Redeploy functions: `pnpm exec sanity blueprints deploy` - -### 3. Create or modify style guides - -Style guides are per-locale: formality level, tone adjectives, and free-form -instructions in Portable Text. - -- Read `packages/l10n/src/schemas/translationStyleGuide.ts` for the schema -- Read `packages/l10n/evals/fixtures.ts` for example style guides (DE, FR, JA) -- Load `references/customization-guide.md` for best practices -- Style guides are fetched by locale code via `STYLE_GUIDE_FOR_LOCALE_QUERY` - -### 4. Run and understand evals - -Two test suites live in `packages/l10n/`: - -```sh -pnpm --filter l10n test # Unit tests: schema, prompt assembly, locale utils -pnpm --filter l10n eval # Model evals: translate with/without context, score delta -``` - -- Evals require `sanity login` and consume AI credits -- Two-layer scoring: deterministic checks (term presence/absence/patterns) + - LLM judge (4 dimensions, 3 trials averaged) -- Pass = deterministic.pass AND judge.overall >= 3.5 -- Load `references/customization-guide.md` for writing new eval cases - -### 5. Deploy functions and infrastructure - -```sh -pnpm exec sanity blueprints deploy -``` - -- Read `sanity.blueprint.ts` for the resource definitions -- Two functions: `mark-translations-stale` (15s timeout, triggers on publish) - and `analyze-stale-translations` (120s timeout, 1GB memory, triggers on - metadata update) -- Both use a shared robot token with editor role -- Load `references/customization-guide.md` for modifying function filters and - env vars - -### 6. Understand prompt assembly - -The pipeline in `packages/l10n/src/promptAssembly.ts`: - -1. `extractDocumentText()` — recursively extract text from a Sanity document -2. `filterGlossaryByContent()` — prune glossary to terms in the source -3. `buildGlossarySection()` — format entries as Approved / DNT / Forbidden -4. `buildStyleGuideSection()` — format formality, tone, instructions -5. `assembleStyleGuide()` — combine glossary + style guide into a single string -6. `extractProtectedPhrases()` — pull DNT terms for the API's protectedPhrases -7. `buildTranslateParams()` — package everything for Agent Actions Translate - -Read the source file directly — it's ~250 lines and well-commented. - -### 7. Debug a translation issue - -Load `references/troubleshooting.md` for common issues: - -- Agent Actions errors (schema not deployed, token missing) -- Style guide too large (>12,000 chars warning) -- Eval failures (sourceText/fieldPath mismatch, auth token resolution) -- Functions issues (pnpm dep resolution, env var loading in jiti) - -### 8. Understand the field-level translation architecture - -- When to use document-level vs field-level: see "Two-Tier Architecture" above -- The `fieldTranslation.metadata` schema uses `liveEdit: true` (patches write - directly, no draft), `hidden: true`, and deterministic IDs via - `getFieldTranslationMetadataId()` -- The 6 derivation rules in `deriveFieldCellStates.ts` merge document state with - metadata to produce the `FieldCellState` matrix -- Inspector auto-detection: `useInternationalizedFields` walks the compiled - schema to find all `internationalizedArray*` fields — no manual registration -- Load `references/field-level-patterns.md` for the full data flow, hook API, - and translation pipeline details - -### 9. Add field-level translations to a document type - -1. Change the field type to `internationalizedArrayText` (or - `internationalizedArrayString`) in your schema definition -2. The inspector auto-discovers it — no registration needed -3. Deploy schema: `cd studio && pnpm exec sanity schema deploy` - -Example: `studio/schemaTypes/person.ts` uses `internationalizedArrayText` for -the `bio` field. The field-level inspector automatically detects it and shows -the field x locale matrix. - -### 10. Customize the field-level review workflow - -Load `references/field-level-patterns.md` for details on: - -- Publish gate behavior — `createFieldTranslationPublishGate` wraps - PublishAction, disables when `needsReview` or `stale` entries exist -- Concurrency limits — `MAX_CONCURRENT = 5` in `useFieldTranslateActions.ts` -- Stale detection sensitivity — `sourceSnapshot` comparison uses - `JSON.stringify`, debounce is 500ms in `useStaleSyncEffect` -- Load `references/customization-guide.md` for modification guidance - -### 11. Debug field-level translation issues - -Load `references/troubleshooting.md` for common issues: - -- Metadata not created — needs write permission (`liveEdit: true`) -- Publish blocked but translations look fine — stale metadata -- Fields not appearing in matrix — must use `internationalizedArray*` type -- Stale not detected — client-side only, runs when inspector is open -- Translations missing from matrix — check source content exists - -## Anti-Patterns - -- **Do NOT duplicate l10n schema types** — the plugin registers them via - `createL10n()`. Adding them to `studio/schemaTypes/` causes conflicts. -- **Do NOT hardcode locale lists** — query `l10n.locale` documents. The seed - migration creates them. -- **Do NOT inject all glossary terms** — use `filterGlossaryByContent()` to - keep prompts focused. -- **Do NOT remove glossary entry fields** — all 7 (term, status, - doNotTranslate, partOfSpeech, definition, context, translations) drive - branching logic in `buildGlossarySection()`. -- **Do NOT use `getCliClient` outside CLI** — it won't resolve auth tokens. - Pass `token` explicitly. See `packages/l10n/evals/authToken.ts`. -- **Do NOT skip `sanity schema deploy`** — Agent Actions requires deployed - schema. Schema ID is `_.schemas.default`. -- **Do NOT manually create `fieldTranslation.metadata` documents** — - deterministic IDs via `getFieldTranslationMetadataId()`. The hooks and actions - create them automatically with `createIfNotExists`. -- **Do NOT use `useFormValue` for field translation data** — the inspector - renders outside form context. Use `documentStore.listenQuery()` instead (see - `useFieldTranslationData.ts`). -- **Do NOT skip the publish gate** — `createFieldTranslationPublishGate` wraps - PublishAction. Don't remove it or bypass it without understanding the - consequences for translation review workflows. - -## Reference Files - -| File | Load when... | -| ------------------------------------ | ----------------------------------------------------------------- | -| `references/architecture.md` | You need the full project map, data flow, or schema overview | -| `references/customization-guide.md` | Customizing glossaries, style guides, evals, or functions | -| `references/troubleshooting.md` | Debugging translation, eval, or deployment issues | -| `references/field-level-patterns.md` | Understanding or customizing the field-level translation workflow | - -## Companion Skills - -- **sanity-best-practices** — General i18n patterns: document-level vs - field-level, `@sanity/document-internationalization` -- **add-l10n-frontend** — Frontend rendering of localized content (Next.js - reference implementation, patterns for other frameworks) diff --git a/agentic-localization/skills/sanity-l10n/references/architecture.md b/agentic-localization/skills/sanity-l10n/references/architecture.md deleted file mode 100644 index c3ef6f5..0000000 --- a/agentic-localization/skills/sanity-l10n/references/architecture.md +++ /dev/null @@ -1,210 +0,0 @@ -# Architecture - -## Monorepo Layout - -``` -starter-agentic-i18n/ -├── sanity.blueprint.ts Infrastructure-as-code (dataset, robot token, functions) -├── .env.local Single source for all env vars (all workspaces read this) -├── docs/I18N_RESEARCH.md Gap analysis: enterprise TMS vs AI translation APIs -│ -├── packages/l10n/ @starter/l10n — the core plugin -│ ├── src/ -│ │ ├── index.ts createL10n(), injectLanguageField, withLocaleFilter -│ │ ├── promptAssembly.ts Prompt assembly pipeline (the main bridge) -│ │ ├── queries.ts GROQ queries for locales, glossaries, style guides -│ │ ├── types.ts Schema type name constants -│ │ ├── core/ Pure utilities (zero React — safe for serverless) -│ │ │ ├── types.ts Workflow statuses, stale analysis types, config -│ │ │ ├── fieldMetadataIds.ts Deterministic IDs for fieldTranslation.metadata -│ │ │ ├── computeFieldChanges.ts Field-level diffing -│ │ │ ├── buildFieldSummary.ts Human-readable change summary for AI -│ │ │ ├── extractBlockText.ts Plain text from Portable Text -│ │ │ ├── staleAnalysisPrompt.ts System prompt for change analysis -│ │ │ ├── staleAnalysisCache.ts Cache helpers for metadata documents -│ │ │ └── sanitizeTranslationValue.ts Clean AI output before write -│ │ ├── schemas/ Sanity document/object type definitions -│ │ │ ├── translationLocale.tsx l10n.locale -│ │ │ ├── translationGlossary.ts l10n.glossary -│ │ │ ├── glossaryEntry.ts l10n.glossary.entry (object) -│ │ │ ├── translationStyleGuide.ts l10n.style-guide -│ │ │ ├── localeTranslation.ts l10n.locale.translation (object) -│ │ │ ├── metadataFields.ts translation.metadata fields -│ │ │ └── fieldTranslationMetadata.ts fieldTranslation.metadata (liveEdit, hidden) -│ │ ├── contexts/ Shared context providers (layout-level) -│ │ │ ├── LocalesContext.tsx Single listenQuery for locales -│ │ │ ├── GlossariesContext.tsx Single listenQuery for glossaries -│ │ │ └── L10nProvider.tsx Composes providers at studio layout -│ │ ├── fieldActions/ AI Assist field action integration -│ │ │ ├── useInternationalizedFields.ts Schema walk: discover i18n fields -│ │ │ └── useTranslateFieldAction.ts Per-locale translate sub-actions -│ │ └── translations/ React UI: translation pane, inspector, hooks -│ │ ├── FieldTranslationContent.tsx Field × locale matrix inspector -│ │ ├── deriveFieldCellStates.ts Pure state derivation (6 rules) -│ │ ├── useFieldTranslateActions.ts Bulk translate/approve/dismiss -│ │ ├── useFieldTranslationData.ts Realtime field snapshot -│ │ ├── useFieldWorkflowMetadata.ts Metadata subscription -│ │ ├── useFieldTranslationPublishGate.ts Publish gate wrapper -│ │ ├── useStaleSyncEffect.ts Debounced stale persistence -│ │ ├── useLocales.ts Thin wrapper over LocalesContext -│ │ ├── createSemaphore.ts Concurrency limiter -│ │ ├── StaleDiffPopover.tsx Stale cell diff UI -│ │ └── ... (other doc-level translation files) -│ └── evals/ Translation quality evaluation framework -│ ├── fixtures.ts Shared test data (locales, glossaries, source texts) -│ ├── scoring.ts Deterministic scoring (term presence/absence/patterns) -│ ├── judge.ts LLM-as-judge (4 dimensions × weights, 3 trials) -│ ├── model-scoring.ts Combined scoring + baseline comparison -│ ├── translate.ts Calls Agent Actions Translate (noWrite: true) -│ ├── authToken.ts Resolves Sanity auth token for evals -│ └── setup.ts Global setup/teardown (seeds eval source doc) -│ -├── functions/ Sanity Functions (serverless) -│ ├── mark-translations-stale.ts Marks translations stale on source publish -│ └── analyze-stale-translations.ts AI analysis + pre-translation of stale fields -│ -├── studio/ Sanity Studio workspace -│ ├── sanity.config.ts Plugin config, localizedSchemaTypes list -│ ├── schemaTypes/ Article, person, topic, tag -│ └── migrations/ Deterministic locale seeding -│ -├── apps/ -│ ├── translations-dashboard/ Real-time overview (Sanity App SDK) -│ └── frontend/ Next.js frontend with path-based i18n routing -│ └── src/app/[lang]/ Locale-parameterized routes -│ -└── packages/ - ├── @starter/eslint-config/ Shared ESLint config - └── @starter/tsconfig/ Shared tsconfig base -``` - -## Sub-Path Exports - -The l10n package uses sub-path exports to maintain a React-free boundary for -serverless functions: - -| Import path | Contents | React-free? | -| --------------------------------------------- | ------------------------------------------------------- | ----------- | -| `@starter/l10n` | `createL10n`, `injectLanguageField`, `withLocaleFilter` | No | -| `@starter/l10n/promptAssembly` | Assembly pipeline, types | Yes | -| `@starter/l10n/queries` | GROQ query strings | Yes | -| `@starter/l10n/core` | All core utilities | Yes | -| `@starter/l10n/core/types` | Workflow statuses, analysis types | Yes | -| `@starter/l10n/core/computeFieldChanges` | Field-level diffing | Yes | -| `@starter/l10n/core/buildFieldSummary` | Change summary for AI prompt | Yes | -| `@starter/l10n/core/staleAnalysisPrompt` | System prompt template | Yes | -| `@starter/l10n/core/staleAnalysisCache` | Cache read/write helpers | Yes | -| `@starter/l10n/core/sanitizeTranslationValue` | Clean AI output | Yes | -| `@starter/l10n/core/fieldMetadataIds` | `getFieldTranslationMetadataId` — deterministic IDs | Yes | - -Functions import from `@starter/l10n/core/*` and `@starter/l10n/promptAssembly` -— never from the root export (which pulls in React). - -## Data Flow: Stale Detection Pipeline - -``` -Source doc published (language == 'en-US') - │ - ▼ -mark-translations-stale (Function) - │ Finds translation.metadata for the doc - │ Sets all workflow states → 'stale' - │ Records staleSourceRev = published _rev - │ - ▼ -translation.metadata updated (stale count > 0) - │ - ▼ -analyze-stale-translations (Function) - │ 1. Guard: skip if valid cache exists for this staleSourceRev - │ 2. Fetch source doc ref from metadata - │ 3. Fetch historical doc (History API at sourceRevision) + current doc - │ 4. Compute field-level diff (computeFieldChanges) - │ 5. AI analysis via agent.action.prompt → StaleAnalysisResult - │ 6. Write analysis cache to metadata (phase 1) - │ 7. Pre-translate changed fields per stale locale (phase 2) - │ └── Batched by LOCALE_BATCH_SIZE=3, uses per-locale style guides - │ - ▼ -Editor reviews in Translation Inspector - │ Sees: explanation, materiality, per-field suggestions - │ Actions: apply pre-translation, retranslate, dismiss, skip -``` - -## Data Flow: Prompt Assembly Pipeline - -``` -Source document + target locale - │ - ▼ -extractDocumentText(document) Extract all human-readable text - │ - ▼ -filterGlossaryByContent(glossaries, doc) Prune to relevant terms - │ - ▼ -assembleStyleGuide(glossaries, locale, styleGuide?) - │ ├── buildGlossarySection() Approved / DNT / Forbidden terms - │ └── buildStyleGuideSection() Formality, tone, instructions - │ - ▼ -buildTranslateParams(options) - │ ├── assembleStyleGuide() → styleGuide string - │ ├── extractProtectedPhrases() → protectedPhrases array - │ └── measureStyleGuide() → warns if > 12,000 chars - │ - ▼ -Agent Actions Translate API call -``` - -## Schema Types - -| Type name | Kind | Key fields | Source | -| --------------------------- | -------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------- | -| `l10n.locale` | document | code (BCP-47), title, nativeName, fallback (ref) | `schemas/translationLocale.tsx` | -| `l10n.glossary` | document | title, sourceLocale (ref), entries[] | `schemas/translationGlossary.ts` | -| `l10n.glossary.entry` | object | term, status, doNotTranslate, partOfSpeech, definition, context, translations[] | `schemas/glossaryEntry.ts` | -| `l10n.style-guide` | document | title, locale (ref), formality, tone[], additionalInstructions (PT) | `schemas/translationStyleGuide.ts` | -| `l10n.locale.translation` | object | locale (ref), translation, gender | `schemas/localeTranslation.ts` | -| `fieldTranslation.metadata` | document | documentRef (weak ref), documentType, workflowStates[] (field, language, status, source, sourceSnapshot) | `schemas/fieldTranslationMetadata.ts` | - -## GROQ Queries - -| Export | Returns | Used by | -| ------------------------------ | ------------------------------------------------------ | ----------------------------------------- | -| `SUPPORTED_LANGUAGES_QUERY` | `{id, title}[]` — all locales, ordered by title | `LocalesContext` (single subscription) | -| `GLOSSARIES_QUERY` | Glossaries with resolved entries + locale translations | `GlossariesContext` (single subscription) | -| `STYLE_GUIDE_FOR_LOCALE_QUERY` | Style guide for a specific `$localeCode`, or null | Translation inspector, prompt assembly | - -## Data Flow: Field-Level Translation Workflow - -``` -useInternationalizedFields(documentType) - │ Schema walk — finds all internationalizedArray* fields - │ Returns InternationalizedFieldDescriptor[] - │ - ├──▶ useFieldTranslationData(documentId, fields, locales) - │ listenQuery (draft + published, i18n fields only) - │ Returns FieldTranslationSnapshot (matrix, sourceLanguages, currentSourceValues) - │ - ├──▶ useFieldWorkflowMetadata(documentId) - │ listenQuery for fieldTranslation.metadata - │ Returns stateMap keyed by "field::language" - │ - ▼ -deriveFieldCellStates(snapshot, stateMap, currentSourceValues) - │ Pure function: 6 derivation rules → FieldCellState matrix - │ - ├──▶ useStaleSyncEffect (debounced 500ms) - │ Persists newly-stale entries to metadata document - │ - └──▶ FieldTranslationContent (inspector UI) - ├── Summary bar: status counts + progress bar - ├── Matrix table: rows = fields, columns = locales - ├── StaleDiffPopover: click stale cell → diff + dismiss/retranslate - └── Action bar: translate missing, approve all - │ - └──▶ useFieldTranslateActions - Per-cell: translate(noWrite) → patch doc → patch metadata - Semaphore: max 5 concurrent, AbortController per cell -``` diff --git a/agentic-localization/skills/sanity-l10n/references/customization-guide.md b/agentic-localization/skills/sanity-l10n/references/customization-guide.md deleted file mode 100644 index ad5cb94..0000000 --- a/agentic-localization/skills/sanity-l10n/references/customization-guide.md +++ /dev/null @@ -1,314 +0,0 @@ -# Customization Guide - -## Glossary Customization - -### The 7-Field Anatomy - -Every glossary entry has 7 fields. Each one drives branching logic in -`buildGlossarySection()` — don't remove any. - -Read `packages/l10n/src/schemas/glossaryEntry.ts` for the schema definition and -`packages/l10n/src/promptAssembly.ts` for how each field is consumed. - -| Field | Type | Effect on prompt | -| ---------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------ | -| `term` | string (required) | The source-language term being defined | -| `status` | enum: approved / forbidden / provisional / non-standard | Controls which subsection the entry lands in (Approved Terms, Forbidden Terms) | -| `doNotTranslate` | boolean | Moves entry to "Do Not Translate" subsection; hides the translations array | -| `partOfSpeech` | enum: noun / verb / adjective / ... | Appended as metadata: "Studio (noun)" | -| `definition` | text | Adds a definition line: "Definition: ..." | -| `context` | string | Adds a usage context line: "Context: ..." | -| `translations` | array of `l10n.locale.translation` | Per-locale approved translations with optional gender | - -### Designing for Quality Deltas - -The strongest glossary entries are brand names that look like common English -words. These create measurable quality differences because models translate them -as generic terms without explicit guidance. - -**Strong entries** (high delta): - -- "Releases" — looks like a generic English noun, but it's a Sanity product name -- "Perspectives" — same pattern -- "Portable Text" — looks like a description, but it's a proper noun (DNT) -- "Content Lake" — compound term that gets split and translated without guidance - -**Weak entries** (low delta): - -- "Dashboard" — generic tech term, models handle it correctly without help -- "Workspace" — same -- "API" — universally understood acronym - -Read `packages/l10n/evals/fixtures.ts` for the example entries and -`packages/l10n/evals/` for how deltas are measured. - -### Adapting to Your Domain - -1. **Audit your terminology** — List brand names, product features, and internal - terms that look like common English. These are your high-value entries. -2. **Add DNT entries** for terms that must stay in the source language across all - locales (product names, feature names). -3. **Add forbidden entries** for terms you never want in output (e.g., "CMS", - "headless CMS" if you prefer "content platform"). -4. **Add approved translations** for terms that have specific translations per - locale (e.g., a feature name that has an official German equivalent). -5. **Test with evals** — translate with and without your glossary, measure the - delta. If the delta is near zero, the entries aren't adding value. - -### `shouldNotContain` Gotcha - -When writing eval expectations, don't block common target-language words that -appear naturally in translation. For example, "Veröffentlichungen" (German for -"publications") appears naturally when translating "Coordinate launches" — even -though the product name "Releases" was correctly preserved elsewhere in the same -text. Only block terms that would ONLY appear as a mistranslation. - -## Style Guide Customization - -Style guides are per-locale documents with three components. Read -`packages/l10n/src/schemas/translationStyleGuide.ts` for the schema. - -### Formality - -Enum: `formal`, `informal`, `casual`. Maps to a line in the assembled prompt: -"Formality: Use {level} register." - -### Tone - -Array of 1–5 adjectives (e.g., "professional", "approachable", "concise"). -Formatted as: "Tone: professional, approachable, concise." - -### Additional Instructions - -Free-form Portable Text (bold/italic/code decorators only). This is where you -put locale-specific rules that don't fit formality or tone: - -- "Use Markdown-style backticks for UI element names" -- "Address the reader with 'vous' (formal you)" -- "Prefer shorter sentences for Japanese readability" - -### Per-Locale Targeting - -Style guides are linked to a specific `l10n.locale` document via the `locale` -reference field. The query `STYLE_GUIDE_FOR_LOCALE_QUERY` fetches the guide -matching the target locale code. Create one style guide per locale that needs -specific treatment. - -Read `packages/l10n/evals/fixtures.ts` for example style guides (DE formal + -precise, FR formal + elegant, JA formal + concise). - -## Adding Localized Content Types - -### Step by Step - -1. **Define the schema type** in `studio/schemaTypes/` — standard Sanity - document type. Don't add a `language` field manually; the plugin injects it. - -2. **Register it** — add the type name to `localizedSchemaTypes` in - `studio/sanity.config.ts`: - - ```ts - const l10n = createL10n({localizedSchemaTypes: ['article', 'tag', 'yourNewType']}) - ``` - -3. **Deploy schema** — required for Agent Actions: - - ```sh - cd studio && pnpm exec sanity schema deploy - ``` - -4. **Update function filters** — if the new type should trigger stale detection, - update the event filter in `sanity.blueprint.ts`: - - ```ts - filter: "_type in ['article', 'yourNewType'] && language == 'en-US'" - ``` - -5. **Redeploy functions**: - ```sh - pnpm exec sanity blueprints deploy - ``` - -### What `localizedSchemaTypes` Does - -Only types listed here get: - -- The injected `language` field (via `injectLanguageField`) -- Translation metadata tracking -- The Translation Pane and Inspector UI -- Locale-scoped document lists (via `withLocaleFilter`) - -## Functions and Blueprint Customization - -### The Two Functions - -Read the source files directly for the full implementation: - -**`functions/mark-translations-stale.ts`** - -- Triggers on: document publish events -- Default filter: `_type == 'article' && language == 'en-US'` -- Action: finds `translation.metadata` for the doc, sets all workflow states to - `stale`, records `staleSourceRev` -- Timeout: 15 seconds - -**`functions/analyze-stale-translations.ts`** - -- Triggers on: `translation.metadata` updates where stale count > 0 -- Action: 7-step pipeline (history fetch → field diff → AI analysis → cache → - pre-translate per locale) -- Timeout: 120 seconds, 1GB memory -- Batches locale translations in groups of 3 - -### Modifying Function Filters - -Both functions define their trigger in `sanity.blueprint.ts` via the `event` -property. To add a new content type to stale detection: - -1. Update the `filter` string in the `mark-translations-stale` resource -2. The `analyze-stale-translations` function doesn't need a filter change — it - triggers on any `translation.metadata` update with stale entries - -### Environment Variables - -Functions access env vars defined in the blueprint's `env` property. The -blueprint loads from the root `.env.local` file. Key vars: - -- `SANITY_STUDIO_PROJECT_ID` — project ID (required) -- `SANITY_STUDIO_DATASET` / `BLUEPRINT_DATASET` — dataset name -- Robot token is provisioned as a blueprint resource and injected automatically - -### Blueprint Env Loading Gotcha - -The blueprint file is loaded by jiti (not Node.js directly). -`process.loadEnvFile()` silently succeeds but doesn't set vars in jiti context. -The blueprint uses `readFileSync` + manual parsing instead. See the top of -`sanity.blueprint.ts`. - -## Field-Level Workflow Customization - -### Adding Field-Level Types - -The `internationalizedArray` plugin is configured inside `createL10n()` in -`packages/l10n/src/plugin.ts`: - -```ts -internationalizedArray({ - languages: (client) => - client.fetch(SUPPORTED_LANGUAGES_QUERY, {}, {tag: 'plugin.languages'}), - defaultLanguages: [defaultLanguage], - fieldTypes: ['string', 'text'], -}) -``` - -### Request Tags - -The starter sets `requestTagPrefix: 'kit.agentic-l10n'` on every -`createClient({...})` and adds per-call `tag: '.'` options -(e.g. `tag: 'translate.style-guide'`), producing combined tags like -`kit.agentic-l10n.translate.style-guide` — handy for filtering your own -request logs. Keep this scheme when extending, or change `requestTagPrefix` in -your client config to use whatever tagging scheme you prefer. See -[Request tags](https://www.sanity.io/docs/apis-and-sdks/js-client-request-tags). - -To support additional value types (e.g., `blockContent`), add them to the -`fieldTypes` array. Then use `internationalizedArrayBlockContent` as the field -type in your schema. - -### Customizing the Publish Gate - -`createFieldTranslationPublishGate` in -`packages/l10n/src/translations/useFieldTranslationPublishGate.ts` wraps -PublishAction and disables it when `needsReview` or `stale` entries exist. - -It's wired in `plugin.ts` via the `document.actions` callback — it wraps any -action with `action === 'publish'` for types NOT in `localizedSchemaTypes` -(those use document-level translation instead). - -To modify gating rules: - -- **Change which statuses block publish** — edit the `hasUnresolved` check in - the gate function (e.g., only block on `stale`, allow `needsReview` through) -- **Add a force-publish override** — check the user's role before returning - `disabled: true`, or add a confirmation dialog -- **Remove the gate entirely** — remove the `document.actions` callback in - `plugin.ts` - -### Customizing Concurrency - -Translation API calls are limited to `MAX_CONCURRENT = 5` concurrent requests -in `packages/l10n/src/translations/useFieldTranslateActions.ts`. - -Lower this value if you're hitting rate limits. Raise it if you have higher API -quotas and want faster bulk operations. The constant is at the top of the file. - -### Customizing Stale Detection - -Stale detection compares `sourceSnapshot` (stored at translation time) against -the current source value using `JSON.stringify` equality. This runs client-side -in `deriveFieldCellStates()` — it only fires when the inspector is open. - -The `useStaleSyncEffect` debounces metadata writes at 500ms to avoid excessive -writes during rapid source edits. To adjust: - -- **Debounce interval** — change the `500` timeout in `useStaleSyncEffect.ts` -- **Comparison granularity** — the `JSON.stringify` comparison is exact. For - more lenient comparison (e.g., ignoring whitespace changes), modify the - `isSourceChanged` check in `deriveFieldCellStates.ts` - -## Eval Framework - -### Two Test Suites - -The l10n package has two vitest configs: - -- `vitest.config.ts` — unit tests (`*.test.ts`): schema validation, prompt - assembly, locale utilities. Fast, no network. -- `vitest.eval.config.ts` — model evals (`*.eval.ts`): translate via Agent - Actions API, score results. Slow, requires auth, consumes AI credits. - -### Writing a New Eval Case - -An `EvalCase` defines a translation scenario. Read -`packages/l10n/evals/types.ts` for the type and existing eval files for -examples. - -```ts -const myCase: EvalCase = { - id: 'my-case', - description: 'What this tests', - sourceText: 'The English text to translate', - sourceLocale: enUS, - targetLocale: deDE, - glossaries: [techGlossary], // from fixtures.ts - styleGuide: deDEStyleGuide, // from fixtures.ts - expectations: { - shouldContain: ['expected term'], // must appear in output - shouldNotContain: ['bad term'], // must NOT appear - shouldMatchPattern: [/regex/i], // pattern match - description: 'Criteria for the LLM judge', - }, - baselineRisks: ['What goes wrong without context'], -} -``` - -### Two-Layer Scoring - -1. **Deterministic** (`scoring.ts`): `checkTermPresence`, `checkTermAbsence`, - `checkPatterns` — binary pass/fail per check. -2. **LLM judge** (`judge.ts`): 4 quality dimensions with weights, averaged over - 3 trials to reduce variance. - -Combined pass criteria: `deterministic.pass AND judge.overall >= 3.5`. - -### Fixture Design Lessons - -- **sourceText must match fieldPath** — the judge compares sourceText against - the translated field. Mismatch causes low scores even when translation is - correct. -- **Japanese DNT delta is near zero** — the Translate API already preserves - English product names in Latin script for JA. French and German glossary evals - show stronger deltas (+1.2 to +1.55). -- **Generic tech terms don't differentiate** — "Dashboard" and "Workspace" - translate correctly without glossaries. Use Sanity-specific product names that - LOOK like generic English. diff --git a/agentic-localization/skills/sanity-l10n/references/field-level-patterns.md b/agentic-localization/skills/sanity-l10n/references/field-level-patterns.md deleted file mode 100644 index 8c414bb..0000000 --- a/agentic-localization/skills/sanity-l10n/references/field-level-patterns.md +++ /dev/null @@ -1,305 +0,0 @@ -# Field-Level Translation Patterns - -## Document-Level vs Field-Level Comparison - -This starter uses two complementary translation architectures: - -| Aspect | Document-level | Field-level | -| --------------- | -------------------------------------------------------------- | -------------------------------------------------------------- | -| Plugin | `@sanity/document-internationalization` | `sanity-plugin-internationalized-array` | -| Storage | Separate document per locale (e.g., `article__i18n_es-MX`) | Inline array entries on the same document | -| Metadata doc | `translation.metadata` | `fieldTranslation.metadata` | -| Workflow states | `missing`, `usingFallback`, `needsReview`, `approved`, `stale` | `missing`, `needsReview`, `approved`, `stale` | -| Stale detection | Server-side via Sanity Functions | Client-side via `deriveFieldCellStates` + `useStaleSyncEffect` | -| Publish gate | None (separate docs) | `createFieldTranslationPublishGate` wraps PublishAction | -| Inspector UI | Translation pane (per-locale document list) | Field x locale matrix (FieldTranslationContent) | -| Use case | Full document translation (articles, pages) | Per-field translation (bios, descriptions, taglines) | - -**When to use which**: Use document-level when the entire document is translated -as a unit (articles, blog posts). Use field-level when only specific fields need -translation while the document itself is language-agnostic (person profiles, -product records with a translatable description field). - -## Data Flow - -``` -Schema walk (useInternationalizedFields) - │ Recursively finds all internationalizedArray* fields - │ Returns InternationalizedFieldDescriptor[] (path, depth, valueType) - │ - ▼ -useFieldTranslationData(documentId, fields, locales) - │ listenQuery for draft+published, projects only i18n fields - │ Client-side coalesce (draft preferred over published) - │ Derives: matrix (field×locale → filled/empty), sourceLanguages, currentSourceValues - │ Returns: FieldTranslationSnapshot - │ - ▼ -useFieldWorkflowMetadata(documentId) - │ listenQuery for fieldTranslation.metadata document - │ Returns: states[], stateMap (keyed by field::language), metadataId - │ - ▼ -deriveFieldCellStates(snapshot, stateMap, currentSourceValues) - │ Pure function: merges doc snapshot + metadata → FieldCellState matrix - │ Applies the 6 derivation rules (see below) - │ - ├─▶ useStaleSyncEffect(cellStates, stateMap, metadataId, ...) - │ Debounced (500ms) — persists newly-stale entries to metadata - │ - └─▶ FieldTranslationContent (inspector UI) - │ Renders summary bar, matrix table, action bar - │ - ▼ - useFieldTranslateActions(snapshot, schemaId, documentType, cellStates) - Translate, approve, dismiss actions with semaphore concurrency -``` - -## The 6 Derivation Rules - -`deriveFieldCellStates()` in -`packages/l10n/src/translations/deriveFieldCellStates.ts` is a pure function -that merges document state (filled/empty) with metadata workflow state into a -`FieldCellState` matrix. The rules: - -| # | Condition | Result | Rationale | -| --- | ------------------------------------------------------------------ | --------------------- | --------------------------------------------------------- | -| 1 | No array entry for this locale | `missing` | Translation doesn't exist yet | -| 2 | Entry exists, no metadata | `approved` (implicit) | Manual/pre-existing content — no workflow tracking needed | -| 3 | Entry exists, metadata `needsReview`, source unchanged | `needsReview` | AI translated but not yet reviewed | -| 4 | Entry exists, metadata `needsReview` or `approved`, source changed | `stale` | Source content changed since translation was done | -| 5 | Entry exists, metadata `stale` | `stale` | Already marked stale (persisted) | -| 6 | Entry exists, metadata `approved`, source unchanged | `approved` | Reviewed and source hasn't changed | - -**Source locale** is always implicitly `approved` (skipped from derivation). - -**Staleness detection** compares `meta.sourceSnapshot` (JSON.stringify of source -value at translation time) against the current source value. If they differ, the -cell is stale regardless of its metadata status. - -The test suite in `deriveFieldCellStates.test.ts` covers all 6 rules plus edge -cases (multiple fields, missing sourceSnapshot). - -## Key Hooks API - -### `useInternationalizedFields(documentType)` - -**Purpose**: Schema walk — discovers all `internationalizedArray*` fields. - -**File**: `packages/l10n/src/fieldActions/useInternationalizedFields.ts` - -**Pattern**: `useMemo` keyed on `documentType` — walks `useSchema()` once per -type. Recursively descends into object fields and array members. Fields inside -arrays get `depth: -1` (excluded from bulk translate). - -**When to use**: Auto-detection of which fields need the translation inspector. -The inspector only renders when this returns a non-empty array. - -### `useFieldTranslationData(documentId, fields, locales)` - -**Purpose**: Realtime field x locale matrix from inline array values. - -**File**: `packages/l10n/src/translations/useFieldTranslationData.ts` - -**Pattern**: `documentStore.listenQuery()` for both draft and published docs with -a focused GROQ projection (only i18n fields). Client-side coalesces -draft-over-published. Returns `FieldTranslationSnapshot` with matrix, source -languages, and current source values. - -**When to use**: The snapshot is the foundational input for `deriveFieldCellStates` -and `useFieldTranslateActions`. Always consumed via `FieldTranslationContent`. - -### `useFieldWorkflowMetadata(documentId)` - -**Purpose**: Realtime subscription to `fieldTranslation.metadata` workflow states. - -**File**: `packages/l10n/src/translations/useFieldWorkflowMetadata.ts` - -**Pattern**: `documentStore.listenQuery()` for the metadata document. Returns -raw `states[]` array and pre-computed `stateMap` keyed by `field::language` for -O(1) lookups. - -**When to use**: Paired with `deriveFieldCellStates` in the inspector. Also used -by `createFieldTranslationPublishGate` to count unresolved entries. - -### `useFieldTranslateActions(snapshot, schemaId, documentType, cellStates)` - -**Purpose**: Translation orchestration — translate, approve, dismiss stale. - -**File**: `packages/l10n/src/translations/useFieldTranslateActions.ts` - -**Pattern**: `useReducer` for per-cell in-flight state, `useTransition` for -`isTranslating`, promise-based semaphore for max concurrency, AbortController for -cancellation. Returns `translateCell`, `translateField`, `translateLocale`, -`translateAllEmpty`, `approveCell`, `approveAll`, `dismissStaleCell`. - -**When to use**: Consumed by `FieldTranslationContent` for all user actions in the -matrix UI. - -### `useStaleSyncEffect(cellStates, stateMap, metadataId, currentSourceValues)` - -**Purpose**: Debounced lazy persistence of newly-stale entries. - -**File**: `packages/l10n/src/translations/useStaleSyncEffect.ts` - -**Pattern**: When `deriveFieldCellStates` detects entries that are stale -client-side but not yet persisted to metadata, this effect batch-patches them -after a 500ms debounce. - -**When to use**: Always mounted inside `FieldTranslationContent`. Runs -automatically — no manual invocation. - -### `useLocales()` - -**Purpose**: Realtime subscription to supported languages (`l10n.locale` docs). - -**File**: `packages/l10n/src/translations/useLocales.ts` - -**Pattern**: Thin wrapper over `useLocalesContext()` from `contexts/LocalesContext.tsx`. -The actual `listenQuery(SUPPORTED_LANGUAGES_QUERY)` subscription lives in `LocalesProvider`, -mounted once at the plugin's `studio.components.layout` level via `L10nProvider`. -All consumers share a single EventSource connection. Returns `Language[] | undefined` -(`undefined` while loading). - -**When to use**: Consumed by `FieldTranslationContent` for column headers, by -`useTranslateFieldAction` for per-locale sub-actions, by `LocaleNavbar` for the -locale filter, and by `LanguageInput` for the locale picker. - -## Translation Pipeline (per-cell) - -Each cell translation in `useFieldTranslateActions.processCell()` follows a -3-step process: - -### Step 1: Translate with `noWrite: true` - -```ts -const translated = await translate( - { - schemaId, - documentId: actionDocumentId, - fromLanguage: {id: sourceLocaleId}, - toLanguage: {id: locale.id, title: locale.title}, - target: {path: [...field.path, {_key: sourceEntry._key}, 'value']}, - noWrite: true, - }, - doc, -) -``` - -**Why `noWrite`**: The Agent Actions Translate API reads the document from the -Content Lake. If we had already patched in a new array entry and then called -translate without `noWrite`, the API might not see the entry due to -replication delay — the just-committed mutation may not have propagated to the -read replica yet. Using `noWrite` avoids this race: the API translates against -the source document snapshot we provide, and returns the translated document -without writing. - -### Step 2: Patch document - -```ts -client - .patch(actionDocumentId) - .setIfMissing({[fieldName]: []}) - .unset([`${fieldName}[language=="${locale.id}"]`]) - .append(fieldName, [ - {_key: entryKey, _type: itemType, language: locale.id, value: translatedEntry.value}, - ]) - .commit() -``` - -The `setIfMissing` + `unset` + `append` pattern ensures idempotency — if an -entry for this locale already exists, it's replaced. - -### Step 3: Patch metadata - -```ts -tx.createIfNotExists({_id: metadataId, _type: 'fieldTranslation.metadata', ...}) -tx.patch(metadataId, (p) => - p.setIfMissing({workflowStates: []}) - .unset([`workflowStates[_key=="bio--fr-FR"]`]) - .append('workflowStates', [{ - _key: 'bio--fr-FR', - field: 'bio', - language: 'fr-FR', - status: 'needsReview', - source: 'ai', - updatedAt: new Date().toISOString(), - sourceSnapshot: JSON.stringify(sourceEntry.value), - }]) -) -``` - -The `sourceSnapshot` is critical — it records the exact source value at -translation time so `deriveFieldCellStates` can detect staleness later when -the source changes. - -## Publish Gate - -`createFieldTranslationPublishGate` in -`packages/l10n/src/translations/useFieldTranslationPublishGate.ts` wraps any -`DocumentActionComponent` (typically PublishAction). - -**How it works**: - -1. Renders the wrapped action normally -2. Subscribes to `useFieldWorkflowMetadata` for the document -3. Counts `needsReview` and `stale` entries -4. If any unresolved entries exist, sets `disabled: true` with a tooltip - explaining what needs attention - -**Where it's wired**: In `plugin.ts`, the `document.actions` callback maps over -the default actions and wraps any action with `action === 'publish'`. It only -applies to document types NOT in `localizedSchemaTypes` (i.e., types that use -field-level, not document-level, translation). - -**Customization**: To add a force-publish escape hatch, modify the gate function -to check a condition (e.g., user role) before returning `disabled: true`. - -## Concurrency Control - -`useFieldTranslateActions` uses a `createSemaphore(5)` to limit concurrent -translation API calls. Each cell gets its own `AbortController` for cancellation -on unmount. - -**File**: `packages/l10n/src/translations/createSemaphore.ts` - -The `MAX_CONCURRENT = 5` constant is defined at the top of -`useFieldTranslateActions.ts`. Reducing this value reduces API pressure but -slows bulk "translate all" operations. - -## Field Actions (AI Assist Integration) - -`useTranslateFieldAction` in `packages/l10n/src/fieldActions/useTranslateFieldAction.ts` -wires into `@sanity/assist`'s field action system. For each -`internationalizedArray*` field, it creates a "Translate" action group with -per-locale sub-actions ("Translate to French", "Translate to German", etc.). - -This is separate from the bulk inspector UI — it provides inline translate -actions directly on each field in the document form. It uses the same `noWrite` -pattern as `useFieldTranslateActions.processCell()` but does not track workflow -metadata (no `needsReview` state). It's a quick-translate convenience for editors -working directly in the form. - -## Metadata Schema - -The `fieldTranslation.metadata` schema -(`packages/l10n/src/schemas/fieldTranslationMetadata.ts`) has these properties: - -- **`liveEdit: true`** — patches write directly to published (no draft/publish - cycle). This is essential because metadata updates happen frequently during - translation workflows. -- **`hidden: true`** — not visible in desk structure. Internal document only. -- **Deterministic ID**: `fieldTranslation.metadata.` via - `getFieldTranslationMetadataId()` in `packages/l10n/src/core/fieldMetadataIds.ts`. - Never create these documents manually. - -## Key Type Definitions - -From `packages/l10n/src/core/types.ts`: - -- **`FieldWorkflowStateEntry`** — a single entry in the metadata - `workflowStates` array: `field`, `language`, `status`, `source`, `updatedAt`, - `reviewedBy`, `sourceSnapshot` -- **`FieldCellState`** — merged state for one cell in the matrix: `status` - (`missing` | `needsReview` | `approved` | `stale`), plus optional `source`, - `sourceSnapshot`, `reviewedBy`, `updatedAt` diff --git a/agentic-localization/skills/sanity-l10n/references/troubleshooting.md b/agentic-localization/skills/sanity-l10n/references/troubleshooting.md deleted file mode 100644 index fe3fdcb..0000000 --- a/agentic-localization/skills/sanity-l10n/references/troubleshooting.md +++ /dev/null @@ -1,182 +0,0 @@ -# Troubleshooting - -## Agent Actions Errors - -### "Schema not found" or empty translations - -Agent Actions requires a deployed schema. Deploy it: - -```sh -cd studio && pnpm exec sanity schema deploy -``` - -The schema ID is `_.schemas.default` (derived from the workspace name in -`sanity.config.ts`). If you renamed the workspace, the schema ID changes. - -### Auth token not resolved - -`getCliClient` from `sanity/cli` does NOT resolve auth tokens outside the CLI -process. Its `__internal__getToken` defaults to `() => undefined`. - -For evals and scripts, use the helper at `packages/l10n/evals/authToken.ts`: - -1. Checks `SANITY_AUTH_TOKEN` env var -2. Falls back to `ConfigStore('sanity')` (reads from `~/.config/sanity/`) - -For functions, the robot token is provisioned by the blueprint and injected -automatically — no manual token handling needed. - -### Style guide too large - -`measureStyleGuide()` warns when the assembled style guide exceeds 12,000 -characters (~3,000 tokens). The Agent Actions API has a soft limit on style -guide size. - -To reduce size: - -- Use `filterGlossaryByContent()` to prune irrelevant terms -- Keep `additionalInstructions` concise -- Split large glossaries by domain — only pass the relevant one - -## Schema Errors - -### "SchemaError: Unknown type" - -`localizedSchemaTypes` in `studio/sanity.config.ts` must only list types that -actually exist in `studio/schemaTypes/`. Referencing a nonexistent type causes a -SchemaError during `sanity schema deploy` and `sanity dev`. - -### Type name conflicts - -Don't define l10n schema types manually — the plugin registers `l10n.locale`, -`l10n.glossary`, `l10n.style-guide`, etc. via `createL10n()`. Defining them -again in `studio/schemaTypes/` causes duplicate type errors. - -## Eval Failures - -### Low scores despite correct translation - -The judge compares `sourceText` against the translated field content. If -`sourceText` in the eval case doesn't match what was actually written to the -document's field, scores will be artificially low. Make sure the eval fixture's -`sourceText` matches the field being translated. - -### Anthropic API schema errors - -Zod schemas with `.int().min().max()` produce `minimum`/`maximum` on `integer` -type, which the Anthropic API rejects. Use `.number()` with range described in -`.describe()` instead. - -### Judge variance - -The LLM judge is averaged over 3 trials (`JUDGE_TRIALS = 3`) to reduce -variance. If scores fluctuate, check that `expectations.description` gives the -judge clear, objective criteria — vague descriptions produce inconsistent scores. - -## Intl API Quirks - -### `Intl.DisplayNames` output - -`Intl.DisplayNames('en').of('en-US')` returns "American English", not -"English (US)". The locale resolution in `resolveLocaleDefaults()` accounts for -this. - -### Plural categories vary by locale - -`Intl.PluralRules('fr-FR')` returns 3 categories (one, other, many), not 2. -The `pluralize()` utility in the plugin handles this correctly. - -### BCP-47 validation - -`isValidLocale()` uses the `Intl.Locale` constructor. Invalid codes throw — the -schema validation in `translationLocale.tsx` catches this. - -## Field-Level Translation Issues - -### Publish blocked but translations look fine - -Stale metadata may be out of sync with actual document content. The publish -gate reads from `fieldTranslation.metadata`, not from the document itself. - -Check the metadata in Vision: - -```groq -*[_id == "fieldTranslation.metadata."][0]{ - workflowStates[]{field, language, status, sourceSnapshot} -} -``` - -If entries show `needsReview` or `stale` but the translations are correct, -either approve them via the inspector or patch the metadata to `approved`. - -### Fields not appearing in matrix - -The field must use an `internationalizedArray*` type (e.g., -`internationalizedArrayText`, `internationalizedArrayString`). Regular `string` -or `text` fields are not detected. - -Also, fields inside array-of-objects (`depth: -1`) are detected but excluded -from the inspector's bulk translate UI. Only top-level and object-nested fields -appear. - -### Stale detection not working - -Stale detection is **client-side only** — it runs in `deriveFieldCellStates()` -when the inspector is open. If nobody opens the inspector after a source edit, -staleness won't be detected or persisted. - -The comparison uses `JSON.stringify` of the source locale's value. If the -metadata entry has no `sourceSnapshot` (e.g., pre-existing content before the -workflow was added), stale detection is skipped for that entry. - -### "No source content" error - -The source language is the first non-empty entry in the internationalized array. -If no entry has a value, there's nothing to translate from. Fill at least one -locale's value first. - -### Metadata document not created - -`fieldTranslation.metadata` uses `liveEdit: true` — patches write directly -without a draft/publish cycle. This requires the user to have write permission -on the dataset. If the user only has draft-level permissions, metadata creation -will fail silently. - -The metadata document is created via `createIfNotExists` in -`useFieldTranslateActions` — it's created on first translate or approve action, -not on inspector open. - -## Functions Issues - -### Dependencies not found at runtime - -Sanity Functions use Vite to bundle. The transpiler resolves from the nearest -`node_modules/` walking up from the function directory. Runtime deps -(`@sanity/client`, `@sanity/functions`, `groq`) and workspace packages -(`@starter/l10n`) must be in the root `package.json` devDeps. - -Workspace packages resolve via pnpm symlinks and get INLINED by Vite (the -resolved path doesn't match the `/node_modules/` external pattern). This is -expected — don't add a function-level `package.json`. - -### Env vars not loading in blueprint - -The blueprint file is loaded by jiti, not Node.js directly. -`process.loadEnvFile()` silently succeeds but doesn't actually set env vars in -the jiti context. The blueprint uses `readFileSync` + manual line-by-line -parsing. See the top of `sanity.blueprint.ts`. - -`import.meta.dirname` IS synthesized correctly by jiti. `process.cwd()` -reflects the pnpm filter's cwd, NOT the blueprint file's directory. - -### Functions CLI location - -The CLI finds the blueprint by walking UP from cwd. Run function commands from -the repo root: - -```sh -pnpm exec sanity functions test --project-id X --dataset Y -``` - -`sanity.config.ts` is NOT required for functions/blueprints — `resolveRootDir` -falls back to cwd. diff --git a/ai-shopping-assistant/CLAUDE.md b/ai-shopping-assistant/CLAUDE.md index 8c69cff..f7fa7df 100644 --- a/ai-shopping-assistant/CLAUDE.md +++ b/ai-shopping-assistant/CLAUDE.md @@ -61,5 +61,4 @@ Two main directories: `app/` (Next.js frontend) and `studio/` (Sanity Studio). T - `studio/agent-insights-tool/` - Custom Studio tool for viewing chat analytics - `functions/agent-conversation/` - Sanity Function for auto-classifying conversations - `sanity.blueprint.ts` - Function triggers (delta filters) -- `skills/add-sanity-chatbot/` - Claude Code skill for adding chatbot to existing projects - `studio/seed/` - Sample dataset for import diff --git a/ai-shopping-assistant/README.md b/ai-shopping-assistant/README.md index 81f1609..1c0f712 100644 --- a/ai-shopping-assistant/README.md +++ b/ai-shopping-assistant/README.md @@ -27,7 +27,6 @@ An ecommerce storefront with an AI shopping assistant that operates directly on - **Next.js storefront**: Product listing, filtering, detail pages, and a floating chat widget - **The Sanity Studio**: Content management with product schemas, agent configuration, and an insights dashboard - **AI shopping assistant**: Claude-powered chatbot that queries the Content Lake to search products, answer questions, and apply filters -- **Claude Code skill**: A reusable skill for adding the chatbot to your own existing projects ## Prerequisites @@ -118,8 +117,6 @@ ai-shopping-assistant/ ├── functions/ │ └── agent-conversation/ # Sanity Function for auto-classifying chats ├── sanity.blueprint.ts # Function triggers (delta filters) -├── skills/ -│ └── add-sanity-chatbot/ # Claude Code skill for adding chatbot to other projects ├── package.json # Root workspace scripts ├── pnpm-workspace.yaml # pnpm workspace config └── CLAUDE.md # AI assistant context for this project @@ -216,24 +213,6 @@ A custom Studio tool that provides an analytics dashboard for monitoring chatbot | `SANITY_AGENT_CONFIG_SLUG` | No | Slug of the Agent Config document in Studio. Defaults to `default` | | `ANTHROPIC_API_KEY` | Yes | Your Anthropic API key from [console.anthropic.com](https://console.anthropic.com) | -## Adding a Chatbot to Your Own Project - -Already have a Next.js + Sanity project? Use the included Claude Code skill to add the AI chatbot to your site. It walks you through dependencies, API route, chat UI components, and Studio plugin setup. - -Install the skill directly from GitHub: - -```bash -npx skills add https://github.com/sanity-labs/starters/tree/main/ai-shopping-assistant --skill add-sanity-chatbot -``` - -Or, if you've cloned this repo locally: - -```bash -npx skills add ./skills/add-sanity-chatbot -``` - -See [`skills/add-sanity-chatbot/SKILL.md`](skills/add-sanity-chatbot/SKILL.md) for the full workflow and reference docs. - ## Learn More - [Sanity Context docs](https://www.sanity.io/docs/ai/agent-context) diff --git a/ai-shopping-assistant/_index.md b/ai-shopping-assistant/_index.md index c3a340d..5ea12e8 100644 --- a/ai-shopping-assistant/_index.md +++ b/ai-shopping-assistant/_index.md @@ -109,16 +109,6 @@ app/src/app/ └── [slug]/page.tsx # Product detail page ``` -### Skills - -``` -skills/add-sanity-chatbot/ -├── SKILL.md # Skill definition and workflow -└── references/ - ├── chat-implementation.md # Chat UI and API route reference - └── studio-setup.md # Studio plugin setup reference -``` - ## Key Patterns ### MCP Connection diff --git a/ai-shopping-assistant/skills/add-sanity-chatbot/SKILL.md b/ai-shopping-assistant/skills/add-sanity-chatbot/SKILL.md deleted file mode 100644 index 4380d17..0000000 --- a/ai-shopping-assistant/skills/add-sanity-chatbot/SKILL.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -name: add-sanity-chatbot -description: Add an AI chatbot that operates on your Content Lake to an existing Next.js + Sanity project. Use when adding a chat assistant to a site that already has the Studio and a Next.js frontend. Covers dependency installation, API route setup, chat UI components, Studio plugin configuration, and system prompt design. ---- - -# Add an AI Chatbot That Operates on Your Content - -Add an AI chatbot to your existing Next.js + Sanity project. The chatbot connects to the Content Lake via the Sanity Context MCP server, giving the LLM structured, schema-aware access to your content. It can answer questions, run GROQ queries, and reason over your data, not just match keywords. - -**What this gives you:** - -- A chat widget in your Next.js app connected to an LLM -- Schema-aware content access: the agent understands your content model, not just text similarity -- Semantic search layered on top of structural GROQ queries against the Content Lake -- Client-side tools for page context and screenshots - -## Prerequisites - -Before starting, confirm: - -1. **Existing Next.js app** (App Router) with a working frontend -2. **Existing Studio** (v5.1.0+), either embedded or separate -3. **Sanity project credentials** available - -Gather these credentials: - -| Credential | Where to get it | -| ------------------------- | ------------------------------------------------------------------------------- | -| **Sanity Project ID** | Your `sanity.config.ts` or [sanity.io/manage](https://sanity.io/manage) | -| **Dataset name** | Usually `production`. Check your `sanity.config.ts` | -| **Sanity API read token** | [sanity.io/manage](https://sanity.io/manage) -> Project -> API -> Tokens | -| **Anthropic API key** | From [console.anthropic.com](https://console.anthropic.com) (or other provider) | - -## Workflow - -### Step 1: Set Up Sanity Context in Studio - -Install the plugin and create a Sanity Context document to scope what content the chatbot can access. - -See [references/studio-setup.md](references/studio-setup.md) - -### Step 2: Install Dependencies in Your Next.js App - -**IMPORTANT: Do NOT guess package versions.** AI SDK packages update frequently. Always check the versions below or run `npm info version`. - -```bash -npm install @ai-sdk/anthropic@^3.0.23 @ai-sdk/mcp@^1.0.13 @ai-sdk/react@^3.0.52 ai@^6.0.50 zod@^4.3.6 -``` - -Optional dependencies for advanced features (page context capture, screenshots): - -```bash -npm install turndown html2canvas-pro lucide-react -npm install -D @types/turndown -``` - -**Version reference** (from the working ecommerce example): - -| Package | Version | Notes | -| ------------------- | -------- | ------------------------------------ | -| `@ai-sdk/anthropic` | ^3.0.23 | Anthropic provider for Vercel AI SDK | -| `@ai-sdk/mcp` | ^1.0.13 | MCP client for tool discovery | -| `@ai-sdk/react` | ^3.0.52 | React hooks (`useChat`) | -| `ai` | ^6.0.50 | Core Vercel AI SDK | -| `zod` | ^4.3.6 | Schema validation for tool inputs | -| `turndown` | ^7.2.2 | HTML-to-markdown for page context | -| `html2canvas-pro` | ^1.6.6 | Screenshot capture | -| `lucide-react` | ^0.563.0 | Icons for chat UI | - -### Step 3: Set Up Environment Variables - -Add to your `.env.local`: - -```bash -# Sanity Configuration (you may already have these) -NEXT_PUBLIC_SANITY_PROJECT_ID=your-project-id -NEXT_PUBLIC_SANITY_DATASET=production - -# Sanity API token with read access -SANITY_API_READ_TOKEN=your-read-token - -# Sanity Context slug (optional, defaults to "default") -# SANITY_CONTEXT_SLUG=default - -# LLM API key -ANTHROPIC_API_KEY=your-anthropic-key -``` - -The MCP URL is constructed automatically from your project ID, dataset, and the optional `SANITY_CONTEXT_SLUG` (defaults to `default`). - -### Step 4: Create the Chat Implementation - -Create the API route and chat UI components. - -See [references/chat-implementation.md](references/chat-implementation.md) - -### Step 5: Test the Integration - -1. Start your dev server: `npm run dev` -2. Open your app and interact with the chat widget -3. The agent should call `initial_context` first to understand your content types -4. Try asking: "What content do you have access to?" - -You can also test the API route directly: - -```bash -curl -X POST http://localhost:3000/api/chat \ - -H "Content-Type: application/json" \ - -d '{"messages": [{"role": "user", "content": "What content do you have access to?"}]}' -``` - -### Step 6: Customize the System Prompt - -The system prompt shapes how your chatbot behaves. Define it inline in the API route or store it in a Sanity document for easy editing. - -**Basic inline prompt:** - -```ts -const SYSTEM_PROMPT = ` -You are a helpful assistant for this website. - -## Your Capabilities -- Search and retrieve content using the available tools -- Answer questions about the site's content -- Help users find what they're looking for - -## How to Respond -- Be concise and helpful -- When referencing content, include relevant details -- If you can't find what the user wants, suggest alternatives - -## Tool Usage -- Use initial_context first to understand available content types -- Use groq_query to find specific content -- Use schema_explorer when you need field details -`; -``` - -For more prompt examples (e-commerce, docs, support), see the system prompts guide in the reference skill. - -### Step 7: Explore and Optimize (Recommended) - -Once the chatbot works, explore your dataset and build a production-quality system prompt: - -```bash -npx skills add https://github.com/sanity-io/context --skill optimize-agent-prompt -``` - -## Important Notes - -### AI SDK v6: `convertToModelMessages()` - -The Vercel AI SDK v6 requires converting UI messages to model messages before passing to `streamText`: - -```ts -import {convertToModelMessages} from 'ai' - -// In your API route: -messages: await convertToModelMessages(messages), -``` - -Do not pass raw `UIMessage[]` directly to `streamText`. This will cause type errors or silent failures. - -### Next 16 + Turbopack: `next/dynamic` Issues - -If you are using Next.js 16 with Turbopack (the default dev bundler), you may encounter issues with `next/dynamic` for client components. If the chat component fails to render: - -1. Try importing it directly instead of using `next/dynamic` -2. Or disable Turbopack: `next dev --no-turbopack` -3. Check the Next.js GitHub issues for the latest status - -### MCP URL Format - -The Sanity Context MCP server URL has two forms: - -- **Base URL** (all content): `https://api.sanity.io/:apiVersion/context/mcp/:projectId/:dataset` -- **Scoped URL** (filtered content): `https://api.sanity.io/:apiVersion/context/mcp/:projectId/:dataset/:slug` - -Use the scoped URL for production. It limits what content the agent can access based on the GROQ filter in your Sanity Context document. - -### Available MCP Tools - -| Tool | Purpose | -| ----------------- | --------------------------------------------------------------- | -| `initial_context` | Get compressed schema overview (types, fields, document counts) | -| `groq_query` | Execute GROQ queries with optional semantic search | -| `schema_explorer` | Get detailed schema for a specific document type | - -## Troubleshooting - -### MCP connection fails - -1. Create a Sanity Context document in Studio and give it a slug -2. If the slug is not `default`, set `SANITY_CONTEXT_SLUG` in `.env.local` -3. Ensure the Studio is deployed (`npx sanity deploy`) - -### "401 Unauthorized" from MCP - -Your `SANITY_API_READ_TOKEN` is missing or invalid. Generate a new token at [sanity.io/manage](https://sanity.io/manage) -> Project -> API -> Tokens with Viewer permissions. - -### "No documents found" / Empty results - -Check your Sanity Context document's content filter: - -- Is the GROQ filter correct? -- Are the document types spelled correctly? -- Are there **published** documents matching the filter? - -### Tools not appearing in LLM responses - -1. Log `mcpClient.tools()` to verify tools are returned -2. Check the MCP URL (project ID, dataset, slug) -3. Verify the Sanity Context document is **published** - -### The Sanity Context MCP server returns errors or no schema - -The Sanity Context MCP server needs your schema deployed server-side. This happens automatically when Studio runs, but if it's not working: - -1. Ensure Studio is v5.1.0+ -2. Open your Studio in a browser (triggers schema deployment) -3. Or manually deploy: `npx sanity schema deploy` - -### Chat component not rendering - -- Verify the component is marked `'use client'` -- Check browser console for hydration errors -- If using `next/dynamic`, try direct import instead (see Turbopack note above) diff --git a/ai-shopping-assistant/skills/add-sanity-chatbot/references/chat-implementation.md b/ai-shopping-assistant/skills/add-sanity-chatbot/references/chat-implementation.md deleted file mode 100644 index 3954f13..0000000 --- a/ai-shopping-assistant/skills/add-sanity-chatbot/references/chat-implementation.md +++ /dev/null @@ -1,602 +0,0 @@ -# Chat Implementation Guide - -Complete guide for adding the chat API route and UI components to your existing Next.js app. - -## Contents - -- [1. Chat API Route](#1-chat-api-route) -- [2. Client Tools (Optional)](#2-client-tools-optional) -- [3. Context Capture (Optional)](#3-context-capture-optional) -- [4. Chat UI Component](#4-chat-ui-component) -- [5. Mount the Chat Widget](#5-mount-the-chat-widget) -- [6. Advanced Patterns](#6-advanced-patterns) - ---- - -## 1. Chat API Route - -Create `app/api/chat/route.ts` (App Router): - -```ts -import {anthropic} from '@ai-sdk/anthropic' -import {createMCPClient} from '@ai-sdk/mcp' -import {convertToModelMessages, streamText, type UIMessage} from 'ai' - -const SYSTEM_PROMPT = ` -You are a helpful assistant for this website. - -## Your Capabilities -- Search and retrieve content using the available tools -- Answer questions about the site's content -- Help users find what they're looking for - -## How to Respond -- Be concise and helpful -- When referencing content, include relevant details -- If you can't find what the user wants, suggest alternatives - -## Tool Usage -- Use initial_context first to understand available content types -- Use groq_query to find specific content -- Use schema_explorer when you need field details -` - -export async function POST(req: Request) { - const {messages}: {messages: UIMessage[]} = await req.json() - - if (!process.env.ANTHROPIC_API_KEY) { - throw new Error('ANTHROPIC_API_KEY is not set') - } - - const contextSlug = process.env.SANITY_CONTEXT_SLUG || 'default' - const apiVersion = new Date().toISOString().slice(0, 10) - const mcpUrl = `https://api.sanity.io/v${apiVersion}/context/mcp/${process.env.NEXT_PUBLIC_SANITY_PROJECT_ID}/${process.env.NEXT_PUBLIC_SANITY_DATASET}/${contextSlug}` - - const mcpClient = await createMCPClient({ - transport: { - type: 'http', - url: mcpUrl, - headers: { - Authorization: `Bearer ${process.env.SANITY_API_READ_TOKEN}`, - }, - }, - }) - - try { - const mcpTools = await mcpClient.tools() - - const result = streamText({ - model: anthropic('claude-sonnet-4-5-20250929'), - system: SYSTEM_PROMPT, - messages: await convertToModelMessages(messages), - tools: { - ...mcpTools, - }, - maxSteps: 10, - onFinish: async () => { - await mcpClient.close() - }, - }) - - return result.toUIMessageStreamResponse() - } catch (error) { - await mcpClient.close() - throw error - } -} -``` - -**Key points:** - -- `createMCPClient` connects to the Sanity Context MCP server via HTTP transport -- `mcpClient.tools()` returns the available tools (`initial_context`, `groq_query`, `schema_explorer`) -- `convertToModelMessages(messages)` is **required** in AI SDK v6. Do not pass raw `UIMessage[]` -- `maxSteps: 10` allows the LLM to make multiple tool calls in sequence -- Always close the MCP client when done - -### Using a different LLM provider - -Replace the Anthropic provider with any AI SDK-compatible provider: - -```ts -// OpenAI -import {openai} from '@ai-sdk/openai' -model: openai('gpt-4o'), - -// Google -import {google} from '@ai-sdk/google' -model: google('gemini-2.0-flash'), -``` - -Install the corresponding provider package (e.g., `npm install @ai-sdk/openai`). - ---- - -## 2. Client Tools (Optional) - -If you want the chatbot to capture page context or screenshots, create a shared tools file. - -Create `lib/client-tools.ts`: - -```ts -import {z} from 'zod' - -/** User context sent with every message so the agent knows where the user is. */ -export interface UserContext { - documentTitle: string - documentDescription?: string - documentLocation: string -} - -/** Tool names - single source of truth for definitions and handlers. */ -export const CLIENT_TOOLS = { - PAGE_CONTEXT: 'get_page_context', - SCREENSHOT: 'get_page_screenshot', -} as const - -export type ClientToolName = (typeof CLIENT_TOOLS)[keyof typeof CLIENT_TOOLS] -``` - -Then update the API route to include client tools (tools without `execute`; execution happens on the client): - -```ts -import {type ToolSet} from 'ai' -import {z} from 'zod' -import {CLIENT_TOOLS, type UserContext} from '@/lib/client-tools' - -const clientTools: ToolSet = { - [CLIENT_TOOLS.PAGE_CONTEXT]: { - description: 'Page context as markdown: URL, title, and text content. Fast. No visuals.', - inputSchema: z.object({ - reason: z.string().describe('Why you need page context'), - }), - }, - [CLIENT_TOOLS.SCREENSHOT]: { - description: 'Visual screenshot of the page. Use when you need to see images, colors, or layout.', - inputSchema: z.object({ - reason: z.string().describe('Why you need a screenshot'), - }), - }, -} - -// In the streamText call, combine tools: -tools: { - ...mcpTools, - ...clientTools, -}, -``` - ---- - -## 3. Context Capture (Optional) - -If using client tools, create browser-side capture functions. - -Create `lib/capture-context.ts`: - -```ts -import type {UserContext} from './client-tools' - -/** Attribute to mark the chat element (excluded from capture). */ -export const AGENT_CHAT_HIDDEN_ATTRIBUTE = 'agent-chat-hidden' - -/** Lightweight context sent with every message. */ -export function captureUserContext(): UserContext { - const metaDescription = - document.querySelector('meta[name="description"]')?.getAttribute('content') || - document.querySelector('meta[property="og:description"]')?.getAttribute('content') - - return { - documentTitle: document.title, - documentDescription: metaDescription || undefined, - documentLocation: window.location.pathname, - } -} - -/** - * Captures page content as markdown. - * Requires: npm install turndown && npm install -D @types/turndown - */ -export function capturePageContext() { - // Dynamic import to avoid SSR issues - const TurndownService = require('turndown') - const turndown = new TurndownService({ - headingStyle: 'atx', - bulletListMarker: '-', - }) - - // Replace images with alt text only - turndown.addRule('images', { - filter: 'img', - replacement: (_content: string, node: HTMLElement) => { - const alt = (node as HTMLImageElement).alt - return alt ? alt : '' - }, - }) - - // Remove scripts, styles, and other noise - turndown.addRule('removeNoise', { - filter: (node: HTMLElement) => - ['SCRIPT', 'STYLE', 'SVG', 'VIDEO', 'AUDIO', 'IFRAME', 'NOSCRIPT'].includes(node.nodeName), - replacement: () => '', - }) - - const main = document.querySelector('main') || document.body - const clone = main.cloneNode(true) as Element - - // Remove the chat widget from the capture - clone.querySelectorAll(`[${AGENT_CHAT_HIDDEN_ATTRIBUTE}]`).forEach((el) => el.remove()) - - return { - url: window.location.href, - title: document.title, - content: turndown.turndown(clone.innerHTML).slice(0, 4000), - } -} - -/** - * Captures a screenshot of the page. - * Requires: npm install html2canvas-pro - */ -export async function captureScreenshot() { - const html2canvas = (await import('html2canvas-pro')).default - const canvas = await html2canvas(document.body, { - ignoreElements: (el: Element) => el.hasAttribute(AGENT_CHAT_HIDDEN_ATTRIBUTE), - }) - - const MAX_DIMENSION = 4000 - let finalCanvas = canvas - - if (canvas.width > MAX_DIMENSION || canvas.height > MAX_DIMENSION) { - const scale = Math.min(MAX_DIMENSION / canvas.width, MAX_DIMENSION / canvas.height) - const resizedCanvas = document.createElement('canvas') - resizedCanvas.width = Math.floor(canvas.width * scale) - resizedCanvas.height = Math.floor(canvas.height * scale) - const ctx = resizedCanvas.getContext('2d') - ctx?.drawImage(canvas, 0, 0, resizedCanvas.width, resizedCanvas.height) - finalCanvas = resizedCanvas - } - - return finalCanvas.toDataURL('image/jpeg', 0.7) -} -``` - ---- - -## 4. Chat UI Component - -Create a chat component. Below is a minimal version, followed by a full-featured version. - -### Minimal Chat Component - -Create `components/chat/Chat.tsx`: - -```tsx -'use client' - -import {useChat} from '@ai-sdk/react' -import {type UIMessage} from 'ai' -import {useState} from 'react' - -export function Chat() { - const [isOpen, setIsOpen] = useState(false) - const {messages, sendMessage, status, error} = useChat() - const [input, setInput] = useState('') - - const isLoading = status === 'submitted' || status === 'streaming' - - const handleSubmit = (e: React.FormEvent) => { - e.preventDefault() - if (!input.trim()) return - sendMessage({text: input}) - setInput('') - } - - if (!isOpen) { - return ( - - ) - } - - return ( -
- {/* Header */} -
- Chat Assistant - -
- - {/* Messages */} -
- {messages.length === 0 ? ( -

- Ask me anything about this site. -

- ) : ( - messages.map((message) => ( -
- {(message.parts ?? []) - .filter((part) => part.type === 'text' && part.text.trim()) - .map((part, i) => ( -
- {part.type === 'text' ? part.text : null} -
- ))} -
- )) - )} - - {isLoading &&
Thinking...
} - - {error && ( -
- Something went wrong. Please try again. -
- )} -
- - {/* Input */} -
- setInput(e.target.value)} - placeholder="Type a message..." - disabled={isLoading} - style={{ - flex: 1, - padding: '0.5rem 0.75rem', - borderRadius: '0.5rem', - border: '1px solid #d4d4d4', - fontSize: '0.875rem', - outline: 'none', - }} - /> - -
-
- ) -} -``` - -### Full-Featured Chat Component - -For a production-ready component with client-side tools, auto-continuation, and user context, see the ecommerce reference implementation. Key additions: - -**Auto-continuation**: automatically continue the conversation when tool calls complete: - -```tsx -import {DefaultChatTransport, lastAssistantMessageIsCompleteWithToolCalls} from 'ai' - -const {messages, sendMessage, status, addToolOutput, error} = useChat({ - // Include user context with every request - transport: new DefaultChatTransport({ - body: () => ({userContext: captureUserContext()}), - }), - // Auto-continue when tool calls complete - sendAutomaticallyWhen: ({messages}) => { - return lastAssistantMessageIsCompleteWithToolCalls({messages}) - }, - // Handle client-side tool execution - onToolCall: async ({toolCall}) => { - if (toolCall.dynamic) return - - switch (toolCall.toolName) { - case CLIENT_TOOLS.PAGE_CONTEXT: { - addToolOutput({ - tool: CLIENT_TOOLS.PAGE_CONTEXT, - toolCallId: toolCall.toolCallId, - output: capturePageContext(), - }) - return - } - case CLIENT_TOOLS.SCREENSHOT: { - try { - const file = await captureScreenshot() - addToolOutput({ - tool: CLIENT_TOOLS.SCREENSHOT, - toolCallId: toolCall.toolCallId, - output: 'Screenshot captured.', - }) - // Note: send file as follow-up message since addToolOutput doesn't support files - } catch (err) { - addToolOutput({ - tool: CLIENT_TOOLS.SCREENSHOT, - toolCallId: toolCall.toolCallId, - output: `Failed to capture screenshot: ${err instanceof Error ? err.message : String(err)}`, - }) - } - return - } - } - }, -}) -``` - ---- - -## 5. Mount the Chat Widget - -Add the chat component to your layout or a page. - -**In your root layout** (`app/layout.tsx`): - -```tsx -import {Chat} from '@/components/chat/Chat' - -export default function RootLayout({children}: {children: React.ReactNode}) { - return ( - - - {children} - - - - ) -} -``` - -**Or on specific pages only:** - -```tsx -import {Chat} from '@/components/chat/Chat' - -export default function ProductsPage() { - return ( -
- {/* your page content */} - -
- ) -} -``` - ---- - -## 6. Advanced Patterns - -### User Context with Every Request - -Send the current page URL and title with every message so the agent has context: - -```tsx -// In Chat component -transport: new DefaultChatTransport({ - body: () => ({userContext: captureUserContext()}), -}), -``` - -Then in the API route, extract and use it in the system prompt: - -```ts -const {messages, userContext}: {messages: UIMessage[]; userContext: UserContext} = await req.json() - -const systemPrompt = `${SYSTEM_PROMPT} - -# Page context -The user is currently on: ${userContext.documentTitle} (${userContext.documentLocation}) -` -``` - -### Storing the System Prompt in Sanity - -Instead of hardcoding the prompt, store it in a Sanity document for easy editing: - -1. Create a schema type (e.g., `agent.config`) with a `systemPrompt` text field -2. Fetch it in the API route: - -```ts -import {client} from '@/sanity/lib/client' - -const agentConfig = await client.fetch<{systemPrompt: string} | null>( - `*[_type == "agent.config" && slug.current == "default"][0] { systemPrompt }`, - {}, - {tag: 'chat.agent-config'}, -) -``` - -### Request tags - -The reference client at `app/src/sanity/lib/client.ts` sets -`requestTagPrefix: 'kit.ai-shopping-assistant'` and per-call options take a -`tag: '.'` (e.g. `tag: 'chat.agent-config'`), producing the -combined tag `kit.ai-shopping-assistant.chat.agent-config` — handy for filtering -your own request logs. Change or remove `requestTagPrefix` in your client config -to use whatever tagging scheme you prefer. -See [Request tags](https://www.sanity.io/docs/apis-and-sdks/js-client-request-tags). - -### Custom Content Rendering - -For rich content display (product cards, article previews), define custom markdown directives in the system prompt and parse them in the UI. See the ecommerce reference for the `::document{id="..." type="..."}` pattern with `remark-directive`. diff --git a/ai-shopping-assistant/skills/add-sanity-chatbot/references/studio-setup.md b/ai-shopping-assistant/skills/add-sanity-chatbot/references/studio-setup.md deleted file mode 100644 index 251d50e..0000000 --- a/ai-shopping-assistant/skills/add-sanity-chatbot/references/studio-setup.md +++ /dev/null @@ -1,145 +0,0 @@ -# Studio Setup: Adding Sanity Context to Your Existing Studio - -Configure the Sanity Context plugin in your existing Studio to create Sanity Context documents that scope what content the chatbot can access. - -## 1. Install the Package - -In your Studio project directory: - -```bash -npm install @sanity/context -``` - -**Version requirements:** - -| Package | Version | Notes | -| ----------------------- | ------- | --------------------- | -| `@sanity/context` | latest | Check npm for current | -| `sanity` | ^5.8.0 | Studio v5.1.0+ | - -## 2. Add the Plugin to Your Config - -Open your `sanity.config.ts` and add the plugin: - -```ts -import { contextPlugin } from "@sanity/context/studio"; - -export default defineConfig({ - // ... your existing config (name, projectId, dataset, etc.) - plugins: [ - // ... your existing plugins - contextPlugin(), - ], -}); -``` - -This registers the `sanity.agentContext` document type in your Studio. - -### Full example with custom structure (optional) - -If you want to organize agent-related documents under a dedicated section in the Studio: - -```ts -import { defineConfig } from "sanity"; -import { structureTool, type StructureBuilder, type ListItemBuilder } from "sanity/structure"; -import { contextPlugin } from "@sanity/context/studio"; -// ... your other imports - -// Types to group under the "Agents" section in the desk -const AGENT_TYPES = ["sanity.agentContext"]; - -export default defineConfig({ - // ... your existing config - plugins: [ - structureTool({ - structure: (S: StructureBuilder) => { - // Filter agent types out of the default list - const defaultItems = S.documentTypeListItems().filter( - (item: ListItemBuilder) => !AGENT_TYPES.includes(item.getId() ?? ""), - ); - - // Build agent section items - const agentItems = AGENT_TYPES.map((type) => S.documentTypeListItem(type)); - - return S.list() - .title("Content") - .items([ - ...defaultItems, - S.divider(), - S.listItem().title("Agents").child(S.list().title("Agents").items(agentItems)), - ]); - }, - }), - contextPlugin(), - // ... your other plugins - ], -}); -``` - -## 3. Create a Sanity Context Document - -Open your Studio and create a new **Sanity Context** document. Fill in: - -| Field | Description | -| ------------------ | --------------------------------------------------------- | -| **Name** | Display name (e.g., "Product Assistant", "Site Chatbot") | -| **Slug** | URL-friendly identifier, auto-generated from name | -| **Content Filter** | GROQ filter that scopes what content the agent can access | - -### Content Filter Examples - -**All documents of specific types:** - -```groq -_type in ["article", "product", "category"] -``` - -**Published content only:** - -```groq -_type in ["article", "product"] && !(_id in path("drafts.**")) -``` - -**Content in a specific language:** - -```groq -_type == "article" && language == "en" -``` - -The filter UI provides two modes: - -- **Types tab**: Simple checkbox UI to select document types -- **GROQ tab**: Manual entry for complex filters - -**Tip:** Start broad (select all content types), then narrow based on what the chatbot actually needs. - -## 4. Copy the MCP URL - -Once the Sanity Context document has a slug, the MCP URL appears at the top of the document form: - -``` -https://api.sanity.io/:apiVersion/context/mcp/:projectId/:dataset/:slug -``` - -If your slug is not `default`, set `SANITY_CONTEXT_SLUG` in your Next.js app's environment variables. The MCP URL is constructed automatically from your project ID, dataset, and this slug. - -## 5. Publish the Document - -The Sanity Context document **must be published** for the MCP endpoint to work. Drafts are not accessible via the MCP URL. - -## 6. Validate MCP Access (Optional) - -Before building anything, verify the MCP endpoint is reachable: - -```bash -curl -X POST https://api.sanity.io/vX/context/mcp/YOUR_PROJECT_ID/YOUR_DATASET/YOUR_SLUG \ - -H "Authorization: Bearer $SANITY_API_READ_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' -``` - -You should see a JSON response listing `initial_context`, `groq_query`, and `schema_explorer` tools. - -## Next Steps - -With Studio configured and the MCP URL copied, proceed to [chat-implementation.md](chat-implementation.md) to add the chatbot to your Next.js app. diff --git a/analytics-content-ops/skills/analytics-content-ops/SKILL.md b/analytics-content-ops/skills/analytics-content-ops/SKILL.md deleted file mode 100644 index 2a495f6..0000000 --- a/analytics-content-ops/skills/analytics-content-ops/SKILL.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -name: analytics-content-ops -description: Overview of the analytics-informed content operations starter — how performance signal flows from an analytics platform into Sanity as derived signal, and how Studio, GROQ, and Content Agent turn it into editorial action. Trigger on: analytics content ops, performance signal, articlePerformance, triage views, trending rail, content intelligence, stale content, editorial signal. ---- - -# Analytics-Informed Content Operations - -This starter closes the loop between an analytics platform and editorial action. -A nightly sync classifies the catalog and writes **derived signal** into Sanity; -editors act on it in Studio, developers power "trending"/"most-read" features -with GROQ, and Content Agent triages underperforming content automatically. - -## Core principle - -**Sanity is not the analytics platform.** Raw metrics (pageviews, sessions) -never enter Sanity. The sync classifies them into a small, human-legible -vocabulary (`performanceTier`, `trendDirection`, `lifecycleState`, `topReferrer`, -`catalogPercentile`) and writes only that. The analytics platform stays the -system of record; Sanity is where signal becomes action. - -## Content model - -- **`article`** (`studio/schemaTypes/article.ts`) — the editorial document. Adds - two signal-response fields: `editorialPriority` (the editor's flag) and - `agentReview` (state machine: `idle → queued → in_progress → staged → -approved | dismissed`), plus agent-drafted `seoTitle` / `seoDescription`. -- **`articlePerformance`** (`studio/schemaTypes/articlePerformance.ts`) — a - **companion document**, written only by the sync, never edited by humans. - Deterministic id `articlePerformance.` so re-runs upsert in place. - Deliberately separate from `article` so `article._updatedAt` stays an - _editorial_ signal and webhooks can filter sync writes by `_type`. -- **`analyticsContext`** (`studio/schemaTypes/analyticsContext.ts`) — a read-only - singleton with catalog-level counts for cheap Content Agent context queries. - -Vocabulary is mirrored in `studio/lib/performance.ts` (Studio) and -`packages/@starter/analytics-sync/src/types.ts` (sync). Keep the two in sync. - -## Joining performance to articles (GROQ) - -The companion pattern means you always join by reference: - -```groq -*[_type == "article" && defined(slug.current)]{ - ..., - "performance": *[_type == "articlePerformance" && article._ref == ^._id][0]{ - performanceTier, trendDirection, lifecycleState, catalogPercentile - } -} -``` - -The frontend rails live in `frontend/sanity/queries.ts`: - -- `TRENDING_QUERY` — orders by `articlePerformance` where `performanceTier == "trending"` -- `MOST_READ_QUERY` — orders by `catalogPercentile desc` - -## Studio surfaces - -- **`PerformanceTierBadge`** (`studio/components/PerformanceTierBadge.tsx`) — a - document badge: green "Trending", warning "Stale", red "Archive candidate". -- **Performance panel** (`studio/components/PerformancePanel.tsx`) — a read-only - second view on every article, live-subscribed to the companion doc. Wired via - `defaultDocumentNode` in `studio/structure.ts`. -- **Triage views** (`studio/structure.ts`) — Needs Attention, Trending Now, - Archive Candidates, Content Agent Queue. - -## The two-phase sync - -Both phases call the same `runSync` from `@starter/analytics-sync`: - -- **Phase 1** — `scripts/analytics-sync.ts`, run by GitHub Actions - (`.github/workflows/analytics-sync.yml`). Needs `SANITY_API_WRITE_TOKEN`. -- **Phase 2** — `functions/analytics-sync/`, a scheduled Function registered in - `sanity.blueprint.ts`. - -Migrating Phase 1 → Phase 2 is an infrastructure swap, not a rewrite. - -## Jobs to be done - -- **Add a new analytics source** → see the `analytics-provider-pattern` skill. -- **Change what counts as trending/stale** → tune `ClassifyOptions` in - `packages/@starter/analytics-sync/src/classify.ts` (catalog-relative). -- **Automate content improvement** → see the `content-agent-triage` skill. -- **Surface signal on the site** → add a GROQ join in `frontend/sanity/queries.ts`. - -## References - -- `packages/@starter/analytics-sync/src/index.ts` — `runSync` pipeline -- `studio/structure.ts` — triage views + performance panel wiring -- `README.md` / `AGENT.md` — setup and architecture diff --git a/analytics-content-ops/skills/analytics-provider-pattern/SKILL.md b/analytics-content-ops/skills/analytics-provider-pattern/SKILL.md deleted file mode 100644 index fba4e25..0000000 --- a/analytics-content-ops/skills/analytics-provider-pattern/SKILL.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -name: analytics-provider-pattern -description: Build analytics-platform-agnostic sync providers. Core AnalyticsProvider interface, fixture reference implementation, GA4 skeleton, and how to add Amplitude/Heap/Plausible. Trigger on: analytics provider, add analytics source, GA4 integration, fetchMetrics, provider adapter, sync classification, tier tuning. ---- - -# Analytics Provider Pattern - -Make the sync work with any analytics platform by writing one small adapter. The -pattern separates **fetching raw metrics** (provider) from **classifying them** -(catalog-relative) and **writing derived signal** (Sanity). Adding Amplitude or -Heap means writing a new provider, never touching classification or the write -path. - -## Core principle - -**Open–closed.** A new analytics source adds a new provider module and one -`case` in `resolveProvider`. The classification (`classify.ts`) and Sanity write -path (`index.ts` → `runSync`) never change. The provider's only job is to return -`AnalyticsMetric[]`. - -## Package: `@starter/analytics-sync` - -Lives at `packages/@starter/analytics-sync/`, framework-agnostic so it bundles -cleanly into a Sanity Function. - -**Exports:** - -- `.` — `runSync`, `classifyCatalog`, `resolveProvider`, and all types -- `./providers` — `resolveProvider`, `fixtureProvider`, `ga4Provider` - -## The interface - -```typescript -export interface ArticleRef { - slug: string - ageDays: number // derived from publishedAt by the sync -} - -export interface AnalyticsMetric { - slug: string - sessions: number // current window - previousSessions: number // prior window — drives trend direction - ageDays: number - topReferrer: TopReferrer // 'organic' | 'social' | 'direct' | 'referral' | 'email' -} - -export interface AnalyticsProvider { - readonly name: string - fetchMetrics(articles: ArticleRef[]): Promise -} -``` - -A provider is handed the article refs the sync wants metrics for and returns one -`AnalyticsMetric` per article it has data for. Raw metrics stop here — they are -never written to Sanity. - -## Reference implementation: fixture - -`src/providers/fixture.ts` produces deterministic demo metrics (curated per -slug so the seeded catalog spans every tier) — no credentials required. It is -the default (`ANALYTICS_PROVIDER=fixture`) and drives `pnpm seed`. - -## Skeleton: GA4 - -`src/providers/ga4.ts` throws until implemented, so the demo never reports -fabricated numbers as real. Implementation sketch: - -1. Read `GA4_PROPERTY_ID` and `GA4_SERVICE_ACCOUNT_KEY` from env. -2. Call the GA Data API `runReport` for `sessions` by `pagePath` over the current - and previous window, plus `sessionDefaultChannelGroup` for the top referrer. -3. Map each slug to its `pagePath` (e.g. `/article/${slug}`) and return one - `AnalyticsMetric` per matched article. - -## How to add a new provider (Amplitude example) - -### Step 1 — create the module - -```typescript -// packages/@starter/analytics-sync/src/providers/amplitude.ts -import type {AnalyticsMetric, AnalyticsProvider, ArticleRef} from '../types' - -export function amplitudeProvider(): AnalyticsProvider { - return { - name: 'amplitude', - async fetchMetrics(articles: ArticleRef[]): Promise { - const apiKey = process.env.AMPLITUDE_API_KEY - if (!apiKey) throw new Error('AMPLITUDE_API_KEY not set') - // Query Amplitude for sessions per article path, current + previous window, - // then map to AnalyticsMetric. - return articles.map((a) => ({ - slug: a.slug, - sessions: 0, - previousSessions: 0, - ageDays: a.ageDays, - topReferrer: 'organic', - })) - }, - } -} -``` - -### Step 2 — register it in `resolveProvider` - -```typescript -// packages/@starter/analytics-sync/src/providers/index.ts -case 'amplitude': - return amplitudeProvider() -``` - -Also re-export it and select it with `ANALYTICS_PROVIDER=amplitude`. **No other -file changes** — classification and the write path are untouched. - -## Tuning classification (not the provider) - -To change what "trending" or "stale" means, edit `ClassifyOptions` in -`src/classify.ts`. Tiers are **catalog-relative** — a piece is stale compared to -its peers, not against an absolute pageview number: - -- `trendingTopFraction` (0.1) — top 10% by session growth, and `rising` -- `staleBottomFraction` (0.25) + `staleMinAgeDays` (90) — bottom quartile once - old enough -- `newMaxAgeDays` (14) — always "new" while young -- `risingRatio` / `fallingRatio` — trend thresholds vs. the previous window -- `archiveMinAgeDays` (180) — old + bottom-15th percentile + not rising → - `archive_candidate` - -Pass overrides via `runSync({classifyOptions: {...}})` (e.g. per-section tuning). - -## References - -- `packages/@starter/analytics-sync/src/types.ts` — interfaces -- `packages/@starter/analytics-sync/src/providers/` — fixture + ga4 -- `packages/@starter/analytics-sync/src/classify.ts` — tier logic -- `packages/@starter/analytics-sync/src/index.ts` — `runSync` pipeline diff --git a/analytics-content-ops/skills/content-agent-triage/SKILL.md b/analytics-content-ops/skills/content-agent-triage/SKILL.md deleted file mode 100644 index 9f16370..0000000 --- a/analytics-content-ops/skills/content-agent-triage/SKILL.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -name: content-agent-triage -description: Automate content improvement with Content Agent (Agent Actions) safely. The queued → staged review pipeline, draft-as-review-gate pattern, instruction design, and the Content Release upgrade. Trigger on: content agent, agent actions, agent.action.generate, triage, agentReview, stale content refresh, SEO drafting, review queue. ---- - -# Content Agent Triage - -Automate the "nightly catalog triage" journey: the sync flags underperforming -articles, and a scheduled Function uses Agent Actions to draft reasoning and -improved SEO — always into a **draft** a human approves. Nothing goes live -automatically. - -## Core principle - -**The draft is the review gate.** Every agent write lands in -`drafts.`, never the published document. The ops lead reviews the "Content -Agent Queue" in Studio and publishes to approve. The agent only touches -editorial/SEO fields — never the read-only analytics signal. - -## The state machine - -`agentReview.status` on `article` drives the whole pipeline: - -``` -idle → queued → in_progress → staged → approved | dismissed -``` - -- **`queued`** — set by the sync (`runSync`) when an article _newly_ enters the - `stale` tier and its review is idle/unset. Only idle reviews are touched, so - in-flight work is never disturbed. -- **`in_progress`** — set by the triage Function as it starts an article. -- **`staged`** — set after the agent writes; the draft is ready for review. -- **`approved` / `dismissed`** — the human decision (publish or discard draft). - -## The triage Function - -`functions/agent-triage/index.ts` runs ~30 min after the sync (schedule in -`sanity.blueprint.ts`). Per run: - -1. `QUEUED_QUERY` loads `agentReview.status == "queued"` articles, joining their - `articlePerformance` tier / referrer / percentile as context. -2. For each: set `in_progress`, ensure a draft exists (copy published minus - `_rev` into `drafts.`), call `client.agent.action.generate`, then set - `staged` + `releaseId` + `reviewedAt` on the draft. -3. On error, requeue (`status: 'queued'`) so the next run retries. - -## Agent Actions setup - -```typescript -// apiVersion "vX" is required for Agent Actions. -const client = createClient({projectId, dataset, token, apiVersion: 'vX', useCdn: false}) - -await client.agent.action.generate({ - schemaId, // 'default', or SANITY_SCHEMA_ID — must match the deployed schema - documentId: draftId, // always the draft, never the published id - instruction: INSTRUCTION, // uses $tier / $referrer / $percentile placeholders - instructionParams: { - tier: {type: 'constant', value: article.tier ?? 'stale'}, - referrer: {type: 'constant', value: article.referrer ?? 'organic'}, - percentile: {type: 'constant', value: String(article.percentile ?? 0)}, - }, - // Scope writes to exactly these fields — nothing else can change. - target: [{path: 'agentReview.agentNotes'}, {path: 'seoTitle'}, {path: 'seoDescription'}], -}) -``` - -### Safety layers (why this is trustworthy) - -- **Scoped input** — the GROQ filter limits the agent to queued articles. -- **Scoped output** — `target` restricts writes to editorial/SEO fields. -- **Draft-only** — writes go to `drafts.`; publishing is a human act. -- **Grounded instruction** — the prompt passes signal as read-only context and - tells the agent to ground everything in the article's actual content, then - optimize SEO for the article's top acquisition channel. - -## Instruction design - -The `INSTRUCTION` string channel-tailors the SEO advice: organic → search -intent/keywords; social → a scroll-stopping hook; email → narrative depth + CTA; -direct/referral → updated facts + internal linking. It asks for one reasoning -paragraph plus exactly three concrete improvement opportunities. Keep field -limits explicit (seoTitle ≤ 70 chars, seoDescription ≤ 160). - -## Reviewing in Studio - -`studio/structure.ts` defines the **Content Agent Queue** — articles with -`agentReview.status in ["queued", "in_progress", "staged"]`. Editors open a -staged article, read the agent notes in the `agentReview` object, compare the -drafted SEO, and publish (approve) or discard the draft (dismiss). - -## Production upgrade: Content Releases - -Each run currently tags staged drafts with a `releaseId` -(`stale-content-refresh-YYYY-MM-DD`). The documented upgrade is to promote this -batch to a first-class **Content Release** via the Releases API, so the whole -nightly triage can be reviewed and published atomically. See `AGENT.md`. - -## References - -- `functions/agent-triage/index.ts` — the triage Function -- `packages/@starter/analytics-sync/src/index.ts` — where articles get `queued` -- `studio/schemaTypes/article.ts` — `agentReview` object + status field -- `studio/structure.ts` — Content Agent Queue view -- `sanity.blueprint.ts` — schedule + env injection diff --git a/commerce-pdp-management/skills/example/SKILL.md b/commerce-pdp-management/skills/example/SKILL.md deleted file mode 100644 index 2add6ef..0000000 --- a/commerce-pdp-management/skills/example/SKILL.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -name: example -description: 'Example skill placeholder. Replace this with a real skill for your starter.' ---- - -# Example Skill - -This is a placeholder. Create skills to extend Claude Code with starter-specific workflows. - -## When to use - -Describe when this skill should be triggered. - -## Workflow - -1. Step one -2. Step two -3. Step three diff --git a/commerce-plp-management/skills/merchandising/SKILL.md b/commerce-plp-management/skills/merchandising/SKILL.md deleted file mode 100644 index c69eb55..0000000 --- a/commerce-plp-management/skills/merchandising/SKILL.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -name: merchandising -description: 'Workflows for enriching Shopify collections and coordinating campaigns in this commerce-plp-management starter. Use when adding a banner/faceout/badge/tile to a collection, building a custom campaign collection, scheduling a multi-collection launch via Content Releases, or debugging the Shopify metaobject push-sync.' ---- - -# Merchandising workflows - -Concrete, starter-specific recipes for the `collectionEnrichment` model. - -## Enrich an existing Shopify collection - -1. Create a `collectionEnrichment` document; set `handle` to the exact Shopify - collection handle. Keep `collectionType` as `shopify-native`. -2. Add a `banner` (headline + color block), a `faceout` (pick the hero product), - `editorialTiles` (set 1-based `position`), and `badges` (pick product + badge + - optional start/end dates). -3. Publish. The storefront merges immediately (pull path). The push-sync Function - writes the Shopify metaobject and stamps `syncStatus`. - -Absence of a document = pure Shopify output. Delete the document to fully revert. - -## Build a custom campaign collection (gift guide) - -1. New `collectionEnrichment`; set `collectionType` to `sanity-custom` and choose a - fresh `handle` (e.g. `holiday-gift-guide-2026`). Handle is immutable after - publish. -2. Add products to `productList` with the picker; drag to set curation order - (array order is the order). Sanity owns membership; Shopify supplies live data. -3. Add editorial tiles at positions, and an optional `variantOverrides` entry for - a segment (e.g. `loyalty-member`). -4. Publish. The storefront routes `/collections/` to the custom path and - batch-fetches products by GID. - -## Coordinate a multi-collection campaign - -Use native **Content Releases**: add every affected `collectionEnrichment` to one -release, preview, then schedule. All documents publish atomically; the push-sync -runs per document within seconds. No custom code. - -## Debug the push-sync - -- Check the **Shopify sync** card on the document: `synced` (green), `pending` - (yellow), `failed` (red with error). -- The pull path (storefront) is unaffected by push failures. -- Metaobject definition drift → run `pnpm shopify:setup` to reconcile the - `sanity_plp_collection` definition. The contract lives in - `packages/@starter/commerce/src/shopify/metaobject.ts`. -- Badge label changed but Shopify metaobject stale? The `badge-resync` Function - re-syncs referencing collections on `productBadge` publish. diff --git a/email-marketing/skills/email-marketing-ops/SKILL.md b/email-marketing/skills/email-marketing-ops/SKILL.md deleted file mode 100644 index caa50f5..0000000 --- a/email-marketing/skills/email-marketing-ops/SKILL.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -name: email-marketing-ops -description: 'Build multi-variant email campaigns with AI, streaming preview, and Klaviyo dispatch. Covers three-tier document model (campaign brief → promotion artifact → email slot), batch variant generation, multi-turn refinement, @sanity/context wiring, preview accuracy badges, security (7-layer defense), and engagement feedback. Supports both greenfield (new Sanity studio) and brownfield (adding to existing) patterns. Trigger on: email marketing, variant generation, campaign dashboard, Klaviyo sync, preview service, engagement metrics, segment enrichment, email dispatch, AI refinement, campaign brief, promotion artifact, email slot.' ---- - -# Email Marketing with Sanity & Klaviyo - -Build email campaigns as a **three-tier document hierarchy**: - -1. **Campaign** — creative brief (goals, messaging, tone traits, personalization tokens) -2. **Promotion** — segment-variant artifact (subject, preheader, disruptor, modular slots, approval workflow) -3. **EmailSlot** — reusable content block (position, asset, headline, subheadline, CTA) - -Generate N variants from one brief, refine with multi-turn AI, preview with accuracy badges, dispatch to Klaviyo. All from Studio. - -## Core Principles - -**Separation of concerns**: Campaign is intent (what to say, to whom, by when); promotion is execution (how to say it for each segment). Schema enforces this—campaigns have no targeting fields. - -**Modular content**: EmailSlot replaces Portable Text. Enforce consistency, enable component-driven composition. - -**AI-augmented not AI-native**: AI generates variants and refines copy, but humans approve every promotion before send. Thread-based refinement preserves context across turns. - -**Security by design**: 7-layer defense (HTTPS+HSTS, auth 3-paths, input validation, render-time sanitization, CSP headers, rate limiting, audit logging) protects preview service and dispatch pipeline. - -**Observable, not eventual**: Preview accuracy badges (X-Preview-Status) show which tokens are resolved vs. stubbed. Editors know before sending. - -**Engaged audiences as default**: Segments are two-layer (synced from Klaviyo + editable enrichment for copy tone). Enrichment persists across re-syncs; it's editorial metadata, not infrastructure. - -## Orientation - -### Project Map - -Read [references/architecture.md](references/architecture.md) for the full entry points and file structure. Key locations: - -**Packages (domain logic)** - -- `packages/render-email/` — MJML streaming, sanitization, stub handling (`./streaming`, `./stubs`, `./sanitize`, `./types`) -- `packages/esp-connector/` — EspConnector interface + KlaviyoConnector, payload dispatcher (`./klaviyo`, extensible to ./braze, ./ajo) -- `packages/preview-middleware/` — Composable middleware: auth, rate-limit, security-headers, logging (`./auth`, `./rate-limit`, `./security-headers`, `./logging`) -- `packages/eslint-config/`, `packages/tsconfig/`, `packages/sanity-types/` — Shared configs - -**Studio (domain-organized plugins)** - -- `studio/plugins/campaign/` — campaign schema, GenerateVariantsAction, CampaignGrid view, agent context -- `studio/plugins/promotion/` — promotion schema, emailSlot, VariantRefinementPanel, approval workflow -- `studio/plugins/klaviyo/` — sync UI, import trigger, readOnly origin labels -- `studio/plugins/preview/` — shareable preview links, Presentation tool wiring -- `studio/plugins/assist/` — @sanity/assist field-level generation config -- `studio/schemaTypes/reference-data/` — store, urgencyStage, segment (two-layer), brandVoice, enticement, promoCode, termsAndConditions - -**Functions** - -- `functions/on-promotion-approved/` — dispatch to Klaviyo when approved -- `functions/import-klaviyo/` — sync lists and segments from Klaviyo (request-document trigger) -- `functions/on-slot-needs-asset/` — notify creatives on unfilled emailSlot -- `functions/engagement-log-back/` — inbound Klaviyo webhook → patch campaignPerformance - -**App SDK** - -- `apps/campaign-dashboard/` — standalone (no Studio seat) campaign list and performance metrics - -### Two Implementation Patterns - -**Greenfield**: Start from `sanity init --template sanity-labs/starters/email-marketing`. Full three-tier model, all plugins wired. - -**Brownfield**: Add email marketing to an existing Studio. See [references/add-to-existing-studio.md](references/add-to-existing-studio.md). - -## Jobs to Be Done - -### 1. Set up a campaign and generate variants - -- Create a campaign document with: title, store, urgencyStage, segments (array of refs), primaryMessage, toneTraits, previewContext (token → sample value map), startDate, endDate -- Use GenerateVariantsAction on the campaign → creates N promotion documents (one per segment) -- Each promotion has: campaign ref, segment ref, subjectLine, preheader, disruptor, emailSlots array, campaignPerformance (readOnly) - -**Entry point**: `studio/plugins/campaign/documentActions/GenerateVariantsAction.tsx` (placeholder → real agent.action.generate() call) - -### 2. Refine a promotion in multi-turn loop - -- Open a promotion document -- Click the VariantRefinementPanel tab (bottom pane) -- Type a refinement prompt: "Make the subject line shorter and more urgent" -- Select fields to target: subjectLine, preheader, disruptor -- Agent refines those fields; you accept/reject/modify field-by-field -- Each turn preserves prior accepted changes in the live document - -**Entry point**: `studio/plugins/promotion/components/VariantRefinementPanel.tsx` (placeholder → real thread ID, agent context, field-level patching) - -**Context wiring**: `studio/plugins/campaign/hooks/useSanityContext.ts` serializes: - -- Supplemental: brandVoice singleton (tone traits, style rules, legal constraints) -- Local: campaign fields (primaryMessage, emotionalGoal, toneTraits) + segment enrichment (affinityDescription, typicalCopyTone, engagementTier) + previewContext tokens - -### 3. Preview a promotion with accuracy badges - -- Navigate to promotion in Presentation Tool or via preview link -- See `/v1/render/local/:id` for content ops (with Studio session) -- See `/v1/render/klaviyo/:id?token=...` for CRM manager (with preview token) -- Response header `X-Preview-Status` reports resolved vs. stubbed counts and accuracy % - -**Rendering pipeline**: - -1. Fetch promotion + campaign context -2. Build MJML from emailSlots -3. Resolve previewContext tokens (sample data) -4. Stub unresolved Klaviyo tags (fallback values) -5. Render MJML → HTML -6. Sanitize with DOMPurify (whitelist ~20 tags) -7. Return with X-Preview-Status header - -**Entry point**: `packages/render-email/src/index.ts` (renderPromotionLocal, renderPromotionKlaviyo stubs) - -### 4. Dispatch a promotion to Klaviyo - -- Approve a promotion (workflow.state document status → approved) -- on-promotion-approved Function trigger fires -- Compose KlaviyoPayload from promotion + campaign context -- Create template in Klaviyo -- Create campaign from template, targeting segment list -- Send campaign (or schedule for later) -- Log sendId in promotion; update campaignPerformance - -**Entry point**: `functions/on-promotion-approved/index.ts` (placeholder → real promotion fetch, composer, dispatcher) - -**ESP pattern**: Open-closed via exports: `@starter/esp-connector/klaviyo` for Klaviyo, extend with `./braze`, `./ajo` for other ESPs. Dispatcher wraps connector with retry logic, timeout, error handling. - -### 5. Sync Klaviyo audiences into Sanity - -- Create a klaviyoImport document with importState = "requested" -- Trigger: import-klaviyo Function fires -- Fetch lists and segments from Klaviyo API -- Create/update segment documents: externalId (Klaviyo ID), name, type, description, memberCount (readOnly) -- CRM manager enriches each segment: affinityDescription, typicalCopyTone, engagementTier (editable layer persists across re-syncs) -- Segments appear in campaign audience targeting - -**Entry point**: `functions/import-klaviyo/index.ts` (placeholder → real Klaviyo API calls, segment upserts) - -### 6. Track engagement and update campaign performance - -- Klaviyo sends webhook for: opened, clicked, bounced, unsubscribed -- engagement-log-back Function receives event -- Maps Klaviyo campaignId to Sanity promotion ID -- Increments campaignPerformance counters (openRate, CTR, conversionRate) -- Patches promotion document - -**Entry point**: `functions/engagement-log-back/index.ts` (placeholder → real webhook verify, promotion fetch, patch) - -**Dashboard**: `apps/campaign-dashboard/` queries promotions, aggregates performance by segment, shows cycle time and risk (deadline approaching). - -## Security & Operations - -### 7-Layer Defense for Preview Service - -1. **Transport** — HTTPS only, HSTS header enforced -2. **Auth (3 paths)** - - Studio session: browser cookie + `createStudioAgent` auth inheritance - - Preview tokens: @sanity/preview-url-secret, time-bounded, per-link - - Webhook signatures: Klaviyo HMAC-SHA256, timestamp validation -3. **Input validation** — Whitelist document IDs (Sanity format), enum status values -4. **Render-time** — DOMPurify sanitization, MJML validation, Handlebars syntax preserved -5. **Output headers** — CSP, X-Content-Type-Options, X-Frame-Options, Permissions-Policy, HSTS -6. **Rate limiting** — Per-IP token bucket (100 req/min default), 429 w/ Retry-After -7. **Audit logging** — Timestamp, method, path, status, IP, duration (PII redacted) - -See [references/security.md](references/security.md) for threat model and configuration checklist. - -### Testing Strategy - -- **Unit**: MJML rendering, stub handling, sanitization, middleware composition, rate limiting -- **Integration**: Preview routes with auth, error handling, response headers -- **Load**: k6/Artillery for preview service capacity planning - -See [references/testing.md](references/testing.md) for test examples. - -## Customization - -### Brand Voice - -Replace `studio/schemaTypes/reference-data/brandVoice.ts` fields: - -- toneTraits: array of tags (e.g., "authoritative", "witty", "empathetic") -- writingStyleRules: array of strings (e.g., "avoid passive voice", "use Oxford comma") -- prohibitedWords: words to avoid in generated copy -- emailGuidelines: subject line patterns, CTA vocabulary, urgency framing -- legalConstraints: required disclaimers, opt-out language - -Editors maintain this singleton document in Studio. All AI generation pulls from it via `@sanity/context`. - -### Add New ESP (e.g., Braze) - -1. Create `packages/esp-connector/src/braze/` with BrazeConnector + payload types -2. Export from `packages/esp-connector/src/index.ts` -3. Update `functions/on-promotion-approved/` to accept ESP selection (or hardcode) -4. Wire webhook handler in `functions/engagement-log-back/` - -No changes to campaign, promotion, or reference-data schemas. Pattern is extensible. - -### Segment Enrichment - -Two-layer segments keep your sync idempotent. After importing from Klaviyo, enrichment fields persist: - -- affinityDescription: free-text summary of segment behavior -- typicalCopyTone: tags (e.g., "value-conscious", "tech-savvy", "luxury-focused") -- engagementTier: enum (low, mid, high, vip) - -These become part of local context for AI generation (via @sanity/context). If Klaviyo updates the synced layer (name, memberCount), enrichment fields are untouched. - -## References - -- [references/architecture.md](references/architecture.md) — project map and file entry points -- [references/security.md](references/security.md) — 7-layer defense, threat model, config checklist -- [references/testing.md](references/testing.md) — unit/integration/load testing examples -- [references/add-to-existing-studio.md](references/add-to-existing-studio.md) — brownfield: add email marketing to existing Sanity project -- [README.md](../../README.md) — quick start, environment variables, Klaviyo API key setup diff --git a/email-marketing/skills/esp-connector-pattern/SKILL.md b/email-marketing/skills/esp-connector-pattern/SKILL.md deleted file mode 100644 index 8c229de..0000000 --- a/email-marketing/skills/esp-connector-pattern/SKILL.md +++ /dev/null @@ -1,321 +0,0 @@ ---- -name: esp-connector-pattern -description: Build ESP-agnostic email dispatch layers. Core interface, Klaviyo reference implementation, Braze and AJO extension patterns. Trigger on: ESP integration, connector development, payload composition, add new email service provider, multi-ESP support. ---- - -# ESP-Agnostic Connector Pattern - -Build pluggable integrations for any Email Service Provider (ESP). The pattern separates the interface contract from the implementation: a Sanity Function calls a generic `EspConnector` interface; one module per ESP implements that interface with vendor-specific payload composition and dispatch logic. Adding Braze or AJO means writing new code, never modifying existing Klaviyo code. - -## Core Principle - -**Open-Closed Principle:** New ESPs add new code (new `./braze`, `./ajo` exports) without ever modifying the existing Klaviyo implementation. The interface is stable; implementations extend it. - -## Architecture - -### Package: `@starter/esp-connector` - -Lives at `packages/esp-connector/` with `"name": "@starter/esp-connector"` in package.json. - -**Exports:** - -- `.` — `EspConnector` interface, `createPayloadDispatcher()` factory with retry logic -- `./klaviyo` — `KlaviyoConnector` class, `KlaviyoPayload` type -- `./types` — shared types -- `./braze` — (future) `BrazeConnector` class, `BrazePayload` type -- `./ajo` — (future) `AdobeAjoConnector` class, `AjoPayload` type - -**Internal cross-package references use `#imports`:** - -```json -{ - "imports": { - "#types": "./src/types.ts", - "#utils": "./src/utils.ts" - } -} -``` - -No deep relative paths within the package (`../../types`); all references go through `#imports`. - -### Core Interface - -```typescript -export interface EspConnector { - compose(input: ComposerInput): Promise - dispatch(payload: TPayload, adapter: DispatchAdapter): Promise - verify?(payload: TPayload): Promise -} - -export interface ComposerInput { - promotionId: string - campaignId: string - segmentId: string - subjectLine: string - preheader: string - disruptor: string - htmlBody: string - campaignName: string - segments: string[] - personalizationTokens: Record - brandVoice: BrandVoiceContext -} - -export interface DispatchAdapter { - fetch: typeof fetch - timeout: number - maxRetries: number -} - -export interface DispatchResult { - success: boolean - campaignId: string - templateId: string - sendId?: string - error?: string -} -``` - -Implementations are **not** required to match Klaviyo's JSON:API format — each ESP is free to compose its own payload shape. The `TPayload` generic is the escape hatch. - -## Klaviyo Reference Implementation - -Entry point: `packages/esp-connector/src/klaviyo/connector.ts` - -### Structure - -``` -packages/esp-connector/src/klaviyo/ -├── client.ts — Klaviyo API client (klaviyoFetch, v2025-07-15) -├── connector.ts — KlaviyoConnector class (implements EspConnector) -├── payload.ts — KlaviyoPayload type + compose logic -├── index.ts — exports for ./klaviyo subpath -``` - -### Key Components - -**`client.ts` — Klaviyo API client** - -- `klaviyoFetch(method, path, body?, options?)` — wraps fetch with auth headers, Revision header -- `createKlaviyoTemplate()` — POST /api/templates (create email template) -- `createKlaviyoCampaign()` — POST /api/campaigns (create campaign from template) -- `sendKlaviyoCampaign()` — POST /api/campaigns/:id/send (trigger send) -- `getKlaviyoLists()` — GET /api/lists (fetch audience lists) -- `getKlaviyoSegments()` — GET /api/segments (fetch audience segments) - -**`connector.ts` — KlaviyoConnector** - -Implements `EspConnector`: - -- `compose(input)` — assembles KlaviyoPayload JSON from promotion + campaign context -- `dispatch(payload, adapter)` — POST to Klaviyo API with retry logic, timeout, error handling -- `verify?(payload)` — (optional) test-render the payload without sending - -**`payload.ts` — Payload composition** - -Builds the Klaviyo JSON:API request: - -```typescript -interface KlaviyoPayload { - data: { - type: 'email-template' - attributes: { - name: string - subject_line: string - preheader_text: string - html_body: string - } - } -} -``` - -## How to Add a New ESP (Braze Example) - -### Step 1: Create the Braze module structure - -``` -packages/esp-connector/src/braze/ -├── client.ts — Braze API client -├── connector.ts — BrazeConnector class -├── payload.ts — BrazePayload composition -└── index.ts — exports for ./braze subpath -``` - -### Step 2: Implement the connector - -```typescript -// packages/esp-connector/src/braze/connector.ts -import {EspConnector, ComposerInput, DispatchAdapter} from '#types' - -export class BrazeConnector implements EspConnector { - constructor(apiKey: string) { - this.apiKey = apiKey - } - - async compose(input: ComposerInput): Promise { - // Braze-specific payload shape (different from Klaviyo's) - return { - name: input.campaignName, - template_id: '...', // or create template inline - segment_id: input.segmentId, - trigger_properties: { - personalization_tokens: input.personalizationTokens, - }, - } - } - - async dispatch(payload: BrazePayload, adapter: DispatchAdapter): Promise { - // Braze-specific API call - const response = await brazeFetch('POST', '/api/campaigns/trigger/send', payload) - return { - success: response.ok, - campaignId: payload.name, - sendId: response.data.send_id, - } - } -} - -export interface BrazePayload { - name: string - template_id: string - segment_id: string - trigger_properties: Record -} -``` - -### Step 3: Export the subpath - -In `packages/esp-connector/package.json`: - -```json -{ - "exports": { - ".": "./src/index.ts", - "./klaviyo": "./src/klaviyo/index.ts", - "./braze": "./src/braze/index.ts", - "./types": "./src/types.ts" - } -} -``` - -### Step 4: Update the send Function - -In `functions/on-promotion-approved/index.ts`: - -```typescript -import {KlaviyoConnector} from '@starter/esp-connector/klaviyo' -import {BrazeConnector} from '@starter/esp-connector/braze' - -const esp = process.env.ESP_PROVIDER // 'klaviyo' | 'braze' -const connector = - esp === 'braze' - ? new BrazeConnector(process.env.BRAZE_API_KEY) - : new KlaviyoConnector(process.env.KLAVIYO_API_KEY) -``` - -**The existing Klaviyo code never changes.** You only add new Braze files. - -## Dispatch with Retry Logic - -The `createPayloadDispatcher()` factory wraps any connector with resilience: - -```typescript -import {createPayloadDispatcher} from '@starter/esp-connector' - -const dispatcher = createPayloadDispatcher({ - espConnector: new KlaviyoConnector(apiKey), - maxRetries: 3, - backoffMs: 1000, // exponential: 1s, 2s, 4s - timeoutMs: 30000, -}) - -const result = await dispatcher.dispatch(payload, { - fetch: globalThis.fetch, - timeout: 30000, - maxRetries: 3, -}) -``` - -Retries on: - -- Network timeouts -- 5xx status codes -- Transient Klaviyo errors (rate limit, temporary outages) - -Does NOT retry on: - -- 4xx errors (validation, auth failures) -- Payload structure errors - -## Testing the Connector - -Unit test template (no external API calls): - -```typescript -describe('KlaviyoConnector', () => { - it('should compose a valid Klaviyo payload', async () => { - const connector = new KlaviyoConnector('test-key') - const input: ComposerInput = { - promotionId: 'promo-1', - campaignId: 'camp-1', - segmentId: 'seg-1', - subjectLine: 'Test Subject', - preheader: 'Test Preheader', - htmlBody: '', - disruptor: 'Test Disruptor', - campaignName: 'Test Campaign', - segments: ['seg-1'], - personalizationTokens: {first_name: 'John'}, - brandVoice: {toneTraits: ['friendly']}, - } - const payload = await connector.compose(input) - expect(payload.data.attributes.subject_line).toBe('Test Subject') - }) - - it('should handle dispatch errors gracefully', async () => { - const mockAdapter: DispatchAdapter = { - fetch: async () => new Response('{}', {status: 500}), - timeout: 5000, - maxRetries: 3, - } - const connector = new KlaviyoConnector('test-key') - const result = await connector.dispatch(mockPayload, mockAdapter) - expect(result.success).toBe(false) - }) -}) -``` - -## Jobs to Be Done - -### 1. Extend to a new ESP (Braze, HubSpot, etc.) - -- Understand the target ESP's API (template creation, campaign send, list targeting) -- Create `./src/{esp}/client.ts` with API wrappers -- Create `./src/{esp}/connector.ts` implementing `EspConnector<{Esp}Payload>` -- Add export to `package.json#exports` -- Update `functions/on-promotion-approved/` to instantiate the right connector based on config -- Write unit tests for payload composition - -### 2. Compose a promotion into an ESP payload - -- Given a promotion document, campaign context, and brand voice, call `connector.compose(input)` -- Understand what fields the target ESP requires (subject, template, segment list, etc.) -- Map Sanity field names to ESP field names (Klaviyo `{% variable %}` vs. Braze `{{ variable }}`) - -### 3. Dispatch to the ESP with resilience - -- Call `createPayloadDispatcher()` wrapping your connector -- Use the dispatcher's `dispatch(payload)` method with retry + timeout behavior -- Log successes and failures; write campaign ID and send ID back to Sanity - -### 4. Test the payload before sending - -- Call `connector.verify?()` to test-render or validate without triggering a live send -- Useful for the Klaviyo verification preview endpoint - -## References - -- `packages/esp-connector/src/index.ts` — interface definitions and dispatcher factory -- `packages/esp-connector/src/klaviyo/` — Klaviyo reference implementation -- `functions/on-promotion-approved/index.ts` — send Function entry point -- `packages/esp-connector/src/types.ts` — shared types and interfaces diff --git a/email-marketing/skills/example/SKILL.md b/email-marketing/skills/example/SKILL.md deleted file mode 100644 index 2add6ef..0000000 --- a/email-marketing/skills/example/SKILL.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -name: example -description: 'Example skill placeholder. Replace this with a real skill for your starter.' ---- - -# Example Skill - -This is a placeholder. Create skills to extend Claude Code with starter-specific workflows. - -## When to use - -Describe when this skill should be triggered. - -## Workflow - -1. Step one -2. Step two -3. Step three diff --git a/email-marketing/skills/klaviyo-integration/SKILL.md b/email-marketing/skills/klaviyo-integration/SKILL.md deleted file mode 100644 index 5d43de8..0000000 --- a/email-marketing/skills/klaviyo-integration/SKILL.md +++ /dev/null @@ -1,386 +0,0 @@ ---- -name: klaviyo-integration -description: 'Integrate with Klaviyo: API key setup, sync lists and segments, compose and send campaigns, verify templates, handle webhooks. Entry points: KlaviyoConnector, import-klaviyo Function, on-promotion-approved Function, engagement-log-back webhook handler. Trigger on: Klaviyo API, email send, segment sync, engagement tracking, ESP configuration.' ---- - -# Klaviyo Integration for Email Marketing - -Send campaigns through Klaviyo from Sanity. Sync audience lists and segments from Klaviyo; compose and dispatch promotions with template creation and campaign sending; handle inbound engagement webhooks. All wired through the `@starter/esp-connector/klaviyo` reference implementation. - -## Setup - -### 1. Obtain Klaviyo API Key - -In Klaviyo: - -1. Go to **Settings** → **API Keys** -2. Click **Create Private API Key** -3. Name it (e.g., "Sanity Starter") -4. Select **Custom** scope and enable: - - Lists: Read - - Segments: Read - - Templates: Read/Write - - Campaigns: Read/Write - -Copy the private key (format: `pk_...`). - -### 2. Set Environment Variables - -```bash -npx sanity functions env add on-promotion-approved KLAVIYO_API_KEY pk_your_key_here -npx sanity functions env add import-klaviyo KLAVIYO_API_KEY pk_your_key_here -npx sanity functions env add engagement-log-back KLAVIYO_API_KEY pk_your_key_here -``` - -Or via `sanity.json` blueprint config for automatic setup. - -## Architecture - -### Package: `@starter/esp-connector/klaviyo` - -Entry point: `packages/esp-connector/src/klaviyo/` - -**Structure:** - -``` -packages/esp-connector/src/klaviyo/ -├── client.ts — Klaviyo API client -├── connector.ts — KlaviyoConnector class -├── payload.ts — KlaviyoPayload composition -└── index.ts — exports for ./klaviyo subpath -``` - -### Klaviyo API Client - -**File:** `packages/esp-connector/src/klaviyo/client.ts` - -Wraps the Klaviyo v2025-07-15 API with authentication headers and error handling. - -**Core functions:** - -```typescript -export async function klaviyoFetch( - method: 'GET' | 'POST' | 'PATCH' | 'DELETE', - path: string, - body?: unknown, - options?: {apiKey?: string; timeout?: number}, -): Promise> - -// Templates -export async function createKlaviyoTemplate( - templateName: string, - htmlBody: string, - options: {apiKey: string; subject: string; preheader: string}, -): Promise<{id: string}> - -export async function getKlaviyoTemplate( - templateId: string, - options: {apiKey: string}, -): Promise<{id: string; name: string; html: string}> - -// Campaigns -export async function createKlaviyoCampaign( - campaignName: string, - templateId: string, - listId: string, - segmentIds?: string[], - options?: {apiKey: string}, -): Promise<{id: string; status: 'draft' | 'scheduled' | 'sent'}> - -export async function sendKlaviyoCampaign( - campaignId: string, - options: {apiKey: string; scheduled?: boolean; sendTime?: string}, -): Promise<{status: 'sending' | 'sent'}> - -// Audiences -export async function getKlaviyoLists(options: { - apiKey: string -}): Promise> - -export async function getKlaviyoSegments(options: { - apiKey: string -}): Promise> - -// Template verification -export async function renderKlaviyoTemplate( - templateId: string, - personalizationData?: Record, - options?: {apiKey: string}, -): Promise<{html: string; errors: Array<{field: string; reason: string}>}> -``` - -### KlaviyoConnector - -**File:** `packages/esp-connector/src/klaviyo/connector.ts` - -Implements the `EspConnector` interface. - -```typescript -export class KlaviyoConnector implements EspConnector { - constructor(apiKey: string) { - this.apiKey = apiKey - } - - async compose(input: ComposerInput): Promise { - // Assembles Klaviyo JSON:API payload - return { - data: { - type: 'email-template', - attributes: { - name: input.campaignName, - subject_line: input.subjectLine, - preheader_text: input.preheader, - html_body: this.injectPersonalizationTokens(input.htmlBody, input.personalizationTokens), - editor: 'custom', - }, - }, - } - } - - async dispatch(payload: KlaviyoPayload, adapter: DispatchAdapter): Promise { - // 1. Create template - const templateRes = await createKlaviyoTemplate( - payload.data.attributes.name, - payload.data.attributes.html_body, - { - apiKey: this.apiKey, - subject: payload.data.attributes.subject_line, - preheader: payload.data.attributes.preheader_text, - }, - ) - - // 2. Create campaign - const campaignRes = await createKlaviyoCampaign( - payload.data.attributes.name, - templateRes.id, - payload.listId, - payload.segmentIds, - {apiKey: this.apiKey}, - ) - - // 3. Send campaign - const sendRes = await sendKlaviyoCampaign(campaignRes.id, { - apiKey: this.apiKey, - scheduled: payload.scheduledFor ? true : false, - sendTime: payload.scheduledFor, - }) - - return { - success: sendRes.status === 'sent' || sendRes.status === 'sending', - campaignId: campaignRes.id, - templateId: templateRes.id, - sendId: campaignRes.id, - } - } - - verify?(payload: KlaviyoPayload): Promise { - // Test-render without sending - return renderKlaviyoTemplate(payload.templateId, payload.personalizationData, { - apiKey: this.apiKey, - }) - } - - private injectPersonalizationTokens(html: string, tokens: Record): string { - // Convert Sanity preview context tokens to Klaviyo syntax - // { first_name: "John" } → {{ profile.first_name }} - let result = html - for (const [key, value] of Object.entries(tokens)) { - result = result.replace(`{{${key}}}`, `{{ profile.${key} }}`) - } - return result - } -} -``` - -## Functions - -### 1. `import-klaviyo` — Sync lists and segments - -**File:** `functions/import-klaviyo/index.ts` - -Triggered by a request document (`klaviyoImport` type with `importState: 'requested'`). - -**Workflow:** - -1. Fetch all Klaviyo lists via `getKlaviyoLists()` -2. Fetch all Klaviyo segments via `getKlaviyoSegments()` -3. For each list, create or update a Sanity `list` document -4. For each segment, create or update a Sanity `segment` document -5. Mark `importState` as `'complete'` - -**Key:** - -- `segment` documents are **two-layer**: readOnly synced fields (`externalId`, `name`, `memberCount`) + editable enrichment fields (`affinityDescription`, `typicalCopyTone`, `engagementTier`) -- The sync only overwrites the readOnly layer; enrichment persists across re-syncs -- Use `externalId` as the foreign key to Klaviyo's segment ID - -**Schema pattern:** - -```typescript -// studio/schemaTypes/segment.ts -{ - name: 'segment', - type: 'document', - fields: [ - // Synced (readOnly) - { name: 'externalId', type: 'string', readOnly: true }, - { name: 'name', type: 'string', readOnly: true }, - { name: 'description', type: 'text', readOnly: true }, - { name: 'memberCount', type: 'number', readOnly: true }, - - // Enrichment (editable) - { name: 'affinityDescription', type: 'text' }, // CRM-authored audience brief - { name: 'typicalCopyTone', type: 'array', of: [{ type: 'string' }] }, // tags - { name: 'engagementTier', type: 'string', options: { list: ['low', 'mid', 'high', 'vip'] } }, - ], -} -``` - -### 2. `on-promotion-approved` — Send via Klaviyo - -**File:** `functions/on-promotion-approved/index.ts` - -Triggered by `workflow.state` approval (promotion `status: 'approved'`). - -**Workflow:** - -1. Fetch promotion + campaign context -2. Build `KlaviyoPayload` via `new KlaviyoConnector(apiKey).compose()` -3. Dispatch via `createPayloadDispatcher(...).dispatch()` -4. Patch promotion document: write `sendId`, `sentAt`, `sendState: 'sent'` -5. If dispatch fails, patch with `sendState: 'error'` + error message - -**Key patterns:** - -- Use the retry dispatcher to handle transient Klaviyo API failures -- Log successes and failures with campaign + segment context -- Never modify a published promotion after send (idempotence) - -### 3. `engagement-log-back` — Inbound Klaviyo webhooks - -**File:** `functions/engagement-log-back/index.ts` - -Webhook handler for Klaviyo engagement events (opens, clicks, bounces, unsubscribes). - -**Webhook setup in Klaviyo:** - -1. Go to **Settings** → **Integrations** → **Webhooks** -2. Create webhook: - - URL: `https://[your-domain]/functions/engagement-log-back` - - Events: `email.open`, `email.click`, `email.bounce`, `email.unsubscribe` - - Custom header: `X-Webhook-Signature` (Klaviyo provides the signing key) - -**Workflow:** - -1. Verify webhook signature via HMAC-SHA256 (prevent replay attacks) -2. Parse event: `{ event_type: 'email.open', data: { campaign_id: '...', profile: { email: '...' }, timestamp: '...' } }` -3. Map `campaign_id` (Klaviyo UUID) to Sanity promotion ID -4. Increment counters on `promotion.campaignPerformance`: - - `opens += 1` - - `clicks += 1` (if `email.click`) - - `bounces += 1` (if `email.bounce`) -5. Update `lastEngagementAt` timestamp - -**Schema pattern:** - -```typescript -// studio/schemaTypes/campaignPerformance.ts -{ - name: 'campaignPerformance', - type: 'object', - readOnly: true, - fields: [ - { name: 'sentAt', type: 'datetime', readOnly: true }, - { name: 'opens', type: 'number', readOnly: true }, - { name: 'clicks', type: 'number', readOnly: true }, - { name: 'bounces', type: 'number', readOnly: true }, - { name: 'unsubscribes', type: 'number', readOnly: true }, - { name: 'lastEngagementAt', type: 'datetime', readOnly: true }, - ], -} -``` - -## Preview Service: Klaviyo Verification - -The preview service exposes a `/v1/render/klaviyo/:id` endpoint that: - -1. Fetches promotion + campaign context -2. Builds MJML from emailSlots -3. Resolves preview context tokens (sample data from `campaign.previewContext`) -4. Calls `connector.verify?()` to test-render via Klaviyo's `/api/template-render/` endpoint -5. Returns the Klaviyo-rendered HTML with `X-Preview-Status` accuracy badge - -This endpoint shows CRM managers exactly how the email will render in Klaviyo when sent. - -## Jobs to Be Done - -### 1. Set up Klaviyo in a new Sanity project - -- Create Klaviyo private API key -- Set environment variables on Functions -- Run `import-klaviyo` to sync lists and segments -- Verify `list` and `segment` documents appear in Studio - -### 2. Generate and send a promotion to Klaviyo - -- Create `campaign` brief -- Run "Generate variants" action → creates promotions -- Review and approve a promotion -- Approval triggers `on-promotion-approved` Function -- Function composes `KlaviyoPayload`, calls Klaviyo APIs, writes `sendId` back -- Verify campaign appears in Klaviyo account - -### 3. Verify preview before sending - -- In Presentation tool, load `/v1/render/klaviyo/:promotionId` -- See how Klaviyo's template renderer will output it -- Check `X-Preview-Status` header for token resolution counts - -### 4. Track engagement post-send - -- Configure Klaviyo webhook → `engagement-log-back` Function -- Webhook fires for opens, clicks, bounces, unsubscribes -- Function patches promotion's `campaignPerformance` fields -- Dashboard queries aggregates metrics across variants - -### 5. Re-sync Klaviyo audiences after changes - -- New list added in Klaviyo -- Create `klaviyoImport` document with `importState: 'requested'` -- `import-klaviyo` Function fires -- New `list` and `segment` documents appear; enrichment fields remain - -### 6. Add a new segment variant after initial generation - -- New CDP segment created -- Run "Generate for segment" action on campaign -- Selects the single segment -- `GenerateVariantsAction` creates one new promotion for that segment -- Approve and send as normal - -## Testing - -### Unit tests - -- `KlaviyoConnector.compose()` — given input, produces valid JSON:API payload -- Token injection — `{{ first_name }}` → `{{ profile.first_name }}` - -### Integration tests - -- Mock Klaviyo API responses -- `on-promotion-approved` with valid promotion → creates template, campaign, sends -- `import-klaviyo` with mock list/segment responses → creates Sanity documents -- `engagement-log-back` with valid webhook signature → patches campaignPerformance - -### Manual testing - -- Create campaign, generate variant, approve, verify send in Klaviyo account -- Trigger open/click webhook, verify promotion metrics update in Studio - -## References - -- `packages/esp-connector/src/klaviyo/` — Klaviyo API client and connector -- `functions/on-promotion-approved/` — send Function -- `functions/import-klaviyo/` — segment sync Function -- `functions/engagement-log-back/` — webhook handler -- [Klaviyo API v2025-07-15 docs](https://developers.klaviyo.com/en/reference/api_overview) diff --git a/knowledge-base/AGENT.md b/knowledge-base/AGENT.md index 63d7ab8..9c9a655 100644 --- a/knowledge-base/AGENT.md +++ b/knowledge-base/AGENT.md @@ -1,6 +1,6 @@ # Knowledge Base Starter -Governed Sanity knowledge base feeding two AI surfaces from one private dataset, each scoped by its own Agent Context (hosted MCP) config: an external help center (`app/`, slug `customer-support`) and an internal staff tool (`dashboard/` + `dashboard-server/`, slug `team-kb`). See `README.md` for the full picture and `skills/add-scoped-agent-surface/` for adding more surfaces. +Governed Sanity knowledge base feeding two AI surfaces from one private dataset, each scoped by its own Agent Context (hosted MCP) config: an external help center (`app/`, slug `customer-support`) and an internal staff tool (`dashboard/` + `dashboard-server/`, slug `team-kb`). See `README.md` for the full picture. To add another surface, mint a token, define a new `sanity.agentContext` document with its own `groqFilter` and instructions in `studio/scripts/generate-seed.ts`, and point the new client at its slug. ## Quick start diff --git a/knowledge-base/README.md b/knowledge-base/README.md index 6e4b369..9f01b6c 100644 --- a/knowledge-base/README.md +++ b/knowledge-base/README.md @@ -58,7 +58,6 @@ knowledge-base/ ├── dashboard-server/ # Chat proxy holding the internal token (App SDK is browser-only) ├── functions/ # Sanity Functions ├── packages/@starter/ # Shared eslint / tsconfig / generated types -├── skills/ # Claude Code skills for this starter ├── sanity.blueprint.ts # Function registrations ├── pnpm-workspace.yaml # Workspaces + dependency catalog └── package.json # Root scripts diff --git a/knowledge-base/skills/add-scoped-agent-surface/SKILL.md b/knowledge-base/skills/add-scoped-agent-surface/SKILL.md deleted file mode 100644 index e88cda0..0000000 --- a/knowledge-base/skills/add-scoped-agent-surface/SKILL.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -name: add-scoped-agent-surface -description: Add a new scoped AI surface (audience) to a Sanity knowledge base — an Agent Context config that filters which content an agent can see, plus a server-side chat endpoint that holds the token. Use when adding a partner portal, reseller view, regional surface, or any new audience to this starter, or when applying the one-dataset-many-surfaces pattern to an existing Sanity project. ---- - -# Add a Scoped Agent Surface - -One governed dataset can feed any number of AI surfaces, each seeing only the content meant for its audience. This starter ships two — an external help center (`customer-support`) and an internal staff tool (`team-kb`) — and the pattern extends to more: partners, resellers, regions, tiers. - -A surface is four things: - -1. A **`sanity.agentContext` document** — the contract: a GROQ filter scoping which documents the agent can see, plus instructions tuning how it queries -2. A **read token** held server-side (the dataset is private; no token ever reaches the browser) -3. An **MCP URL** addressing that config: `https://api.sanity.io/v2025-03-01/agent-context///` -4. A **server-side chat endpoint** that connects the LLM to that MCP URL - -## Workflow - -### Step 1: Create the Agent Context document - -Add it to the seed generator (`studio/scripts/generate-seed.ts`) or create it directly in the dataset. The two shipped configs are the reference: - -```ts -{ - _id: 'agentContext.partner', - _type: 'sanity.agentContext', - version: '1', - name: 'Partner Portal', - slug: {_type: 'slug', current: 'partner-portal'}, - groqFilter: '_type in ["helpArticle", "faq", "playbook", "product", "topic"]', - instructions: PARTNER_INSTRUCTIONS, -} -``` - -- `groqFilter` is the access boundary — only matching documents are visible through this surface. It can filter on any field, not just `_type` (e.g. `audience` arrays, `status == "published"`). -- `instructions` is a system-prompt addendum the MCP serves to the agent: describe the content model, which types answer which questions, and how documents reference each other. Copy the structure of `EXTERNAL_INSTRUCTIONS` / `INTERNAL_INSTRUCTIONS` in the seed generator. - -Publish the document (seed import publishes it; a draft is invisible to MCP). - -### Step 2: Deploy the Studio - -Agent Context MCP requires a **deployed Studio** — a deployed schema alone returns JSON-RPC error `-32004`. - -```sh -pnpm --filter studio exec sanity deploy -``` - -### Step 3: Mint a read token for the surface - -One token per surface keeps the security story clean (revoke one surface without touching the others): - -```sh -pnpm --filter studio exec sanity tokens add "Partner surface" --role viewer --project-id --json -y -``` - -The token is in the `.key` field of the JSON output. Put it in the env file of whatever server hosts the chat endpoint — never in browser-bundled env vars (anything `NEXT_PUBLIC_*` / `SANITY_APP_*` ships to the client). - -### Step 4: Wire the chat endpoint - -Pick the host based on where the UI lives: - -- **UI in a server-backed app (Next.js):** copy `app/app/api/chat/route.ts` — `createMCPClient` (http transport, Bearer token) + `streamText` + a `displayCards` UI tool, capped with `stepCountIs(8)`. -- **UI in a browser-only app (App SDK, SPA):** copy `dashboard-server/src/index.ts` — same pattern behind a small Hono proxy with CORS locked to the UI origin. The App SDK has no server and cannot hold secrets; the proxy is the secret boundary. - -Point the endpoint at the new surface via env: - -```sh -SANITY_AGENT_CONTEXT_URL=https://api.sanity.io/v2025-03-01/agent-context///partner-portal -SANITY_READ_TOKEN_PARTNER=sk... -``` - -### Step 5: Verify - -List the MCP tools directly (note the dual `Accept` header — the endpoint requires it; the AI SDK sets it automatically): - -```sh -curl -s https://api.sanity.io/v2025-03-01/agent-context///partner-portal \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' -``` - -Expect `initial_context`, `groq_query`, `schema_explorer`, `array_field_reader`. Then ask the chat UI "What content do you have access to?" — the answer should reflect the `groqFilter`, nothing more. - -## Gotchas - -- **MCP returns `-32004`** → the Studio is not deployed (schema deploy alone is not enough). -- **Tools list is empty / config not found** → the `sanity.agentContext` document is a draft; publish it. -- **Agent sees too much/too little** → the `groqFilter` is the only scoping; the viewer token itself reads the whole dataset. Test the filter in Vision before shipping. -- **Semantic search errors** → hybrid search needs Dataset Embeddings enabled (`sanity datasets embeddings enable`); `text::semanticSimilarity()` only works inside `score()`. Keep a keyword `match` fallback (see `app/sanity/search.ts`). -- **New document types** → add them to the relevant `groqFilter`s and mention them in `instructions`, or no surface will surface them.