Technical Documentation: trycompai/crm

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

CRM

What this is Copy Chapter

Most CRMs are a database with a form in front of it. The AI ones bolt a chat box onto
the side of that form. Both leave the actual work — finding out what is true, and
writing it down — to a human who has better things to do.

This is built the other way round. The agent is not a feature of the CRM; the CRM is
where the agent keeps its notes. It runs on its own deployment, on its own schedule,
against its own work queue. It decides what to look at next, books its own follow-ups,
spends a research budget, and stops when the budget runs out. Nothing about it is
request-response: close the browser and it keeps going.

The rule the agent itself never breaks: nothing about a person is guessed. No tool
accepts a confidence score, because a model asked to grade its own certainty will, and
it will be wrong in the direction that makes it look useful. Tools report what they
observed — crm.signature-block, github.account-identity — and a ledger prices the
evidence. Strong evidence writes to the record. Weak evidence becomes a suggestion a
human settles. A confidently wrong fact about a customer is worse than a blank field,
because nobody can tell it is wrong.

Screenshots Copy Chapter

The agent Copy Chapter

apps/agent is its own deployment, built on
eve — Vercel's filesystem-first framework for durable agents.
A tool is a file, a skill is a markdown file, a schedule is a file, and the runtime
handles the durable part: sessions that survive a redeploy, work that resumes where it
stopped.

It runs itself. lib/tasks.ts is the work queue: claimDue leases rows with
FOR UPDATE SKIP LOCKED, so two dispatchers take disjoint work and a run that dies
frees its row when the lease expires. Anything that looks like "every N minutes, the
oldest ten contacts" belongs in a task's dueAt, not in a cron expression. When the
agent wants another look at somebody it calls schedule_recheck and says why — and
the reason is shown to the rep, because an agent that cannot say why it will be back
in fourteen days does not have a reason, it has a default.

Every outside source is optional, and it is designed to run with none of them.
With no API keys at all it still works: read_crm_history reads your own threads,
meetings and signature blocks, which is free and is the best evidence there is — no
data vendor can sell you a reply from the person's own address. Each key opens one
more place to look. It is told at the start of every session which ones this install
has, so it plans around what it actually has rather than discovering the gaps one
failed call at a time, and it prints the list at startup:

[agent] off  Web research (PERPLEXITY_API_KEY)
[agent] on   Company brand data (Settings → General)
[agent] on   LinkedIn (Settings → General)

Company brand data and LinkedIn are both Context,
and both come from the same key. The first is the logo, the colours, the industry and
the real name behind a domain, which is the difference between an account that arrives
as itself and one that arrives as a grey square with its initials in it. The second
reads a person back from a LinkedIn URL already on their record — their real name,
current title, employer and every earlier role — which is what settles who an address
belongs to. It is the one key that is asked for rather than configured: it lives in a
row, the onboarding asks for it, and Settings → General changes it afterwards,
because a self-hoster's admin cannot redeploy to set an environment variable.

The sandbox has no network and no database. Turning it on is what gives the model
a shell — the difference between a tool-caller and something that can keep a dossier,
diff this month's profile against last month's, and grep a thread for a signature
block. deny-all egress costs nothing, because web_fetch runs in the app runtime
and web_search at the model provider. What it removes is the only path by which a
customer's email body could leave through a shell command. The other half of that rule
is an absence: the sandbox is never given DATABASE_URL. A shell with credentials
and egress is exfiltration-shaped even in an internal tool; a shell with neither is a
text processor.

You can talk to it, and watch it work. Every contact, company and deal has an
Agent tab — the steps as it takes them, the leads it throws away and why, and its
questions answered in place when it cannot decide between two people. Conversations
are durable and survive a reload; the record travels in a signed token rather than
being bolted onto the front of your message. Set AGENT_BRIDGE_SECRET to the same
value in both processes to turn it on. Without it the tab reports that it is not
configured, and the agent carries on running its own schedule.

docs/agent.md is the full write-up.

The stack Copy Chapter

A Turborepo monorepo on Bun, deployed on
Vercel.

The app talks to the API over tRPC, and the router type is generated from the
NestJS routers — so the front end is type-safe from the Prisma row to the table cell.
List state (filters, sort, page) lives in the URL, so copying the address bar
reproduces the view.

Layout Copy Section

Three rules the codebase holds to Copy Section

Written up where the work happens, not in a style guide:

• Intelligence never lives in the API (docs/api.md). Nest reports
  that something happened; the agent decides what it means. Two copies of an identity
  matcher once drifted until one matched every employer on earth.
• packages/ui is the only source of UI (docs/design.md). No
  overriding styles at the call site.
• There are no organizations. Single tenant, deliberately. An organizationId
  that is always the same value is a column, an index and a permissions check that
  buys nothing and reads like a real one at review time.

Quick start Copy Chapter

You need Bun and Docker.

git clone https://github.com/trycompai/crm.git && cd crm
cp .env.example .env          # then fill in the values below
bun install

docker compose up -d          # Postgres on :5432

bun run db:deploy             # apply migrations
bun run db:seed               # optional: a believable pipeline to look at
bun run dev

The app is on localhost:3000, the API on
localhost:3001.

That clone gives you release, the default branch and the last tagged release — what you
want if you are running this. main is where unreleased work lands: green, but not cut
yet. If you are here to send a pull request, git switch main first and read
CONTRIBUTING.

The values to set Copy Section

Open .env and set these. Everything else in the file is optional and commented out.

Pick at least one of Google and Microsoft, or add your own identity provider on
Settings → SSO once you are in. Setting both is fine and common: the sign-in page
offers both buttons, and each rep's mail is read from whichever they signed in with.

DATABASE_URL already matches the docker compose Postgres, so leave it alone unless
you brought your own.

Getting the Google OAuth client

1. Google Cloud console → Credentials → Create credentials → OAuth client ID → Web application.
2. Under Authorised redirect URIs, add http://localhost:3001/api/auth/callback/google.
3. Enable the Gmail API and the Calendar API for the project.
4. Copy the client ID and secret into .env.

Google is the sign-in method a clone starts with, and the same client reads Gmail and
Calendar — so most installs want it. The API will nonetheless boot without it: an
install that signs in with Microsoft, or through its own identity provider added on
Settings → SSO, leaves both empty and gets no Google button and no Gmail sync. Set
them together or not at all; half a pair is a button that fails at Google. If your
account is on a Google Workspace domain, set the consent screen to Internal and
nobody outside your org can even reach the prompt.

Getting the Microsoft app registration

1. Azure portal → Microsoft Entra ID → App
   registrations → New registration. Microsoft's own walkthrough is
   Register an application.
2. Under Supported account types, pick Accounts in this organizational directory
   only if everyone signing in is on your tenant. Anything wider is fine too —
   ALLOWED_SIGN_IN still decides who gets an account — but the narrow choice turns
   outsiders away at Microsoft rather than at our door.
3. Set the Redirect URI to Web and
   http://localhost:3001/api/auth/callback/microsoft. In production this is
   https://<your-api-host>/api/auth/callback/microsoft — the API's origin, not the
   app's, because the API is what serves /api/auth/*.
4. API permissions → Add a permission → Microsoft Graph → Delegated
   permissions → tick User.Read and Mail.Read. offline_access is requested
   at sign-in and needs no entry here. If your tenant requires admin consent, click
   Grant admin consent so reps are not each asked.
5. Certificates & secrets → New client secret. Copy the Value, not the
   Secret ID — the value is shown once and never again.
6. Overview → copy the Application (client) ID.
7. Put the two into .env as MICROSOFT_CLIENT_ID and MICROSOFT_CLIENT_SECRET.

Mail.Read is read-only: the CRM can list and read messages and can never send,
reply, move or delete. Reading is forward-only — the first check records the current
time and imports nothing, so connecting an old mailbox does not dump years of mail into
the CRM.

To refuse other tenants at Microsoft rather than relying on ALLOWED_SIGN_IN, set
MICROSOFT_TENANT_ID to your tenant's GUID (Overview → Directory (tenant) ID).
It defaults to common, which accepts any work, school or personal Microsoft account
and leaves the allow-list to sort them out. organizations is the middle setting: any
work or school account, no personal ones.

Microsoft client secrets expire — 24 months at most, and 6 months by default. Note the
expiry somewhere, because the symptom of a lapsed one is every rep's mail quietly
failing to sync.

ALLOWED_SIGN_IN is the entire authorisation model — an unset value means nobody can
sign in, which is the safe direction to fail. It takes whole domains, individual
addresses, or a mix:

ALLOWED_SIGN_IN="acme.com"                       # everyone at your company
ALLOWED_SIGN_IN="acme.com,[email protected]"  # …plus one outsider
ALLOWED_SIGN_IN="[email protected]"                  # a one-person install

Configuration Copy Chapter

There is one .env, at the root of the repo, read by all three processes. Real
environment variables always win, so on a hosting platform you configure it there and
the file is purely a local convenience.

Beyond the values above, everything is optional and the app runs without any
of it. .env.example is the full list with a note on each; the
short version:

Tasks Copy Chapter

Scope any of them with a Turborepo filter: bun run dev --filter=api.

Because sign-in goes through an identity provider, there is no way to get a session from a terminal —
dev:session writes the rows Better Auth would have written and prints the cookie it
would have set. It refuses to run with NODE_ENV=production.

Deploying Copy Chapter

Three deployments and a Postgres: the Next.js app, the NestJS API, and the agent.
They are independent, and the only thing they must agree on is DATABASE_URL and
BETTER_AUTH_SECRET — the API mints the session cookie and the app verifies it, so a
mismatch is a redirect loop rather than an error.

Set API_URL and APP_URL to the real origins, and if the two are on different
subdomains of one parent, set AUTH_COOKIE_DOMAIN to the parent so one cookie covers
both. Add http://your-api-host/api/auth/callback/google — and, if you use Microsoft,
http://your-api-host/api/auth/callback/microsoft — to the provider's
redirect URIs. Set CRON_SECRET and point a scheduler at
POST /internal/sync/mailboxes to keep the mailbox sync running.

apps/api/src/generated/server.ts is committed and build must never regenerate it —
the generator needs a newer GLIBC than most build images have. Regenerate locally and
commit it with the router change that caused it.

Contributing Copy Chapter

We'd rather have a paragraph you wrote than a pull request an agent wrote. See
CONTRIBUTING.md.

Security issues go through SECURITY.md, privately, not a public
issue.

Licence Copy Chapter

MIT.

Overview (`adrs/README.md`) Copy Section

adrs

Proposals live here. One file per idea, .md or .txt, named after the thing you want to change.

Write it yourself, in your own words, at whatever length the idea actually needs — a paragraph is a
perfectly good ADR. See CONTRIBUTING.md for why we'd rather have that than a
pull request full of generated code.

Roughly:

• what you want to change
• why the current behaviour is a problem, ideally with the case that made you notice
• what you'd do instead, and what it would break

Nothing to record after the fact. These are for deciding, and they stay as the record of what was
decided.

Overview (`apps/api/README.md`) Copy Section

`api`

NestJS API for the CRM. Runs on Bun, backed by @crm/db and @crm/auth.

Running it Copy Chapter

cp .env.example .env        # at the repo root — one file for the whole monorepo
openssl rand -base64 32     # -> BETTER_AUTH_SECRET

bun run dev                 # watch mode on http://localhost:3001
bun run test
bun run build && bun run start:prod

Three values are required and the process refuses to boot without them, naming
the one it is missing: DATABASE_URL, BETTER_AUTH_SECRET and
ALLOWED_SIGN_IN. GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are the fourth
value almost every install wants — they are both the sign-in button and the
Gmail and Calendar sync — but they are optional and set as a pair, because an
install that signs in through its own identity provider on Settings → SSO
needs neither. With them, register
http://localhost:3001/api/auth/callback/google as an authorised redirect URI.
src/config/env.validation.ts is the full list of what this process reads;
docs/environment.md explains where the file is
found.

Bun is the runtime, not just the package manager: @crm/db and @crm/auth
ship TypeScript sources, so tsc/node cannot run this app directly. tsc is
used for type checking only (bun run check-types).

Routes Copy Chapter

How auth is wired Copy Chapter

