Documentation source
Documentation source
Documentation source
How AI coding agents should navigate and use this documentation.
# For Coding Agents
This page tells coding agents (Claude Code, Cursor, Copilot, Gemini CLI, etc.) how to find the right documentation when working on the Sprinter Platform.
## Entry Points
| What you need | Where to look |
| ------------------------------- | ------------------------------------------ |
| Quick system overview | `/docs/overview` or `app/llms.txt` route |
| Agent-native source map | `documents/AGENT-NATIVE.md` |
| Full machine-readable reference | `app/llms-full.txt` route |
| Architecture and data flow | `/docs/architecture` |
| Database schema and tables | `/docs/data-model` |
| Specific feature/module | `/docs/features/\{module-name\}` |
| External service integration | `/docs/integrations/\{service\}` |
| Operational procedures | `/docs/runbooks/\{procedure\}` |
| What to build next | `/docs/roadmap/backlog` |
| Feature specs (before building) | `/docs/roadmap/specs/\{feature\}` |
| Spec-first workflow | `/docs/roadmap` |
| Coding standards and rules | `/docs/contributing` |
| Critical rules (always loaded) | `CLAUDE.md` at repo root |
| File-pattern-specific rules | `.claude/rules/*.md` (loaded contextually) |
## How to Find the Right Doc
### By file you are editing
| Files you are touching | Read this doc |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `features/entities/**` | [Entity System](/docs/features/entity-system) |
| `lib/ui-registry/**` | [View System](/docs/features/view-system) |
| `features/blocks/**` | [Block System](/docs/features/block-system) |
| `features/tools/**` | [Tool System](/docs/features/tool-system) |
| `features/agents/**` | [Agent System](/docs/features/agent-system) |
| `features/chat/**` | [Chat](/docs/features/chat) |
| `features/actions/**`, `features/sessions/**`, `features/responses/**` | [Actions](/docs/features/actions), [Sessions](/docs/features/sessions), [Responses](/docs/features/unified-response-system) |
| `features/documents/**` | [Document Processing](/docs/features/document-processing) |
| `features/feed/**` | [Feed](/docs/features/feed) |
| `features/capture/**` | [Capture](/docs/features/capture) |
| `features/navigation/**` | [Navigation](/docs/features/navigation) |
| `features/tenant/**` | [Multi-Tenant](/docs/features/multi-tenant) and [Auth & Permissions](/docs/features/auth-permissions) |
| `features/realtime/**` | [Realtime](/docs/features/realtime) |
| `features/comments/**` | [Comments](/docs/features/comments) |
| `features/graphs/**` | [Graph](/docs/features/graph) |
| `features/webhooks/**` | [Webhooks](/docs/features/webhooks) |
| `features/api-keys/**` | [API Keys](/docs/features/api-keys) |
| `features/analytics/**`, `features/cost/**` | [Analytics & Cost](/docs/features/analytics-cost) |
| `features/skills/**` | [Skills](/docs/features/skills) |
| `features/inngest/**` | [Inngest Integration](/docs/integrations/inngest) |
| `features/custom/**` | Product-specific code; see [Overview](/docs/overview) for the platform/custom boundary |
| `supabase/migrations/**` | [Data Model](/docs/data-model) and [Migrate Runbook](/docs/runbooks/migrate) |
| `lib/supabase/**` | [Supabase Integration](/docs/integrations/supabase) |
| `app/api/**` | [Contributing](/docs/contributing) for API handler rules |
### By task you are doing
| Task | Read these docs |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Adding a new entity field | [Entity System](/docs/features/entity-system), [Actions](/docs/features/actions), [Responses](/docs/features/unified-response-system) |
| Creating a new AI tool | [Tool System](/docs/features/tool-system) |
| Building a new agent | [Agent System](/docs/features/agent-system) |
| Changing prompt assembly, provider caching, or run telemetry | [Agent System](/docs/features/agent-system), [Analytics & Cost](/docs/features/analytics-cost) |
| Changing workspace business context or tenant-authored agent knowledge | [Agent System](/docs/features/agent-system), `features/agents/agent-context.ts`, `features/agents/agent-context-shared.ts`, `features/settings/**` |
| Adding a new block type | [Block System](/docs/features/block-system) |
| Creating a new view layout | [View System](/docs/features/view-system) |
| Writing a migration | [Data Model](/docs/data-model), [Migrate Runbook](/docs/runbooks/migrate) |
| Setting up a new product | [New Product Runbook](/docs/runbooks/new-product) |
| Debugging field population | [Actions](/docs/features/actions), [Sessions](/docs/features/sessions), [Responses](/docs/features/unified-response-system), [Inngest Integration](/docs/integrations/inngest) |
| Adding background processing | [Inngest Integration](/docs/integrations/inngest) |
| Working on auth/permissions | [Auth & Permissions](/docs/features/auth-permissions) |
## Key Rules for Agents
These rules are enforced across the codebase. Violations will cause build failures or review rejections.
1. **Entity types are DB-driven** — never hardcode entity type slugs in platform code
2. **All DB ops are tenant-scoped** — use `getTenantContext()` or `getActiveTenantId()`
3. **Use the auth adapter** — `getUserId()`, `requireAuth()`, `hasPermission()` from `features/tenant/auth.ts`
4. **shadcn/ui for all interactive UI** — never raw HTML inputs or buttons
5. **No hardcoded colors** — use CSS variables (zero-chroma neutrals, navy primary)
6. **No "entities" in UI copy** — use "records", "data", "items" in user-facing text
7. **Co-located tests required** — every file with exported logic needs a `.test.ts`
8. **Messages table** — use `messages`, not `chat_messages`
9. **User tenants table** — use `user_tenants`, not `tenant_members`
## Doc Structure Convention
Every feature doc follows the same structure so agents can reliably find information:
- **Overview** — what, why, who
- **Key Concepts** — types, schemas, terminology
- **How It Works** — architecture, data flow
- **API Reference** — key functions and signatures
- **For Agents** — available tools and actions
- **Design Decisions** — non-obvious choices
- **Related Modules** — cross-references
## Spec-First Workflow
**Every new feature must have a spec before implementation begins.** See [Spec-First Development](/docs/roadmap) for the full workflow.
### Quick Reference for Agents
1. **Check the backlog** — `content/docs/roadmap/backlog.mdx` lists all planned work by priority
2. **Find or write a spec** — `content/docs/roadmap/specs/{feature}.mdx` has the design
3. **Claim it** — Set `status: in-progress` and `assigned-to` in the spec frontmatter
4. **Check file conflicts** — The spec's `files-touched` field lists which files will be modified. If another in-progress spec touches the same files, coordinate or pick different work.
5. **Build it** — The spec is your source of truth
6. **Complete it** — Set `status: completed`. The documentarian promotes spec content to the feature doc.
## Context and Cost Notes
- `agent_context` is the durable tenant-authored workspace business profile. If you change how agent context is assembled or edited, update both the agent docs and the admin/editor flow.
- Anthropic prompt caching depends on stable prompt structure and deterministic tool ordering. If you change tool registration or prompt assembly, preserve stability unless you have a measured reason not to.
- Runtime telemetry for agent runs is recorded via `ai.runtime.completed`. If you add or rename telemetry fields, update the analytics/cost docs and any admin surfaces that summarize them.
### Spec Frontmatter
```yaml
---
title: Feature Name
description: One-line summary
status: draft | approved | in-progress | completed
priority: P0 | P1 | P2 | P3
assigned-to: "" # empty = unclaimed
branch: "" # git branch
target-doc: /docs/features/entity-system
files-touched:
- features/entities/types.ts
---
```
## Keeping Docs Updated
When you complete a feature, fix, or significant change:
1. The `documentarian` sub-agent runs automatically as part of the feature completion checklist
2. It updates the changelog and the relevant feature doc
3. For spec-first features, the documentarian also promotes spec content to the target feature doc
4. If you add a new module, create a new MDX file in `content/docs/features/` and add its slug to `content/docs/features/meta.json`
5. Run `pnpm typecheck` to verify the docs source loader still resolves the updated `content/docs` files