{"owner":"tambo-ai","repo":"tambo","hasSkills":true,"totalSkillsCount":193,"totalTokensCount":75106,"categories":["anthropic-skill","marketplace","root-instruction","claude-rule","subagent-persona","command-prompt","plugin-manifest"],"hasMcp":true,"mcpConfig":{"mcpServers":{"tambo":{"command":"npx","args":["-y","@modelcontextprotocol/server-tambo"]}}},"found":[".claude/skills/ai-sdk-model-manager/SKILL.md",".claude/skills/creating-styled-wrappers/SKILL.md",".claude/skills/api-resource-lifecycle/SKILL.md",".claude/skills/compound-components/SKILL.md",".claude/skills/validating-accessibility/SKILL.md",".claude-plugin/marketplace.json",".claude/skills/building-settings-ui/SKILL.md","plugins/tambo/skills/generative-ui/SKILL.md",".github/AGENTS.md","CLAUDE.md","AGENTS.md","cli/AGENTS.md","cli/CLAUDE.md","create-tambo-app/AGENTS.md","create-tambo-app/CLAUDE.md","docs/AGENTS.md","docs/CLAUDE.md","react-sdk/AGENTS.md","react-sdk/CLAUDE.md","showcase/AGENTS.md","showcase/CLAUDE.md",".claude/agents/planner.md",".claude/agents/researcher.md",".claude/commands/commit.md",".claude/commands/create-pr.md",".claude/commands/execute.md",".claude/commands/plan.md","packages/backend/README.md","packages/backend/package.json","packages/backend/tsconfig.build.json","packages/backend/tsconfig.json","packages/client/AGENTS.md","packages/client/CHANGELOG.md","packages/client/CLAUDE.md","packages/client/README.md","packages/client/package.json","packages/client/tsconfig.cjs.json","packages/client/tsconfig.esm.json","packages/client/tsconfig.json","packages/core/README.md","packages/core/package.json","packages/core/tsconfig.json","packages/db/README.md","packages/db/package.json","packages/db/tsconfig.json","packages/eslint-config/README.md","packages/eslint-config/package.json","packages/react-ui-base/CHANGELOG.md","packages/react-ui-base/README.md","packages/react-ui-base/package.json","packages/react-ui-base/tsconfig.json","packages/testing/package.json","packages/testing/tsconfig.json","packages/typescript-config/base.json","packages/typescript-config/nextjs.json","packages/typescript-config/package.json","packages/typescript-config/react-library.json","packages/ui-registry/AGENTS.md","packages/ui-registry/package.json","packages/ui-registry/tsconfig.json","packages/vite-config/package.json","packages/vite-config/tsconfig.json","plugins/tambo/README.md",".claude/skills/compound-components/examples.md","plugins/tambo/.claude-plugin/plugin.json",".claude/skills/creating-styled-wrappers/references/real-world-example.md","packages/db/migrations/meta/0000_snapshot.json","packages/db/migrations/meta/0001_snapshot.json","packages/db/migrations/meta/0002_snapshot.json","packages/db/migrations/meta/0003_snapshot.json","packages/db/migrations/meta/0004_snapshot.json","packages/db/migrations/meta/0005_snapshot.json","packages/db/migrations/meta/0006_snapshot.json","packages/db/migrations/meta/0007_snapshot.json","packages/db/migrations/meta/0008_snapshot.json","packages/db/migrations/meta/0009_snapshot.json","packages/db/migrations/meta/0010_snapshot.json","packages/db/migrations/meta/0011_snapshot.json","packages/db/migrations/meta/0012_snapshot.json","packages/db/migrations/meta/0013_snapshot.json","packages/db/migrations/meta/0014_snapshot.json","packages/db/migrations/meta/0015_snapshot.json","packages/db/migrations/meta/0016_snapshot.json","packages/db/migrations/meta/0017_snapshot.json","packages/db/migrations/meta/0018_snapshot.json","packages/db/migrations/meta/0019_snapshot.json","packages/db/migrations/meta/0020_snapshot.json","packages/db/migrations/meta/0021_snapshot.json","packages/db/migrations/meta/0022_snapshot.json","packages/db/migrations/meta/0023_snapshot.json","packages/db/migrations/meta/0024_snapshot.json","packages/db/migrations/meta/0025_snapshot.json","packages/db/migrations/meta/0026_snapshot.json","packages/db/migrations/meta/0027_snapshot.json","packages/db/migrations/meta/0028_snapshot.json","packages/db/migrations/meta/0029_snapshot.json","packages/db/migrations/meta/0030_snapshot.json","packages/db/migrations/meta/0031_snapshot.json","packages/db/migrations/meta/0032_snapshot.json","packages/db/migrations/meta/0033_snapshot.json","packages/db/migrations/meta/0034_snapshot.json","packages/db/migrations/meta/0035_snapshot.json","packages/db/migrations/meta/0036_snapshot.json","packages/db/migrations/meta/0037_snapshot.json","packages/db/migrations/meta/0038_snapshot.json","packages/db/migrations/meta/0039_snapshot.json","packages/db/migrations/meta/0040_snapshot.json","packages/db/migrations/meta/0041_snapshot.json","packages/db/migrations/meta/0042_snapshot.json","packages/db/migrations/meta/0043_snapshot.json","packages/db/migrations/meta/0044_snapshot.json","packages/db/migrations/meta/0045_snapshot.json","packages/db/migrations/meta/0046_snapshot.json","packages/db/migrations/meta/0047_snapshot.json","packages/db/migrations/meta/0048_snapshot.json","packages/db/migrations/meta/0049_snapshot.json","packages/db/migrations/meta/0050_snapshot.json","packages/db/migrations/meta/0052_snapshot.json","packages/db/migrations/meta/0053_snapshot.json","packages/db/migrations/meta/0054_snapshot.json","packages/db/migrations/meta/0055_snapshot.json","packages/db/migrations/meta/0056_snapshot.json","packages/db/migrations/meta/0057_snapshot.json","packages/db/migrations/meta/0058_snapshot.json","packages/db/migrations/meta/0059_snapshot.json","packages/db/migrations/meta/0060_snapshot.json","packages/db/migrations/meta/0061_snapshot.json","packages/db/migrations/meta/0062_snapshot.json","packages/db/migrations/meta/0063_snapshot.json","packages/db/migrations/meta/0064_snapshot.json","packages/db/migrations/meta/0065_snapshot.json","packages/db/migrations/meta/0066_snapshot.json","packages/db/migrations/meta/0067_snapshot.json","packages/db/migrations/meta/0068_snapshot.json","packages/db/migrations/meta/0069_snapshot.json","packages/db/migrations/meta/0070_snapshot.json","packages/db/migrations/meta/0071_snapshot.json","packages/db/migrations/meta/0072_snapshot.json","packages/db/migrations/meta/0073_snapshot.json","packages/db/migrations/meta/0074_snapshot.json","packages/db/migrations/meta/0075_snapshot.json","packages/db/migrations/meta/0076_snapshot.json","packages/db/migrations/meta/0077_snapshot.json","packages/db/migrations/meta/0078_snapshot.json","packages/db/migrations/meta/0079_snapshot.json","packages/db/migrations/meta/0080_snapshot.json","packages/db/migrations/meta/0081_snapshot.json","packages/db/migrations/meta/0082_snapshot.json","packages/db/migrations/meta/0083_snapshot.json","packages/db/migrations/meta/0084_snapshot.json","packages/db/migrations/meta/0085_snapshot.json","packages/db/migrations/meta/0086_snapshot.json","packages/db/migrations/meta/0087_snapshot.json","packages/db/migrations/meta/0088_snapshot.json","packages/db/migrations/meta/0089_snapshot.json","packages/db/migrations/meta/0090_snapshot.json","packages/db/migrations/meta/0091_snapshot.json","packages/db/migrations/meta/0092_snapshot.json","packages/db/migrations/meta/0093_snapshot.json","packages/db/migrations/meta/0094_snapshot.json","packages/db/migrations/meta/_journal.json","packages/ui-registry/src/components/control-bar/config.json","packages/ui-registry/src/components/edit-with-tambo-button/config.json","packages/ui-registry/src/components/elicitation-ui/config.json","packages/ui-registry/src/components/form/config.json","packages/ui-registry/src/components/graph/config.json","packages/ui-registry/src/components/input-fields/config.json","packages/ui-registry/src/components/map/config.json","packages/ui-registry/src/components/mcp-components/config.json","packages/ui-registry/src/components/message-input/config.json","packages/ui-registry/src/components/message-suggestions/config.json","packages/ui-registry/src/components/message-thread-collapsible/config.json","packages/ui-registry/src/components/message-thread-full/config.json","packages/ui-registry/src/components/message-thread-panel/config.json","packages/ui-registry/src/components/message/config.json","packages/ui-registry/src/components/scrollable-message-container/config.json","packages/ui-registry/src/components/thread-content/config.json","packages/ui-registry/src/components/thread-dropdown/config.json","packages/ui-registry/src/components/thread-history/config.json","plugins/tambo/skills/building-with-tambo/references/add-components-to-registry.md","plugins/tambo/skills/building-with-tambo/references/cli.md","plugins/tambo/skills/building-with-tambo/references/component-rendering.md","plugins/tambo/skills/building-with-tambo/references/components.md","plugins/tambo/skills/building-with-tambo/references/skills.md","plugins/tambo/skills/building-with-tambo/references/threads.md","plugins/tambo/skills/building-with-tambo/references/tools-and-context.md","plugins/tambo/skills/generative-ui/references/cli.md","plugins/tambo/skills/generative-ui/references/component-rendering.md","plugins/tambo/skills/generative-ui/references/components.md","plugins/tambo/skills/generative-ui/references/skills.md","plugins/tambo/skills/generative-ui/references/threads.md","plugins/tambo/skills/generative-ui/references/tools-and-context.md","docs/content/docs/reference/cli/commands/meta.json"],"skills":{".claude/skills/ai-sdk-model-manager/SKILL.md":"---\nname: ai-sdk-model-manager\ndescription: Manages AI SDK model configurations - updates packages, identifies missing models, adds new models with research, and updates documentation\nmetadata:\n internal: true\n---\n\n# AI SDK Model Manager\n\nThis skill helps maintain AI SDK model configurations in the Tambo Cloud codebase. It automates the process of keeping model definitions up-to-date with the latest AI SDK releases.\n\n## What This Skill Does\n\n1. **Updates AI SDK Packages** - Checks and updates @ai-sdk/openai, @ai-sdk/google, @ai-sdk/groq, and other provider packages to their latest versions\n2. **Identifies Missing Models** - Compares TypeScript definitions in the SDKs against configured models to find newly available models\n3. **Researches Models** - Gathers information about new models including capabilities, context windows, pricing, and use cases\n4. **Prompts User** - Asks which models to add before making changes\n5. **Adds Models** - Updates model configuration files with proper TypeScript types and metadata\n6. **Updates Documentation** - Updates relevant docs and README files to reflect new model availability\n\n## When to Use This Skill\n\nUse this skill when:\n\n- You want to check if AI SDK packages need updating\n- New models have been released by OpenAI, Google, Anthropic, or other providers\n- You're getting TypeScript errors about model IDs not being in SDK types\n- You want to ensure Tambo supports the latest models\n\n## Files This Skill Works With\n\n- `packages/core/src/llms/models/*.ts` - Model configuration files\n- `packages/backend/package.json` - AI SDK dependencies (source of truth for versions)\n- `docs/content/docs/models/*.mdx` - Model documentation\n- `README.md` - Main documentation file\n\n## Process\n\n### Step 1: Update AI SDK Packages\n\nCheck current versions and update to latest:\n\n```bash\ncd packages/backend\nnpm outdated | grep '@ai-sdk'\nnpm install @ai-sdk/openai@latest @ai-sdk/google@latest @ai-sdk/groq@latest @ai-sdk/anthropic@latest @ai-sdk/mistral@latest\n```\n\n### Step 2: Identify Missing Models\n\nFor each provider, inspect the TypeScript definitions:\n\n```bash\n# Check what models are in the SDK types\ncat node_modules/@ai-sdk/openai/dist/index.d.ts | grep 'type.*ModelId'\ncat node_modules/@ai-sdk/google/dist/index.d.ts | grep 'type.*ModelId'\ncat node_modules/@ai-sdk/groq/dist/index.d.ts | grep 'type.*ModelId'\n```\n\nCompare against current model configurations in:\n\n- `packages/core/src/llms/models/openai.ts`\n- `packages/core/src/llms/models/gemini.ts`\n- `packages/core/src/llms/models/groq.ts`\n- `packages/core/src/llms/models/anthropic.ts`\n- `packages/core/src/llms/models/mistral.ts`\n\n### Step 3: Research New Models\n\n**Use the researcher subagent to gather information about each missing model:**\n\n```\nLaunch a researcher subagent to find:\n- Official documentation link\n- Model capabilities (reasoning, vision, function calling, etc.)\n- Context window size (inputTokenLimit)\n- Pricing tier\n- Best use cases\n- Release date and status (experimental, stable, deprecated)\n```\n\nThe researcher subagent has access to web search and can efficiently gather this information for multiple models in parallel.\n\n### Step 4: Prompt User\n\nPresent findings:\n\n```\nFound the following new models in updated AI SDK packages:\n\nOpenAI:\n- gpt-6-preview (200k context, experimental reasoning model)\n- gpt-4.2-turbo (1M context, improved function calling)\n\nGoogle:\n- gemini-3.5-pro (2M context, advanced reasoning)\n\nWhich models would you like to add? (all/none/specific)\n```\n\nWait for user response before proceeding.\n\n### Step 5: Add Selected Models\n\n**Consider launching parallel subagents to add models to each provider file:**\n\nFor models spread across multiple providers (OpenAI, Google, Groq), launch separate subagents to edit each file concurrently. This is faster than doing them sequentially.\n\nFor each model being added, ensure these required fields:\n\n- `apiName`: Exact model ID string from SDK\n- `displayName`: Human-friendly name\n- `status`: \"untested\" | \"tested\" | \"known-issues\"\n- `notes`: Brief description of capabilities and use cases\n- `docLink`: Official provider documentation URL\n- `tamboDocLink`: \"https://docs.tambo.co\"\n- `inputTokenLimit`: Context window size in tokens\n- `modelSpecificParams`: Any special parameters (reasoning, thinking, etc.)\n\nFollow existing patterns in each file and ensure model IDs match SDK type definitions exactly.\n\nExample:\n\n```typescript\n\"gpt-6-preview\": {\n apiName: \"gpt-6-preview\",\n displayName: \"gpt-6-preview\",\n status: \"untested\",\n notes: \"Experimental next-generation reasoning model with extended context\",\n docLink: \"https://platform.openai.com/docs/models/gpt-6-preview\",\n tamboDocLink: \"https://docs.tambo.co\",\n inputTokenLimit: 200000,\n modelSpecificParams: reasoningParameters,\n},\n```\n\n### Step 6: Verify TypeScript\n\nRun type checking to ensure all model IDs are valid:\n\n```bash\ncd packages/core\nnpm run check-types\n```\n\nIf there are type errors, fix model IDs to match SDK definitions exactly.\n\n### Step 7: Update Documentation\n\n**Consider using subagents to update documentation in parallel:**\n\nIf updating multiple documentation files, launch parallel subagents to handle:\n\n1. **README.md** - Update the \"Supported LLM Providers\" section if new providers or significant models were added\n2. **docs/content/docs/models/\\*.mdx** - Add new models to appropriate documentation pages with:\n - Model name and description\n - Key capabilities\n - Context window\n - Example use cases\n - Links to provider docs\n\n### Step 8: Run Quality Checks\n\nBefore completing:\n\n```bash\ncd packages/core\nnpm run lint\nnpm run check-types\nnpm run test\n```\n\n### Step 9: Create Pull Request\n\n**Create a PR with proper conventional commit format:**\n\n```bash\ngh pr create --title \"feat(models): add [model names] support\" --body \"$(cat <<'EOF'\nUpdated AI SDK packages and added support for newly released models:\n\nModels added:\n- [list models here]\n\nPackage updates:\n- @ai-sdk/openai: X.X.X → X.X.X\n- @ai-sdk/groq: X.X.X → X.X.X\n\nAll type checks passing, documentation updated.\nEOF\n)\"\n```\n\n**PR title format:** `feat(models): add [model names] support`\n\nUse `feat(models):` for new models or `deps(core):` for package updates only.\n\n## Guidelines\n\n- **Use subagents for efficiency** - Launch researcher subagents for gathering information and parallel subagents for editing multiple files\n- **Always research before adding** - Don't guess at model capabilities or context limits\n- **Match SDK types exactly** - Model IDs must match the TypeScript definitions in node_modules\n- **Mark new models as \"untested\"** - Let the team test before marking as \"tested\"\n- **Include official doc links** - Always link to provider's official documentation\n- **Be conservative** - Only add models the user explicitly approves\n- **Update docs comprehensively** - Don't just update code, update all relevant documentation\n\n## Error Handling\n\nIf you encounter:\n\n- **Type errors after adding models** - Double-check the model ID matches the SDK's TypeScript definition exactly\n- **Missing model in SDK** - The provider may not have released it yet, suggest waiting for next SDK update\n- **Conflicting model names** - Use the SDK's preferred naming convention\n- **Unknown context limits** - Research provider docs or mark as \"unknown\" and note it needs verification\n\n## Notes\n\n- This skill should be run periodically (monthly or when new models are announced)\n- Always check the git diff before committing to ensure only intended changes were made\n- Some models may have special requirements (API access, pricing tier, etc.) - note these in the model's `notes` field\n- If a model is renamed in the SDK, update both the key and apiName, and consider adding a deprecation note to the old entry\n",".claude/skills/creating-styled-wrappers/SKILL.md":"---\nname: creating-styled-wrappers\ndescription: Creates styled wrapper components that compose headless/base compound components. Use when refactoring styled components to use base primitives, implementing opinionated design systems on top of headless components, or when the user mentions \"use base components\", \"compose primitives\", \"styled wrapper\", or \"refactor to use base\".\nmetadata:\n internal: true\n---\n\n# Styling Compound Wrappers\n\nCreate styled wrapper components that compose headless base compound components. This skill complements `building-compound-components` (which builds the base primitives) by focusing on **how to properly consume and wrap them** with styling and additional behavior.\n\n**Real-world example**: See [references/real-world-example.md](references/real-world-example.md) for a complete before/after MessageInput refactoring.\n\n## Core Principle: Compose, Don't Duplicate\n\nStyled wrappers should **compose** base components, not **re-implement** their logic.\n\n```tsx\n// WRONG - re-implementing what base already does\nconst StyledInput = ({ children, className }) => {\n const { value, setValue, submit } = useTamboThreadInput(); // Duplicated!\n const [isDragging, setIsDragging] = useState(false); // Duplicated!\n const handleDrop = useCallback(/* ... */); // Duplicated!\n\n return (\n \n );\n};\n\n// CORRECT - compose the base component\nconst StyledInput = ({ children, className, variant }) => {\n return (\n \n \n {children}\n \n \n );\n};\n```\n\n## Refactoring Workflow\n\nCopy this checklist and track progress:\n\n```\nStyled Wrapper Refactoring:\n- [ ] Step 1: Identify duplicated logic\n- [ ] Step 2: Import base components\n- [ ] Step 3: Wrap with Base Root\n- [ ] Step 4: Apply state-based styling and behavior\n- [ ] Step 5: Wrap sub-components with styling\n- [ ] Step 6: Final verification\n```\n\n### Step 1: Identify Duplicated Logic\n\nLook for patterns that indicate logic should come from base:\n\n- SDK hooks (`useTamboThread`, `useTamboThreadInput`, etc.)\n- Context creation (`React.createContext`)\n- State management that mirrors base component state\n- Event handlers (drag, submit, etc.) that base components handle\n\n### Step 2: Import Base Components\n\n```tsx\nimport { MessageInput as MessageInputBase } from \"@tambo-ai/react-ui-base/message-input\";\n```\n\n### Step 3: Wrap with Base Root\n\nReplace custom context/state management with the base Root:\n\n```tsx\n// Before\nconst MessageInput = ({ children, variant }) => {\n return (\n {children}\n );\n};\n\n// After\nconst MessageInput = ({ children, variant, className }) => {\n return (\n \n {children}\n \n );\n};\n```\n\n### Step 4: Apply State-Based Styling and Behavior\n\nState access follows a hierarchy — use the simplest option that works:\n\n1. **Data attributes** (preferred for styling) — base components expose `data-*` attributes\n2. **Render props** (for behavior changes) — use when rendering different components\n3. **Context hooks** (for sub-components) — OK for styled sub-components needing deep context access\n\n```tsx\n// BEST - data-* classes for styling, render props only for behavior\n// Note: use `data-[dragging]:*` syntax (v3-compatible), not `data-dragging:*` (v4 only)\nconst StyledContent = ({ children }) => (\n \n {({ elicitation, resolveElicitation }) => (\n <>\n {/* Drop overlay uses group-data-* for styling */}\n
\n
Drop files here
\n
\n\n {elicitation ? (\n \n ) : (\n children\n )}\n \n )}\n \n);\n\n// OK - styled sub-components can use context hook for deep access\nconst StyledTextarea = ({ placeholder }) => {\n const { value, setValue, handleSubmit, editorRef } = useMessageInputContext();\n return (\n \n );\n};\n```\n\n**When to use context hooks vs render props:**\n\n- Render props: when the parent wrapper needs state for behavior changes\n- Context hooks: when a styled sub-component needs values not exposed via render props\n\n### Step 5: Wrap Sub-Components\n\n```tsx\n// Submit button\nconst SubmitButton = ({ className, children }) => (\n \n {({ showCancelButton }) =>\n children ?? (showCancelButton ? : )\n }\n \n);\n\n// Error\nconst Error = ({ className }) => (\n \n);\n\n// Staged images - base pre-computes props array, just iterate\nconst StagedImages = ({ className }) => (\n \n {({ images }) =>\n images.map((imageProps) => (\n \n ))\n }\n \n);\n```\n\n### Step 6: Final Verification\n\n```\nFinal Checks:\n- [ ] No duplicate context creation\n- [ ] No duplicate SDK hooks in root wrappers\n- [ ] No duplicate state management or event handlers\n- [ ] Base namespace imported and `Base.Root` used as wrapper\n- [ ] `data-*` classes used for styling (with `group-data-*` for children)\n- [ ] Render props used only for rendering behavior changes\n- [ ] Base sub-components wrapped with styling\n- [ ] Icon factories passed from styled layer to base hooks\n- [ ] Visual sub-components and CSS variants stay in styled layer\n```\n\n## What Belongs in Styled Layer\n\n### Icon Factories\n\nWhen base hooks need icons, pass a factory function:\n\n```tsx\n// Base hook accepts optional icon factory\nexport function useCombinedResourceList(\n providers: ResourceProvider[] | undefined,\n search: string,\n createMcpIcon?: (serverName: string) => React.ReactNode,\n) {\n /* ... */\n}\n\n// Styled layer provides the factory\nconst resources = useCombinedResourceList(providers, search, (serverName) => (\n \n));\n```\n\n### CSS Variants\n\n```tsx\nconst inputVariants = cva(\"w-full\", {\n variants: {\n variant: {\n default: \"\",\n solid: \"[&>div]:shadow-xl [&>div]:ring-1\",\n bordered: \"[&>div]:border-2\",\n },\n },\n});\n```\n\n### Layout Logic, Visual Sub-Components, Custom Data Fetching\n\nThese all stay in the styled layer. Base handles behavior; styled handles presentation.\n\n## Type Handling\n\nHandle ref type differences between base and styled components:\n\n```tsx\n// Base context may have RefObject\n// Styled component may need RefObject\n} />\n```\n\n## Anti-Patterns\n\n- **Re-implementing base logic** - if base handles it, compose it\n- **Using render props for styling** - prefer `data-*` classes; render props are for behavior changes\n- **Duplicating context in wrapper** - use base Root which provides context\n- **Hardcoding icons in base hooks** - use factory functions to keep styling in styled layer\n",".claude/skills/api-resource-lifecycle/SKILL.md":"---\nname: api-resource-lifecycle\ndescription: Guides CRUD operations for API resources with cascading dependencies, descriptive validation, and orphan prevention. Use when adding delete/remove operations, creating validation logic, building resources that depend on other resources, or when the user mentions \"cascade delete\", \"orphan records\", \"duplicate detection\", \"validation errors\", \"resource cleanup\", or \"rollback on failure\".\nmetadata:\n internal: true\n---\n\n# API Resource Lifecycle\n\nPatterns for building reliable CRUD operations in Tambo Cloud.\n\n## Gotchas\n\n- The codebase uses `CONFLICT` for duplicate name errors in skills but `BAD_REQUEST` for the same pattern in MCP servers. Always use `CONFLICT` for duplicates.\n- PostgreSQL unique violation code is `23505`. Catch it and map to a domain-specific exception rather than letting the raw DB error propagate.\n- When replacing a provider key, all skills with `externalSkillMetadata` for that provider must have their metadata cleared, or they'll reference a stale key.\n- Skills are silently skipped (not errored) at runtime when the provider doesn't support them. This is intentional -- don't add validation that blocks skill creation for unsupported providers.\n- `Promise.allSettled` (not `Promise.all`) for batch external API calls -- partial failures need cleanup, not an all-or-nothing abort.\n\n## Cascading Deletes\n\nDefault to `onDelete: \"cascade\"` in the schema. Only use manual transaction cascades when deletion requires external API calls, metadata cleanup, or cross-reference logic.\n\n```typescript\n// packages/db/src/schema.ts\nexport const skills = pgTable(\"skills\", {\n id: text(\"id\").primaryKey(),\n projectId: text(\"project_id\")\n .notNull()\n .references(() => projects.id, { onDelete: \"cascade\" }),\n // ...\n});\n```\n\n### Manual cascades in transactions\n\nWhen deletion requires cleanup beyond FK cascades (external APIs, metadata, cross-references), wrap in a transaction:\n\n```typescript\n// packages/db/src/operations/project.ts\nexport async function deleteProject(db: HydraDb, id: string): Promise {\n return await db.transaction(async (tx) => {\n await tx\n .delete(schema.providerKeys)\n .where(eq(schema.providerKeys.projectId, id));\n await tx.delete(schema.apiKeys).where(eq(schema.apiKeys.projectId, id));\n await tx\n .delete(schema.projectMembers)\n .where(eq(schema.projectMembers.projectId, id));\n const deleted = await tx\n .delete(schema.projects)\n .where(eq(schema.projects.id, id))\n .returning();\n return deleted.length > 0;\n });\n}\n```\n\n**Reference:** `packages/db/src/operations/project.ts` lines 255-278\n\n### Metadata cleanup on replacement\n\nWhen a resource is replaced (not deleted), clear dependent metadata so dependents re-sync under the new resource:\n\n```typescript\n// apps/web/server/api/routers/project.ts - addProviderKey\n// When replacing a provider key, clear skill metadata for that provider\nconst skills = await operations.listSkillsForProject(ctx.db, projectId);\nawait Promise.all(\n skills\n .filter((s) => s.externalSkillMetadata?.[providerName])\n .map(async (s) => {\n const { [providerName]: _, ...remaining } = s.externalSkillMetadata ?? {};\n return operations.updateSkill(ctx.db, {\n projectId,\n skillId: s.id,\n externalSkillMetadata: remaining,\n });\n }),\n);\n```\n\n**Reference:** `apps/web/server/api/routers/project.ts` lines 863-880\n\n### Rules\n\n- If a child record has no meaning without its parent, use `onDelete: \"cascade\"` in the schema\n- If deletion requires multi-step cleanup or external API calls, wrap in a transaction\n- When replacing a resource, clear dependent metadata so dependents re-sync\n- Always delete children before the parent in manual cascades\n- Check for affected dependents and document the cascade chain in code comments\n\n## Validation Errors\n\nEvery error must say what went wrong and what to do instead. Include the specific value that failed and an example of what's valid.\n\n```typescript\n// Zod: include format example\nname: z.string().min(1, \"Name is required\").max(64)\n .regex(SKILL_NAME_PATTERN, \"Name must be kebab-case (e.g. scheduling-assistant)\"),\n\n// tRPC: include the conflicting value\nthrow new TRPCError({\n code: \"CONFLICT\",\n message: `Server key \"${serverKey}\" is already in use by another MCP server in this project`,\n});\n```\n\n### Error code mapping\n\n| Situation | tRPC Code | When to use |\n| ----------------------- | ----------------------- | ------------------------------------- |\n| Resource not found | `NOT_FOUND` | ID lookup returned null |\n| Input validation failed | `BAD_REQUEST` | Zod schema or business rule violation |\n| Duplicate resource | `CONFLICT` | Name/key already exists |\n| Unexpected failure | `INTERNAL_SERVER_ERROR` | Catch-all for unhandled errors |\n\n## Duplicate Detection\n\nDefault to database unique constraints with custom exception mapping. Only use pre-creation queries when no DB constraint exists.\n\n```typescript\n// packages/db/src/operations/skills.ts\nconst PG_UNIQUE_VIOLATION = \"23505\";\nconst SKILLS_NAME_UNIQUE_CONSTRAINT = \"skills_project_id_name_idx\";\n\nexport class SkillNameConflictError extends Error {\n constructor(name: string) {\n super(`A skill named \"${name}\" already exists in this project`);\n this.name = \"SkillNameConflictError\";\n }\n}\n\nexport async function createSkill(\n db: HydraDb,\n data: NewSkill,\n): Promise {\n try {\n const [skill] = await db.insert(schema.skills).values(data).returning();\n return skill;\n } catch (error) {\n if (isSkillNameConflict(error)) {\n throw new SkillNameConflictError(data.name);\n }\n throw error;\n }\n}\n```\n\n### Pre-creation queries (fallback)\n\nWhen no unique DB constraint exists, query before inserting:\n\n```typescript\nconst existingKeys = await getExistingServerKeys(ctx.db, projectId);\nif (existingKeys.includes(serverKey)) {\n throw new TRPCError({\n code: \"CONFLICT\",\n message: `Server key \"${serverKey}\" is already in use by another MCP server in this project`,\n });\n}\n```\n\n**Reference:** `apps/web/server/api/routers/tools.ts` lines 119-126\n\n## Orphan Prevention\n\nWhen creating a resource that syncs to an external API, roll back on failure:\n\n```typescript\n// apps/web/server/api/routers/skills.ts\n// Create in DB first, then sync to provider\nconst skill = await operations.createSkill(ctx.db, { ... });\n\n// If provider sync fails, delete the DB record\ntry {\n await createSkillOnProviderAndPersist(ctx.db, input.projectId, skill);\n} catch (error) {\n await operations.deleteSkill(ctx.db, input.projectId, skill.id);\n throw error;\n}\n```\n\n**Rules:**\n\n- Create the DB record first (gives you an ID for the external API call)\n- If the external sync fails, delete the DB record to avoid orphans\n- The user sees an error and can retry, rather than seeing a broken record\n- For batch operations, use `Promise.allSettled` and clean up partial failures\n\n**Reference:** `apps/web/server/api/routers/skills.ts` lines 195-204\n\n## Checklist\n\nWhen building a new CRUD operation:\n\n```\nResource Lifecycle Checklist:\n- [ ] Delete cascades documented (which dependents are affected?)\n- [ ] Database-level cascades set up for simple parent-child FK relationships\n- [ ] Manual cascade logic wrapped in a transaction for complex cleanup\n- [ ] All Zod validation messages are descriptive with examples\n- [ ] TRPCError messages include the specific value that caused the error\n- [ ] Duplicate detection before creation (custom exception or pre-query)\n- [ ] Error codes are correct (CONFLICT for duplicates, NOT_FOUND for missing)\n- [ ] External API sync failures roll back the DB record\n- [ ] Resource replacement clears dependent metadata\n```\n",".claude/skills/compound-components/SKILL.md":"---\nname: building-compound-components\ndescription: Creates unstyled compound components that separate business logic from styles. Use when building headless UI primitives, creating component libraries, implementing Radix-style namespaced components, or when the user mentions \"compound components\", \"headless\", \"unstyled\", \"primitives\", or \"render props\".\nmetadata:\n internal: true\n---\n\n# Building Compound Components\n\nCreate unstyled, composable React components following the Radix UI / Base UI pattern. Components expose behavior via context while consumers control rendering.\n\n## Project Rules\n\nThese rules are specific to this codebase and override general patterns.\n\n### Hooks Are Internal\n\nHooks are implementation details, not public API. **Never export hooks from the index.**\n\n```tsx\n// index.tsx - CORRECT\nexport const Component = {\n Root: ComponentRoot,\n Content: ComponentContent,\n};\nexport type { ComponentRootProps, ComponentContentRenderProps };\n\n// index.tsx - WRONG\nexport { useComponentContext }; // Don't export hooks\n```\n\nConsumers access state via **render props**, not hooks. When styled wrappers in the **same package** need hook access, import directly from the source file:\n\n```tsx\nimport { useComponentContext } from \"../base/component/component-context\";\n```\n\n### No Custom Data Fetching in Primitives\n\nBase components can use `@tambo-ai/react` SDK hooks (components require Tambo provider anyway). **Custom data fetching logic** (combining sources, external providers) belongs in the styled layer.\n\n```tsx\n// OK - SDK hooks in primitive\nconst Root = ({ children }) => {\n const { value, setValue, submit } = useTamboThreadInput();\n const { isIdle, cancel } = useTamboThread();\n return {children};\n};\n\n// WRONG - custom data fetching in primitive\nconst Textarea = ({ resourceProvider }) => {\n const { data: mcpResources } = useTamboMcpResourceList(search);\n const externalResources = useFetchExternal(resourceProvider);\n const combined = [...mcpResources, ...externalResources];\n return
{combined.map(...)}
;\n};\n```\n\n### Pre-computed Props Arrays for Collections\n\nWhen exposing collections via render props, **pre-compute all props in a memoized array** rather than providing a getter function.\n\n```tsx\n// AVOID - getter function pattern\nconst Items = ({ children }) => {\n const { rawItems, selectedId, removeItem } = useContext();\n const getItemProps = (index: number) => ({\n /* new object every call */\n });\n return children({ items: rawItems, getItemProps });\n};\n\n// PREFERRED - pre-computed array\nconst Items = ({ children }) => {\n const { rawItems, selectedId, removeItem } = useContext();\n\n const items = React.useMemo(\n () =>\n rawItems.map((item, index) => ({\n item,\n index,\n isSelected: selectedId === item.id,\n onSelect: () => setSelectedId(item.id),\n onRemove: () => removeItem(item.id),\n })),\n [rawItems, selectedId, removeItem],\n );\n\n return children({ items });\n};\n```\n\n## Workflow\n\nCopy this checklist and track progress:\n\n```\nCompound Component Progress:\n- [ ] Step 1: Create context file\n- [ ] Step 2: Create Root component\n- [ ] Step 3: Create consumer components\n- [ ] Step 4: Create namespace export (index.tsx)\n- [ ] Step 5: Verify all guidelines met\n```\n\n### Step 1: Create context file\n\n```\nmy-component/\n├── index.tsx\n├── component-context.tsx\n├── component-root.tsx\n├── component-item.tsx\n└── component-content.tsx\n```\n\nCreate a context with a null default and a hook that throws on missing provider:\n\n```tsx\n// component-context.tsx\nconst ComponentContext = React.createContext(\n null,\n);\n\nexport function useComponentContext() {\n const context = React.useContext(ComponentContext);\n if (!context) {\n throw new Error(\"Component parts must be used within Component.Root\");\n }\n return context;\n}\n\nexport { ComponentContext };\n```\n\n### Step 2: Create Root component\n\nRoot manages state and provides context. Use `forwardRef`, support `asChild` via Radix `Slot`, and expose state via data attributes:\n\n```tsx\n// component-root.tsx\nexport const ComponentRoot = React.forwardRef<\n HTMLDivElement,\n ComponentRootProps\n>(({ asChild, defaultOpen = false, children, ...props }, ref) => {\n const [isOpen, setIsOpen] = React.useState(defaultOpen);\n const Comp = asChild ? Slot : \"div\";\n\n return (\n setIsOpen(!isOpen) }}\n >\n \n {children}\n \n \n );\n});\nComponentRoot.displayName = \"Component.Root\";\n```\n\n### Step 3: Create consumer components\n\nChoose the composition pattern based on need:\n\n**Direct children** (simplest, for static content):\n\n```tsx\nconst Content = ({ children, className, ...props }) => {\n const { data } = useComponentContext();\n return (\n
;\n};\n```\n\n**Sub-context** (for lists where each item needs own context):\n\n```tsx\nconst Steps = ({ children }) => {\n const { reasoning } = useMessageContext();\n return (\n \n {children}\n \n );\n};\n\nconst Step = ({ children, index }) => {\n const { steps } = useStepsContext();\n return (\n \n {children}\n \n );\n};\n```\n\n### Step 4: Create namespace export\n\n```tsx\n// index.tsx\nexport const Component = {\n Root: ComponentRoot,\n Trigger: ComponentTrigger,\n Content: ComponentContent,\n};\n\n// Re-export types only - never hooks\nexport type { ComponentRootProps } from \"./component-root\";\nexport type { ComponentContentProps } from \"./component-content\";\n```\n\n### Step 5: Verify guidelines\n\n- **No styles in primitives** - consumers control all styling via className/props\n- **Data attributes for CSS** - expose state like `data-state=\"open\"`, `data-disabled`, `data-loading`\n- **Support asChild** - let consumers swap the underlying element via Radix `Slot`\n- **Forward refs** - always use `forwardRef`\n- **Display names** - set for DevTools (`Component.Root`, `Component.Item`)\n- **Throw on missing context** - fail fast with clear error messages\n- **Export types** - consumers need `ComponentProps`, `RenderProps` interfaces\n- **Hooks stay internal** - never export from index, expose state via render props\n- **SDK hooks OK, custom fetching not** - `@tambo-ai/react` hooks are fine, combining logic goes in styled layer\n- **Pre-compute collection props** - use `useMemo` arrays, not getter functions\n\n## Pattern Selection\n\n| Scenario | Pattern | Why |\n| -------------------- | --------------- | ------------------------------- |\n| Static content | Direct children | Simplest, most flexible |\n| Need internal state | Render prop | Explicit state access |\n| List/iteration | Sub-context | Each item gets own context |\n| Element polymorphism | asChild | Change underlying element |\n| CSS-only styling | Data attributes | No JS needed for style variants |\n\n## Anti-Patterns\n\n- **Hardcoded styles** - primitives should be unstyled\n- **Prop drilling** - use context instead\n- **Missing error boundaries** - throw when context is missing\n- **Inline functions in render prop types** - define proper interfaces\n- **Default exports** - use named exports in namespace object\n- **Exporting hooks** - hooks are internal; expose state via render props\n- **Custom data fetching in primitives** - SDK hooks are fine, but combining/external fetching belongs in styled layer\n- **Re-implementing base logic** - styled wrappers should compose, not duplicate\n- **Getter functions for collections** - pre-compute props arrays in useMemo instead\n",".claude/skills/validating-accessibility/SKILL.md":"---\nname: validating-accessibility\ndescription: >-\n Use this skill when creating, modifying, or reviewing any .tsx component in apps/web, even if\n the user doesn't mention \"accessibility.\" Covers semantic HTML, aria labels, navigation landmarks,\n forms, dialogs, and keyboard navigation. Trigger on: adding buttons, links, toggles, icons, or\n any interactive element; building or editing forms; adding dialogs or modals; reviewing UI code.\n Includes inline verification patterns for scanning violations. Not for styling or layout changes\n that don't involve interactive elements.\nmetadata:\n internal: true\n---\n\n# Accessibility Checklist\n\nEvery UI component in `apps/web` must meet these standards. No partial compliance.\n\n## Gotchas\n\n- **`role=\"button\"` divs may exist in the codebase** -- fix them when touching affected files. `` elements with `role=\"button\"` for sortable columns are acceptable.\n- **Nested interactive elements** -- when replacing a `