This process owns authentication. It mounts /api/auth/* and is the only one
that writes session cookies; the Next.js app in apps/app reads those sessions
straight from Postgres via @crm/auth and calls the routes above with
credentials: "include".

AuthModule.forRoot({ auth }) mounts the Better Auth handler and registers a
global AuthGuard, so every route is protected unless it opts out:

@Get('public')
@AllowAnonymous()          // no session required
@OptionalAuth()            // session optional; @Session() may be undefined

It also calls enableCors({ origin: trustedOrigins, credentials: true }) for
the whole app, which is what lets the browser at localhost:3000 talk to it —
APP_URL is the single knob for that, comma-separated if the app is served from
more than one origin.

main.ts creates the app with bodyParser: false — Better Auth needs the raw
request body, and the library installs its own parsers around the auth routes.

AuthHooksService uses @AfterUpdate("user") to drop a cached profile the
moment its row changes. Database hooks require databaseHooks: {} in the Better
Auth options and endpoint hooks require hooks: {} (both set in @crm/auth);
the library throws at startup without them.

Caching Copy Chapter

AppCacheModule registers @nestjs/cache-manager globally. It uses REDIS_URL
when set and otherwise falls back to a per-instance in-memory store — fine for
local development, not for more than one API instance.

AuthService.getProfile is the reference pattern: read through the cache, write
with an explicit TTL, invalidate on change.

Notes Copy Chapter

• Better Auth stores rate limits in the database (rateLimit.storage), so every
  request to /api/auth/* needs a reachable Postgres. Moving this to
  secondaryStorage backed by Redis would remove that dependency.
• Environment variables are validated at boot by src/config/env.validation.ts.
  The process refuses to start on a bad config.

Overview (`apps/app/README.md`) Copy Section

This is a Next.js project bootstrapped with create-next-app.

Getting Started Copy Chapter

First, run the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying app/page.tsx. The page auto-updates as you edit the file.

This project uses next/font to automatically optimize and load Geist, a new font family for Vercel.

Learn More Copy Chapter

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.
• Learn Next.js - an interactive Next.js tutorial.

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!

Deploy on Vercel Copy Chapter

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.

Overview (`packages/auth/README.md`) Copy Section

`@crm/auth`

Better Auth configuration for the monorepo, backed by
@crm/db.

Enabled: Google sign-in, account linking, cookie-cached sessions, and
database-backed rate limiting. This is an internal, single-tenant app — there
are no organizations, and email + password is switched off so the only way in
is a Google account.

Topology Copy Chapter

The NestJS API (apps/api, port 3001) mounts /api/auth/* via
@thallesp/nestjs-better-auth and is the only process that writes session
cookies. The Next.js app (apps/app, port 3000) imports this package on the
server to read sessions straight from Postgres, and points its browser client
at the API for sign-in and sign-out.

Both processes therefore need the same BETTER_AUTH_SECRET and DATABASE_URL,
or the cookie one writes will not verify in the other.

Usage Copy Chapter

Server Copy Section

import { auth } from "@crm/auth";

// Session for an incoming request
const session = await auth.api.getSession({ headers: request.headers });

auth.handler is a standard (Request) => Promise<Response> function, so it
mounts anywhere. In a Next.js App Router route (app/api/auth/[...all]/route.ts):

import { auth } from "@crm/auth";

export const GET = auth.handler;
export const POST = auth.handler;

Client Copy Section

import { signIn, signOut, useSession } from "@crm/auth/client";

await signIn.social({ provider: "google", callbackURL: "/" });

NEXT_PUBLIC_API_URL decides which origin the client talks to. It must point at
whichever process mounts the handler — the NestJS API. The Next.js app inlines
it at build time from API_URL, in next.config.ts, so there is one variable
rather than two spellings of one origin. Unset, the client uses the current
origin.

The client plugin list mirrors the server plugin list. Keep them in sync or the
inferred client API will drift from the routes the server exposes.

Setup Copy Chapter

cp .env.example .env      # at the repo root — there is no per-package env file
openssl rand -base64 32   # -> BETTER_AUTH_SECRET

This package is a library and never loads an env file of its own; it reads
whatever process.env its host process has, and src/env.ts imports
@crm/env/load so the repo-root .env is picked up even when the Better Auth
CLI loads auth.ts directly. See
docs/environment.md.

Create an OAuth client in the Google Cloud console and add
<API_URL>/api/auth/callback/google — http://localhost:3001/api/auth/callback/google
in development — as an authorised redirect URI.

ALLOWED_SIGN_IN decides who may sign in, and an empty value admits nobody. It
is the whole authorisation model: there are no roles and no organizations, so
src/workspace.ts is worth reading before you change anything here.

Changing the schema Copy Chapter

Adding a plugin or an additional user field changes the database schema. After
editing src/auth.ts:

bun run auth:generate   # rewrites packages/db/prisma/schema.prisma
bun run db:migrate      # create the migration

Notes Copy Chapter

• JIT package. exports point at TypeScript sources, which keeps Better
  Auth's inferred types intact — declaration emit tends to break them.
  Turbopack transpiles workspace packages automatically, so a Next.js app needs
  no transpilePackages entry.
• Next.js server actions need the nextCookies() plugin (from
  better-auth/next-js) as the last entry in the plugin array. It is omitted
  here so the package stays framework-agnostic; add it — along with next as a
  dependency — once an app relies on setting cookies from server actions.
• Cross-origin cookies. On localhost the API and the app differ only by
  port, which cookies ignore. Deployed on separate subdomains they need
  AUTH_COOKIE_DOMAIN set to the shared parent (.example.com).

Overview (`packages/db/README.md`) Copy Section

`@crm/db`

PostgreSQL access for the monorepo: the Prisma schema, migrations, and a shared
PrismaClient instance.

Usage Copy Chapter

import { db } from "@crm/db";

const users = await db.user.findMany({ take: 10 });

Types and query helpers come from the same entrypoint:

import { Prisma, type User } from "@crm/db";

Setup Copy Chapter

docker compose up -d       # Postgres matching the DATABASE_URL in .env.example
cp .env.example .env       # at the repo root
bun run db:generate        # generate Prisma Client
bun run db:deploy          # apply the migrations

DATABASE_URL comes from the repo-root .env, loaded by @crm/env — see
docs/environment.md. src/client.ts imports
@crm/env/load before reading it, and prisma.config.ts does the same so the
CLI works without any app running.

Scripts Copy Chapter

Each is also exposed at the repo root (bun run db:migrate) and routed through
turbo run.

The root bun run dev command runs dev:prepare before any service starts and
reruns it when the schema or migrations change. Services that hold a Prisma
client restart only after preparation finishes, so they cannot retain an older
generated model map.

Notes Copy Chapter

• Prisma 7 + driver adapter. There is no query engine binary; the client
  talks to PostgreSQL through @prisma/adapter-pg. See src/client.ts.
• Generated code is not committed. prisma generate writes to
  src/generated/, which is gitignored and declared as the build task's
  output so Turborepo caches it.
• JIT package. exports point at TypeScript sources; the consumer compiles
  them. Turbopack transpiles workspace packages automatically, so a Next.js app
  needs no transpilePackages entry. Non-bundler consumers need a TypeScript
  runtime — the NestJS API runs on Bun for exactly this reason.
• Auth models are generated. User, Session, Account, Verification
  and RateLimit come from @better-auth/cli. Do not hand-edit them — change
  the Better Auth config in @crm/auth and re-run bun run auth:generate.
  The generator is additive: it adds models and fields a plugin needs but never
  removes the ones a dropped plugin left behind, so removing a plugin means
  deleting its models from the schema by hand.

Overview (`.agents/skills/nuqs/README.md`) Copy Section

nuqs Best Practices for Next.js

A comprehensive best practices skill for using nuqs - type-safe URL query state management - in Next.js applications.

Overview Copy Chapter

This skill provides 42 rules across 8 categories to help AI agents and developers write correct, performant, and maintainable code when using nuqs for URL state management.

Getting Started Copy Chapter

# Install dependencies (if any)
pnpm install

# Build AGENTS.md from references
pnpm build

# Validate the skill
pnpm validate

Categories Copy Chapter

Creating a New Rule Copy Chapter

1. Create a new file in references/ with the pattern {prefix}-{slug}.md
2. Use the template from assets/templates/_template.md
3. Include YAML frontmatter with title, impact, impactDescription, tags
4. Add Incorrect and Correct code examples
5. Run pnpm build to regenerate AGENTS.md
6. Run pnpm validate to check for errors

Rule File Structure Copy Chapter

---
title: Rule Title
impact: CRITICAL|HIGH|MEDIUM|LOW
impactDescription: Quantified impact (e.g., "2-10× improvement")
tags: prefix, keyword1, keyword2
---

## Rule Title

Explanation of WHY this matters.

**Incorrect (annotation):**
\`\`\`tsx
// Bad code example
\`\`\`

**Correct (annotation):**
\`\`\`tsx
// Good code example
\`\`\`

Reference: [Link](url)

File Naming Convention Copy Chapter

• Rule files: {prefix}-{descriptive-slug}.md (e.g., parser-use-typed-parsers.md)
• Prefix must match a section defined in references/_sections.md
• Use lowercase with hyphens

Impact Levels Copy Chapter

Scripts Copy Chapter

• pnpm build - Regenerate AGENTS.md from references
• pnpm validate - Check skill against quality guidelines

Contributing Copy Chapter

1. Check existing rules to avoid duplication
2. Follow the rule template structure
3. Include production-realistic code examples
4. Quantify impact where possible
5. Run validation before submitting

References Copy Chapter

• nuqs Documentation
• nuqs GitHub
• Next.js Documentation

Overview (`.agents/skills/vercel-composition-patterns/README.md`) Copy Section

React Composition Patterns

A structured repository for React composition patterns that scale. These
patterns help avoid boolean prop proliferation by using compound components,
lifting state, and composing internals.

Structure Copy Chapter

• rules/ - Individual rule files (one per rule)
  • _sections.md - Section metadata (titles, impacts, descriptions)
  • _template.md - Template for creating new rules
  • area-description.md - Individual rule files
• metadata.json - Document metadata (version, organization, abstract)
• AGENTS.md - Compiled output (generated)

Rules Copy Chapter

Component Architecture (CRITICAL) Copy Section

• architecture-avoid-boolean-props.md - Don't add boolean props to customize
  behavior
• architecture-compound-components.md - Structure as compound components with
  shared context

State Management (HIGH) Copy Section

• state-lift-state.md - Lift state into provider components
• state-context-interface.md - Define clear context interfaces
  (state/actions/meta)
• state-decouple-implementation.md - Decouple state management from UI

Implementation Patterns (MEDIUM) Copy Section

• patterns-children-over-render-props.md - Prefer children over renderX props
• patterns-explicit-variants.md - Create explicit component variants

Core Principles Copy Chapter

1. Composition over configuration — Instead of adding props, let consumers
   compose
2. Lift your state — State in providers, not trapped in components
3. Compose your internals — Subcomponents access context, not props
4. Explicit variants — Create ThreadComposer, EditComposer, not Composer
   with isThread

Creating a New Rule Copy Chapter

1. Copy rules/_template.md to rules/area-description.md
2. Choose the appropriate area prefix:
   • architecture- for Component Architecture
   • state- for State Management
   • patterns- for Implementation Patterns
3. Fill in the frontmatter and content
4. Ensure you have clear examples with explanations

Impact Levels Copy Chapter

• CRITICAL - Foundational patterns, prevents unmaintainable code
• HIGH - Significant maintainability improvements
• MEDIUM - Good practices for cleaner code

Overview (`.agents/skills/vercel-react-best-practices/README.md`) Copy Section

React Best Practices

A structured repository for creating and maintaining React Best Practices optimized for agents and LLMs.

Structure Copy Chapter

• rules/ - Individual rule files (one per rule)
  • _sections.md - Section metadata (titles, impacts, descriptions)
  • _template.md - Template for creating new rules
  • area-description.md - Individual rule files
• src/ - Build scripts and utilities
• metadata.json - Document metadata (version, organization, abstract)
• AGENTS.md - Compiled output (generated)
• test-cases.json - Test cases for LLM evaluation (generated)

Getting Started Copy Chapter

1. Install dependencies:

   bash Copy

   pnpm install

2. Build AGENTS.md from rules:

   bash Copy

   pnpm build

3. Validate rule files:

   bash Copy

   pnpm validate

4. Extract test cases:

   bash Copy

   pnpm extract-tests

Creating a New Rule Copy Chapter

1. Copy rules/_template.md to rules/area-description.md
2. Choose the appropriate area prefix:
   • async- for Eliminating Waterfalls (Section 1)
   • bundle- for Bundle Size Optimization (Section 2)
   • server- for Server-Side Performance (Section 3)
   • client- for Client-Side Data Fetching (Section 4)
   • rerender- for Re-render Optimization (Section 5)
   • rendering- for Rendering Performance (Section 6)
   • js- for JavaScript Performance (Section 7)
   • advanced- for Advanced Patterns (Section 8)
3. Fill in the frontmatter and content
4. Ensure you have clear examples with explanations
5. Run pnpm build to regenerate AGENTS.md and test-cases.json

Rule File Structure Copy Chapter

Each rule file should follow this structure:

---
title: Rule Title Here
impact: MEDIUM
impactDescription: Optional description
tags: tag1, tag2, tag3
---

## Rule Title Here

Brief explanation of the rule and why it matters.

**Incorrect (description of what's wrong):**

```typescript
// Bad code example

Correct (description of what's right):

// Good code example

Optional explanatory text after examples.

Reference: Link

File Naming Convention Copy Chapter

• Files starting with _ are special (excluded from build)
• Rule files: area-description.md (e.g., async-parallel.md)
• Section is automatically inferred from filename prefix
• Rules are sorted alphabetically by title within each section
• IDs (e.g., 1.1, 1.2) are auto-generated during build

Impact Levels Copy Chapter

• CRITICAL - Highest priority, major performance gains
• HIGH - Significant performance improvements
• MEDIUM-HIGH - Moderate-high gains
• MEDIUM - Moderate performance improvements
• LOW-MEDIUM - Low-medium gains
• LOW - Incremental improvements

Scripts Copy Chapter

• pnpm build - Compile rules into AGENTS.md
• pnpm validate - Validate all rule files
• pnpm extract-tests - Extract test cases for LLM evaluation
• pnpm dev - Build and validate

Contributing Copy Chapter

When adding or modifying rules:

1. Use the correct filename prefix for your section
2. Follow the _template.md structure
3. Include clear bad/good examples with explanations
4. Add appropriate tags
5. Run pnpm build to regenerate AGENTS.md and test-cases.json
6. Rules are automatically sorted by title - no need to manage numbers!

Acknowledgments Copy Chapter

Originally created by @shuding at Vercel.

Overview (`apps/agent/agent/sandbox/workspace/README.md`) Copy Section

/workspace

Scratch space for research in progress. Nothing in here is the record — the CRM
is the record, and it is reached through tools, not through this filesystem.

Useful for:

• Dossiers. dossiers/<contactId>.json — dump a profile you fetched, then
  grep/jq it instead of re-reading it into context.
• Diffs. Keeping last month's profile next to this month's is how a job
  change becomes visible without a second lookup.
• Working notes while you assemble a brief across several sources.

Two things this filesystem must never hold:

1. Anything out of a mailbox. Email bodies and meeting notes stay in the
   turn, in the app runtime. read_crm_history gives you the whole message
   because it is our own data; writing it here moves it somewhere with a
   different lifetime and a different set of eyes on it.
2. Credentials. There are none here, and there is no reason to create any.

There is no network from this sandbox. web_fetch and web_search still work
— they run outside it.

Agent Panel (`docs/agent-panel.md`) Copy Section

The Agent panel — read when touching the record sheet's Agent tab

lib/agent-record.ts maps a record kind to everything downstream: the header sent, the
claim minted, the field a conversation is filed under, the empty-thread questions.
AgentConversation holds only the handle (session id + cursor); the transcript is in
AgentEvent from the audit hook.

• Load with session.snapshot(), never by hand — one call returns the event
  prefix, the cursor, and a continuation token iff eve will accept another turn.
  Hand-rolling the stream produced every panel bug this thing has had.
• The token is the authority on whether a message can be sent, not our reading of
  the events.
• streamIndex: 0 on resume — the saved index is where the last reader stopped.
• The snapshot is cached for a minute, not refetched on every mount. A settled
  thread cannot change under us — ready is waiting on the rep, ended is over — and
  the snapshot is the whole session from index 0, tens of megabytes on a real thread.
  A live thread stays live through refetchInterval, which ignores staleTime.
• loadThread rethrows an abort. Swallowing it caches a false offline for the
  life of the staleTime; only a genuinely unreachable agent may return one.
• The archive is fetched only when the snapshot fails. It is the offline fallback
  and nothing else, so loading it up front bought a serial round trip on every open.
  Nothing renders until it lands — useEveAgent reads initialEvents once, at mount.
• It ages with the snapshot, and is never staleTime: Infinity. A session's
  archive is not immutable: the agent appends to it every turn. Held forever, an
  agent that goes down, comes back, and goes down again renders the first outage's
  transcript and silently drops what happened in between. Both reads mirror the same
  session, so both expire at SETTLED_TTL_MS.
• Never key the transcript on the archive. A refetch that lands while it is
  mounted is ignored on purpose; remounting to pick it up would abort a live answer,
  which is the same failure keepMounted exists to prevent. Correcting a stale
  fallback is the next mount's job.
• The audit hook does not archive reasoning.appended. Every delta carries
  reasoningSoFar, the whole reasoning to that point, so the archive grew as the
  square of the tokens — one insert per token, 90% of AgentEvent, for events the
  transcript never renders. reasoning.completed still lands. eve's durable stream
  keeps its own copy either way; this is only what we file.
• Quiet for 90 seconds is over, not working — restarted agents leave sessions with
  no closing boundary, which would lock the thread forever.
• An unreachable agent is offline, not working — fall back to the AgentEvent
  archive and keep the composer usable.
• An ended thread gets a Start-a-new-conversation button, not a locked box;
  composerState() keeps ended and working apart.
• Nothing mounts until the list has loaded, or a new session starts and remounts.
• The landed thread is captured once (resolveThread), or the first save swaps the
  open conversation out from under a live answer. It lives in ?thread=.
• keepMounted on the tab descriptor (detail-sheet.tsx) — Radix drops an inactive
  tab, aborting the stream mid-answer.
• autoScroll and nothing else; scrollAnchor stops it following the bottom.
• One MessageScrollerItem per message, not per part; ids prefer toolCallId.
• Scoped to the rep — a session id in a body decides which row, never whose.

This lives in the API and is not a breach of rule one: listing history decides nothing.

Agent (`docs/agent.md`) Copy Section

Agent — `apps/agent`

An eve app, its own deployment, owning every piece of
intelligence in this repo. Read with api.md, whose first rule is that none of this
may move into the API. Local dev, the bridge env vars and the manual dispatch command
are in docs/setup.md.

Read the eve guide before writing eve code —
apps/agent/node_modules/eve/docs/README.md matches the installed version;
.agents/skills/eve is the skill. Guessing typechecks, builds, then misbehaves.

Model Copy Chapter

Default zai/glm-5.2-fast; DEFAULT_AGENT_MODEL in @crm/db/settings because the
agent and the API both need it.

• A row (AppSetting), not an env var, via defineDynamic on session.started.
  Open conversations keep their model — prompt caches are per model.
• lib/model.ts always sends modelContextWindowTokens; eve never inherits it.
• A failed read logs and keeps the compiled fallback. Never throws.
• The chooser offers only tool-use models (ModelCatalogService).
• Not a frontier model, deliberately — refusing wrong answers is enforced by the
  tools and evidence model, not model strength.

Pictures are copied, never linked Copy Chapter

mirror() copies bytes to Vercel Blob; the record points at our copy. Lives in
@crm/db/blob — writers are lib/brand-images.ts, lib/portrait.ts,
FaviconService, ImageMirrorService, prisma/seed.ts.

• The key hashes the bytes — idempotent, and a redesigned mark gets a new URL.
• COMPANY_IMAGE_FIELDS (@crm/db/images) is the one list of picture columns.
• Fetch through @crm/db/safe-fetch — vendor URLs are SSRF vectors.
• No BLOB_READ_WRITE_TOKEN means no photographs; logos keep the origin URL.
• isOptimizable (@crm/db/images) is the whole rule: next.config.ts
  allow-lists only our Blob host (a wildcard makes us an open image proxy), and a
  mirrored SVG is still refused.
• Faces are not optimized — AvatarImage skips <Image> because Radix probes the
  URL itself, doubling fetches.
• A photograph only comes from a source already tied to this person —
  lib/portrait-sources.ts: their LinkedIn, their GitHub, their employer's team page,
  each keyed on an identifier already on the record.
• There is no image search by name, and there must never be. Nobody audits a face.
  Guess where to look, never what you will find.

Two lanes Copy Chapter

schedules/dispatch.ts, split by DIRECT_KINDS in @crm/db/agent-tasks.

Neither visible kind has anything to decide, and through a session they queued
behind sixty LLM runs for 25 minutes (test/lanes.integration.spec.ts). The row says
what the work is; the lane only says whether it needs a conversation.

Priority: brand 900 · portrait 800 · workspace 500 · requested 300 ·
meeting 200 · identify 100 · sweep 50 · companyProfile 40 · recheck 0. The
top two are what a rep reads before deciding what to open.

claimDue sorts what it claims — Postgres does not order UPDATE … RETURNING by
its sub-select's ORDER BY.

Dispatch on demand Copy Section

POST /internal/crm/dispatch drains both lanes; AgentTriggerService.poke() calls
it after writing any AgentTask.

• Fire-and-forget, never awaited — the row is still the message.
• Both lanes. Visible-only made them diverge under eve dev, where there is no
  cron: logos resolved instantly while identify sat at attempts = 0 forever.
• Calls the channel's own send, not receive — it is already on the crm channel.
  Principal from APP_AUTH (lib/app-auth.ts); taskAuth() keeps schedule and route
  from drifting.
• drainAll collapses via collapsing() (lib/pool.ts) — forty new contacts poke
  forty times, and claimDue hands each a disjoint batch. Per-process; cross-process
  overlap is leases and FOR UPDATE SKIP LOCKED.
• An abandoned sweep is still in flight, and dispatchHealth() says so. The
  timeout aborts the lanes, which stop between items, but the sweep only leaves
  unsettledSweeps when it truly settles. Until then health reports running: true
  and the endpoint answers 503, and a new sweep is refused rather than stacked on
  top of stuck work.
• A slow start(task) is reconciled, never failed. Past
  sweep.startTimeoutMs the lane stops waiting, the record stays Researching, and
  the late session id is attached by noteSession when the send lands. Only a send
  that actually rejects settles the record FAILED; a send that never lands is
  retired by retireExhausted after MAX_ATTEMPTS. A session id that never
  reaches the row after research.link.attempts raises unlinkedSessions in
  health, so a task running under a session nobody recorded is visible.
• AGENT_BRIDGE_SECRET unset refuses rather than opens.

`POST /internal/crm/verify-key` Copy Section

Probes a candidate Context key → valid/invalid/unknown. No session, no model, no
task row; exists because the API may not call Context.

• The probe is free and chosen to be — a free-provider address gets a 422 before
  billable resolution. Do not point it at a real domain: ten credits per typo.
• classifyKey rejects on 401 and nothing else.
• The candidate key, never the stored one.

Blank fields are filled on the dispatch tick Copy Section

sweepBlankFacts (lib/blank-facts.ts) applies every pending suggestion whose field is
still empty and clears the ones that have stopped saying anything. It runs at the top of
schedules/dispatch.ts, every minute, over every contact in the workspace — it is a
database pass with no session, no model, no task row and no credits, so there is nothing
to ration and nobody to scope it to.

• Scans 2000 suggestions and fills at most 500 a pass, and reports what it did not
  reach (unscanned) rather than a clean sweep it did not make.
• Idempotent — a second pass fills nothing, because those fields are no longer blank.
• The suggestions left are conflicts, every one against a value already on the
  record. That number should stay small and reads as work for a rep.
• It does not belong on sign-in, and that is not a preference. It lived there for one
  release and never once ran. Two reasons, either fatal: onSignedIn fires on
  session.create, so a rep already signed in never triggers it; and BackfillService
  does its work in a detached void (async () => …)() after the response, on a Nest API
  that is a Vercel serverless function (apps/api/api/index.ts) — the tail of that
  chain is not guaranteed to run at all. A cron in the agent is the only trigger here
  that is a fact rather than a hope.

Stale rows are closed on the dispatch tick Copy Section

reconcileStaleTasks (lib/stale-tasks.ts) runs before drainAll, every minute. Like
the blank-field pass it is a database pass with no session, no model and no credits. It
closes rows that are provably done or provably dead, so the queue a rep reads is the
work that is actually happening.

• It only looks at work that is due. A recheck booked ninety days out is not
  stale, it is scheduled, and closing it would delete the next look at that contact.
• A live lease is never touched. That is work in flight, whatever the record says.
• A record that completed after the task started closes the task with a plain
  outcome. That is the row the settle path failed to close: research landed, facts were
  written, and the task sat open holding the contact on Researching.
• A dead lease with attempts left goes back to waiting, and the lease is cleared so
  the row reads as waiting rather than as running. Exhausted rows are retired by
  retireExhausted, which is the one rule for giving up.
• Idempotent — a second pass in the same minute closes nothing, because the rows it
  closed have a finishedAt and the rows it released have no lease.
• Scans 200 rows a pass and reports unscanned rather than a clean sweep it did not
  make. The counts are in dispatchHealth().staleTasks, so a growing number of stale
  rows is visible at GET /internal/crm/dispatch-health.

It is a safety net, not the fix. The settle path still fails to close some rows;
this pass keeps that from reaching a rep, and the count it reports is how you see the
underlying bug getting worse.

Backfills Copy Section

Sign-in sweep covers records never looked up (10 credits/company);
ImageMirrorService in the same sweep re-hosts off-site pictures (free);
backfill:images fixes enriched records missing only pictures (free);
backfill:facts is the blank-field sweep above run by hand, with --dry to read it
first — the cron covers it, so this is for a machine pointed at another database.

• The image sweep keeps "every picture is ours" true, not true-since-Tuesday.
  25 rows/table/sweep.
• Nobody clicks a suggestion into a blank field. The rule is enforced at the write
  path, so no queue forms; the sweep is for rows written before it existed and for the
  field a rep clears while a suggestion is pending. An unreachable agent leaves the
  suggestions where they are — the API cannot apply one itself.
• A finished portrait task stands that contact down for thirty days — that third
  source costs credits and usually finds nothing.
• No button, deliberately — a rep cannot know which records predate a resolver.
• The trigger is signing in, via databaseHooks.session.create.after in
  packages/auth; BackfillService subscribes with onSignedIn and has no router
  (@crm/auth must not import a Nest provider). Five-minute stand-down, and auto()
  returns before work starts.
• The 500-row cap is on the pass, not each query in it. Deduplicate the union, cut
  to 500, count remaining against the union.

Evidence, not confidence Copy Chapter

No tool accepts a confidence, a score, or a sourceUrl offered as proof. Tools
report what they observed (crm.signature-block, github.account-identity) and
lib/evidence.ts prices it. A model asked to grade its own certainty will, and will be
wrong in the direction that looks useful.

• lib/facts.ts is the only write path to a contact's fields. Applies at
  VERIFIED, proposes below it, and enforces three things a prompt cannot: never
  overwrite a human, never re-offer a dismissal, never write without a primary source.
• A band decides only when there is something to lose. An empty field is filled by
  whatever cleared the floor for keeping, whatever the band — approving a sourced guess
  into a blank is a click that can only say yes, and a rep with four hundred contacts
  reads none of them. fillsBlank is the whole rule: no human value in the way and
  nothing already found. PROBABLE still means a rep decides when the field is
  already filled, which is the case where a wrong answer costs something. The dispatch
  tick applies the same rule to rows that predate it — sweepBlankFacts, above.
• Applying settles the field's other suggestions. They were all offers to fill the
  same blank, and the sheet shows one at a time — so left alone, accepting one reveals
  the next, forever. The same rule holds when a rep accepts one (decideFact).
• The same value is never offered twice. A second PROPOSED row with a value
  already waiting is refused at the write path, not deduplicated on read.
• "The same value" is sameValue, and a URL is compared as an address, not a
  string. canonicalValue lowercases, collapses whitespace, and for http(s) drops
  the scheme, www., a trailing slash and the query, and reads twitter.com as
  x.com. Compared byte for byte, …/in/pogrebs/ is not …/in/pogrebs, so the record
  showed a suggestion offering back the URL already in the field — the exact click this
  whole rule exists to remove. The stored value is still what the source said; only
  the comparison normalises. The refusal
  is for offers only — the check runs after applies is decided, so evidence that has
  reached VERIFIED since the offer was made still lands, settles the suggestion it
  matches, and replaces the older value. Refusing it there left a weaker value on the
  record with the answer sitting unread beneath it.
• A new fact field goes in FIELDS (lib/facts.ts) and FACT_COLUMNS
  (apps/api/src/contacts/contacts.service.ts).

Optional by default Copy Chapter

lib/capabilities.ts is the single place that knows what is set: prints it at boot,
states it in the session instructions, and gives tools a shared "not configured,
retrying will not help" result — checked before the research budget is charged. A
missing key removes a place to look. Never an error, never throws.

capabilities() is async because the Context key is a row;
capabilitiesFrom()/markdownFor() are the pure halves. contextDevKey() is the only
resolver, and lib/context-dev.ts memoises its client on the key string.

Budget and scheduling Copy Chapter

• lib/focus.ts — per-session budget in defineState; running out is a normal ending.
  A unit is one metered vendor call, not one credit. spend(2) is what a
  billable lookup costs: a brand lookup is 10 Context credits, a person enrich is
  20. Both charge 2, because the budget rations calls per contact and a session
      with a budget of 4 must still be able to make two of them.
• lib/tasks.ts — claimDue leases with FOR UPDATE SKIP LOCKED.
• schedules/dispatch.ts is the only schedule and decides nothing. "Every N
  minutes, the oldest ten contacts" belongs in a dueAt.
• tools/schedule_recheck.ts — its reason is shown to the rep.

Three records, no dead ends Copy Chapter

Every read hands back the ids of neighbouring records. Breaking this made the agent
ask a rep who had a company open, contacts on screen, to paste an email.

A preamble or tool result naming a record without its id is a bug — the only
recovery is asking the human. Ambiguity is fine: four Marchettis is four rows with
titles. search_crm does no fuzzy matching — "Marchetti" reaching "Marchetta" is a
wrong record about a real person.

Preambles Copy Section

lib/preamble.ts varies on which record (each names its neighbours with ids and
points at the read to start from) and who opened it — a dispatched task is a
research pass with a budget, a rep in the sheet is a conversation. Told neither, the
agent answered a question with a work plan. taskKind is the tell.

task.ts is the resolver and owns one side effect: seeding lib/focus.ts, without
which the audit hook files events against nothing.

A fourth record kind = sessionPreamble entry + a read + a TOOL_VERBS line
(apps/app/lib/agent-transcript.ts) + a COPY entry (lib/agent-record.ts).

Every session knows who *we* are Copy Section

composeClosing() puts a Who we are block before the capabilities in every
preamble; lib/workspace.ts is the only renderer.

• Tiny, enforced by the write path — MAX_NARRATIVE (320) and MAX_LINE in
  @crm/db/workspace. It is prompt-cached and precedes every question.
• It says what the context is for — fit, competitor, partner, or nothing — and
  never a pitch, or the model sells our own product back to us.
• No profile still gets the name line, plus do not guess at what we sell.
• The profile dies with its website — readWorkspaceIdentity returns it only while
  website matches.
• Not a Company row — that needs excluding from every list, facet and join. One
  WorkspaceProfile keyed on WORKSPACE_ID.

The pass is a workspace-profile task using web_fetch (no credits), filed only via
write_workspace_profile, queued by WorkspaceService.update on a website change. A
finished attempt stands the sweep down for seven days.

What may be read, and what may leave Copy Chapter

It may read everything, including full email bodies — internal single-tenant tool,
and a signature block is the best source of a job title there is. The boundary is
egress:

1. No customer text in a third-party query. Derived questions only.
2. Nothing from a mailbox into /workspace — different lifetime.
3. Nothing sensitive logged. Reading is not logging.

skills/data-boundaries.md is the agent's copy. Keep them in step.

Sandbox Copy Chapter

agent/sandbox/sandbox.ts: bash, file tools, /workspace, deny-all egress on
the backend factory so it cannot be forgotten per session. Costs nothing —
web_fetch runs in the app runtime, web_search at the provider.

Never give the sandbox DATABASE_URL. CRM access is authored tools. A shell with
credentials and network is exfiltration-shaped; with neither it is a text processor.

Team-agent builder and runner Copy Chapter

agent_builder and agent_runner are declared subagents with independent
instructions, tools and deny-all sandboxes. They inherit nothing from the root. The
root built-in agent copy tool is disabled; these two named specialists are the only
delegation paths for custom agents.

• Creation requires the current CREATE_AGENT turn. Every builder tool checks the
  purpose and command type in session auth. A normal builder chat cannot create a
  draft by prompt alone.
• Builder clarification is durable HITL. The specialist calls eve's built-in
  ask_question directly; descendant input requests are proxied to the root channel,
  and the same child turn resumes when the user answers. The authored
  tools/ask_question.ts disable override must stay absent. Builder task output is
  typed as draft_ready and carries the immutable version ids only after save.
• Empty never means all. A version chooses SELECTED or WORKSPACE record scope.
  Selected scope requires at least one record tagged in that private conversation;
  workspace scope is an explicit grant and cannot also list selected records.
• Connections are executable permissions. Only google:gmail and
  google:calendar are accepted, only when connected, and the runner does not query
  their synced tables unless the deployed manifest includes that source.
• Actions are structured permissions. crm.activity.create separately names
  NOTE, TASK, or both. Runtime enforcement never infers a grant from the action's
  prose summary. Every action is ledgered before execution and keyed by eve's call id
  for replay safety.
• CRM events are shared domain contracts. @crm/db/crm-events owns the event
  vocabulary, record kind, and builder-facing description used by the API, builder,
  and worker. API writes enqueue a durable agent-event task; the agent worker alone
  matches live triggers and creates runs. Do not duplicate event lists in prompts or
  feature code.
• Versions can have multiple triggers. The manifest stores a triggers array and
  each entry becomes its own AgentTrigger row. Deployment enables every trigger on
  the approved version, so one agent can react to several independent lifecycle
  moments without polling or duplicate agents.
• Deployment is the human approval boundary. Saving produces a private READY
  version and never deploys it. The review screen shows its triggers, scope, actions,
  access and exact files. A user's Deploy action pins that immutable version for the
  team. Scheduled runner sessions use task mode and therefore cannot pause for a
  per-action approval; the deployed permission and idempotent runtime checks are the
  boundary.
• Approved instructions are system context. The runner resolves the pinned
  version instructions at session.started, then calls inspect_run for the manifest
  and current run state. Every runner tool also checks the team-agent purpose and
  revalidates scope and action permission.
• Stopping a run is a row, not a signal. agents.cancelRun settles the
  AgentRun to CANCELLED inside one transaction — terminal event, outstanding
  AgentAction rows, audit entry — and then pokes
  POST /internal/crm/cancel-run, which calls eve's cancel({ continuationToken })
  for run:<id>. The row is what stops the work: every run tool refuses a run
  that is not RUNNING, so a cancel that never reaches the agent still means
  nothing further is written. The poke only stops it spending tokens, and an unset
  AGENT_BRIDGE_SECRET costs exactly that and nothing more.
• Cancelling is not undoing. eve keeps side effects that already completed, so
  a note, task or Slack message the run already made stays. The dialog says so.
• Whoever started it can stop it, plus the creator and workspace admins.
  canCancel is computed server-side per run and is what the button reads, so the
  control and the 403 cannot disagree.
• turn.cancelled settles the run too, keyed off run: in the continuation
  token, so a cancel from any other path still reaches finishedAt rather than
  leaving the run reading Running forever.
• No generic execution surface. Both specialists disable shell, file, arbitrary
  web and todo built-ins. The runner also disables direct questions; the builder keeps
  only ask_question for durable clarification. CRM access exists only through their
  small authored tool sets. Tool code runs in the trusted app runtime; the sandbox
  remains isolated and deny-all.

Runner manifests fail closed when either the explicit record-scope mode or an
activity type grant is missing. Versions created before these typed permissions were
introduced must be revised and deployed again before they can run.

bun run --filter=agent eval runs the eve end-to-end builder eval against the real
HTTP channel. It creates an isolated private conversation, dispatches the builder,
asserts the declared subagent path, verifies a READY side-effect-free manifest, and
cleans up its rows. It skips visibly when the database, bridge secret or model
credential is unavailable.

The bridge Copy Chapter

browser → /eve/v1/*  (same origin, session cookie, x-crm-contact header)
        → apps/app/app/eve/v1/[...path]/route.ts
            checks the Better Auth session, strips the cookie,
            mints a 2-minute HS256 token naming the rep + record
        → AGENT_URL/eve/v1/* → channels/eve.ts repFromCrm()
                             → instructions/task.ts reads attributes.contactId

• The record travels in the token, never in the message.
• Mounted at /eve/v1/* because that is where useEveAgent() looks — no host,
  no CORS, no cross-site cookie.
• The proxy is an enforcement point, not a passthrough — the agent never sees the
  session cookie, so if that route did not check, nothing would.
• eve's jwtHmac() resolves to principalType: "service" — wrong for a person,
  and lib/approval.ts reads exactly those fields to decide whether to pause for a
  human. repFromCrm maps the subject to a real user principal
  (test/channel-auth.spec.ts).
• AGENT_BRIDGE_SECRET unset skips the auth entry rather than opening it.

The panel Copy Section

lib/agent-record.ts maps a record kind to everything downstream. The panel's own
rules — snapshot loading, composer state, thread capture, scrolling — are in
docs/agent-panel.md. It lives in the API and is not a breach of rule one:
listing history decides nothing.

Continuation tokens are namespaced Copy Chapter

eve prefixes them with the channel name. channels/crm.ts mints task:<id>;
session.waiting returns crm:task:<id>. Minting the prefix ourselves meant matching
against crm:crm:task:<id> and returning before completeTask — research ran, facts
were written, sessions looked clean, but no task reached finishedAt, so contacts
sat on "Researching" forever. Hidden because the archived event's
data.continuationToken is un-namespaced while channel.continuationToken is not.

Conversations are kept Copy Section

A record accumulates conversations, and they survive a reload. AgentConversation
holds the handle — the durable eve session id plus its cursor — while the
transcript itself is already in AgentEvent, written by the audit hook. Nothing
is stored twice.

• Resuming. The panel passes the saved cursor as initialSession, so
  reopening a contact continues last week's thread rather than starting another.
  eve keeps sessions for 30 days.

• Replay from the start. streamIndex: 0 on resume, deliberately — the
  saved index is where the last reader stopped, and a reopened thread should
  show what was said in it, not only what has happened since.

• Which thread is open lives in the URL (?thread=), like every other view
  state in the sheet, so a refresh keeps your place and a conversation is a link.
  It is cleared when the record or the tab changes, by the same rule that drops
  a half-typed quick-add form.

• Nothing mounts until the list has loaded. Rendering a thread while the
  history is still in flight starts a new eve session and then remounts onto
  the real one — which presents as "the history only appears if I refresh".

• The thread the panel landed on is captured once. Re-deriving "the latest"
  as the list changes would swap the open conversation out from under a live
  answer the moment the first save adds a row. resolveThread in
  lib/agent-transcript.ts holds the rule, and it is tested.

• The panel is not unmounted when you switch tabs. It holds a live stream,
  and Radix drops an inactive tab by default — which aborts the stream
  mid-answer, so the reply landed in the durable session with nothing attached
  to receive it. That is the "I went to another tab and the answer never came
  back" bug, and no amount of re-reading state on the way in could fix it,
  because the events had been dropped. keepMounted on the tab descriptor
  (detail-sheet.tsx) keeps it alive; it renders nothing until the tab is
  opened once, so flicking through records costs nothing.

• A thread is loaded with session.snapshot(), not by hand. One call
  returns the complete event prefix, the cursor that continues from it, and a
  continuation token if and only if eve will accept another turn — about 30ms
  against a hundred-event thread. lib/agent-session.ts is the whole of it.

  What it replaced is worth remembering, because every panel bug of the last
  day came out of it: a raw fetch of …/stream?startIndex=-1, parsing the
  last line into a state machine. The endpoint follows, so awaiting the body
  never returned. The stream opens with a bare newline, so "the first line" was
  empty — which failed closed to "busy" and locked every reopened
  conversation with "still working on the last question", including ones parked
  with a perfectly good token. And a read that failed reported the session as
  working rather than reporting itself as broken, so it could never recover.
  The framework had a documented answer to the exact question that code was
  asking. Read the guide before hand-rolling the protocol.

• The token is the authority on whether a message can be sent, not our
  reading of the events. eve returns one only when the captured prefix ends
  parked, which is precisely the condition under which the next send lands.

• A turn that has gone quiet for 90 seconds is over, not working. A
  restarted agent leaves sessions with no closing boundary; they never park, and
  treating them as in-flight locks that thread forever.

• An unreachable agent is offline, not working. One is a fact about us
  and the other a claim about the session; stated as the latter it is both
  untrue and unrecoverable, since the read fails identically next time. The
  transcript then comes from our own AgentEvent archive — which is also what
  makes a thread older than eve's 30-day retention still readable — and the
  composer stays usable.

• An ended thread gets a button, not a locked box. Ended and working both
  disable the composer and mean completely different things: one is a wait of
  seconds, the other is permanent. composerState() keeps them apart, and an
  ended thread offers Start a new conversation, which moves the picker to a
  new thread. The transcript stays on screen throughout, and the save hook
  treats the fresh session as a new conversation by comparing session ids
  rather than by whether the panel started empty.

• autoScroll and nothing else. The scroller is a state machine
  (following-bottom, free-scrolling, anchored-to-message) and
  scrollAnchor selects the third, which stops it following the bottom — the
  answer then streams below the fold while the modes fight over each new row.
  Left alone, autoScroll follows the tail while the reader is at the bottom
  and releases the moment they scroll away, which lights the jump-to-end button.

• One MessageScrollerItem per message, not per part. The row is what the
  scroller measures; a row per tool call adds a boundary every few hundred
  milliseconds during an answer. Part ids prefer toolCallId, which is stable
  across a call's streaming states.

• A thread nobody has spoken in is loaded from nothing. The snapshot query
  is disabled without a conversation; a brand-new thread mounts with no session
  and no events, and its first message creates both.

• Scoped to the rep. Two people asking about the same contact are having two
  conversations. ConversationsService filters on the caller, and a session id
  in a request body decides which row, never whose.

• Cached the way api.md prescribes: read through
  cache-manager (Redis when REDIS_URL is set), write on miss, explicit
  invalidation on every save. The list is read on every sheet open and changes
  only when somebody sends a message, which is the shape a cache is for.

This lives in the API rather than the agent, and that is not a breach of rule
one: listing a record's history researches nothing, scores nothing and decides
nothing. The agent owns judgement; the data surface owns filing.

Turning it on Copy Section

Same value in both processes, from the one root .env:

AGENT_URL="http://127.0.0.1:2000"        # the default
AGENT_BRIDGE_SECRET="$(openssl rand -base64 32)"

Then bun run dev (the agent serves on :2000) and open any contact.

If the Agent tab errors:

eve dev takes about five seconds to bind, and it listens on IPv4 only.
That is why AGENT_URL defaults to http://127.0.0.1:2000 rather than
http://localhost:2000: Node resolves localhost to ::1 first, so the
localhost form fails to connect on a machine where the agent is plainly
running — and reports itself as "not reachable", which sends you looking in the
wrong place.

A variable in .env is not enough on its own: Turbo runs in strict env mode, so
apps/app/turbo.json and apps/agent/turbo.json both declare the pair in
passThroughEnv. Adding a variable and not declaring it produces exactly the
401 above.

Checking it without a browser Copy Section

localDev() accepts anything on loopback, so a bare curl to 127.0.0.1
proves nothing about the bridge. Send a non-loopback Host to make that entry
skip:

curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'Host: agent.example.com' \
  http://127.0.0.1:2000/eve/v1/info                      # 401

curl -s -H 'Host: agent.example.com' \
  -H "authorization: Bearer $TOKEN" \
  http://127.0.0.1:2000/eve/v1/info | jq '.tools.available | length'

GET /eve/v1/info is the whole inventory — tools, skills, schedules, channels,
sandbox, and a diagnostics count that is the fastest way to find a file eve
silently ignored.

Watching it work Copy Chapter

eve dev shows every tool call, every result and every token in its interactive
TUI, and it is the agent package's default dev command. The package's Turbo
task is explicitly interactive, so select the agent pane and press Enter to hand
stdin to eve. Type /traces to open the live trace viewer; Ctrl+Z returns input
to Turbo.

dev:headless keeps eve dev --no-ui available when a terminal cannot render
the nested TUI. It starts the same server on the same port with the same routes
and watcher. In that mode hooks/activity.ts narrates the session instead: a
line per tool call with its arguments, a line per result with how long it took,
the finish reason and token spend of each step, and any failure with its code.

• The lines go to stderr, not stdout. The TUI's default log mode is stderr
  and it keeps stdout buffered and hidden, so a console.log here would be
  invisible in the mode it exists to serve. Written to stderr the same lines show
  under --no-ui, under the TUI, and in eve logs.
• Contents print outside production; the shape prints everywhere. Which tool
  ran, whether it worked, what it cost — none of that is anybody's data, so it
  logs wherever the agent runs. Arguments and replies carry names, addresses and
  whatever a rep typed, which is the "nothing sensitive logged" rule above, so
  they are gated on NODE_ENV. In production the durable record is an
  AgentEvent row, not a log drain.
• It is not the audit trail. hooks/audit.ts writes every event to
  AgentEvent whatever this prints, and the panel's transcript is read back from
  there. A change to one is not a change to the other.
• A call is timed by remembering it, because the result event does not carry
  the tool name or a duration. The map of in-flight calls is bounded rather
  than trusted: a turn that dies between request and result would otherwise leak
  an entry per call, forever, in a process that stays up for days.

eve logs reads the full record back, but only for an interactive eve dev
— that is the process that writes .eve/logs/. Under --no-ui the pane is the
record, so keep the turbo scrollback rather than going looking for a file that
was never written.

Two consequences of opting into dev:headless, both worth recognising rather
than debugging:

• A headless dev process cannot reconnect. An interactive eve dev
  reconnects to a local server that is already up; dev:headless rejects it and
  exits non-zero. A dev server is already running for this eve agent means
  exactly what it says: use the terminal it is in, or stop it before starting
  another.
• An orphaned agent holds the port. If turbo dies without reaping its child,
  nothing on screen says so and every later dev:headless fails the same way.
  lsof -nP -iTCP:2000 -sTCP:LISTEN names the process to kill.

Nothing is researching, and the queue only grows Copy Section

eve dev never fires schedules on their cron cadence. It is one line in
eve's own schedules guide,
and it used to be the single most confusing thing about working on this agent,
because every visible part of the loop worked: the Research button wrote its
AgentTask row, the sheet said Queued, the toast promised the page would
update — and schedules/dispatch.ts, the only thing that turns a row into a
session, was never called. Twenty rows sat with attempts = 0 and AgentEvent
was empty. Nothing was broken and nothing reported a problem, because nothing
ran.

The poke is what makes dev behave like production now, which is most of why
it was widened to both lanes — see dispatch on demand.
A row written by the API is dispatched immediately whatever the clock is doing,
so the schedule is a backstop rather than the only door.

It only does that when AGENT_BRIDGE_SECRET is set, and that variable is
optional: poke() reads it first and returns without sending anything when it is
unset. So an install that has not set it is back at the paragraph above with no
cron behind it either — rows queue, nothing dispatches, and the queue looks
exactly like a slow agent. Set it, or run the dispatch below by hand.

That leaves two cases where the clock's absence bites even with the poke
working, and both look identical to the above: a task the API did not
write — schedule_recheck,
which books its own dueAt weeks out — and anything queued while the agent was
down, since a missed poke is not retried. For those, the dev server mounts a
one-shot route that runs the exact dispatch path production cron uses:

bun run --filter=agent dispatch
# {"scheduleId":"dispatch","sessionIds":["wrun_01KZ…", …]}

It drains both lanes, exactly as the cron does: up to VISIBLE_BATCH (60)
brand and portrait rows six at a time, handled in the process with no session
at all, and RESEARCH_BATCH (12) research rows, one session each. So the
sessionIds it prints are the research rows only — a run that resolved forty
logos prints an empty list and was not idle. Either way it spends real credits, a
vendor call per visible row and a model session per research one; that is the
point of it, and the reason it is a command you run rather than a ticker somebody
leaves on. Watch the agent pane; the session ids it returns are also streamable at
GET /eve/v1/session/:id/stream.

eve start on a built app does run the schedule, and so does Vercel, where
each defineSchedule becomes a Cron Job. Dev is the only place the clock is
missing.

The continuation token you write is not the one you read Copy Section

eve namespaces a continuation token with the channel's name. channels/crm.ts
mints task:<id>; by the time session.waiting hands it back on the channel
context it is crm:task:<id>. The eve channel's own sessions read back as
eve:<uuid> for the same reason.

This is worth stating because of how it failed, which was silently and
completely. taskToken() used to mint crm:task:<id> itself, so the handler was
matching startsWith("crm:task:") against crm:crm:task:<id>, getting null,
and returning before completeTask. Nothing errored. The research ran, facts
were written, briefs were saved, and the agent pane showed a clean session — but
no task ever reached finishedAt, so every contact sat on "Researching"
forever and the sweep re-queued work that had already been done. Twenty-eight
tasks, zero finished.

Two things made it survive a reading:

• The event data and the channel accessor disagree. session.waiting's
  data.continuationToken carries the token as stored — un-namespaced — while
  channel.continuationToken carries it namespaced. Debugging from the archived
  event says the token is fine, because from that angle it is.
• Nothing downstream depends on settling. The record's status is the only
  thing that notices, and "still researching" is indistinguishable from
  "researching slowly" until you look at attempts in the table.

So taskFromToken keys on the task: marker rather than a fixed prefix, which
reads correctly whoever namespaced it and still settles sessions parked before
the fix. test/crm-token.spec.ts pins all three forms.

The general rule: a channel handler must not assume the token it receives is
byte-identical to the one it sent. Parse for your own marker.

Tests Copy Chapter

bun run --filter=agent test. The integration specs need DATABASE_URL and run
against a real Postgres, which is the point — "never overwrite a human" is only
true if the transaction says so.

The test/e2e scripts are separate and you run them by hand. Three of them cost
money or change something outside the database, so each one is off unless you
switch it on:

Stop the local agent before you run an e2e script against a dev database. A
running agent leases the rows the script seeds and retires exhausted tasks the
script did not create.
taskFromToken keys on the task: marker, not a fixed prefix
(test/crm-token.spec.ts). A channel handler must not assume the token it receives
is byte-identical to the one it sent.

Api (`docs/api.md`) Copy Section

API Rules

Logging Copy Chapter

apps/api/src/logging. new Logger(Thing.name) picks up ContextLogger. Never
console.log. Format follows NODE_ENV and is not configurable.

• One object, not extra arguments — logger.log({ message: "Saved", userId });
  Nest prints a line per argument.
• Errors pass the stack second — logger.error({ message }, err.stack). Passing
  the error object drops the trace.
• Never log headers, query strings, or bodies — cookies and personal data.
• LoggingModule stays first in AppModule's imports, and Better Auth routes log
  via its own middleware option — it mounts before MiddlewareConsumer, so
  /api/auth/* never reaches ours.
• requestId from RequestLoggerMiddleware via AsyncLocalStorage;
  UserContextInterceptor adds userId. Prisma statements are opt-in
  (PRISMA_LOG_QUERIES).

Intelligence never lives in the API Copy Chapter

The API serves HTTP, auth, tRPC and the mailbox sync. It does not research, enrich,
score, summarise, match identities or decide anything about a person or company — not
as a fallback, not behind a flag. That is the eve agent in apps/agent, which owns
the vendor clients, the confidence model and the writes.

Nest's half is to report that something happened: AgentTriggerService writes an
AgentTask row. A row, not an HTTP call — the agent already leases from that table,
so the row survives the agent being down.

About to add a vendor client to apps/api? You want apps/agent/agent/lib. One
documented exception, for timing: the exchange-rate fetcher, below.

One organization, and it is not a tenancy boundary Copy Chapter

Single tenant. No org header, no org interceptor, no org-scoped cache keys, no
organizationId on any CRM record.

A singleton workspace exists — Better Auth's organization plugin, one row with
id WORKSPACE_ID (the literal workspace, in @crm/db, re-exported by @crm/auth
so the agent needn't depend on it). It answers only: what are we called, who works
here, what do we sell.

• The id is a constant, never a parameter. A function taking an organizationId
  has turned the plugin into tenancy plumbing.
• Signing in is the join; no invite flow. ensureWorkspaceMembership runs in
  databaseHooks.session.create.before and degrades, never throws — a throw fails
  the session create and locks everyone out. The plugin's invitation table is unused.
• First account is owner, and the hook enrols pre-existing users, oldest first.
• Permissions come from @crm/auth — canRenameWorkspace, canChangeRole,
  canConfigureSso, canManageCurrency — enforced by the service and used to
  disable the UI control, so the button and the 403 cannot disagree.
  WorkspaceService adds one invariant: the last owner cannot be demoted, with
  FOR UPDATE on the owner rows before counting.
• Reads and writes go through tRPC, not authClient.organization.*.
• Name and website are required at onboarding and cannot be skipped, in the form
  and in updateWorkspaceInput, posting the same workspace.update as settings.
• Onboarded state is onboardedAt inside the plugin's metadata blob, not a
  column; isOnboarded/markOnboarded (@crm/db/workspace) are the only accessors,
  and markOnboarded preserves every other key.
• The name starts as DEFAULT_WORKSPACE_NAME (CRM), a placeholder not an
  answer. The header renders <name> CRM, so workspaceLabel tests the name rather
  than comparing to the default.
• The website queues the agent's workspace-profile task and goes through
  normalizeDomain, rejecting null. Stored canonical, so re-saving uncanonically
  counts as a change and re-queues research.

Gates in `proxy.ts` Copy Section

Onboarding, then /onboarding/research for the Context key. Asked server-side every
request.

• getSessionCookie() decides signed-in; pages still resolve the real session via
  requireMailboxAccess().
• Nothing is cached in a cookie — both facts revert on a database reset while a
  year-long marker insists the gate passed. Cache in the API if cost ever matters.
• Both reads run concurrently, but order decides which is asked — the research
  read is never made while onboarding is open.
• An unreachable API fails open (unknown lets the request through).
• /sign-in, /grant-access, /eve are ungated. /sign-in is the only path a
  stranger may read; / joins it only when IS_MARKETING is set.
• There is no way past the key gate but to answer — Skip stranded installs, every
  later company sitting PENDING with nothing saying so.

The name is also the URL Copy Section

Served under the workspace slug (/comp-ai/companies). Cosmetic, not tenancy —
every query still resolves through WORKSPACE_ID.

• The slug is the plugin's column, written by workspaceSlug(name)
  (@crm/db/workspace) on rename and create. Never derive it on read.
• ensureWorkspaceMembership reconciles it; RESERVED_SLUGS prevents collision with
  a real route (a collision gets -crm).
• The proxy is the only thing that puts the slug on. Missing or stale slugs are
  redirected with the query string intact, not 404'd; [slug]/layout.tsx is the
  backstop.
• appPath in proxy.ts is the one place / resolves for a signed-in rep, which
  keeps every callbackURL correct without knowing about slugs.
• Renaming moves the URL, so workspace-form.tsx replaces the location onto the
  slug workspace.update returns.

SSO is a row, not a deployment Copy Chapter

An ssoProvider row via Better Auth's sso plugin, on Settings → SSO, because a
self-hoster's admin cannot redeploy.

• OpenID Connect only — issuer, client id, secret; endpoints from discovery. No
  SAML UI: it needs an X.509 cert and SP signing key we have nowhere to keep.
• SsoService passes WORKSPACE_ID, never an input.
• Management is tRPC (sso.*); signing in is authClient.signIn.sso().
• sso.signInOptions is the one public procedure in the app. Every other sso.*
  takes AuthMiddleware at the method, which is what leaves it open. A client
  secret is never read back out.
• It is the API's answer, not the app's — the API serves /api/auth/*.
• An install with no Google, no Microsoft and no provider says so, naming the
  variables; a read that fails falls back to offering Google.
• A provider hides the social buttons, it does not disable them —
  /sign-in?method=google and ?method=microsoft still work, so a mistyped issuer
  cannot lock an admin out.
• Signing in with an IdP does not cost you Gmail. needsMailboxGrant (@crm/auth)
  walls only an account whose sign-in rows are all mailbox providers — Google,
  Microsoft, or both — and none of them granted. mailboxGrantsNeeded returns which,
  so /grant-access offers the button they can actually use.
• ALLOWED_SIGN_IN still decides who gets an account, in
  databaseHooks.user.create.before, for SSO sign-ups too.
• organizationProvisioning: { disabled: true } — ensureWorkspaceMembership already
  does the join.

tRPC is the data surface; REST is auth and health only Copy Chapter

• One router per module, *.router.ts (the codegen glob), with
  @Router({ alias }) and @UseMiddlewares(AuthMiddleware). No AuthMiddleware
  means public — there is no other guard.
• Routers are thin: zod in, service call out; Prisma lives in *.service.ts.
• Services throw Nest's HttpException family; DomainErrorMiddleware maps them.
• Filter, sort and paginate in Prisma. List procedures take listInput and return
  { rows, total, facetCounts }. Never filter a whole table in the browser; never
  interpolate sort into a field name — use resolveOrderBy.
• src/generated/server.ts is generated and committed, and build must never
  regenerate it — the generator needs GLIBC 2.39, newer than Vercel's build image.
  Only check-types and dev run it. If the app cannot see a new procedure, it has
  not run.

The OpenAPI document is built at runtime, not committed Copy Chapter

GET /openapi.json serves one document: Nest's own controllers plus a REST bridge
under /rest generated from every tRPC procedure. Swagger UI renders it at /.
createApp builds both halves and merges them, so nothing is generated at build
time and no file is checked in — the document is whatever the routers are.

SwaggerModule.setup runs before app.init(), because it registers its Express
routes synchronously and Nest's own routing would otherwise shadow them. The factory
form defers building the document to the first request, which is what lets it read
the tRPC router that only exists after init.

Two rules follow for the serverless build:

• @nestjs/swagger stays in EXTERNALS in apps/api/scripts/build-func.mjs, because
  swagger-ui-dist resolves its assets from disk at runtime and cannot be bundled.
• Anything external must be vendored, and vendoring follows non-optional
  peerDependencies, not only dependencies. Nest packages declare their runtime
  needs as peers, so following dependencies alone ships a function that throws
  MODULE_NOT_FOUND on the first request. Adding a name to EXTERNALS without
  checking it lands in .vercel/output breaks production, and the build stays green.

Two mail providers, one pipeline Copy Chapter

apps/api/src/mailbox is everything neither Google nor Microsoft owns:
MailboxApiClient (bearer GET, and the one place a status code becomes an outcome),
SyncStateService (the MailboxSync row), MailboxTokenService,
MailboxMatchService, participants.ts, message-text.ts, and
ThreadWriterService.

• ThreadWriterService.store is the only writer of EmailThread, EmailMessage
  and the EMAIL activity. Gmail and Outlook each parse their own wire format down
  to one IncomingMessage and hand it over; matching, threading, counting and
  stamping happen once. A second copy of that is how a rule like reply before you
  create a company comes to be true in one inbox and not the other.
• A thread is keyed by RFC message id, not by the provider's thread id. Root comes
  from References → In-Reply-To → own Message-ID, so a rep on Gmail and a rep on
  Outlook land on the same EmailThread for the same conversation. Graph only returns
  internetMessageHeaders when $selected and not for every message, so Outlook falls
  back to outlook-conversation:<conversationId> — threading that still holds inside
  Outlook, just not across to Gmail.
• MailboxSync.source is the discriminator — calendar, gmail, outlook. Each
  provider's module only ever sees its own, and sync/mailbox-sync.service.ts is the
  one place that dispatches. One cron, one budget:
  POST /internal/sync/mailboxes (/google is kept as an alias so an existing
  deployment's cron keeps working).
• Gmail is forward-only from a historyId, Outlook from a timestamp. Graph has no
  mailbox-wide delta, so the Outlook cursor is the last receivedDateTime seen,
  re-read with a one-second overlap; rfcMessageId is unique, so the overlap costs a
  duplicate fetch and never a duplicate row.
• Microsoft has no token-revocation endpoint. revoke clears the columns and the
  UI says the consent itself is removed in the user's Microsoft account. Google's still
  posts to oauth2.googleapis.com/revoke and refuses to clear if that fails.

Not every address on a thread is a person Copy Chapter

externalParticipants (mailbox/participants.ts) is the one gate, discarding us
(allow-list domains, User table), rep decisions (SuppressedContact,
SuppressedDomain), and addresses no human reads.

• isMachineDomain (companies/domain.ts) sits beside FREE_EMAIL_DOMAINS;
  domainFromEmail returns null for both, and companyForEmail is the only path from
  address to company — so a caller ignorant of the rule still cannot create one.
  .calendar.google.com covers shared calendars, rooms and ICS feeds.
• Matches the host, never a substring — calendar.acme.com is a real company.
• isMachineAddress also catches opaque local parts (24 hex chars, UUIDs),
  deliberately narrow: a false positive is a real customer never filed.
• It leaves no row — a rep may still type these into quick-add; only the inbox
  is barred from deciding. syncAttendees filters the same addresses beside
  attendee.resource.
• isAutomatedAddress is a separate list about the local part (sales@,
  noreply@), which is why [email protected] never becomes a lead.

People on a deal Copy Chapter

DealContact is the join, and deals.attachContact / detachContact /
setContactRole are the only ways to write it. deals.contactOptions is what the
picker reads.

• A contact on a deal works at that deal's company, enforced in the service and
  not merely by the picker — the same rule as companies.setPrimaryContact.
• Attaching is an upsert and re-attaching keeps the role already there, so a
  double click cannot blank what somebody typed.
• Detaching removes the row, never the contact. They stay in the CRM, on the
  company, with their history.
• role is blanked to null, never stored as "" — blankToNull, as everywhere
  else.

Deleting a record is archive first, purge later Copy Chapter

contacts.archive, companies.archive, deals.archive set archivedAt. Nothing
else changes — no suppression, no cascade cleanup, no stamp recompute — because the
row is still there, just filtered out of every list.

• archivedFilter(input.archived) is in every buildWhere and every facetCounts
  where. A list call defaults to archived: false; the Archived view is the same
  procedure with archived: true. There is no third "everything" mode — mixing
  active and archived rows in one table is exactly what this feature removes.
• archive/restore are a bare update({ archivedAt }), nothing more. They do
  not touch AgentTask, SuppressedContact, or lastActivityAt — the record is
  unchanged, only hidden.
• purge is the old delete. Same transaction, same suppression, same
  AgentTask/AgentEvent cleanup, same ActivityStampService.recomputeAfterDelete.
  Read the rest of this section as purge's contract, not archive's.
• A rep can purge straight from the Archived view — retention is a ceiling, not a
  wait. bulkPurge/the per-record "Delete forever" action call it directly, no
  different from the cron.

Pruning: ArchiveRetentionController (internal/archive/prune, CRON_SECRET-gated,
apps/api/vercel.json) reads AppSetting.archiveRetentionDays
(readArchiveRetentionDays, @crm/db/settings, default 180) and calls each service's
purgeExpired(before) — findMany({ archivedAt: { lte: before } }) capped at
ARCHIVE.prune.maxBatch (archive/archive-config.ts), then purge per row through
the ordinary runBulk. Settings → General has the day count
(settings.archiveRetention / setArchiveRetention).

Below is purge's contract — everything that used to be delete's:

• A purged contact is suppressed by address, or the sync recreates them from the
  next thread. ContactsService.purge writes SuppressedContact, and
  externalParticipants drops it like a SuppressedDomain — one filter covering
  contact creation, company auto-creation and attribution.
• Keyed lower case. normalizeEmail (crm/values.ts) is the one canonicaliser,
  on contacts.create, .update and the suppression; conflict checks and allowAgain
  match case-insensitively.
• The address comes from the delete itself
  (tx.contact.delete({ select: { email: true } })), not a read before it — and the
  404 is that statement's own P2025 through translate.
• Adding them back lifts the suppression via allowAgain inside the write's
  transaction. Never automatic.
• Purging a company does not suppress its domain — its people survive with no
  company, and domain suppression stays the explicit Settings → Connections control.
• Clear AgentTask and AgentEvent yourself — they carry contactId/companyId
  with no foreign key, so nothing cascades.
• Recompute lastActivityAt on exactly the records the purge reached.
  ActivityStampService.targetsOf(where) collects them inside the transaction (the
  evidence is what gets deleted); recomputeMany restamps. A company's where must
  follow its deals: { OR: [{ companyId }, { deal: { companyId } }] }.
  recomputeAll() is for a purge only.
• Recompute after commit, logging rather than throwing — the row is already gone,
  and a raised error makes the browser skip invalidation and retry into a 404.

Money Copy Chapter

A deal is sold in one currency and reported in another, and only baseAmount may
ever be summed. The rules — baseCurrency, countedWhere/pendingWhere, frozen
rates, the supported currencies, the keyless feed, and why the fetcher is the one
documented exception to no intelligence in the API — are in docs/currency.md.
Read it before touching any amount, total, chart or rate.

Freshness: invalidate the query, don't disable the cache Copy Chapter

• Invalidate in onSuccess through useCrmCache() (lib/trpc/cache.ts), never by
  listing keys at the call site. Say what changed — cache.deal(id),
  cache.company(id), cache.contact(id), cache.activity(). A new mutation adds a
  call there, not a new list of keys.
• A deletion is cache.removed(ref) — one wide fan-out, and the only place
  refetchType: "none" is right: the deleted record's byId query is still mounted
  while the sheet animates shut, so refetching reads a 404 into the closing sheet,
  while leaving it alone serves 30s of a dead record from cache.
• { settle: "record" } for inline editors, so the field's spinner clears without
  waiting for the table.
• Infinite queries need pathKey(), not queryKey() — the latter stamps
  { type: "query" } and silently cannot match { type: "infinite" }.
  activities.timeline is read both ways.
• cache-manager is per-value and opt-in, not an interceptor;
  AuthService.getProfile is the model.
• Background writes need polling, not invalidation — refetchInterval while
  PENDING/RUNNING, via isEnriching() and ENRICHMENT_POLL_MS. Lists poll too,
  not just the sheet.

Connections (`docs/connections.md`) Copy Section

Connections — rules for AI agents

Covers /settings/connections and everything under it: the index, per-connection
pages, the intake endpoint, the add-connection picker, and identity matching.

Read docs/design.md first. Read docs/api.md before touching apps/api, and
docs/agent.md before touching apps/agent. The Paper file is
app.paper.design/file/01KZ72S23CM00WXN6S1MP68M03/1-0, page crm - grim.

The one rule that governs everything here Copy Chapter

A connection is a capability. An automation is an agent.

A connection page shows what a connection can do, who it is wired to, and which
agents use it. It never owns, authors, or edits an automation. Automations are
built in the agent builder chat by tagging the integration, and they live at
/agents/:agentId.

This is already true in code: builderResource.kind in
apps/api/src/conversations/conversations.contracts.ts is
["integration", "company", "contact", "deal"], and the composer picker in
apps/app/components/agent-builder/agent-composer.tsx is labelled "Tag CRM
records and integrations" with ids shaped google:calendar, google:gmail.
A new integration becomes taggable by extending that enum's id space, not by
building a second authoring surface.

If you find yourself adding a toggle, a trigger builder, or an "Edit automation"
form to a settings page, stop — that work belongs in the builder.

Removing a connection is an owner or admin decision Copy Chapter

A connection is shared. One person disconnecting Slack stops every agent that
posts to it and clears the cached channel list for everybody, so
SlackConnectionService.disconnect asks canManageConnections (@crm/auth)
after AgentAccessService.assertMember, and slack.status returns canManage
so the button is disabled for the same people the service refuses. Being signed
in is not authorisation: AuthMiddleware only proves a session exists.

Everything additive — joining a channel, creating one, refreshing people — stays
open to any workspace member, because the agent builder needs it and Slack can
undo it.

Connecting Slack is refused at the OAuth endpoints, not in the UI Copy Chapter

Connecting is the same decision as disconnecting, because replaceSlackConnection
deletes every other Slack account row: a second person connecting replaces the
workspace's Slack, and every deployed agent then reads from and posts to whichever
Slack they installed. Hiding the button is not enough — authClient.oauth2.link
is one POST.

slackConnectGuard (packages/auth/src/slack-connect.ts) is Better Auth's
hooks.before, and it asks the same canManageConnections the API does. It
covers all three doors: /oauth2/link, /sign-in/oauth2 (Slack is a connection,
never a sign-in method, and that endpoint needs no session) and
/oauth2/callback/slack. The callback is the one that matters — refusing there
happens before the code is exchanged, so a refused attempt writes no
SlackWorkspaceGrant user token and deletes no bot token. Google and Microsoft
sign in on different paths and never reach the guard.

A workspace with no owner and no admin lets any member connect. There is nobody
left to ask, and a fresh install must not be locked out of its first connection.

Direction is the organising idea Copy Chapter

Every connection declares what it brings in and what it sends. Use those
two words. Not arrows, not "inbound/outbound", not scope tokens.

Sends earns its place by being reassuring when it is empty. HubSpot reads
"Nothing, so nothing here can change HubSpot" — that is the guarantee a migration
needs, stated where someone will look for it.

Destinations: derived or chosen Copy Chapter

When an agent sends something, its destination is one of two kinds. Getting this
distinction wrong is what makes an automation feel like it works by magic.

Derived — follows from the record, so never ask. The deal's owner. The
channel that belongs to this deal. Say so explicitly in the UI ("The person who
booked, at the email they booked with. Nothing to choose.") so the absence of a
control reads as deliberate.

Chosen — cannot be inferred, so must be asked exactly once. A standing
channel like #sales. A naming pattern for channels the agent creates
(#deal-{company}). A billing contact.

Chosen destinations are collected in the builder conversation with the
Questionnaire, not in a settings form. See "The Questionnaire" below.

Slack needs two grants, not one Copy Chapter

A bot token cannot add itself to a private channel. No Slack scope grants that.
The workspace must also hand over a user token (xoxp-), which the app then
uses to act as the person who connected Slack.

• Public channel — the bot self-joins with conversations.join. Bot token only.
• Private channel — only a user token can invite the bot. Both tokens.

The bot token lives on Account. The user token lives on SlackWorkspaceGrant,
keyed by Slack team id, because the grant belongs to the workspace and not to the
person who clicked Connect. packages/auth/src/slack-grant.ts writes it, and
apps/agent/agent/lib/slack-connection.ts is the only place that reads either.

A missing user grant is a capability that is off, not an error. The connection
page names it, and the private-channel row falls back to asking a human.

The cached row does not choose the token. joinSlackChannel
(apps/agent/agent/lib/slack-membership.ts) reads the channel from Slack with
conversations.info before it picks a path. slackChannel.isPrivate and
isMember are a cache, and a cache is wrong the moment somebody adds the bot in
Slack — or the moment a new column arrives with a default, which classifies every
existing row as public and non-member until the inventory next runs. A bot that
cannot see the channel at all is read as private and not a member, which is the
only safe reading. When Slack and the row disagree the row is corrected and a
slack-people-match task is queued, so the connection page stops showing the
stale classification too.

Nothing else calls Slack to read the channel list. The agent builder reads
the cached rows and, when they are older than SLACK.inventory.staleMs, queues
the same background task rather than waiting on a round trip
(apps/agent/agent/lib/slack-people.ts). A builder chat that blocks on Slack is
a builder chat that is as slow as Slack is.

Permissions are shown in groups, not one line each Copy Chapter

Sixteen scopes read as noise. Group them by what they touch — people, channels it
can read, messages it can send, channels it can change — and give each group a
count of how many reach the whole workspace. SLACK_SCOPE_GROUPS in
packages/auth/src/slack-scopes.ts owns both the grouping and the plain wording.

The catalogue is the single source. auth.ts builds its scope request from it and
the page renders from it, so the screen cannot promise something the app never
asked for.

Identity matching is connection-level Copy Chapter

"Message whoever owns the deal" needs a CRM user and a Slack member. Those are
two identities. Match on email, show the result, and let a human fix it.

An unmatched person must be allowed. The automation stops and says so rather than
guessing at a similar name — and the connection page surfaces the count so the
gap is visible before it bites.

The Questionnaire Copy Chapter

The strongest pattern in this work. When the builder cannot derive something, it
asks in chat rather than failing or guessing.

Reuse packages/ui/src/components/questionnaire.tsx — Questionnaire,
QuestionnaireItem, QuestionnaireTitle, QuestionnaireDescription,
QuestionnaireChoices, QuestionnaireChoice, QuestionnaireActions,
QuestionnaireSubmit. It is wired through agent-clarification-composer.tsx and
builderQuestionResponseInput.

Rules for a question:

• Ask only what cannot be derived. Say which parts you already worked out.
• Title is the question in plain words. Description says why it is being asked
  ("This one is a standing channel, so it is the same every time").
• Choices carry a fact that helps decide — member counts, last activity — not
  decoration.
• Always offer an escape ("Search for another channel").
• Footnote the constraint that shapes the list ("Only channels Slack has been
  added to").
• The submit label restates the answer: "Use #sales", not "Continue".

Failure is on the surface Copy Chapter

Nobody owns these automations day to day, and a broken one currently sits for a
week or two. So every connection surface leads with liveness, not configuration:
"Last call arrived 31 minutes ago", "1 call needs a look", "3 of 4 matched".

An automation you cannot see rot in is one nobody will own.

Irreversible things are bounded in writing Copy Chapter

Anything that messages a customer states its own limits next to the switch:
"It stops the moment Stripe reports the payment, and never messages the same deal
twice in a day." "It runs once per deal." An agent that DMs people about money
needs its guardrails legible to whoever turns it on.

Layout Copy Chapter

Page metrics are tokens. Never a literal.

--spacing-block-inline is the one doing real work: a card sits flush at the
column edge and carries 20px of its own padding, so card text lands in the same
lane as the title on a flat page. The two page types stay aligned without
matching each other's chrome.

Short single-decision pages (empty state, pre-connect, match people) centre
vertically. List pages top-align so nothing jumps when a row is added.

Cards versus flat Copy Chapter

Cards are for discrete, independently-actionable objects — an agent you can
pause on its own, a connection row with its own Manage button, a choice in a
picker, a Questionnaire.

Flat sections separated by a 1px --color-dark-border rule are for a page
describing one thing — the intake page, the pre-connect page.

The split is by what the block is, not by page. Do not card a section; do not
flatten a list of separately-actionable objects.

Brand marks Copy Chapter

packages/ui/src/components/brand-logos/ has claude, eve, github, google,
microsoft, nextjs, slack, stripe, vercel. Stripe is there — use it.

Missing from the repo and living only in Paper: hubspot (hubspot icon
L5E-0), docusign (docusign logo L5Z-0), ergo (ergo logo KJJ-0).
Extract their path data into brand-logos/*.tsx shaped like stripe.tsx when
building these screens.

Until a mark exists, EntityLogo falls back to an initials monogram on
bg-muted — that is correct behaviour, not a placeholder to design around. Only
icon marks are used at these sizes; the wordmarks stay unused.

Docusign is spelled with a lowercase s since its 2024 rebrand. The note-taker is
Ergo.

Crm Plan (`docs/crm-plan.md`) Copy Section

Plan — Agentic CRM (HubSpot replacement)

A lightweight, opinionated CRM for our sales team. Companies are the top-level
object; Contacts and Deals hang off them; everything that happens is an
Activity on a timeline. Company knowledge is filled in by an agent using
Context.dev rather than typed by a human.

This is the build plan: decisions, data model, contracts, conventions and
phased delivery. Read it with AGENTS.md,
design.md and api.md.

1. The decisions that stop this becoming a nightmare Copy Chapter

Five choices carry the whole design. Everything else follows from them.

1. Core fields are real columns. Custom fields are one JSONB column. Not
   EAV. A table showing eight custom columns must not become eight joins. §5.
2. One property registry drives columns, filters, forms and the detail
   sheet. System fields and custom fields are described by the same
   metadata, so adding a column to the CRM is a data change, not four code
   changes. §5.
3. Permissions are enforced in the tRPC middleware and again in the service.
   The UI hides buttons; it never guards anything. Row-level ownership is a
   service concern because no statement grammar can express it. §6.
4. Sheets, not inner pages. A row click opens a sheet keyed by a URL param.
   Back button closes it, links are shareable, and we never build a
   /companies/[id]/contacts/[id]/edit route tree. §10.
5. Everything that lists data is the same DataTable. Ported verbatim from
   mvp, driven by nuqs, paginated server-side. §10.

Choice table Copy Section

Judgment calls worth your veto Copy Section

• UNQUALIFIED_TO_BUY is terminal, not linear. You listed it between two
  active stages, but it's a disqualification. Treated like CLOSED_LOST:
  excluded from pipeline value and forecast, shown under a Closed tab. Say the
  word if you want it mid-funnel.
• Reps read everything, write only what they own. Sales teams need
  visibility; letting anyone edit anyone's deal is how data rots. Activities are
  the exception — anyone can log an activity against any record.
• Company.domain and Contact.email are unique. Duplicates are the #1
  way a CRM rots, and it makes the HubSpot import idempotent. Cost: two people
  behind one info@ need separate records.
• Not everything is a custom property. The sales-critical fields are real
  columns with real constraints. Custom properties exist for the team's own
  additions. Making everything dynamic is the Salesforce trap.
• Many-to-many associations everywhere, with labels and primary flags. Your
  call, over my earlier suggestion to flatten them. It costs a join on every
  company column and turns the company timeline into a union (§4) — both
  handled, neither free. In exchange the model matches how you actually sell,
  and we never hit the wall where a contact genuinely sits on two accounts.
• No Tickets, Quotes, Subscriptions, Payments, Orders or Payment links. The
  record sidebars in your screenshots are mostly empty (0) cards. Rebuilding
  those is rebuilding HubSpot. §15.

Repo issues found while surveying Copy Section

• docs/review.md does not exist but AGENTS.md says "Always review" it.
  Every agent session currently starts by failing to read a required file.
• docs/api.md describes a multi-tenant world this repo doesn't have. The
  org-context and per-org cache-generation sections came from the MVP; there are
  no organizations here. The logging rules apply verbatim and must stay. Trim
  the rest in Phase 0.
• apps/app/make-session.tmp.ts is a stray scratch file.
• The existing codebase is heavily commented. The no-comments rule applies to
  new code; existing comments are left alone rather than churned.

2. Hosting on Vercel, and what it costs us Copy Chapter

Vercel is a serverless platform. Three things about this stack break there if
we don't design for them, and all three are cheap to handle now and expensive
to retrofit.

The API runtime changes from Bun to Node. apps/api currently builds with
bun build --target=bun and runs bun src/main.ts. Vercel has no Bun runtime.
NestJS deploys as a single Node serverless function via @vercel/node, with a
cached bootstrap so warm invocations reuse the Nest app:

let cached: Promise | null = null;

export default async function handler(req: IncomingMessage, res: ServerResponse) {
  cached ??= bootstrap();
  const app = await cached;
  app.getHttpAdapter().getInstance()(req, res);
}

Keep the Bun scripts for local dev; add Node build/start scripts for Vercel.
bun test stays as-is for local test runs.

Fire-and-forget dies on serverless. The function freezes once the response
is sent, so void this.enrichment.enqueue(id) silently never finishes. Use
waitUntil from @vercel/functions — the same primitive mvp already relies on
per docs/api.md. Enrichment is a ~7–18s Context.dev call, comfortably inside
the function budget. When volume outgrows it, move to a durable queue; the
EnrichmentService interface stays the same either way, which is the point of
putting it behind a service in the first place.

Postgres connections exhaust. Every concurrent invocation is a new client.
Use a pooled connection string for the app and a direct one for migrations:

DATABASE_URL="postgres://...pooler...?pgbouncer=true&connection_limit=1"
DIRECT_URL="postgres://...direct..."

with directUrl in the Prisma datasource. Neon or Supabase both give you this;
so does Prisma Accelerate. Getting this wrong produces "too many connections"
under load and nothing before it.

Redis must be serverless-friendly. Provision Upstash through the Vercel
Marketplace. @keyv/redis (already a dependency) speaks the Redis protocol,
which Upstash supports over TLS; Fluid Compute keeps the connection alive
across invocations.

Deployment shape Copy Section

Two Vercel projects from one repo: crm-app (root apps/app) and crm-api
(root apps/api). Turborepo remote caching on. apps/app rewrites /api/* to
the API deployment, so the browser stays same-origin and the session cookie
just works.

3. Architecture Copy Chapter

browser
  │  same-origin /api/trpc
  ▼
apps/app  (Next.js 16, RSC)                        Vercel project crm-app
  ├─ app/api/[...path]/route.ts ──proxy──▶ crm-api
  ├─ server components: getServerTrpc() → prefetch → HydrationBoundary
  └─ client: useTRPC() + TanStack Query, nuqs for all table + sheet state
                                              │
apps/api  (NestJS, Node function)              ▼    Vercel project crm-api
  ├─ /api/trpc          routers: companies contacts deals activities
  │                              properties attachments users dashboard
  ├─ /api/auth/*        Better Auth (Google) + admin plugin (RBAC)
  ├─ /api/blob/upload   client-upload token handshake
  ├─ services           Prisma, property validation, ownership guards
  └─ enrichment         Context.dev via waitUntil
        │                       │                   │
   Postgres (pooled)         Redis (Upstash)    Vercel Blob
   packages/db              sessions, defs,     attachments
                            aggregates

Dependencies to add Copy Section

nestjs-trpc@^2.13.0, @keyv/redis, cache-manager, react-hook-form and
better-auth@^1.6.25 are already present.

4. Core data model Copy Chapter

Auth models are owned by Better Auth and regenerated by bun run auth:generate
— never hand-edited. User gains only back-relations (CompanyOwner,
ContactOwner, DealOwner, ActivityAuthor, AttachmentUploader,
SavedViewAuthor) plus the admin plugin's fields (§6).

SavedView below references PropertyEntity, which is declared in §5 — Prisma
schemas are order-independent, so the split across sections is presentational
only. It is all one schema.prisma.

/* Detailed source-code truncated for AI context efficiency. */

