## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - `AGENTS.md` tells every contributor and agent to read `doc/DATABASE.md` before a schema or migration change > - That file grew to 2,611 lines. About 1,950 of them were notes on the tables of one feature, added one pull request at a time > - The setup steps and the migration rules started at line 792, below those notes > - This pull request cuts `doc/DATABASE.md` to 377 lines: setup, and the rules that apply to every schema change > - The benefit is a guide that a person or an agent can read in full before a schema change ## Linked Issues or Issue Description Refs #21670 (the same cleanup for `doc/DEVELOPING.md`). **Issue type** Outdated or confusing documentation. **Where is the issue?** `doc/DATABASE.md` **What's wrong?** The file was 2,611 lines. It opened with a Better Auth upgrade note and 492 lines on task query performance. The schema change workflow started at line 1367. **Suggested fix** Keep database setup and the general rules in `doc/DATABASE.md`. Remove the notes on individual tables. The schema and its tests describe those. ## What Changed - `doc/DATABASE.md` is now 377 lines. It keeps the three database modes, client tuning, the schema change workflow, migration compatibility, the migration authoring checklist, migration snapshots, the rule for retries after a lost connection, transaction-aware work signals, plugin namespaces, and backups. The wording of the kept text is unchanged. - New `doc/database-client-internals.md` holds the response-size diagnostic, the notes on the postgres.js patch, and the transaction memory note. The text is moved without wording changes. - "Experimental remote workspace snapshots" moved to `doc/workspace-storage.md`, which links to it. - "Execution admission accounting" moved to `server/src/modules/README.md`, which links to it. - Deleted about 1,950 lines of notes on one feature each. No other file linked to them. The deleted sections are: Better Auth 1.7.16 upgrade, Durable native provider backups, Workspace cohort admission proofs, Original local Git sources for archived workspaces, Proactive agent chat messages, Persistent case handoffs, Task query performance, Tool profile reads, Execution identity row locks, Remote workspace row locks, Managed adapter settings, Cloud configuration migration receipt, Cloud runtime identity singleton, Unclaimed Cloud warm standby, Native finalization history and idle sleep, Feedback history and idle sleep, Resource membership tables, Decision training snapshot retention, Decision queues and triage provenance, Native runner persistence, Chat communication snapshots, Telegram private draft identities, Attachment upload provenance, Question-response delivery receipts, Secret storage, Persistent agent conversations, Resource lifecycle events, Legacy controller ownership, Agent file persistence and legacy revisions, Large API response snapshots, Runner API response reservations, Internal agent commentary, Agent identity keys and backups, Slack app registration, Slack manager workspace grants, Installed skill packages, Project repository skill synchronization, Task workspace records, Execution recovery query performance, Agent runtime synchronization journal, Retired Pipelines storage, Prompt injection classification, Deferred conversation requests, GitHub inherited review-wait reads, Sandbox creation ownership, Object-backed run evidence, Cloud runtime configuration singleton, Independent accounting and budget evaluation, Standard workspace and Classic opt-in, Project environment rolling compatibility. - Also deleted from kept sections: the subscription-table note and the issue-reference backfill note in the embedded mode section, the HTTP access log note and the per-endpoint retry notes in the connection loss section, and the notes on migrations `0355`, `0313`, and `0314` in the authoring checklist. - `AGENTS.md` now states what `doc/DATABASE.md` is for. ## Verification - A script built the new files by line range from the old file. It asserts the old line count and the first line of each range. - A link check on every changed Markdown file, and on the four files that link to a `DATABASE.md` anchor, found 0 missing files and 0 missing anchors. - `node scripts/check-maps.mjs` passes. - `node --test .github/scripts/tests/*.test.mjs`: 808 pass, 0 fail. - `pnpm verify` was not run. This worktree has no installed dependencies, and the change has no runtime code. ## Risks - The deleted notes were not all read in full before deletion. The decision was by section: a section about one feature's tables, with no inbound link, was deleted. The text stays in git history. - Two deleted sections describe procedures for an operator: the duplicate-account check before the Better Auth 1.7.16 migration, and the secret storage tables. Restore them into a focused doc if operators still need them. - No runtime behavior changes. ## Model Used - Claude Fable 5.2 (`claude-fable-5-2`), Claude Code desktop, with tool use. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [ ] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
10 KiB
AGENTS.md
Guidance for human and AI contributors working in this repository.
This codebase is yours: what it's for and how it's built are your call, and you'll keep building on it. The invariants and rules below record what has been decided so far. If you think one of them is wrong, say so and propose the change; do not work around it.
1. Purpose
Paperclip is a control plane for AI-agent companies.
The code and its tests are the source of truth for current behavior.
The focused docs under doc/ are background. They can be out of date, so do not treat them as requirements when they disagree with the code or with the task.
2. Read This First
Read the doc that matches your change before you start:
| Your change touches | Read |
|---|---|
| Product behavior or scope | doc/GOAL.md, doc/PRODUCT.md |
| Setup, commands, testing, worktrees | doc/DEVELOPING.md |
| Schema, migrations, DB clients | doc/DATABASE.md |
| An Apps catalog connection | doc/connections/CONNECTOR-PLAYBOOK.md (the canonical connection authoring runbook) |
Anything under ui/ |
DESIGN.md |
Scoped repository rules
rules/*.mdc holds the architecture rules that reviewers apply to a pull
request. Each file starts with a short header: description is a one-sentence
summary of the rule, globs lists the files it covers, and alwaysApply: true
means it covers the whole repository.
You do not need to read the rule bodies before every change. List the headers to see which rules exist and what each one asks for:
grep -E '^(description|globs|alwaysApply):' rules/*.mdc
Write the change so that it satisfies the descriptions of the rules that cover your files. Read the full body of a rule only in these cases:
- You are making a design decision in the area the rule covers, such as adding a module, a background worker, or persisted state.
- The description does not tell you whether your change complies.
- A reviewer cites the rule.
These rules supplement this file and any applicable nested AGENTS.md
instructions. See rules/README.md for rule authoring and
Greptile setup.
3. Repo Map
server/: Express REST API and orchestration servicesui/: React + Vite board UIpackages/db/: Drizzle schema, migrations, DB clientspackages/shared/: shared types, constants, validators, API path constantspackages/adapters/: agent adapter implementations (Claude, Codex, Cursor, etc.)packages/adapter-utils/: shared adapter utilitiespackages/plugins/: plugin system packagespackages/skills-catalog/: app-shipped skills catalog (@paperclipai/skills-catalog)packages/teams-catalog/: app-shipped teams catalog (@paperclipai/teams-catalog)cli/:paperclipaiCLI package (published bin, agent-facing commands)skills/: Paperclip runtime/operational skills (not part of the app catalog)doc/: operational and product docsdoc/plans/: dated repo plan docs, namedYYYY-MM-DD-slug.md. A plan for a Paperclip issue goes in the issue'splandocument instead.rules/: scoped repository rules (see section 2)
4. Dev Setup
node scripts/agent-preflight.mjs # prepare a new or updated worktree
pnpm dev # API and UI at http://localhost:3100
Leave DATABASE_URL unset to use the embedded database. See "Agent worktree
preflight", "Start Dev", "Quick Health Checks", and "Database in Dev" in
doc/DEVELOPING.md.
5. Core Engineering Rules
-
Keep changes company-scoped. Every domain entity should be scoped to a company and company boundaries must be enforced in routes/services. The few instance-wide exceptions are listed in
rules/company-scope-exceptions.mdc. Do not add another without adding it to that list. -
Keep contracts synchronized. If you change schema/API behavior, update all impacted layers:
packages/dbschema and exportspackages/sharedtypes/constants/validatorsserverroutes/servicesuiAPI clients and pages
-
Preserve control-plane invariants.
- Single-assignee task model
- Atomic issue checkout semantics
- Approval gates for governed actions
- Budget hard-stop auto-pause behavior
- Activity logging for mutating actions
-
Keep behavior with its owning module. Provider protocols, payload parsing, and feature-specific sequencing belong to the module that owns them. Shared code uses narrow, normalized contracts. Explain any substantive change outside the owning module. See
rules/module-boundaries.mdc.
6. Database Changes
Follow "Schema change workflow" in doc/DATABASE.md: edit the schema, run
pnpm db:generate, then typecheck.
7. Verification Before Hand-off
Run the smallest check that proves the change. The default local and agent path is:
pnpm verify
This selects affected Vitest files with the same conservative dependency policy
as CI. It includes committed, staged, unstaged, and untracked changes against the
merge base with local origin/master (or master), and it reuses passing checks
whose inputs are unchanged. Use --base <ref> for another base, --explain to
inspect the selection, and --no-cache for fresh execution. See "Incremental
local verification" in doc/DEVELOPING.md for how reuse and invalidation work.
Follow these rules:
- Exit 2 means the change needs broader verification. Run focused checks and
let required CI supply that coverage, or explicitly use
pnpm verify --fullfor the full local Vitest suite. Do not automatically follow exit 2 with a full local run. - Do not default to repo-wide checks. Do not run repo-wide typecheck, build, or test on every heartbeat when a narrower check is enough to prove the change. Use the broad checks below only when they resolve an actual remaining gap, such as a local platform fault or explicit full-suite qualification.
- Browser suites stay opt-in. Run
pnpm test:e2eandpnpm test:release-smokeonly when your change touches them or when you are explicitly verifying CI/release flows. - CI covers the final revision. For a PR-ready handoff, run the relevant local checks and require the applicable CI typecheck, build, and test checks to pass for the final tested revision. Record their scope, revision, environment, and result links. Fresh CI can supply broad coverage; do not duplicate a full local run merely to prepare a PR, resume a chat, or repeat unchanged passing verification. A selected local pass does not replace required CI, release qualification, browser acceptance, or a local/platform-specific regression.
- Evidence expires. After edits or a rebase, rerun affected checks and invalidate evidence whose inputs or required coverage changed. Failed or interrupted attempts are never passes.
- Report gaps. If anything cannot be run, explicitly report what was not run and why.
- Attach deliverables. When you work a Paperclip issue and produce a file for
the user to inspect, attach it as the
paperclipskill anddoc/AGENT-ARTIFACTS.mddescribe. A local filesystem path is not enough.
Broad local checks:
pnpm -r typecheck
pnpm test:run
pnpm build
pnpm test and pnpm test:run run the full suite. If memory is limited, use
node scripts/typecheck-low-memory.mjs instead of pnpm -r typecheck. See
"Typecheck memory" in doc/test-infrastructure.md.
Maps and Storybook
The feature map and the sibling
agent access map are optional references for
user entry points, agent entry points, permission boundaries, verification
recipes, and coverage gaps. They record coverage scope, not proof that a live
journey passed. Routine fixes, polish, refactors, and test changes do not require
map updates. When you do edit a map, follow
the feature-map scope rule and
the map contract, then run node scripts/check-maps.mjs.
After story or recipe changes, update the affected source annotations or recipe
and run node scripts/storybook-catalog.mjs. Indexes are generated and ignored;
never commit them. See the Storybook feature catalog
for the full workflow. Structural checks are not production acceptance.
8. API and Auth
Every route under server/src/routes/ that reads or writes company data checks
company access and actor permissions, logs mutations to the activity log, and
returns consistent HTTP errors. See rules/api-route-expectations.mdc.
9. UI Expectations
- Keep routes and nav aligned with available API surface
- Use company selection context for company-scoped pages
- Surface failures clearly; do not silently ignore API errors
- Follow
DESIGN.mdfor every UI design decision, including the token-only rule and form footers.
10. Fixing a Bug
When you are asked to fix a bug, attempt to use test-driven development and prove the fix red-green:
- Reproduce the error yourself.
- Write a test that fails because of the bug.
- Write the fix.
- Run the test and confirm that it passes.
- Verify that the fix worked: repeat the reproduction from step 1 and confirm that the error is gone.
11. Pull Requests
Fill in every section of .github/PULL_REQUEST_TEMPLATE.md, however you create the pull request. Do not write an ad-hoc body. See "PR Requirements" in CONTRIBUTING.md for the details and thinking-path examples.
12. Definition of Done
A change is done when all are true:
- Behavior matches what the task asked for and preserves the invariants in section 5
- Relevant local verification and required CI typecheck, test, and build checks pass for the final revision, with any acceptance or platform-specific gaps resolved (section 7)
- Contracts are synced across db/shared/server/ui
- Docs updated when behavior or commands change.
doc/DEVELOPING.mdholds setup, commands, and everyday workflow only, anddoc/DATABASE.mdholds database setup and the rules for every schema change. Put a note about how a subsystem behaves in that subsystem's doc (see "More documentation" indoc/DEVELOPING.md), or leave it in the PR description when the code and tests already say it. - PR description follows the PR template with all sections filled in (including Model Used)