AGENTS.md

What this is

Elmo is an open-source AI visibility platform (Answer Engine Optimization): it tracks how AI answer engines like ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews mention, cite, and describe brands. It is a pnpm + Turborepo monorepo on Node.js 24 (enforced via engines), TypeScript, and PostgreSQL.

• apps/web — product dashboard (TanStack Start + Vite, port 3000)
• apps/worker — pg-boss background jobs (AI evaluations, citation tracking, reports)
• apps/www — marketing site, docs, and blog (port 3001)
• apps/cli — @elmohq/cli, the Docker Compose deployment CLI
• packages/lib — shared logic and the Drizzle schema/migrations
• packages/ui — shared shadcn-based UI components
• packages/docs — user-facing docs content (MDX), rendered by apps/www
• packages/deployment — deployment-mode config, per-mode auth hooks, cloud billing/email
• packages/config — env validation and shared constants/types
• packages/api-spec — OpenAPI spec
• e2e/ — Playwright end-to-end tests

Full setup instructions are in the developer guide at packages/docs/content/docs/developer-guide/.

Commands

• pnpm dev — all dev servers (turbo)
• pnpm test — Vitest unit tests
• pnpm build — build all packages
• pnpm format — Biome format
• pnpm lint — Biome check (errors only; warnings are not gated)
• pnpm lint:fix — apply everything Biome can fix on its own
• Migrations: from packages/lib, pnpm exec drizzle-kit migrate (NEVER RUN THESE UNLESS EXPLICITLY INSTRUCTED BY THE USER)
• E2E tests need Playwright browsers (pnpm exec playwright install) and a running app; they are separate from unit tests
• shadcn components: always install with the CLI (pnpm dlx shadcn@latest add <component>, from packages/ui or apps/www — each has its own components.json) — never hand-create them

Don't run formatting, linting, type checks, or tests after every change — only to diagnose what you're working on, or when asked.

Before handing work back or opening a PR, run pnpm lint and get it passing; CI fails on it. pnpm lint:fix handles the rest. Never silence a lint error with biome-ignore — fix the code.

Tests

• Add tests for the purpose and externally observable behavior of the code, not its implementation shape. Do not test that internal helpers, component structure, configuration objects, or incidental markup have a particular form unless that form is itself a supported contract.
• Prefer tests that exercise a user outcome, public API, business rule, failure mode, or regression. A refactor that preserves behavior should not require test changes.

Package management and supply-chain security

• Always use pnpm. Never install or run dependencies with npm, yarn, or npx — that sidesteps the workspace's protections.
• A dependency that more than one package uses is versioned once, in the catalog in pnpm-workspace.yaml, and each package depends on it as "catalog:". Peer dependency ranges stay as written: they state compatibility, not the version we install.
• This repo enforces pnpm supply-chain security via pnpm-workspace.yaml: minimumReleaseAge (a multi-day cooldown on new releases), trustPolicy: no-downgrade, blockExoticSubdeps, and an allowBuilds allowlist for install scripts.
• Never weaken or bypass these controls: don't add minimumReleaseAgeExclude entries, don't flip packages to true in allowBuilds, don't suppress pnpm audit advisories, and don't remove overrides (many are scoped security patches or dedup anchors). If an install fails because of these controls, that is the system working — report it instead of working around it.

Environment

.env must exist at both the repo root and apps/web/.env (Vite reads its project root; the worker reads apps/web/.env via --env-file). Minimum for local mode: DATABASE_URL, DEPLOYMENT_MODE=local, BETTER_AUTH_SECRET, ELMO_ENCRYPTION_KEY (openssl rand -base64 32), APP_URL/VITE_APP_URL, DISABLE_TELEMETRY=1, and SCRAPE_TARGETS plus the keys of the providers it names. Env validation also requires one direct LLM key (OPENAI_API_KEY, OPENROUTER_API_KEY, ANTHROPIC_API_KEY, or MISTRAL_API_KEY) for onboarding and the Opportunities report, and the worker needs TYPESAFE_API_KEY, or OPENROUTER_API_KEY to call Jev through OpenRouter (Jev judges mentions and sentiment). For UI-only work, SCRAPE_TARGETS=stub:stub, ONBOARDING_LLM_TARGET=stub:stub and TYPESAFE_API_KEY=stub need no keys at all.

Git workflow

• Work happens in PRs against main.
• Commit as you go: small, atomic commits that show real progress. Don't rewrite history (amend, rebase, force-push) to make it look tidy afterward.
• Commit subjects are plain imperative sentences — no conventional-commit prefixes. Write paginate top cited domains, not feat(web): paginate top cited domains.
• Don't bump package versions; releases go through Changesets.
• Don't add coding-agent attribution (such as "Generated with …" lines or Co-Authored-By trailers) to commit messages or PR descriptions.

Private data

• Unless explicitly authorized, never put identifying information or non-public stats into a PR description, commit message, issue or PR comment, or any committed text (code, comments, tests, fixtures, docs, changesets). This covers anything you get from MCP servers, databases, or APIs you've been given access to, including the GitHub API.
• That includes conversion rates, customer or user names, emails, and domains, revenue and billing figures, cloud usage amounts, traffic numbers, names of private repositories, internal projects, services, or infrastructure, and any other non-public information. Describe the change in general terms or use made-up placeholder data instead.
• This repo is public. Before running gh pr create, gh pr edit, gh pr comment, gh issue, or git commit, reread the text against this list and strip anything you learned while investigating that isn't already public. Notes from your investigation are the usual source of leaks.

Comments and docs

• Adding code comments should be rare. Default to writing none; good names and clear code are the documentation.
• Add a comment only when it explains a non-obvious why or context the code can't show (a workaround, a surprising constraint, an external quirk). Never restate what the code already says, and don't add section labels, docstrings that echo the signature, or narration of your change.
• The same applies to docs and this file: never write down what's already derivable from the repo (what a file imports, what a script runs, how code is structured).
• Don't describe prior behavior ("previously this did X") and don't reference GitHub issues or tickets in code — that context belongs in the commit message or PR.

Copy and UI text

• Use APA Style title case for all non-prose text: titles, headings, buttons, links used as actions, nav items, tabs, form labels, table headers, and chart titles.
• Sentences and prose stay in sentence case.
• Elmo has no dark mode. Never design or implement anything for one.

Changesets

• Add one only for user-facing changes (something an end user of the product would notice). Internal refactors, dependency bumps, and CI tweaks don't get one.
• Keep it to one short, product-focused sentence; default to patch; scope it to the packages actually affected.
• If a non-package directory (like e2e/) breaks Changesets tooling, fix the tooling configuration rather than inventing versions.
• Never create a changeset for apps/www.