Activity.companyId is denormalised, and many-to-many complicates it. It is
stamped with the primary company of whatever the activity hangs off, so the
common case — one company, one timeline — stays a single indexed range scan.

But under M2M an activity on a deal shared by two companies belongs on both
timelines, and one stamped column cannot say that. The company timeline is
therefore a union:

WHERE "companyId" = $1
   OR "dealId"    IN (SELECT "dealId"    FROM "companyDeal"    WHERE "companyId" = $1)
   OR "contactId" IN (SELECT "contactId" FROM "companyContact" WHERE "companyId" = $1)

Every branch is indexed, and a company with a few hundred associated records
resolves in single-digit milliseconds. The denormalised column still earns its
place: it keeps the overwhelmingly common single-company read on one index, and
it is what lastActivityAt propagation walks.

If a company ever accumulates thousands of associated records, the fix is an
ActivityCompany fan-out table written alongside the activity. Do not build it
now — measure first. Noting it here so the upgrade path is deliberate rather
than a rewrite.

lastActivityAt is denormalised too, and this one is not optional. Your
HubSpot screenshots show Last activity date as a visible, sortable column on
every list and in every record's Data highlights. Computed as a correlated
MAX(activity.createdAt) subquery it would run once per row per page — the
single easiest way to make this CRM feel slow. It is a real indexed column,
written by the same service method that writes the activity, and backfilled by
the seed. Same argument for the createdAt indexes: Create date is the
default sort on the companies list.

