Glossary

Quick reference for the names and abbreviations that show up in this codebase and team conversation. Page is alphabetical; cross-links go to the canonical chapter for each concept.

A

AGENTS.md — agent guidelines file at the repo root. Claude Code, Cursor, and the SDK auto-attach it to agent context. Short, dense, runbook-style. Mirror of CLAUDE.md for non-Claude agents. See Reading paths for the agent reading order.

agentation — the dev-only runtime that records agent-driven UI actions for replay. Catalog package agentation. Toggled via Cmd+. → d → a.

B

Better-Auth — the authentication library apps/web uses (better-auth: 1.6.5 in the catalog). Has a non-obvious auto-injection quirk documented at Better-Auth quirks.

BFF — Backend-for-Frontend. The Next.js route handlers under apps/web/src/app/api/auth/[...all] that proxy from the app origin to auth.todayai.dev / auth.t.ai. The reason the localhost-direct dev mode needs to strip Domain from relayed Set-Cookie headers.

Bugbot — Cursor's PR review bot. Runs as an optional check that doesn't block merge.

C

catalog — the catalog: field in pnpm-workspace.yaml. Single source of dep versions across every package; catalogMode: strict rejects ad-hoc versions in workspace package.json files. See pnpm workspaces.

CLAUDE.md — the dense agent-runtime reference at the repo root, auto-attached by Claude Code. Captures repo conventions and tacit knowledge that won't fit in README. The mirror of AGENTS.md for Claude specifically.

Cmd+. overlay — the in-app debug chord menu. Press Cmd+. anywhere in apps/web. See Debugging tools.

cloud dev — short for "Claude Code on the web cloud-dev session." A sandboxed VM in claude.ai/code where the agent runs end-to-end (edit, test, push). See Cloud dev.

codegen — pnpm api:generate, which runs @hey-api/openapi-ts to regenerate the TypeScript API client from the cloud's OpenAPI spec. See API codegen.

D

dev — the development branch. Every PR lands here through the merge queue. Production is main; dev → main is a manual fast-forward via sync-main.yml.

Dexie — IndexedDB wrapper library. Backs the chat runtime's local persistence layer; see Chat runtime.

E

E2E — end-to-end tests. Playwright suites under apps/web/e2e/. Split into smoke (cheap, narrow) and full (broad, slower). See Playwright tiers.

F

Fumadocs — the docs-site framework that powers apps/webview-bridge-docs, design-system/docs, and apps/dev-docs. Built on Next.js + MDX.

H

@hey-api/openapi-ts — the OpenAPI → TypeScript code generator used by pnpm api:generate. Outputs to apps/web/src/lib/api/generated/. See API codegen.

L

/llms.txt — convention for AI-readable site indexes. This site emits /llms.txt (index) and /llms-full.txt (concatenated). Per-page markdown is reachable via Accept: text/markdown content negotiation.

LFS — Git Large File Storage. Used for Playwright visual-regression PNG snapshots. CI's LFS Check workflow validates LFS pointer integrity.

localhost-direct — the default dev mode where pnpm dev serves at bare http://localhost:<port>. No proxy, no MITM, no CA trust. Enabled by LOCALHOST_BFF=true in apps/web/.env.development. See Local development.

M

main — the production branch. Only the sync-main.yml workflow advances it. Production deploys fire on main pushes.

MDX — Markdown with JSX. The docs sites' content format. Watch out for <URL> autolinks (rejected as JSX), { ... } blocks (parsed as JSX expressions if not in backticks), and frontmatter description: values containing YAML-significant characters.

merge queue — GitHub's PR merge serialization for dev. Runs a speculative-branch CI pass before fast-forwarding dev. See Merge queue.

Moon — the task graph runner. Owns :typecheck, :test, :build across every workspace project. The root pnpm scripts wrap it. See Moon task orchestration.

MSW — Mock Service Worker. The mock layer for Storybook, unit tests, and the runtime mockMode=true path. See MSW mocks

• MSW handlers and fixtures.

O

OIDC — OpenID Connect. The auth protocol behind the auth interaction model. OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_INTERNAL_AUTHORITY env vars configure the web client.

Opal — the higher-level product flow primitives package (@todayai-labs/opal). Built on top of @todayai-labs/tdx-ui + @todayai-labs/tdx-tokens. Includes the onboarding shells, narrative mark, shader background. See Workspace → Design system.

OpalShaderShell — the shared shell mounted by the three auth surfaces (login, oauth/select-account, oauth/consent). Bundles the Opal background, 600 px content column, and brand-mark plumbing. See Opal shader shell.

oxlint / oxfmt — the Rust-rewrite Lint + Format tools that replaced ESLint + Prettier. See Linting.

P

PR-A..PR-Z..PR-AA — the Excel-column-style PR letter convention. See PR workflow.

preview — the Vercel preview environment, hosted on *.todayai.dev. Used by smoke / full E2E and by every PR's deploy. Distinct from production (today.ai) and development (t.ai / localhost).

Postbox — the iOS TDChat data layer pattern that the chat runtime is a TypeScript port of.

proxy.ts — Next.js 16's middleware filename. Renamed from middleware.ts. See Next.js 16.

S

SKILL.md — the format for Claude / Cursor skills under .claude/skills/<skill>/SKILL.md. See Claude skills.

SSR — Server-Side Rendering. Next.js renders pages on the server first, then hydrates on the client. The getEnvironment() helper is designed to return a stable value across the SSR / hydration boundary.

Storybook — component sandbox. Five installs in this repo (one per app + two in design-system). See Storybook topology.

T

TCK — Today Canvas Kit. Private packages under @todayai-labs/tck* shipped from todayai-labs/today-tck. Used to embed canvas / widget experiences in apps/web.

TDX — Today Design eXchange. The design system, split into three workspace packages: @todayai-labs/tdx-tokens, @todayai-labs/tdx-ui, and the design-system/docs site published as @todayai-labs/tdx-docs.

three-tier domains — t.ai (dev) / todayai.dev (preview) / today.ai (production). See Three-tier domains.

tsgo — TypeScript Native Preview, the Rust-backed tsc replacement. Catalog package @typescript/native-preview. Always run via tsgo --build, never tsc --noEmit. See TypeScript with tsgo.

Turbopack — Next.js 16's default bundler for dev and for the docs sites' build. apps/web still uses webpack for next build explicitly.

V

Vercel — the deploy platform. Four projects: today-web, today-admin, today-tdx-docs, today-dev-docs. See Deployment.

W

WebView Bridge — the typed message channel between embedded web content and native hosts (iOS/macOS WKWebView, Android, Windows WebView2). Documented in the separate apps/webview-bridge-docs site.

worktree — git worktree add. Used for parallel branches. See Parallel worktrees.

wproxy / whistle — alternative to Proxyman for local domain proxying. Used when MITM is needed (rare — localhost-direct covers most cases). See Local development.