docs(repo): consolidate cloud docs (#1412)

Co-authored-by: CharlieHelps <charlie@charlielabs.ai>

Author: alecf

CLAUDE.md

@@ -1,26 +1,13 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Guidelines for Claude Code (claude.ai/code) when touching this repo.
 
-**⚠️ IMPORTANT: Read @AGENTS.md before making any changes or using any tools. It contains detailed architectural guidance and development workflows.**
+**Read @AGENTS.md first.** It owns architecture, naming, workflow rules, testing expectations, and anything code-related. Keep that file open—this doc just points you there.
 
-## Quick Reference
+## Three Things to Remember
 
-This is a Turborepo monorepo for Tambo AI containing:
+1. Follow that doc for everything: repo layout, commands, coding standards, doc rules, Charlie workflow, MCP guidance, etc.
+2. Use the workspace scripts it lists (`npm run dev`, `npm run lint`, `npm run check-types`, `npm test`, `npm run db:*`, Docker helpers in `scripts/cloud/`, …).
+3. Defer to it whenever instructions collide; if something’s still unclear, ask the user.
 
-- **react-sdk/** - Core React hooks and providers
-- **cli/** - Command-line tools and component registry
-- **showcase/** - Next.js demo application
-- **docs/** - Documentation site with Fumadocs
-- **create-tambo-app/** - App creation bootstrap tool
-
-## Essential Commands
-
-```bash
-turbo dev               # Start all packages in development
-turbo build             # Build all packages
-turbo lint              # Lint all packages
-turbo test              # Test all packages
-```
-
-For detailed information on architecture, development patterns, and cross-package workflows, see @AGENTS.md.
+That’s it—keep this doc minimal so every agent gets one authoritative direction.

CONTRIBUTING.md

@@ -1,104 +1,165 @@
-## Contributing to tambo
+# Contributing to tambo
 
-Thank you for contributing! This guide outlines our workflow and the quality bar for changes. Please read it end-to-end before opening a PR.
+Thanks for helping! This guide covers workflow expectations only—**all coding standards, architecture rules, and naming conventions live in @AGENTS.md.**
 
-### Code of Conduct
+## Quick Links
 
-By participating, you agree to uphold a respectful, inclusive environment. Be kind, constructive, and collaborative.
+- That guide – canonical reference for architecture, naming, coding rules, doc expectations, AI usage, Charlie workflow, etc.
+- `docs/` + `devdocs/` – public docs + internal references (update them with code changes).
+- [RELEASING.md](./RELEASING.md) – API/SDK/Cloud release process.
 
-### Workflow overview
+## Workflow Overview
 
-1. Open or pick up an issue.
-2. Create a feature branch from `main`.
-3. Implement your change with tests and docs.
-4. Open a PR with a semantic versioning title and the checklist below.
-5. Get at least one approval and a green CI run.
+1. Pick or file an issue.
+2. Branch from `main` (`alecf/<descriptive-name>` when using Conductor).
+3. Build the feature/fix with tests + docs alongside the code.
+4. Run lint, types, and tests locally.
+5. Open a PR with a Conventional Commit title and include the checklist below.
+6. Iterate with reviewers (and Charlie, the AI code reviewer) until CI is green and approvals are in.
 
-### PR titles and semantic versioning (required)
+## PR Titles and Semantic Versioning
 
-We infer release impact from PR titles using Conventional Commits semantics. Use one of:
+We infer release impact from PR titles using [Conventional Commits](https://www.conventionalcommits.org/) syntax:
 
-- `feat(scope): add something` → Minor version bump
-- `fix(scope): fix something` → Patch version bump
-- `perf(scope): ...`, `refactor(scope): ...`, `docs(scope): ...`, `chore(scope): ...` → Typically patch or no release
-- `feat(scope)!: breaking change summary` or include a `BREAKING CHANGE:` footer → Major version bump
+- `feat(scope): ...` → Minor bump
+- `fix(scope): ...`, `perf(scope): ...`, `refactor(scope): ...`, `docs(scope): ...`, `chore(scope): ...` → Patch bump or none
+- Breaking change → `feat(scope)!: ...` or include a `BREAKING CHANGE:` footer
 
-Examples:
+Scopes reference areas like `api`, `web`, `core`, `cli`, `docs`, `sdk`. Keep titles imperative and concise. Examples: `feat(api): add transcript export endpoint`, `fix(web): prevent duplicate project creation`.
 
-- `feat(button): add destructive variant`
-- `fix(table): restore keyboard navigation`
-- `feat(api)!: remove deprecated v1 endpoints`
+## Documentation & Visual Changes
 
-Scopes are usually package or area names (e.g., `button`, `cli`, `docs`, `sdk`). Keep titles clear and imperative.
+- Every functional change must update the relevant docs (`docs/`, root `.md`, or `devdocs/`).
+- Component work must keep Showcase + CLI registry in sync.
+- UI/DX changes require a ≤90s video demo attached to the PR.
+- Link the doc change (or follow-up issue) in your PR description.
 
-### TypeScript SDK policy (Stainless-generated)
+## API + SDK Source of Truth
 
-- The TypeScript SDK is auto-generated by Stainless from the API schema.
-- Do not modify the SDK by hand. Instead, land the API change in [the api server](./apps/api/); when deployed, the SDK will be regenerated automatically over the next hour.
-- If you need new client behavior, propose it via API changes or helper utilities that wrap the generated client in this repo (not edits to generated files).
+- API lives in `apps/api`.
+- The TypeScript SDK (`@tambo-ai/typescript-sdk`) is generated by Stainless after API deploys. Do **not** edit it manually—let Stainless open the release PR.
+- React SDK updates follow the workflow in [RELEASING.md](./RELEASING.md).
 
-### Visual changes require a short video demo
+## Required Checks
 
-Any PR that changes visuals (new component, component behavior/style, or UI in [tambo](https://github.com/tambo-ai/tambo)) must include a brief demo video (≤ 2 minutes). Loom links are fine. Show:
+```bash
+npm run lint
+npm run check-types
+npm test
+```
 
-- Where to find the feature
-- Before vs after (if applicable)
-- Key interactions and edge cases
+Add targeted tests for new behavior and keep migrations in sync with DB changes. When in doubt about placement, follow the guidance in that doc.
 
-### Documentation is mandatory
+## Charlie (AI Review Agent)
 
-All changes must update our documentation site. Include:
+- Reply to every comment.
+- Use `@CharlieHelps yes please` to apply a suggestion, `fixed` when you handled it yourself, or explain why you’re declining.
+- Batch the `yes please` comments in a single review when applying multiple fixes.
 
-- Updated reference pages (props, usage, examples)
-- New guides or tutorial steps if introducing concepts
-- Migration notes if behavior changes
+## Security & Secrets
 
-Link the docs PR or commit in your PR description.
+- Never commit credentials. Use the documented env files (`apps/api/.env`, `apps/web/.env.local`, `packages/db/.env`, `docker.env`).
+- Rotate anything leaked immediately.
 
-### Component library changes must update showcase and CLI
+## PR Checklist
 
-- Add or update examples in the component showcase so reviewers can validate visually
-- Update the CLI so new components can be scaffolded/added by the CLI
-- Add a minimal usage example to the docs and CLI help output where applicable
+- [ ] Conventional Commit title (`!` for breaking changes)
+- [ ] Linked issue(s) or context
+- [ ] Docs updated (or follow-up issue linked)
+- [ ] Showcase/CLI updated if components changed
+- [ ] Visual change video attached (if applicable)
+- [ ] Tests added/updated; `npm run lint`, `npm run check-types`, `npm test` all pass
+- [ ] SDK workflow respected (no manual edits to generated clients)
 
-### AI-generated code policy
+## Need More Guidance?
 
-- Any AI-generated code must be reviewed by a human and brought up to our readability, testing, and documentation standards.
-- Follow our internal AI rules/policy document (link internally). Do not include secrets or customer data in prompts.
+If you’re looking for coding standards, naming rules, CLI/showcase sync details, AI policy, or MCP instructions, that single source of truth has you covered.
 
-### Quality bar
+## Code of Conduct
 
-- TypeScript, ESLint, and Prettier must pass: `pnpm -w lint` and `pnpm -w typecheck`
-- Tests must pass locally and in CI: `pnpm -w test`
-- Add tests for new logic and meaningful changes
-- Keep functions small, well-named, and guard edge cases early
+Participate respectfully and keep collaboration constructive.
 
-### PR checklist (include in description)
+## API and SDK Source of Truth
 
-- [ ] Semantic PR title using Conventional Commits (`feat`, `fix`, `!` for breaking)
-- [ ] Linked issue(s)
-- [ ] If SDK needed: confirm it will be regenerated by Stainless (no manual SDK edits)
-- [ ] JSDoc updated in code where relevant
-- [ ] Docs site updated (pages/examples/CLI help), or a separate doc PR is linked
-- [ ] Visual change demo video attached (≤ 2 min)
-- [ ] Showcase updated for component changes
-- [ ] CLI updated to support new components or options
-- [ ] Tests added/updated and all CI checks green
+- API changes live in `apps/api`.
+- The TypeScript SDK (`@tambo-ai/typescript-sdk`) is generated by Stainless from the deployed API spec. Never edit the SDK by hand or publish it manually.
+- Deploy API changes, let Stainless open the SDK release PR, review that PR, then land dependency bumps here as needed.
 
-### Branching, commits, and reviews
+## Visual Changes Need a Short Video
 
-- Branch from `main`, rebase as needed to keep history clean
-- Use small, focused commits with clear messages (Conventional Commits encouraged, but PR title governs versioning)
-- At least one reviewer approval required; request experts for API or design-heavy changes
+UI or DX-affecting PRs (components, dashboard tweaks, CLI UX) must ship with a ≤90s screen recording showing before/after and key flows. Loom links are fine.
 
-### Releases
+## Documentation Requirements
 
-- We follow Semantic Versioning (semver). Release type is derived from PR titles and/or maintainer input
-- Changelogs are generated by CI (or maintainers) based on merged PRs
-- Maintainers may squash and edit titles to reflect the correct semver impact
+Every functional change must update docs in the right place:
 
-### Links
+- Public docs: `docs/` (Fumadocs) or the relevant MDX page.
+- Developer docs: root `.md` files or `devdocs/`.
+- Link the doc change (or follow-up issue) in your PR.
 
-- Community Discord: https://discord.gg/dJNvPEHth6
+If you touch components:
+
+- Update Showcase examples (`showcase/`) so reviewers can interact with the change.
+- Update the CLI registry (`cli/src/registry/`) so scaffolding stays in sync.
+- Mirror any CLI component changes into `docs/` components if they originated there.
+
+## Lint, Types, and Tests (Required)
+
+Before requesting review, all of these must pass:
+
+```bash
+npm run lint
+npm run check-types
+npm test
+```
+
+Fix lint warnings, keep TypeScript strict, and add focused tests for new logic. Database changes must include matching Drizzle migrations (`npm run db:generate`).
+
+## Coding Standards
+
+- Favor small, functional modules with explicit error handling.
+- Early-return instead of deep nesting; avoid mutation.
+- Keep business logic outside UI components; use `lib/`, `services/`, or `utils/` helpers.
+- Follow React naming conventions (see `devdocs/NAMING_CONVENTIONS.md`) and loading-state rules (`devdocs/LOADING_STATES.md`).
+- Use tRPC inside `apps/web` instead of ad-hoc `/api` routes.
+- Never edit generated SDK files; wrap them if you need helpers.
+
+## AI-Generated Code Policy
+
+AI output must be reviewed and cleaned up by you. Follow the internal AI policies described there and never paste secrets or private data into prompts.
+
+## Working with Charlie (AI Code Reviewer)
+
+Charlie may leave inline suggestions on your PR. Reply to every comment:
+
+- Use `@CharlieHelps yes please` if you want it to apply a fix.
+- Reply with `fixed` (plus context) after resolving manually.
+- Explain if the suggestion is being declined.
+
+Batch multiple `@CharlieHelps yes please` replies in a single review if you want Charlie to apply several fixes together.
+
+## Security and Secrets
+
+Do not commit API keys or credentials. Use the documented env files (`apps/api/.env`, `apps/web/.env.local`, `packages/db/.env`, `docker.env`). Rotate anything leaked immediately.
+
+## PR Checklist (Copy into Description)
+
+Copy the checklist from the **PR Checklist** section above into your PR description.
+
+## Branching, Commits, and Reviews
+
+- Keep branches small and focused; rebase on `main` when needed.
+- Use clear, scoped commits (Conventional Commits encouraged).
+- At least one maintainer approval required. Pull in subject-matter experts for API, DB, or design-heavy changes.
+
+## Releases
+
+- Release-please manages tagging and changelog generation for each package. Maintainers may edit PR titles to ensure correct SemVer impact.
+- See [RELEASING.md](./RELEASING.md) for the full workflow across API, SDKs, and apps.
+
+## Links
+
+- Discord: https://discord.gg/dJNvPEHth6
+- Docs: https://docs.tambo.co
 
 Thanks for helping improve tambo!