Lifecycle stage and lead status are first-class, not custom. Both objects
carry lifecycleStage; contacts and companies carry leadStatus. They drive
filters, pipeline reporting and the Data highlights strip, so they get enum
columns with indexes rather than JSONB. Changing either writes a
LIFECYCLE_CHANGE activity and stamps lifecycleStageChangedAt, which is what
lets the record header say "Customer for 21 hours" and offer history — the
timeline is the history, so there is no second audit table to keep in sync.

Associations are many-to-many by default, matching HubSpot — a contact can
sit on several companies, a deal can span several, and a deal has as many
contacts as it has humans in the room. This was your call over my earlier
recommendation, and it is the right one for a company selling to groups and
subsidiaries; the rest of this section is what it takes to do it without
paying for it later.

Three typed join tables, not one polymorphic edge table. A generic
Association { fromType, fromId, toType, toId } looks tempting and is the same
mistake as EAV, one level up: no foreign keys, no cascade deletes, no Prisma
relations, and every query hand-written. There are exactly three pairings, that
number is bounded, so CompanyContact, CompanyDeal and DealContact each get
real columns and real integrity.

There are two independent notions of "primary", and conflating them is a
bug. HubSpot only models the first:

• isPrimaryCompany — this contact's (or this deal's) main company. Drives
  the Primary badge and the "Company" column on list views.
