---
description: Repo-wide conventions for the Echodo monorepo
alwaysApply: true
---

# Echodo monorepo (always-on)

The authoritative agent guide for this repo is [AGENTS.md](mdc:AGENTS.md). Read it before doing anything non-trivial. This rule only restates the load-bearing constraints.

## Stack at a glance

- pnpm 9 + Turborepo + TypeScript 5.7, Node >= 20. ESM only.
- `apps/web` — Next.js 15 App Router, React 19, tRPC, NextAuth v5, Drizzle, TipTap + Yjs + Hocuspocus, Tailwind + Radix.
- `apps/collab-server` — Hocuspocus (Yjs) over Postgres + Redis.
- `apps/mcp-server` — Model Context Protocol server.
- `packages/database` — Drizzle schema, client, migrations, markdown-backlog importer.
- `packages/shared` — Cross-app types and zod schemas. No React, no Node-only APIs, no DB.
- `packages/ai` — Vercel AI SDK wrappers and prompts.

## Hard rules

- Use `pnpm` (never `npm`/`yarn`) and filter by workspace: `pnpm --filter @tasks/<name> <script>`.
- Run `pnpm lint && pnpm type-check` before declaring a task done. There is no test runner yet — don't pretend there is.
- Validate every external input (HTTP, env, frontmatter, MCP args) with **zod**. Cross-package schemas live in `packages/shared`.
- `strict: true` is on. No `any`, no `// @ts-ignore`. Use `// @ts-expect-error <reason>` only when truly necessary.
- Multitenancy is enforced by `workspace_id` on every tenant-scoped DB row. **Every** query against such tables must filter by `workspace_id`.
- Never read `AGENT-DEPLOY.md`, `.env`, or any `*-credentials.*` content into committed files, logs, or PR descriptions. They contain homelab credentials and are gitignored.
- Don't hand-edit existing migrations under [packages/database/migrations](mdc:packages/database/migrations). Generate a new one with `pnpm db:generate`.
- `NEXT_PUBLIC_*` is the only browser-exposed env prefix. Never put secrets behind it.

## Style

- Comments explain *why*, not *what*. No narration comments (`// import x`, `// loop over items`) and no "I just changed this" breadcrumbs.
- Prefer named exports and `import type { ... }` for type-only imports.
- Don't commit, push, or amend without explicit user instruction.