Studio

Studio is an open-source AI platform that connects models and agents to an organization’s data, tools, and workflows. It provides the common infrastructure for building specialized business applications, including storefront solutions. Authentication, MCP connectivity, monitoring, and cost controls belong to the platform so each application can focus on the work its users need to do.

Before changing code

Read the guidance for each area your change touches, including when working from the repository root:

Working locally

Use docker compose up --build --watch (bun run dev) for API + web development. Compose owns PostgreSQL, NATS, object storage, and startup migrations; source syncs into containers while dependencies stay in the image. Do not add managed service downloads or process supervision to the CLI. Frontend-only and local Kubernetes workflows remain available. CONTRIBUTING.md owns setup, worktree isolation, and lifecycle commands; workspace READMEs own builds.

Before pushing, run bun run verify and include any formatting changes in the commit. CI runs the broader checks. Run focused integration or E2E tests when the changed behavior needs them, following TESTING.md.

Investigate failing checks. Before calling a failure pre-existing, reproduce it on the base revision or provide equivalent evidence. Report what passed, what failed, and what was not run.

Shared decisions

• Use @decocms/shared/std for sleep, retry, and backoff across runtimes. Extend the existing utilities when necessary; the circuit breaker is a separate fault-isolation mechanism.
• Deliver state changes through the existing push paths. Keep the idle poll as a fallback; shortening it is not a fix for staleness. Read the API instructions before adding a producer or consumer.
• Keep authorization and data access scoped to the current principal and organization. Feature flags gate product behavior, not access.
• Use thread in domain identifiers, storage, and wire contracts. User-facing text calls it a "chat". Chat and ChatLayout may name UI composition; their domain state still uses threadId and thread contracts.
• Validate external input with schemas. Narrow unions with discriminants or property checks instead of casting away uncertainty.
• Fix underlying type, lint, and unused-code findings. Do not add exclusions or weaken checks just to make a change pass. Remove code and exports your change makes unused.
• Keep comments focused on reasons the code cannot express. Simplify a workaround before adding a long explanation for it.

Check the behavior you changed

• Cover relevant empty, invalid, duplicate, and oversized inputs and schema variants. Update tests that assert the old behavior, including contracts shared across test suites.
• Trace overlapping operations: what happens to an earlier operation's output when another starts? Retry side effects only when idempotent. Claim work at dispatch and coordinate writes that share a destination.
• Complete the lifecycle of persisted state. Include update and deletion, clean up with the parent, and clear prior terminal state when restarting.
• Keep cache and list keys distinct across tenants and entity shapes. Bound caches with a TTL and size cap, invalidate bad entries, and publish only after a health signal.
• Changes on boot, install, or dispatch hot paths need their own default-off flag. Keep rollout separate from deployment; do not reuse an unrelated flag.
• Include relevant verification and migration notes in PRs. For UI changes, upload screenshots or videos as GitHub attachments and embed their asset URLs in the PR body. Never commit PR-only evidence to the repository, including .github/screenshots/ or .github/pr-assets/. Follow the PR template.

Credentials and shared artifacts

Keep real credentials and customer identifiers out of source, fixtures, logs, PRs, and other shared artifacts. Use synthetic examples. Redact secrets before quoting debugging output.

Never name an organization or customer in commit messages, PR titles or descriptions, review comments, or issues. That covers org names and slugs, site, repository, and branch names, URLs, people, and IDs of their threads, projects, or connections. Describe the case generically, such as "a project with Fast Preview on, on a PR branch", even while debugging a reported issue.

Strip embedded credentials at the persistence boundary and fail closed if a value cannot be parsed safely. Test the written artifact's bytes, not only an intermediate object. Treat pushed credentials as exposed: rotate them first; rewriting Git history does not revoke them.

Documentation

Public product documentation lives in docs-tanstack and is published at Studio documentation. Update product guides and architecture there. When code differs, preserve the specification and identify the implementation gap.

Keep workspace setup, contributor guidance, and implementation plans in this repository's READMEs and engineering documents.

Keep each instruction in one place. Put task-specific guidance near its owner and link to it here with a condition for reading it. Let code, schemas, and tool configuration own discoverable implementation details. When a decision changes, update its existing explanation instead of appending a correction.

Before changing a workspace README, read the README requirements in CONTRIBUTING.md.