• isPrimaryContact — this company's main point of contact, which you asked
  for in the original brief. Same for a deal's lead contact.

They point in opposite directions across the same row, so CompanyContact
carries both flags.

Postgres enforces one primary per side; the application does not. Prisma
cannot express partial unique indexes, so these go in a hand-written migration
and are not optional — "two primary companies" is exactly the corruption that
makes a CRM untrustworthy:

CREATE UNIQUE INDEX company_contact_one_primary_company
  ON "companyContact" ("contactId") WHERE "isPrimaryCompany";
CREATE UNIQUE INDEX company_contact_one_primary_contact
  ON "companyContact" ("companyId") WHERE "isPrimaryContact";
CREATE UNIQUE INDEX company_deal_one_primary_company
  ON "companyDeal" ("dealId") WHERE "isPrimaryCompany";
CREATE UNIQUE INDEX deal_contact_one_primary_contact
  ON "dealContact" ("dealId") WHERE "isPrimaryContact";

Promoting a new primary is a two-statement transaction: demote the old, promote
the new. The index turns a race into a failed write rather than silent
duplication.

Deal.companyId was required and is now gone, so the "every deal belongs to
a company" invariant moves into the service: creating a deal requires at least
one company association, and removing the last one is rejected. A schema-level
NOT NULL was doing real work here; losing it means the service has to.

Association labels are a managed vocabulary, not free text. AssociationLabel
holds the options per pairing — Decision maker, Champion, Billing contact,
Parent company — editable in Settings next to custom properties, validated
server-side on write. Free text would give us four spellings of "champion"
inside a month.

What this costs, honestly. Every list that shows a company column now reads
through a join filtered to isPrimaryCompany, and every per-company count is a
join count rather than a foreign-key scan. Both are indexed and fine at this
scale. The real cost is the timeline, below.

Timeline semantics. Past = occurredAt set, or completedAt set, or a
NOTE/STAGE_CHANGE/ENRICHMENT row using createdAt. Upcoming =
dueAt > now() and completedAt IS NULL. Overdue = dueAt < now() and
completedAt IS NULL.

Pipeline math. Open stages are DEMO_BOOKED, QUALIFIED_TO_BUY,
DECISION_MAKER_BOUGHT_IN, CONTRACT_SENT. Closed are CLOSED_WON,
CLOSED_LOST, UNQUALIFIED_TO_BUY. Pipeline value sums amount over open
stages only. Moving to a closed stage stamps closedAt and requires
closedReason on the two losing outcomes.

5. Custom properties Copy Chapter

The part that decides whether this is maintainable in two years.

Why JSONB and not EAV Copy Section

An entity-attribute-value table is the textbook answer and the wrong one here.
Rendering a table with eight custom columns means eight joins or a pivot, on
every page of every list. Values live in one customFields JSONB column on the
row we already selected: zero extra queries, atomic writes, and a GIN index
that makes containment filters fast.

The trade — no referential integrity on values — is bought back by validating
every write against the definition registry server-side.

The registry Copy Section

enum PropertyEntity { COMPANY CONTACT DEAL }
enum PropertySource { SYSTEM CUSTOM }

enum PropertyType {
  TEXT
  LONG_TEXT
  NUMBER
  CURRENCY
  DATE
  BOOLEAN
  SELECT
  MULTI_SELECT
  URL
  EMAIL
  PHONE
  USER
}

model PropertyDefinition {
  id     String         @id @default(cuid())
  entity PropertyEntity
  source PropertySource @default(CUSTOM)
  key    String
  label  String
  type   PropertyType

  description String?
  options     Json?
  required    Boolean @default(false)
  showInTable Boolean @default(false)
  filterable  Boolean @default(true)
  sortable    Boolean @default(false)
  order       Int     @default(0)

  archivedAt DateTime?
  createdAt  DateTime  @default(now())
  updatedAt  DateTime  @updatedAt

  @@unique([entity, key])
  @@index([entity, archivedAt])
  @@map("propertyDefinition")
}

SYSTEM rows describe the real columns from §4 — name, domain, stage,
amount, owner. They are seeded from a versioned TypeScript constant and
upserted on boot, never hand-edited, and their key/type are immutable. Only
label, showInTable, order are editable on a system row.

CUSTOM rows describe keys inside customFields.

Your existing HubSpot custom fields validate the design Copy Section

The deal record in your screenshots carries Deal Type, Term, Deal
Segment, Forecast Context, Forecast Context (manual), Competitors
Mentioned, Compliance Frameworks and Compliance Timeline; the company
carries VAT ID, Record source and Frameworks; the contact carries
Buying Role, Assessment, assessment-source and the Original Traffic
Source drill-downs. Every one of these is a CUSTOM definition in the
registry — no schema migration, no code change.

Two are worth calling out. Compliance Frameworks renders as removable tag
chips, which is the MULTI_SELECT type. And assesment-source is misspelled
in HubSpot today: the import maps it to a correctly-spelled key with the old
name preserved as an alias, so we carry the data across without carrying the
typo forward forever.

Seed these as part of the migration so day one in the new CRM has the same
fields the team already uses.

One registry, four consumers Copy Section

properties.list({ entity }) returns both kinds in one array. From it:

Adding a property becomes a row in one table. No code change touches four
files, which is the entire point.

Rules that keep it safe Copy Section

• key is immutable after creation. Renaming the label is free; renaming
  the key orphans every stored value. The API rejects key changes outright.
• Delete is archive. archivedAt hides the property everywhere and leaves
  the JSONB untouched, so an accidental delete is a one-click restore. Hard
  purge is a separate, explicit, owner-only action that strips the key from
  every row in a transaction.
• Every write is validated server-side against a Zod schema compiled from
  the definitions and cached in Redis, invalidated when a definition changes.
  Unknown keys are rejected, not silently stored — silent acceptance is how you
  end up with four spellings of the same field.
• Type changes are restricted to safe widenings (TEXT→LONG_TEXT,
  NUMBER→CURRENCY). Anything else requires archive-and-recreate, so no
  write can land against a type that no longer matches the stored data.
• USER type values store a user id and are resolved through the same
  owner-picker component as system owner fields.

Filtering and sorting Copy Section

Filtering uses Prisma's JSON path filters against the GIN index:

where: { customFields: { path: [def.key], equals: value } }

Sorting is the sharp edge: Prisma cannot orderBy into a JSON column. The list
service takes a raw ORDER BY "customFields" #>> ARRAY[$1] escape hatch, with
the key validated against the definition registry before it reaches SQL — an
allowlist derived from data we control, never the raw query string. Only
properties flagged sortable are offered in the sort menu.

Free-text q searches system text columns in v1. Extending it across custom
text properties wants pg_trgm; that is a later, measured change.

6. Role-based access control Copy Chapter

Better Auth's admin plugin with createAccessControl, imported from the
dedicated paths for tree-shaking. The org plugin's role model does not apply —
there are no organizations. Roles live on user.role.

// packages/auth/src/permissions.ts
import { createAccessControl } from "better-auth/plugins/access";
import { defaultStatements, adminAc } from "better-auth/plugins/admin/access";

export const statement = {
  ...defaultStatements,
  company:    ["read", "create", "update", "delete"],
  contact:    ["read", "create", "update", "delete"],
  deal:       ["read", "create", "update", "delete", "reassign"],
  activity:   ["read", "create", "update", "delete"],
  attachment: ["read", "create", "delete"],
  property:   ["read", "manage"],
  member:     ["read", "manage"],
} as const;

export const ac = createAccessControl(statement);

Three layers, and why each exists Copy Section

1. tRPC middleware. PermissionsMiddleware reads
   meta: { permissions: { deal: ["update"] } } off the procedure and checks it
   against the role — mvp's pattern, minus the org lookup. Coarse-grained, and
   it catches an entire router that someone forgot to guard.
2. Service-level ownership. No statement grammar expresses "only rows where
   ownerId = me". A shared assertCanMutate(record, user) runs inside the
   service, before the write. This is the layer that actually protects a rep's
   deal from another rep.
3. UI. roleCan() hides buttons a user cannot use. Presentation only.
   Anything enforced solely here is not enforced.

Two operational details that bite later Copy Section

• Role changes lag the cookie cache. session.cookieCache is on with a
  5-minute maxAge, and the cached user object carries the role. Revoke the
  user's sessions when their role changes so the next request re-reads from the
  database. Otherwise a demotion takes up to five minutes to bite.
• Re-run bun run auth:generate after adding the plugin. It adds role,
  banned, banReason, banExpires to User and impersonatedBy to
  Session. Skipping this produces runtime adapter errors, not type errors.

First Google sign-in bootstraps as owner if no users exist; everyone after
defaults to rep, promoted from Settings → Members.

7. Attachments on Vercel Blob Copy Chapter

vercel blob create-store crm-attachments writes BLOB_READ_WRITE_TOKEN into
the project. Not yet created — see §14.

model Attachment {
  id          String @id @default(cuid())
  pathname    String @unique
  filename    String
  contentType String
  size        Int

  companyId  String?
  company    Company?  @relation(fields: [companyId], references: [id], onDelete: Cascade)
  contactId  String?
  contact    Contact?  @relation(fields: [contactId], references: [id], onDelete: Cascade)
  dealId     String?
  deal       Deal?     @relation(fields: [dealId], references: [id], onDelete: Cascade)
  activityId String?
  activity   Activity? @relation(fields: [activityId], references: [id], onDelete: Cascade)

  uploadedById String
  uploadedBy   User   @relation("AttachmentUploader", fields: [uploadedById], references: [id])
  createdAt    DateTime @default(now())

  @@index([companyId])
  @@index([dealId])
  @@map("attachment")
}

Client uploads, not server uploads. Vercel caps a serverless request body
at 4.5 MB; a signed contract PDF blows straight through that. Use
upload() from @vercel/blob/client against a handleUpload route that
authenticates the session, checks attachment: ["create"], and only then issues
a token. Server-side put() is reserved for small files we generate ourselves.

Store the pathname, not the URL. Blob URLs carry an unguessable random
suffix, which is obscurity, not authorisation — and a CRM holds customer
contracts. Downloads go through an API route that checks RBAC and then issues a
presigned URL (the CLI exposes blob presign and blob signed-token; confirm
the SDK flag names when implementing). Row payloads never contain a directly
fetchable URL.

Deletes are two-phase. Delete the row, then delete the blob in waitUntil.
A dangling blob costs pennies; a dangling row is a broken download.

The @crm/ui attachment.tsx component already models the
idle/uploading/processing/error/done states the upload flow needs.

8. Speed: Redis and rendering Copy Chapter

Three distinct uses of Redis. Conflating them is how caches go stale.

1. Better Auth secondary storage. Port mvp's
   packages/auth/src/secondary-storage.ts verbatim. Every RSC render validates
   a session; on Vercel that is a Postgres round trip per render unless sessions
   live in Redis. Biggest single win available.
2. Application cache via the existing AppCacheModule. Cache the things
   that are hot and rarely change: property definitions, the user list, and
   dashboard aggregates. Keys are namespaced crm:v{gen}:{entity}:{hash}; a
   write bumps that entity's generation counter rather than deleting keys.
3. Enrichment dedupe. A short-lived enrich:lock:{domain} key stops two
   concurrent creates of the same domain from both burning 10 credits.

Do not cache per-record reads behind Redis in v1. TanStack Query already
dedupes and caches client-side, and record freshness after a write matters more
than shaving a query. Cache aggregates and registries; leave records live.

Rendering. Every list page prefetches on the server through
getServerTrpc() and hydrates:

const queryClient = getServerQueryClient();
await queryClient.prefetchQuery(trpc.companies.list.queryOptions(params));
return (
  <HydrationBoundary state={dehydrate(queryClient)}>
    <CompaniesPanel />
  </HydrationBoundary>
);

Parsed nuqs values feed the prefetch, so the first paint is already filtered and
sorted — no loading flash on a shared link. Subsequent filter changes stay
shallow and are served by TanStack Query.

9. The agentic layer Copy Chapter

apps/api/src/enrichment/ — a typed ContextDevClient over
https://api.context.dev/v1 plus an EnrichmentService invoked through
waitUntil.

Field mapping. title→name (only when the record was created domain-first
and unnamed); description/slogan→description; logos[] picked by
mode+type, never logos[0] — light+logo→logoUrl, dark+logo→
logoDarkUrl, icon→iconUrl; colors[0].hex→brandColor (key off hex,
the name is generated); industries.eic[0]→industry/subIndustry;
address→city/stateCode/country/countryCode; socials[]→ the social
URLs by type; links→pricingUrl/careersUrl. Whole payload →
CompanyEnrichment.raw, so re-deriving a field never costs credits again.

Error handling. Every field is nullable — never overwrite a human-entered
value with null. 400 NOT_FOUND and WEBSITE_ACCESS_ERROR are SKIPPED, not
FAILED, and are not billed. 422 on an email lookup (free or disposable) is
SKIPPED with no company created. 403 on prefetch logs once and falls through
to a direct retrieve. 408/429 get one backoff retry, then FAILED with the
reason in enrichmentError. Cold lookups run p50 ≈ 7s, p90 ≈ 18s, so
timeoutMS: 60000 and never in the request path.

Progress in the UI is a TanStack Query refetchInterval that runs while
enrichmentStatus is PENDING or RUNNING and returns false once it settles
— not a setInterval in an effect.

CONTEXT_DEV_API_KEY lives in the API's environment, declared @IsOptional()
in env.validation.ts. No key means enrichment is disabled, logged once at
boot, and companies stay PENDING. The key is server-side only.

Deal intelligence (Phase 11) Copy Section

Your deal record shows a Deal Score card and an AI-written Forecast Context
that reads like a summary of the timeline. That is the second agent, and it is
the one that makes this "agentic" rather than "enriched":

• Deal score — a 0–100 health number with a one-paragraph rationale,
  derived from stage age, activity recency and cadence, contact coverage
  (do we have a champion and an economic buyer?), and what the notes
  actually say. Adds dealScore, dealScoreSummary, dealScoredAt,
  forecastContext and forecastContextManual to Deal in a Phase 11
  migration — deliberately not in the §4 schema, so the core model ships
  without waiting on the model work. Recomputed on stage change and on a
  nightly cron, never in the request path.
• Forecast context — a rolling summary of the deal's timeline, regenerated
  when the timeline changes materially. Their record keeps Forecast Context
  and Forecast Context (manual) side by side; we do the same, and
  forecastContextManual always wins when set.
• Stalled-deal detection — an open deal with no activity in N days raises a
  task for its owner. This is the cheapest high-value automation in the whole
  product and needs no model at all.

Use Claude via the Anthropic API for these; the scoring prompt reads the
timeline the CRM already stores, so there is nothing new to integrate.

10. API contract Copy Chapter

Every list endpoint speaks one shape, so one table component drives everything.

export const listInput = z.object({
  q:        z.string().default(""),
  sort:     z.string().default(""),
  dir:      z.enum(["asc", "desc"]).default("asc"),
  page:     z.number().int().min(1).default(1),
  pageSize: z.number().int().min(1).max(100).default(25),
  filters:  z.record(z.string(), z.string()).default({}),
});

Returning { rows, total, facetCounts }, where facetCounts feeds the counts
in the filter dropdowns.

One associations router serves all three pairings, taking
{ pairing, fromId, toId } rather than one endpoint per direction — the
alternative is nine near-identical procedures. setPrimary runs the
demote-then-promote transaction from §4, and unlink refuses to remove a
deal's last company.

listInput.filters carries facet values as strings. Date-range facets encode
as either a named window (last_7_days, this_month, last_quarter) or an
explicit from..to pair of ISO dates; the service resolves both to a Prisma
gte/lte on the mapped column. Named windows are resolved server-side so a
shared URL means the same thing tomorrow as it does today.

Every router carries @UseMiddlewares(AuthMiddleware, PermissionsMiddleware)
with per-procedure meta.permissions. deals.setStage writes the
STAGE_CHANGE activity and stamps stageChangedAt/closedAt in one
transaction — a stage change that doesn't appear on the timeline is a bug, so
it cannot be two calls.

11. Frontend Copy Chapter

Routes — flat, because sheets carry the depth Copy Section

apps/app/app/(app)/
  page.tsx           dashboard
  companies/page.tsx
  contacts/page.tsx
  deals/page.tsx
  settings/properties/page.tsx
  settings/members/page.tsx

There are no [id] routes. A record opens in a sheet driven by a URL param:
?company=cmp_123, ?deal=deal_456, ?new=company. The back button closes it,
the URL is shareable, and we never grow a nested route tree. Deep links render
the list server-side and open the sheet on top.

Sheets Copy Section

Port responsive-sheet.tsx and detail-sheet.tsx from mvp — Sheet on
desktop, Drawer on mobile, behind one API. DetailSheet supplies Header / Stats / Properties / Section / Body /
Footer, which maps onto the HubSpot record layout almost one to one — their
three-column page becomes one vertical sheet:

• Header — logo, name, domain link, owner, enrichment chip, then the
  composer row your screenshots put under the record title: Note · Email ·
  Call · Task · Meeting · More. Same five, same order.

• Stats — DetailSheetStats is their Data highlights strip verbatim:
  Create date · Lifecycle stage · Last activity date. On a deal, stage
  replaces lifecycle.

• Properties — their About this company / Details panel. System
  properties first in registry order, then custom, all from §5. Inline-editable
  in place; no separate edit mode.

• Sections — the right rail, flattened: Companies, Contacts, Deals,
  Attachments, Timeline. Each shows a count and an Add action, and each
  renders a SimpleTable rather than the full DataTable — these are short
  embedded lists, not paginated views. The associated-deal rows carry an inline
  stage dropdown, matching the contact record in your screenshot.

  Because associations are many-to-many, each row also carries a Primary
  badge and an association label chip, both editable in place, exactly as
  your screenshots show. Sections cap at five rows with a View all associated
  … link that opens the full list filtered to that record — a company with
  forty contacts must not render forty rows inside a sheet. Adding an
  association is a cmdk search over existing records with a create-new
  fallback, so linking never means leaving the sheet.

• Footer — save, delete, re-enrich.

Timeline. Grouped by month with day sub-headers, newest first, matching
their Recent activities. It gets its own search box, an activity-type filter,
a date-window filter and a collapse-all toggle. Upcoming and overdue items pin
above the history with a completion checkbox.

Create buttons live in the page shell header Copy Section

Every list page puts its primary action in PageShellActions, which the shell
already positions top-right:

Companies
    Every account we sell to.
  
  
    <CreateCompanyButton />

The button sets ?new=company; the same sheet component handles create and
edit, distinguished by whether an id is present. One component, one form
schema, two entry points.

The data table, and its rules Copy Section

Ported from /Users/lewiscarhart/mvp/apps/app/components/data-table/, rewriting
@trycompai/ui → @crm/ui:

Everything it needs already exists in @crm/ui: table, dropdown-menu,
input-group, button, spinner, lib/row-accent. The hook stays app-side
because it is routing state, not UI. nuqs becomes a packages/ui dependency
since the table owns the expand and hide params.

Behaviour carried over unchanged:

• table-fixed layout, overflow-hidden cells, so long values truncate instead
  of blowing out the table
• sticky header with bg-background
• search in an InputGroup with a leading Search icon
• one dropdown per facet, radio-group single-select, all as the reset option
• a tab dropdown for the primary partition, with counts from facetCounts
• a Sort dropdown listing sortable columns plus asc/desc, and clickable sortable
  headers with an arrow indicator and aria-sort
• a Columns dropdown toggling hideable columns, persisted in ?hide=
• the whole filter row collapses behind a Filters button under sm, with an
  active-filter count
• useDeferredValue on rows so typing stays smooth
• ROW_ACCENT on clickable rows; expandable rows use ROW_ACCENT_EXPANDABLE
• pagination footer showing range and total

Five CRM-specific additions, four of them driven by the HubSpot screenshots:

1. Columns come from the property registry, not a literal array (§5).
2. A row click sets the record's URL param instead of navigating.
3. Date-range facets. mvp's DataTable only has single-select radio
   facets, but every HubSpot list filters on Create date, Last activity
   date and Close date. Add a type discriminator to DataTableFacet:
   select keeps today's behaviour, dateRange renders a preset list (Today,
   Last 7 days, This month, Last quarter, Custom) over @crm/ui's existing
   calendar and popover. This is the one real extension to the ported
   component; everything else is reuse.
4. Saved views as tabs above the table. HubSpot's "Active Customers",
   "Intent", "Closed Won Deals". Because the entire table state already lives
   in the URL, a saved view is a stored query string — savedViews.create
   snapshots query.search, and clicking a tab replaces the search params.
   A + tab saves the current filter set. This is nearly free given the
   architecture and it is the feature the team will notice missing on day one.
5. Standard cell renderers, so every list looks like one product:
   OwnerCell (avatar + name, No owner when null), RelativeDateCell
   ("Today at 10:07", "Yesterday at 3:20 PM", then absolute), CurrencyCell
   (right-aligned, tabular numerals), StageBadge, LifecycleBadge, and
   @crm/ui's existing empty-cell rendering -- for every null — matching
   HubSpot exactly.

Default columns Copy Section

Mirroring your screenshots, so the team's muscle memory survives the move.

Companies default-sort by Create date descending; Deals by Close date
ascending. Everything beyond the first four columns is hideable, so the
Columns dropdown is genuinely useful rather than decorative.

The Company column renders the primary association, with a +N chip when a
record has more — one line per row, no wrapping, and the full set is one click
away in the sheet. AssociationCell owns this so all three lists agree.

Forms Copy Section

react-hook-form + zodResolver + @crm/ui Field primitives
(Field, FieldGroup, FieldLabel, FieldContent, FieldDescription,
FieldError), matching mvp's person-sheet.tsx.

• One schema per form, shared with the tRPC input where the shapes match.
• Controller for non-native controls (Select, Switch, Combobox);
  register for plain inputs.
• "" means clear, undefined means leave alone. The submit handler maps
  empty strings to explicit null. Collapsing the two makes "clear this field"
  silently a no-op — mvp learned this the hard way.
• Submit through useMutation with an optimistic row patch, toast.error
  on failure, invalidate on settle.
• The custom-property section is generated from buildFormSchema(defs) and
  rendered by a PropertyField switch on type.
• No effect resets the form when the selected record changes. The sheet body
  is keyed: <RecordForm key={recordId} />.

12. Conventions Copy Chapter

No `useEffect` Copy Section

Banned in app and feature code. The five replacements:

packages/ui/src/hooks/use-mount-effect.ts already exists and is the only
sanctioned wrapper. Concretely in this codebase: sheet open state is derived
from nuqs, never synced; search debounce is nuqs' limitUrlUpdates, not a
timer; enrichment polling is refetchInterval, not setInterval; form reset is
a key, not a dependency array.

Enforce it with Biome — noRestrictedImports banning the useEffect named
import from react, scoped to apps/app/** and packages/ui/src/hooks/**.
packages/ui/src/components is already Biome-excluded, so vendored shadcn files
(calendar, sidebar, carousel) are unaffected. Verify the importNames
syntax against Biome 2.5 when wiring it.

No code comments Copy Section

New code carries no comments. Names, types and small functions do the
explaining; anything that genuinely needs prose goes in docs/. Existing
comments stay — churning them adds diff noise and no value. biome-ignore
directives and the auto-generated Prisma header are not comments in this sense.

Add both rules to AGENTS.md so every agent session picks them up.

13. Phases Copy Chapter

Each phase ends green on bun run check-types and bun run lint.

Phase 0 — Plumbing. Dependencies; apps/api/src/trpc/ (module, context,
auth + permissions + logging middleware, error handler) from the mvp reference;
nestjs-trpc generate + exports["./app-router"]; the /api/[...path] proxy;
lib/trpc/*; NuqsAdapter + TRPCReactProvider; the data table into
packages/ui; Biome no-useEffect rule; housekeeping on docs/review.md,
docs/api.md and the stray temp file. Verify: the dashboard renders
users.me through a server-prefetched tRPC query.

Phase 1 — Auth, RBAC and hosting. admin plugin + access control in
packages/auth; bun run auth:generate; Redis secondary storage; owner
bootstrap; PermissionsMiddleware; two Vercel projects; pooled DATABASE_URL +
DIRECT_URL; Upstash; blob store. Verify: a readonly user gets 403 from a
mutation, and the button is hidden.

Phase 2 — Schema, registry and seed. Models from §4 and §5; one migration;
system property definitions seeded from the versioned constant; seed ~15
companies with real domains, ~40 contacts, ~25 deals across stages, ~150
activities including overdue and upcoming. Verify: db:migrate, db:seed,
inspect in Studio.

Phase 3 — Companies. companies + properties routers; the standard cell
renderers; the dateRange facet type; list page with the registry-driven
DataTable and the default columns from §11; company sheet with header,
composer row, Data highlights, properties, contacts, deals; lifecycle stage and
lead status editable inline; create button in PageShellActions. Verify:
filter by owner and a date window, sort, page; copy the URL into a new tab and
get the same view with the sheet open.

Phase 3b — Associations. associations router; the three join tables with
their partial unique indexes; AssociationLabel vocabulary and its settings
screen; AssociationCell; the add/link/label/set-primary UI in the sheet
sections. Lands here because Companies is the first surface that needs it and
every later phase assumes it. Verify: a contact on two companies shows Primary
on exactly one, and a concurrent double-promote fails the write instead of
producing two.

Phase 4 — Contacts. contacts router; list; sheet; multi-company
associations with labels; lifecycle stage, lead status and buying role.
Replaces the placeholder page.

Phase 5 — Deals. deals router; list with stage tab, owner facet and close
date range; inline stage change writing STAGE_CHANGE; forecast category; deal
sheet with stage stepper, amount, associated companies and contacts with
labels; the at-least-one-company service invariant. Verify: a stage change
appears on the deal and on the timelines of every associated company, and
lastActivityAt moves on all affected records.

Phase 5b — Saved views. savedViews router; the tab strip above every
table; save-current-filters, rename, reorder, share. Verify: a saved view
survives a reload and a different browser.

Phase 6 — Activity, tasks, dashboard. Timeline component and composer;
activities router; complete and snooze; dashboard with pipeline by stage,
closing this month, overdue tasks, recent activity.

Phase 7 — Attachments. Blob client uploads; handleUpload token route;
RBAC-checked presigned downloads; attachment sections on all three sheets.

Phase 8 — Custom properties UI. Settings → Properties: create, edit,
reorder, archive, restore; live preview against the table.

Phase 9 — The agent. ContextDevClient, EnrichmentService, waitUntil,
field mapping, status polling, contact-email → company, research brief.
Verify: create a company with domain stripe.com and watch logo, description,
industry, socials and address populate within ~20s without a reload.

Phase 10 — Migration and polish. HubSpot CSV import for companies,
contacts, deals, their custom fields and their associations with labels and
primary flags — HubSpot exports associations as separate files, so the
importer runs records first, associations second, and reconciles primaries in a
third pass. Dedupe on domain/email, lifecycle and lead-status value
mapping, assesment-source typo fix, lastActivityAt backfill, prefetch
warming, dry-run report first. Then deal board view (?view=board) and the
cmdk quick switcher.

Phase 11 — Deal intelligence. Deal score, forecast context, stalled-deal
tasks (§9). Last because it is worth nothing until the timeline has real data
in it.

14. Open items Copy Chapter

• Vercel Blob store — done. crm-attachments
  (store_pXY7wYOD7ccPGUNP), region iad1, private access, in the
  comp-ai-test team. Not yet attached to a project, because the repo has no
  Vercel projects yet; attaching it in Phase 1 is what populates
  BLOB_READ_WRITE_TOKEN. Private access confirms §7's design — the CLI
  requires --access public|private and exposes blob presign, so
  RBAC-checked presigned downloads are the supported path, not a workaround.
• Postgres provider for pooled connections — Neon and Supabase both work;
  pick one and I'll wire DATABASE_URL/DIRECT_URL.
• docs/review.md — write it or drop the AGENTS.md reference.

15. Deliberately out of scope Copy Chapter

Email sync, calendar sync, sequences and cadences, workflow automation, a
reporting builder, and territory rules. Plus every object sitting at (0) in
your record sidebars: Tickets, Quotes, Subscriptions, Payments, Orders, Payment
links and Products. Multiple pipelines are out too — your deals list shows an
"All Pipelines" selector over a single "Deals pipeline", so one opinionated
pipeline is the honest version of what you actually run.

Each of these is a HubSpot feature we are choosing not to rebuild. If sales
asks for one, it is a new plan, not a phase.

Currency (`docs/currency.md`) Copy Section

Currency — read when touching deal amounts, totals, or rates

Two amounts, and only one is ever summed. (_sum: { amount: true } once added euros
to dollars and printed $2.0M, silently.)

• amount + currency is what the customer pays. Never converted in place.
• baseAmount is the only column any total, chart, average or sort may touch;
  fxRate/fxRateAt record how it got there.
• baseCurrency says what baseAmount is denominated in — without it a figure
  converted against a stale base is indistinguishable from a correct one.
  • countedWhere(base) filters every money aggregate. Counts are deliberately
    not filtered, so stage groups read counts and sums from separate queries.
  • pendingWhere(base) = null baseAmount or wrong baseCurrency, and it
    matches null explicitly — { not: base } is NULL, not true, for a null
    column, so such rows were invisible everywhere.
  • Compose with AND, never spread — it contains an OR, and so does the deals
    list's own where.
  • Every writer of baseAmount writes baseCurrency in the same statement:
    ConversionService and prisma/seed.ts.
• The rate is resolved once and frozen. create/update call
  ConversionService.dealFields when amount or currency changes, reading the
  unchanged one back in the same call. Converting on read makes a closed quarter change
  value every morning.
• A missing rate is a null, disclosed not zeroed — it falls out of _sum
  automatically, and unconverted counts those rows so the UI can say 3 deals in CHF
  are not included.
• fillMissing() never touches a converted deal; rerateAll() is the only thing
  that overwrites a frozen rate, and only on a reporting-currency change.

ExchangeRate.rate = units of baseCurrency per unit of quoteCurrency, so
baseAmount = amount × rate everywhere. The feed quotes the other way; RatesService
inverts on ingest.

• MANUAL beats FETCHED (unique on (base, quote, source)), which makes the
  fetcher optional — Settings → Currencies is the manual path. resolveRate refuses a
  rate ≤ 0.
• Re-rating deduplicates codes through a Set — currency was free text, so
  usd and USD were two groups each updating every variant.
• MAX_AMOUNT_CENTS (deals.contracts.ts) is what Decimal(14, 2) holds;
  baseAmount is Decimal(24, 4) so amount × rate still fits.
• Reporting currency is AppSetting.reportingCurrency, read only through
  readReportingCurrency.
• Codes are validated against isCurrencyCode (@crm/db/currency), not a regex —
  z.string().length(3) accepted ZZZ. isWellFormedCurrency is separate because
  Intl throws on non-three-letter input.
• CURRENCIES is eleven currencies and that is all this CRM supports — USD, EUR,
  JPY, GBP, CNY, AUD, CAD, CHF, HKD, SGD, ZAR, in array order. isCurrencyCode is the
  single gate for the picker, the feed filter and the stored setting. A refresh
  prunes FETCHED rows outside the list and leaves MANUAL alone.
• applyRate rounds to the reporting currency's minorUnitsOf, not to two. The
  ×100 cents transport cannot represent a three-decimal minor unit; nor can
  Decimal(14, 2).

Feed: open.er-api.com, keyless, two attempts at 6s. Check result, not just
the status — an unsupported base returns HTTP 200 with {"result":"error"}. An
unreachable provider warns and returns { ok: false }; only the interactive refresh
throws.

The fetcher is in the API deliberately: a daily rate decides nothing, and
DealsService needs it synchronously to write baseAmount in the same transaction.
Any judgement about it belongs in apps/agent.

POST /internal/sync/rates is guarded by CRON_SECRET (timingSafeEquals) and
fails closed when unset. A route is not a schedule — add it to
apps/api/vercel.json in the same change or nothing runs it.

Design (`docs/design.md`) Copy Section

Design — Rules for AI Agents

• /packages/ui is the single source of truth for all UI.
• Always use shared shadcn components from /packages/ui.
• Do not override component styles with className.
• Do not introduce custom border radii, spacing, colours, shadows, or other visual deviations.
• Corners are rounded, from the scale only: rounded-sm (4px) for the smallest
  controls, rounded-md (5px) for buttons, inputs and segments, rounded-lg
  (8px) for surfaces that contain controls — popovers, dialogs, menus, table
  shells. Never a literal radius at the call site.
• rounded-none is still correct in one case: an element that must join its
  neighbour edge to edge. The input inside an input group, the middle cells of
  a selected date range, and the drawer handle are the existing examples.
• If a component needs a new variant or style, implement it in /packages/ui so the entire application stays consistent.

Colour Copy Chapter

Flat white, neutral greys, and one brand green (#006B4F). The greys are
untinted on purpose: there is no scene to tint them toward, and a tinted grey
without a reason reads as indecision.

Only two things are filled: primary for the action you want, destructive
for the one you cannot undo. Everything else — secondary, outline, ghost — is a
white chip in light and a dark chip in dark. That is what keeps a rep's eye
landing on go or stop and skimming past the rest.

--primary and --destructive hold the same value in both themes. A brand
colour that changes per theme is not one colour, it is two, and both then need
maintaining. The single exception is --ring, which lightens in dark: a fill
carries the brand, but a ring only has to be seen, and #006B4F is too close to
the dark background to register.

Environment (`docs/environment.md`) Copy Section

Environment

Setup, DB commands, Google Cloud and the vercel env pull hazard: docs/setup.md.

One `.env`, at the repo root Copy Chapter

.env.example is the documentation — every variable the repo reads, with a note,
and nothing that is not read. packages/env walks up to the workspace root and reads
.env, then .env.local on top.

• Real environment variables always win — the loader never overwrites
  process.env, so Vercel/Docker/CI takes precedence.
• Never add a per-package .env. Four once existed with duplicate
  DATABASE_URL/BETTER_AUTH_SECRET; when they drifted the API minted a cookie the
  app could not verify and the browser bounced between /sign-in and / forever.
• The root marker is a package.json declaring workspaces — stopping at the
  first turbo.json resolves the API's root to apps/api.

A new variable has three homes, not two Copy Chapter

.env.example and — if the API reads it — env.validation.ts are the two people
remember. The third is globalPassThroughEnv in the root turbo.json, and it is
the one that bites: Turborepo hides an undeclared variable from every task it runs, so
a deployment that sets the variable perfectly still hands the code undefined, and
nothing anywhere says so. That is how MICROSOFT_CLIENT_ID shipped with the sign-in
button quietly missing. passThroughEnv, never env — a secret in env is a
cache key, which means a cache miss on every rotation and the secret in the cache
metadata. The root file's comment has the whole account.

Required Copy Chapter

DATABASE_URL, BETTER_AUTH_SECRET, ALLOWED_SIGN_IN. Everything else has a
localhost default or is genuinely optional.

GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET are the sign-in button and the
Gmail/Calendar sync — optional, so an SSO-only install needn't create a Google project,
but set together or not at all (packages/auth/src/env.ts throws on one).

MICROSOFT_CLIENT_ID + MICROSOFT_CLIENT_SECRET are the same bargain for Entra
ID: the other sign-in button and the Outlook mail sync, one app registration, the
same pair rule. MICROSOFT_TENANT_ID defaults to common and is the only one of
the three that is genuinely optional on its own — set it to your tenant's GUID to
refuse other tenants at Microsoft instead of at ALLOWED_SIGN_IN. There is no
Microsoft equivalent of hd: tenantId is the whole of it.

Neither pair is required, but an install wants one of them or an SSO provider —
with none, the sign-in page says so by name rather than rendering nothing.

ALLOWED_SIGN_IN — comma-separated whole domains or single addresses (bare
addresses exist for a solo self-hoster, where gmail.com would be an open door). One
list, read by the sign-in guard and the sync's "which side is external" decision —
if they drifted a colleague would be refused at the door or filed as a lead. An empty
list fails closed. Parsed on demand. packages/auth/src/workspace.ts.

Where things are Copy Chapter

• API_URL (:3001) mints session cookies and serves /api/auth/*;
  next.config.ts republishes it as NEXT_PUBLIC_API_URL, so one variable does both
  sides. BETTER_AUTH_URL is a legacy fallback.
• Editing a file under packages/ does not restart the API. Restart it by hand.
  bun --watch src/main.ts refuses to watch outside its project directory and
  says so once at boot: File ... is not in the project directory and will not be watched. So a change to packages/auth or packages/db leaves the API
  serving the old module until someone kills it. This cost an hour once: the
  Slack OAuth scope list was correct in source and stale in the process, and
  every reconnect kept asking Slack for the old scopes.
  Running the API from the repo root fixes the watch and breaks Nest, which
  resolves its tsconfig paths from the current directory and then cannot build
  its dependency graph. There is no fix in the dev script today.
• APP_URL (:3000) is also the trusted-origin and callbackURL allow-list.
• Every OAuth redirect_uri is built from API_URL, never APP_URL. Better
  Auth serves /api/auth/* at baseURL, and baseURL is apiUrl. A redirect
  built from APP_URL points at the web app, where /api/auth/callback does not
  exist, and the provider rejects it with "redirect_uri did not match". This is
  invisible until someone sets APP_URL to a tunnel or a LAN host, at which
  point the redirect silently becomes that host. ssoCallbackBase() is the
  pattern; slackRedirectUri in auth.ts once was not.
• AUTH_COOKIE_DOMAIN only for API and app on different subdomains of one parent.
• AGENT_URL is the agent's deployment, server-side only, and must include the
  scheme — validated at boot, or it throws when a task is queued instead.
• AUTH_COOKIE_PREFIX is crm (@crm/auth/cookies), set on both
  advanced.cookiePrefix in auth.ts and getSessionCookie(request, { cookiePrefix })
  in proxy.ts — one alone redirects every signed-in request. Better Auth's default
  collides with any neighbour on a shared parent domain, silently: sign-in completes,
  the row is written, every reader resolves null. Changing it signs everybody out.

`IS_MARKETING` — landing page flag, off by default Copy Chapter

"true" serves app/(landing) at /; anything else sends a signed-out visitor to
/sign-in, because the page markets this product.

• Only the literal true (same shape as PRISMA_LOG_QUERIES).
• It decides one thing: what a stranger at / sees.
• isMarketing() (apps/app/lib/env.ts) reads per request, so a config change
  needs no rebuild. Declared in apps/app/turbo.json passThroughEnv.

Typed, validated env Copy Chapter

apps/api/src/config/env.validation.ts runs via ConfigModule.forRoot({ validate }),
and lists every variable the API reads and nothing else.

• Validation runs while AppModule is evaluated — a test must set variables before
  importing it (see the dynamic import() in test/auth.e2e.spec.ts).
• The schema is the API's, not the repo's — @crm/auth and the agent read their own.

Optional: what the agent can do Copy Chapter

Every outside source is optional and the agent runs with none. A missing key removes a
place to look; never an error, never throws. agent/lib/capabilities.ts is the
single place that knows what is set.

BLOB_READ_WRITE_TOKEN is also in env.validation.ts and apps/api/turbo.json
because the API and the seed write pictures too. The Next.js app is deliberately
excluded — recognising our URL for the image optimizer needs no token.

The Context key is asked for, not configured Copy Section

CONTEXT_DEV_API_KEY is not a variable here and must not become one. The key lives
in AppSetting, is asked for at /onboarding/research, and changes on Settings →
General — an admin who cannot redeploy cannot set a variable.

• It buys two places to look, not one. Company brand data by domain, and a person
  read back from a LinkedIn URL already on their record. Both capabilities in
  agent/lib/capabilities.ts turn on and off with this one key.
• An install that had the variable is asked again: no migration, no fallback, and
  the gate cannot be dismissed.
• Nothing is lost while waiting. A keyless brand task settles SKIPPED before
  anything marks the row RUNNING, and settle only overwrites RUNNING — so the
  company stays PENDING, which the sweep re-queues
  (test/keyless-brand.integration.spec.ts).
• Saving the key runs the company sweep immediately (fire-and-forget).
• readContextDevKey (@crm/db/settings) is the only reader, read live with no
  cache. An unreadable database is a capability that is off, not an exception.
• The key is never read back — only whether one is set, and its last four.
• The agent checks it, not the API (a vendor client in the API is a bug):
  settings.setResearchKey calls POST /internal/crm/verify-key and writes unless the
  answer is invalid. 401 is the only answer meaning the key is wrong, and a
  check that cannot be made is not a failed check — unknown saves anyway and logs it
  unverified.

Mailbox sync Copy Chapter

Always on, on whichever social provider is configured, so there is no extra redirect
URI beyond the sign-in one. Scopes are requested at sign-in and gated by
requireMailboxAccess(), because granular consent lets a user untick one and still
sign in.

An SSO rep is not gated — needsMailboxGrant (@crm/auth) walls only an account
whose sign-in rows are all mailbox providers. It cannot be "has the scopes": an SSO
rep has no Google or Microsoft account to grant on, and revoke() keeps the account
row, so trying the optional feature and revoking would lock them out. They connect from
Settings → Connections, posting the same linkSocial call.

One granted mailbox is enough. A rep with both providers linked who granted Google
is not asked for Outlook; mailboxGrantsNeeded names the ones still outstanding and
/grant-access offers exactly those buttons.

Microsoft's granted scopes come back fully qualified —
https://graph.microsoft.com/Mail.Read, not Mail.Read. parseScopes is the one
canonicaliser and strips that prefix, so the comparison is against the bare permission
everywhere.

Sync is forward-only — Gmail records the current historyId on its first pass and
imports nothing, Calendar reads from now, and Outlook records now as its cursor.

CRON_SECRET (min 16 chars) guards POST /internal/sync/mailboxes and
/internal/sync/rates; both fail closed when unset. /internal/sync/google is
kept as an alias of the first, so an existing deployment's cron does not break on
deploy. Crons live in apps/api/vercel.json — mailboxes */5 * * * *, rates
daily. Minute-level schedules need a Pro plan; on Hobby it silently becomes daily.

Deliberate absences: no GOOGLE_SYNC_ENABLED (a switch that can disable a mandatory
feature is only ever wrong), no GOOGLE_WORKSPACE_DOMAIN (ALLOWED_SIGN_IN already
says who is internal — two sources is how a colleague becomes a lead), no
GMAIL_BACKFILL_DAYS, no OUTLOOK_BACKFILL_DAYS, no rate provider variable.

Telemetry is on, and turning it off is one variable Copy Chapter

CRM_TELEMETRY_DISABLED="1" — or DO_NOT_TRACK=1, honoured identically — and nothing
is sent. No client is constructed, so there is no queue waiting to flush later.

• Server side only, posthog-node in the API and the agent. posthog-js
  appears once, on the trycrm.ai landing page, and nowhere a record can be
  reached: autocapture on a CRM would lift contact names and deal amounts out of
  somebody else's database. That one import is gated on
  window.location.hostname, not on IS_MARKETING — turning the landing page on
  for your own domain never loads it. docs/telemetry.md.
• There is no variable for the destination. The project key and host are
  constants in packages/telemetry/src/project.ts. A phc_ key is write-only —
  it can send events and read nothing back — so making it configurable would
  only imply it were a secret. Edit the constants to point somewhere else.
• The install ID is a row, not a file — install, one row, UUID written by
  the migration. Vercel's filesystem is ephemeral, so ~/.crm/telemetry-id
  would count containers.
• Declared in env.validation.ts as optional, like everything else here. Every
  event and the never-sent list are in docs/telemetry.md.

Not env vars Copy Chapter

• Cache TTL — DEFAULT_TTL_MS (60s) in cache.module.ts; CACHE_TTL_MS overrides.
• Redis — optional; without REDIS_URL the cache is per-instance in-memory, which
  is wrong for multi-instance.
• Sign-in method — Google and Microsoft are in code; an IdP is a row (SSO, in api.md).

List Building Roadmap (`docs/list-building-roadmap.md`) Copy Section

List-Building Roadmap

A plan to answer the Director of Sales Development's read on the CRM: filtering
looks thin for real BDR list-building. Integrations are out of scope, by his own
note — this is about fields, filters, and views inside the CRM itself.

1. What he saw Copy Chapter

"As it stands it looks like a research/automation layer more than a system of
record — I'd be concerned about moving off HubSpot/Salesforce-caliber
filtering without seeing those gaps closed first."

— Director of Sales Development, first-look feedback

He is right about the current state. Today's filtering is this small:

• 3 Company filters — owner, industry, enrichment
• 2 Contact filters — owner, company
• 1 value per filter — no "is any of" yet
• 0 saved or shared list views

2. Why this is cheaper than it looks Copy Chapter

Two systems already in the CRM cover most of the fields on his list. Neither is
exposed as a filter yet — that is the actual gap, not missing intelligence.

Already built — admin fields. An admin-configurable field system already
backs every record sheet and table: FieldDefinition + FieldOption +
FieldValue, with a SELECT type for picklists and a USER type for a second
owner. Account type, segment/tier, territory, lifecycle stage, and lead source
all fit this today — no database migration required.

Already built — agent inference. The agent already scores seniority and
function (persona) per contact from evidence, the same pipeline that fills
title and LinkedIn today. It just isn't wired to a column, so it never reaches
the table or a filter.

3. The gap map Copy Chapter

Every field from his note, what backs it today, and the plan to close it.

Companies view Copy Section

All seven rows below are already seeded as FieldDefinition rows
(seedCompanyFields in packages/db/prisma/seed.ts) with real option sets. The
gap is not the field — it is that none of them show on the table or reach the
filter bar yet.

Contacts view Copy Section

4. The part that actually blocks list-building Copy Chapter

Adding every field above still will not give a BDR a HubSpot-style
list-builder. The filter bar itself is one value at a time. This is the real
foundation, and it comes before the fields above pay off.

1. Filters are single-select (Medium) — a BDR cannot say "VP or Director"
   or "SF Bay Area or NYC" in one filter today — each filter holds exactly one
   value.
2. Admin fields are not filterable at all (Medium) — every custom
   field — present or future — shows up as a column only. None of it reaches
   the filter bar without new plumbing.
3. No saved or shared views (Large) — a working list a BDR builds today
   lives only in the URL. There is no way to name it, save it, or hand it to a
   teammate.

5. Sequence Copy Chapter

Four phases, in order — each phase's fields are inert without the phase before
it.

Phase 1 — Filter engine foundation *(ships first)* Copy Section

Multi-select ("is any of") on every filter. Any admin-defined SELECT or
USER field becomes a filter automatically. An activity-recency filter goes in
here too.

Resolves: unlocks every field below · engagement / activity recency

Phase 2 — Company segmentation fields Copy Section

Turn on table and filter visibility for the seven Company fields from the gap
map — account type, BDR owner, segment/tier, territory, lifecycle stage, lead
source, ICP fit score. All seven are already seeded; nothing new to create.

Resolves: account type · BDR owner · segment/tier · territory · lifecycle
stage · lead source · ICP fit score

Phase 3 — Contact intelligence, surfaced Copy Section

Sync the agent's existing seniority and persona facts into real, filterable
fields. Add the title filter.

Resolves: seniority · persona · title filter

Phase 4 — Saved & shared views *(later, on request)* Copy Section

Name a filter combination, save it, share it with the team. Sequence status
waits here too, tied to an outreach-tool connection if that scope reopens.

Resolves: reusable BDR lists · sequence status (needs an integration)

6. Issues Copy Chapter

Reported in full, including risks this plan does not remove.

1. RISK — New fields alone do not fix list-building. Filters stay single-select
   without phase 1.
   Fix: build multi-select filtering first. Sequence, above, already orders
   this first.
2. NOT DONE — Custom fields are not wired into any filter today. They render as
   table columns only.
   Fix: not done. Planned in phase 1 as automatic facet generation.
3. NOT DONE — Sequence status has no source of truth inside this CRM.
   Fix: not done. Needs an outreach-tool integration — out of scope now, per
   your note.
4. RISK — A BDR owner shipped as an admin field will not appear in
   owner-based reports until someone decides it should.
   Fix: ship as an admin field first. Promote to a first-class column only if
   reporting needs it later.
5. UNKNOWN — No user role distinguishes an AE from a BDR today, so no field
   can default itself by role.
   Fix: not investigated. Confirm before phase 2 whether role-based defaults
   matter to him.

Scoped to the CRM's own data model and filter UI. Integrations, per your note,
are out of scope for this plan.

Setup (`docs/setup.md`) Copy Section

Setup and local development

Operational detail moved out of the rule docs. api.md, agent.md and
environment.md are what agents read before changing code; this is what a person
reads once.

First run Copy Chapter

cp .env.example .env        # fill DATABASE_URL, BETTER_AUTH_SECRET, ALLOWED_SIGN_IN
docker compose up -d        # Postgres, matching .env.example
bun run db:migrate && bun run db:seed
bun run dev                 # app :3000, api :3001, agent :2000

Prisma from the repo root: db:generate, db:migrate, db:push, db:reset,
db:seed, db:studio, db:deploy.

dev depends on ^dev:prepare, so every start applies pending migrations and
regenerates the Prisma client before a single server boots. That is why the first
run needs db:migrate only for the seed that follows it. When the database and
schema.prisma have diverged past what migrate deploy can reconcile,
dev:prepare stops the whole run rather than starting servers against a schema
they do not match — reconcile with db:migrate, or db:reset when the divergence
is an edited migration that has already been applied.

Google Cloud Copy Chapter

• Enable the Gmail API and the Google Calendar API on the project.
• Set the consent screen to User type: Internal if you are on Workspace.
  gmail.readonly is a restricted scope, so an External app needs OAuth
  verification plus an annual CASA assessment. Going External later means the full
  review — a decision, not a checkbox.

The agent bridge Copy Chapter

AGENT_URL="http://127.0.0.1:2000"   # 127.0.0.1, not localhost: eve dev is IPv4-only
AGENT_BRIDGE_SECRET="$(openssl rand -base64 32)"

localDev() accepts any loopback request, so curl 127.0.0.1 proves nothing about
the bridge — send -H 'Host: agent.example.com'. GET /eve/v1/info is the whole
inventory, including a diagnostics count that finds files eve silently ignored.

Running the agent Copy Chapter

The agent package's default dev command is interactive eve dev. The root
Turbo task marks it interactive, so select the agent pane and press Enter before
using the eve TUI. Run turbo run dev:headless --filter=agent when a terminal
cannot render the TUI; that uses eve dev --no-ui, and the Turbo pane is the
record because only interactive development writes .eve/logs/ for eve logs.
Reach for the Turbo task rather than bun run --filter=agent dev:headless: the
package script alone skips dev:prepare, so the agent would start against
unmigrated tables.

hooks/activity.ts is the replacement narration, to stderr (the TUI hides
stdout), printing shape everywhere and argument contents outside production only. It
is not the audit trail — hooks/audit.ts writes AgentEvent regardless.

• A second bun run dev fails the whole turbo run.
• An orphaned agent holds the port: lsof -nP -iTCP:2000 -sTCP:LISTEN.

Nothing is researching, and the queue only grows Copy Section

eve dev never fires schedules on their cron cadence, and everything visible
still works — the row is written, the sheet says Queued, and dispatch.ts is never
called. The poke covers this only when AGENT_BRIDGE_SECRET is set; unset,
poke() returns silently and the queue looks exactly like a slow agent.

Tasks the API did not write (schedule_recheck) and anything queued while the agent
was down still need a manual run:

bun run --filter=agent dispatch    # exact production path, both lanes, real credits

Its printed sessionIds are research rows only, so a run that resolved forty logos
prints an empty list and was not idle. eve start and Vercel do run the schedule.

`vercel env pull` writes `.env.local`, which wins Copy Chapter

.env.local is the override the loader reads last, and vercel env pull writes
production credentials there by default. Pull once and every process silently
points at production — not as an error, but as bun run dev working perfectly against
the live database. On 2026-08-01 eleven migrations landed on Neon from a laptop.

1. Pull somewhere inert: vercel env pull .env.vercel.
2. packages/db/scripts/require-local-db.ts guards db:migrate, db:push,
   db:reset, db:seed and takes ALLOW_REMOTE_DB=1. db:deploy is unguarded on
   purpose. It reads the root files directly rather than process.env, because Bun
   auto-loads the working directory's .env while Prisma's CLI only sees
   @crm/env/load.

Migrations run on the production deploy, and nowhere else Copy Chapter

apps/api/scripts/build-func.mjs runs prisma migrate deploy during the crm-api
build, gated on VERCEL_ENV === "production". The schema therefore moves when the
release pull request merges and release deploys — with the code that needs it,
and once rather than once per branch.

Preview deploys share the production database: DATABASE_URL is a single value
across production, preview and development. Until that changes, a preview of a
branch that adds a migration runs against a database without those tables — it
builds, and the pages that touch them fail. Test schema changes locally, where
bun run dev migrates for you. Before the gate existed the reverse was true and
worse: every preview applied its own migrations to the production database, so on
2026-08-07 the live schema ran six migrations ahead of the live code all day.

`migrate deploy` is not proof the schema is right Copy Section

The build follows the deploy with prisma migrate diff --exit-code against
schema.prisma and shouts in the build log when they disagree. No pending migrations to apply only means _prisma_migrations has a row for every file —
it says nothing about what the tables actually look like.

They came apart once. A prisma db push shaped production from a laptop, the
migration rows were recorded as applied without their SQL ever running, and
agentConversationAttachment went live without its position column. Every deploy
reported nothing pending, for days, while conversations.builderById returned 500.
The tell is an object in the database that no migration defines — there was an
agentConversationAttachment_submissionId_createdAt_idx that appears in no
migration file, only in a db push of an older schema.

Reconciling is one command, and it is worth reading before running:

DATABASE_URL="…" bunx prisma migrate diff \
  --from-config-datasource --to-schema prisma/schema.prisma --script

Secrets hygiene Copy Chapter

.gitignore ignores .env and .env.* with one negation for .env.example, so
.env.bak is ignored too. .env.example ships no secret — placeholders are empty
strings, asserted by packages/env/test/root.spec.ts. Generate your own secret;
never reuse one from an example, a tutorial, or another environment.

Tests Copy Chapter

bun run --filter=api test
bun run --filter=agent test    # integration specs need DATABASE_URL + real Postgres

The test database rebuilds itself when it drifts Copy Section

bun run db:test creates crm_test and runs migrate deploy on it. The database
name must end in _test; the suite deletes rows it expects to put back, so it
refuses anything else.

migrate deploy only applies migrations that are missing. It never removes a
table, a column or a constraint the database has and the schema does not. A
crm_test built on a branch that was later abandoned therefore keeps that branch's
objects forever, and db:test used to report already exists and move on. The
extra objects are invisible until one of them rejects a write, and then the failure
names a constraint that appears in no migration and in no schema — a stray
trackedEvent_visitorId_fkey once failed seven tracking specs this way, on every
branch, for as long as the database survived.

So db:test now checks the database it found and rebuilds it when either is true:

• It holds a migration this branch does not have. The database came from
  another branch. The name of the first one is printed.
• It no longer matches schema.prisma, by prisma migrate diff. Something
  was pushed or altered by hand.

A rebuild drops the database and re-runs every migration, and it says which of the
two reasons fired. Force one with bun run db:test --reset. Nothing else in the
repo may drop a database, and this may only because the _test suffix is checked
first.

Telemetry (`docs/telemetry.md`) Copy Section

Telemetry

What this install reports about itself, in full. The decisions behind it are in
adrs/telemetry.md; this file is the list.

Turn it off with CRM_TELEMETRY_DISABLED="1" or DO_NOT_TRACK=1 in the root .env, then
restart. This file is the full account of what is sent; there is no settings page for it, so
this is the thing to read.

Where it goes is not configurable and deliberately so: the project key and host are constants
in packages/telemetry/src/project.ts. A phc_ key is write-only — it sends events and reads
nothing back — so a variable would only have made a public identifier look like a secret. Point
a fork somewhere else by editing that file. Nothing is sent while NODE_ENV is
test, so a test run cannot emit.

The shape of it Copy Chapter

• Server side only, in everything you run. posthog-node in apps/api and apps/agent.
  No autocapture, no session replay and nothing client-side anywhere a record can be reached.
  Autocapture on a CRM would lift contact names, email addresses, company domains and deal
  amounts out of your database; the simplest way not to hold that is not to collect it. The
  single exception is the marketing site at trycrm.ai, which is a web page and not an
  install — The landing page, below, is the whole of it, and it cannot run on your
  hostname.
• One identifier, a UUID generated by the migration that created your database. It is
  attached to nothing else. identify() is never called, there are no person properties, and no
  user, email or ALLOWED_SIGN_IN value is ever sent.
• One event a day, plus eight one-shot setup events and one event per failure.
• No IP address. Every event sets $ip: null and disables geoip, and the receiving project
  has anonymize_ips on so the address is dropped at ingestion. Both are needed: PostHog stamps
  $ip from the incoming connection whatever the SDK sends, and reads a null as "not provided"
  rather than "do not keep". Point this at a different project and you must set it there too.
• Never blocks and never throws. Every send is fire-and-forget behind a swallowed handler; a
  telemetry failure logs at debug and is invisible everywhere else.
• Off leaves no marks. With telemetry disabled the rollup route returns before the funnel
  sweep runs: no milestone is recorded, no counter is drained, no rollup day is claimed. Turn it
  back on and the funnel is still whole, because nothing was quietly consumed while it was off.
• Nothing is sent from a test run. NODE_ENV=test disables it, and apps/api and apps/agent
  additionally set CRM_TELEMETRY_DISABLED=1 in their test scripts — because a spec is allowed
  to reassign process.env.NODE_ENV, and one that does was enough to let a real event out.
• An allowlist, in code. ALLOWED_PROPERTIES in packages/telemetry/src/allowlist.ts names
  every property that may be sent. Anything else is dropped before the event is built — not by
  review, not by convention.

Events Copy Chapter

`install_daily` Copy Section

Once per install per day, from the API itself. Counts and distributions from grouped queries.
Never a value from a row.

It runs in-process and needs no cron. TelemetryService rolls up on boot and then hourly,
and the day claim below makes all but the first of those a no-op. That covers both shapes an
install comes in: a serverless deployment rolls up on a cold start, a long-running container on
the timer. POST /internal/telemetry/rollup still exists for a platform cron that would rather
drive it, and still refuses without CRON_SECRET — it is an anonymous route, so an unauthenticated
one would let a stranger drive any install's aggregation. Nothing depends on it: an install that
never sets CRON_SECRET reports exactly the same.

The day is claimed under a row lock on install before anything is gathered, so two crons that
fire at once produce one event rather than two — and the second does not find the counters
already drained. A rollup that fails to send hands the day and the counters back, so tomorrow's
run is not suppressed by a send that never happened.

The event carries a deterministic uuid, stableUuid(install.uuid, "install_daily", day) — a
SHA-256 digest in a v8 UUID — and PostHog ingests a repeat of one it has already seen only once.
RFC 4122 defines v5 as SHA-1, and CodeQL rightly refuses to see a hash of the install identity
and a weak algorithm in the same expression. Nothing here needs v5, so it is v8, the slot RFC 9562
leaves for a derivation of one's own. The lock
stops two processes racing; the id stops the same process sending twice, which the release path
can otherwise cause. Counting installs survives a duplicate either way, because PostHog's unique
math is per install per day, but tool_calls_total and the other summed properties would be
counted twice, and now are not.

A send reports failure conservatively. posthog-node does not reject on a failed send — its
sendImmediate catches the error and emits it on the client instead — so client.ts enqueues and
awaits flush(), which does throw, and additionally checks the client's error counter, which any
capture in flight can move. Either signal is treated as a failure. That errs toward re-sending a
rollup that actually landed, which the deterministic id makes free, rather than consuming a day
whose event never arrived, which cannot be recovered.

The install

Capabilities — booleans, never values

cap_perplexity, cap_context_dev, cap_blob, cap_github, cap_redis,
cap_agent_bridge, cap_cron_secret, cap_ai_gateway, cap_google_oauth, cap_sso_provider,
cap_tracking, is_marketing.

Each is only whether the key is set. cap_context_dev is whether an AppSetting row holds one,
cap_sso_provider whether an ssoProvider row exists, cap_tracking whether a tracking site id
has been minted — never the id itself. No key, value or last-four is sent.

cap_context_dev covers both of the agent's Context capabilities: company brand data by domain,
and reading a person off a LinkedIn URL. They are one key, so they are one boolean.

The agent

Tool names are matched against the authored tools in apps/agent/agent/tools/ and eve's own
builtins. Anything else is counted as other. Task kinds are matched against TASK_KINDS.

Tool counts are read from the agentEvent rows the audit hook already writes — the event type
and the tool name only. AgentEvent.data itself is never sent.

The evidence ledger

Evidence kinds are matched against the eleven in lib/evidence.ts; anything else is other.
method is a label a tool writes, so it is sent only when it matches a strict lowercase
dotted-slug shape under 40 characters — a name, an address or a sentence cannot pass, and is
counted as other instead. The fact's value, field, evidence and sourceUrl are never
sent.

The CRM

Website tracking

The setup funnel Copy Section

Eight events, each sent once per install, ever. Each carries the timestamp of the thing it
records rather than the moment it was noticed, so the funnel reads true even though a nightly
job is what sends it.

migrations_applied → first_sign_in → google_oauth_configured → first_mailbox_sync →
first_non_seed_contact → first_agent_task_claimed → first_agent_task_completed →
first_fact_applied

They carry no properties of their own beyond the common ones — version, days since install,
whether this is Vercel.

google_oauth_configured is the one step with no row to read a time off: two environment
variables leave no timestamp behind. It is stamped from the first Google account row when
one exists — configuration must have come before the account did — and otherwise from the
moment the sweep first saw the variables set. That sweep runs on every API boot, not only on
the cron, so an install that arrives configured is stamped on its first boot.

first_fact_applied is the earliest decidedAt of any fact a human accepted, or the earliest
observedAt of any fact the agent applied itself, whichever came first. Facts that were
applied and later superseded still count — being replaced later does not make the first
application not have happened.

The step is claimed before it is sent, and handed back if the send fails. The claim is the
insert itself — telemetryMilestone.step is the primary key, so of two processes sweeping at the
same instant exactly one is told it landed the row, and only that one sends. A failed send deletes
the row, so the next sweep tries again rather than losing the step forever.

This is the opposite of the ordering the funnel shipped with, which sent first and recorded after.
That was chosen on the grounds that a duplicate is a rounding error while a lost step cannot be
recovered — but it made a duplicate the likely outcome rather than a rare one, because both the
boot sweep and the rollup call sweep(). One install sent first_fact_applied six times.
Claiming first costs the case the old ordering was protecting against: a crash between the claim
and the send drops the step. Each event also carries a deterministic uuid,
stableUuid(install.uuid, step), so a step that is genuinely sent twice is still ingested once.

Nothing is recorded at all while telemetry is off.

Errors Copy Section

Error class and where it came from. Never a message, never a stack trace, never a payload:
our errors would carry contact fields.

sync_error's error_source is derived from sync_source rather than passed in, so one
mailbox pipeline that dispatches to both providers cannot report an Outlook failure as a Google
one. A source that is not one of the three is sent as other, and its error_source as
mailbox_sync.

route is the route pattern — /internal/sync/google, /trpc/contacts.list — never a URL
with parameters in it. Anything that does not match a strict path shape is sent as other, and
so is any error class that is not a plain identifier.

The landing page Copy Chapter

trycrm.ai is the one place posthog-js runs: web analytics and session replay of strangers
reading a pitch. It is a website, not an install — there is no database behind that page and
no record within reach of it. Everything above still holds for the CRM itself.

It cannot run on your hostname. analyticsAllowed (apps/app/lib/analytics.ts) compares
window.location.hostname against two literals — trycrm.ai and www.trycrm.ai — and
posthog-js sits behind a dynamic import() on the far side of that check. Turn
IS_MARKETING="true" on and serve the same page from a domain of your own and the SDK is
never fetched: not sent and then dropped, never downloaded. The gate is the hostname rather
than IS_MARKETING, because IS_MARKETING is precisely the flag a self-hoster is invited to
set.

PostHog refuses it from the other side too. recording_domains on the receiving project names
the same two origins, so replay and heatmaps are declined for any other page that presents the
key.

It shares the install's project, key and host, and the two do not mix: the landing page
sends $pageview, $pageleave, $autocapture, $web_vitals and the two CTA events below
about a browser, an install sends install_daily and its funnel about a database. Install
events set $process_person_profile: false, so they never become a person and never join one.

The two CTA events Copy Section

Both carry one property, cta_location — hero or closing — because both buttons appear
twice on the page and which one a stranger reaches is the only interesting thing about them.
Nothing else is attached.

They go through captureLanding in components/landing/analytics.tsx, behind the same
hostname gate and the same dynamic import() as init. On any other hostname the SDK is never
fetched, so the click is not sent and then dropped — there is nothing there to send it. Both
sends are fire-and-forget behind a swallowed handler; neither delays the copy or the
navigation.

anonymize_ips stays on, and that costs something here: PostHog drops the address before
geoip runs, so the landing page has no country, region or city. That setting is what makes the
no-IP promise above true for every install, and an install's anonymity outranks a marketing
map. A separate project is the only way to have both.

ALLOWED_PROPERTIES does not reach these events — it guards what packages/telemetry builds,
and these are the browser SDK's own. What it sends is ordinary web analytics: URL, referrer,
UTM parameters, browser, device, screen size, a session ID. Replay masks every input by
default and the page has no field to type in.

What is never sent Copy Chapter

• Any Contact or User name, email, title or photo
• Any Company name, domain, industry or location
• ContactFact.value, .sourceUrl, .evidence, .field
• AgentTask.reason and AgentTask.outcome — both free text the agent wrote about a named person
• ContactBrief content, WorkspaceProfile.website, .narrative, .sections
• EmailThread and EmailMessage subjects or bodies, CalendarEvent titles, CalendarAttendee rows
• Deal names and amounts. Stage distribution is fine; amounts are not.
• AgentEvent.data, AgentConversation content, prompts, completions, reasoning traces
• ALLOWED_SIGN_IN, AppSetting.contextDevApiKey, any key, secret, token or connection string
• SuppressedDomain and SuppressedContact values — counts only
• IP address. Set $ip: null and disable geoip. n8n collects IP and has to caveat their
  anonymity claim because of it. We do not need it and we would rather the claim be unqualified.

On that last line: the two properties alone do not achieve it, because PostHog fills $ip in from
the connection during ingestion. anonymize_ips is enabled on the receiving project, which is what
actually drops it. See adrs/telemetry.md.