| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 1 | 19 | 0% |
| Commands | 0 | 0 | 13 | 0% |
| Section tags | 1 | 0 | 9 | 10% |
What each file covers
Sections
0 shared · 1 only in A · 19 only in B- − Execution Contract
- + AGENTS.md
- + 1. Purpose
- + 2. Read This First
- + 3. Repo Map
- + 4. Dev Setup (Auto DB)
- + 5. Core Engineering Rules
- + 6. Database Change Workflow
- + 7. Verification Before Hand-off
- + 8. API and Auth Expectations
- + 9. UI Expectations
- + 10. Pull Request Requirements
- + 11. Definition of Done
- + 11. Fork-Specific: HenkDz/paperclip
- + Branch Strategy
- + Hermes (built-in)
- + Local Dev
- + Fork QoL Patches (not in upstream)
- + Plugin System
- + Design system
Commands
0 shared · 0 only in A · 13 only in B- + pnpm install
- + pnpm dev
- + pnpm db:generate
- + pnpm -r typecheck
- + pnpm test
- + pnpm test:e2e
- + pnpm test:release-smoke
- + pnpm test:run
- + pnpm build
- + gh pr create
- + npx vite build
- + node node_modules/vite/bin/vite.js build
- + pnpm check:token-gates
Section tags
1 shared · 0 only in A · 9 only in B- + setup
- + test
- + code-style
- + git-pr
- + security
- + database
- + ui
- + do-not
- + agent-behaviour
- api
Line diff
paperclipai/paperclip · server/src/onboarding-assets/default/AGENTS.md
@@ −1 @@
1You are an agent at Paperclip company.
2
3## Execution Contract
4
5- Start actionable work in the same heartbeat. Do not stop at a plan unless the issue explicitly asks for planning.
6- Keep the work moving until it is done. If you need QA to review it, ask them. If you need your boss to review it, ask them.
7- Leave durable progress in task comments, documents, or work products, then update the issue to a clear final disposition before you exit.
8- When your work produces a user-inspectable deliverable file, follow the Paperclip skill's "Generated Artifacts and Work Products" workflow before final disposition. Use `skills/paperclip/scripts/paperclip-upload-artifact.sh` when working in this repo, create/update an artifact work product when the file is the deliverable, and link the uploaded attachment in the final comment. Do not rely on local filesystem paths as the only access path. If an important file intentionally remains workspace-only, create/update a work product with `metadata.resourceRef.kind: "workspace_file"` and a workspace-relative path, then name that work product and path in the final comment. Treat browse/search as a fallback for recovering workspace files, not the preferred deliverable path.
9- When your work produces or updates an operator-facing engineering output, create/update the matching work product: `pull_request` for opened PRs, `preview_url` for published previews, `runtime_service` for managed preview/dev services, `commit` for notable pushed commits, and `branch` when the branch itself is the handoff. A comment is not a substitute for the work product access path.
10- Comments, documents, screenshots, work products, and `Remaining` bullets are evidence, not valid liveness paths by themselves.
11- Final disposition checklist: mark `done` when complete and verified; use `in_review` only with a real reviewer, approval, interaction, or monitor path; use `blocked` only with first-class blockers or a named unblock owner/action; create delegated follow-up issues with blockers when another agent owns the next step; keep `in_progress` only when a live continuation path exists.
12- Use child issues for parallel or long delegated work instead of polling agents, sessions, or processes.
13- Create child issues directly when you know what needs to be done. If the board/user needs to choose suggested tasks, answer structured questions, or confirm a proposal first, create an issue-thread interaction on the current issue with `POST /api/issues/{issueId}/interactions` using `kind: "suggest_tasks"`, `kind: "ask_user_questions"`, or `kind: "request_confirmation"`.
14- Use `request_confirmation` instead of asking for yes/no decisions in markdown. For plan approval, update the `plan` document first, create a confirmation bound to the latest plan revision, use an idempotency key like `confirmation:{issueId}:plan:{revisionId}`, and wait for acceptance before creating implementation subtasks.
15- `ask_user_questions` and confirmations default `supersedeOnUserComment` to `true`, so a later board/user comment invalidates the pending request. Set it to `false` only when the request should stay open through discussion. If you wake up from a superseding comment, revise the artifact, question set, or proposal and create a fresh interaction if input is still needed.
16- If someone needs to unblock you, assign or route the ticket with a comment that names the unblock owner and action.
17- Respect budget, pause/cancel, approval gates, and company boundaries.
18
19Do not let work sit here. You must always update your task with a comment.
20
paperclipai/paperclip · AGENTS.md
@@ +1 @@
1# AGENTS.md
2
3Guidance for human and AI contributors working in this repository.
4
5## 1. Purpose
6
7Paperclip is a control plane for AI-agent companies.
8The current implementation target is V1 and is defined in `doc/SPEC-implementation.md`.
9
10## 2. Read This First
11
12Before making changes, read in this order:
13
141. `doc/GOAL.md`
152. `doc/PRODUCT.md`
163. `doc/SPEC-implementation.md`
174. `doc/DEVELOPING.md`
185. `doc/DATABASE.md`
19
20`doc/SPEC.md` is long-horizon product context.
21`doc/SPEC-implementation.md` is the concrete V1 build contract.
22
23## 3. Repo Map
24
25- `server/`: Express REST API and orchestration services
26- `ui/`: React + Vite board UI
27- `packages/db/`: Drizzle schema, migrations, DB clients
28- `packages/shared/`: shared types, constants, validators, API path constants
29- `packages/adapters/`: agent adapter implementations (Claude, Codex, Cursor, etc.)
30- `packages/adapter-utils/`: shared adapter utilities
31- `packages/plugins/`: plugin system packages
32- `doc/`: operational and product docs
33
34## 4. Dev Setup (Auto DB)
35
36Use embedded PGlite in dev by leaving `DATABASE_URL` unset.
37
38```sh
39pnpm install
40pnpm dev
41```
42
43This starts:
44
45- API: `http://localhost:3100`
46- UI: `http://localhost:3100` (served by API server in dev middleware mode)
47
48Quick checks:
49
50```sh
51curl http://localhost:3100/api/health
52curl http://localhost:3100/api/companies
53```
54
55Reset local dev DB:
56
57```sh
58rm -rf data/pglite
59pnpm dev
60```
61
62## 5. Core Engineering Rules
63
641. Keep changes company-scoped.
65Every domain entity should be scoped to a company and company boundaries must be enforced in routes/services.
66
672. Keep contracts synchronized.
68If you change schema/API behavior, update all impacted layers:
69- `packages/db` schema and exports
70- `packages/shared` types/constants/validators
71- `server` routes/services
72- `ui` API clients and pages
73
743. Preserve control-plane invariants.
75- Single-assignee task model
76- Atomic issue checkout semantics
77- Approval gates for governed actions
78- Budget hard-stop auto-pause behavior
79- Activity logging for mutating actions
80
814. Do not replace strategic docs wholesale unless asked.
82Prefer additive updates. Keep `doc/SPEC.md` and `doc/SPEC-implementation.md` aligned.
83
845. Keep repo plan docs dated and centralized.
85When you are creating a plan file in the repository itself, new plan documents belong in `doc/plans/` and should use `YYYY-MM-DD-slug.md` filenames. This does not replace Paperclip issue planning: if a Paperclip issue asks for a plan, update the issue `plan` document per the `paperclip` skill instead of creating a repo markdown file.
86
876. Attach inspectable generated artifacts.
88When your task produces a user-inspectable deliverable file, follow the Paperclip skill's "Generated Artifacts and Work Products" workflow before final disposition. In this repo, prefer the self-contained skill helper at `skills/paperclip/scripts/paperclip-upload-artifact.sh` so the file is available through the Paperclip API, create/update an artifact work product when the file is the deliverable, link the uploaded artifact in the final issue comment, and then set status. Do not rely on local filesystem paths as the only access path. If an important file intentionally remains workspace-only, create/update a work product with `metadata.resourceRef.kind: "workspace_file"` and a workspace-relative path, then name that work product and path in the final comment. Treat browse/search as a fallback for recovering workspace files, not the preferred deliverable path. See `doc/AGENT-ARTIFACTS.md` for details and `.mp4`/`.webm` examples.
89
90## 6. Database Change Workflow
91
92When changing data model:
93
941. Edit `packages/db/src/schema/*.ts`
952. Ensure new tables are exported from `packages/db/src/schema/index.ts`
963. Generate migration:
97
98```sh
99pnpm db:generate
100```
101
1024. Validate compile:
103
104```sh
105pnpm -r typecheck
106```
107
108Notes:
109- `packages/db/drizzle.config.ts` reads compiled schema from `dist/schema/*.js`
110- `pnpm db:generate` compiles `packages/db` first
111
112## 7. Verification Before Hand-off
113
114Default local/agent test path:
115
116```sh
117pnpm test
118```
119
120This is the cheap default and only runs the Vitest suite. Browser suites stay opt-in:
121
122```sh
123pnpm test:e2e
124pnpm test:release-smoke
125```
126
127Run the browser suites only when your change touches them or when you are explicitly verifying CI/release flows.
128
129For normal issue work, run the smallest relevant verification first. Do not default to repo-wide typecheck/build/test on every heartbeat when a narrower check is enough to prove the change.
130
131Run this full check before claiming repo work done in a PR-ready hand-off, or when the change scope is broad enough that targeted checks are not sufficient:
132
133```sh
134pnpm -r typecheck
135pnpm test:run
136pnpm build
137```
138
139If anything cannot be run, explicitly report what was not run and why.
140
141## 8. API and Auth Expectations
142
143- Base path: `/api`
144- Board access is treated as full-control operator context
145- Agent access uses bearer API keys (`agent_api_keys`), hashed at rest
146- Agent keys must not access other companies
147
148When adding endpoints:
149
150- apply company access checks
151- enforce actor permissions (board vs agent)
152- write activity log entries for mutations
153- return consistent HTTP errors (`400/401/403/404/409/422/500`)
154
155## 9. UI Expectations
156
157- Keep routes and nav aligned with available API surface
158- Use company selection context for company-scoped pages
159- Surface failures clearly; do not silently ignore API errors
160
161## 10. Pull Request Requirements
162
163When creating a pull request (via `gh pr create` or any other method), you **must** read and fill in every section of [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md). Do not craft ad-hoc PR bodies — use the template as the structure for your PR description. Required sections:
164
165- **Thinking Path** — trace reasoning from project context to this change (see `CONTRIBUTING.md` for examples)
166- **What Changed** — bullet list of concrete changes
167- **Verification** — how a reviewer can confirm it works
168- **Risks** — what could go wrong
169- **Model Used** — the AI model that produced or assisted with the change (provider, exact model ID, context window, capabilities). Write "None — human-authored" if no AI was used.
170- **Checklist** — all items checked
171
172## 11. Definition of Done
173
174A change is done when all are true:
175
1761. Behavior matches `doc/SPEC-implementation.md`
1772. Typecheck, tests, and build pass
1783. Contracts are synced across db/shared/server/ui
1794. Docs updated when behavior or commands change
1805. PR description follows the [PR template](.github/PULL_REQUEST_TEMPLATE.md) with all sections filled in (including Model Used)
181
182## 11. Fork-Specific: HenkDz/paperclip
183
184This is a fork of `paperclipai/paperclip` with QoL patches and a **built-in** Hermes adapter story on branch `feat/externalize-hermes-adapter` ([tree](https://github.com/HenkDz/paperclip/tree/feat/externalize-hermes-adapter)).
185
186### Branch Strategy
187
188- `feat/externalize-hermes-adapter` now ships `hermes_local` and `hermes_gateway` as built-in core adapters.
189- Older fork branches may still document plugin-only Hermes; treat this file as authoritative for the current branch.
190
191### Hermes (built-in)
192
193- `hermes_local` is available without Adapter manager installation and runs the local Hermes CLI.
194- `hermes_gateway` is available without Adapter manager installation and calls an already-running Hermes API server.
195- Operators may still install external Hermes packages through Adapter manager to override/shadow the built-ins.
196- Optional: `file:` entry in `~/.paperclip/adapter-plugins.json` remains useful for local development of override packages.
197
198### Local Dev
199
200- Fork runs on port 3101+ (auto-detects if 3100 is taken by upstream instance)
201- `npx vite build` hangs on NTFS — use `node node_modules/vite/bin/vite.js build` instead
202- Server startup from NTFS takes 30-60s — don't assume failure immediately
203- Kill ALL paperclip processes before starting: `pkill -f "paperclip"; pkill -f "tsx.*index.ts"`
204- Vite cache survives `rm -rf dist` — delete both: `rm -rf ui/dist ui/node_modules/.vite`
205
206### Fork QoL Patches (not in upstream)
207
208These are local modifications in the fork's UI. If re-copying source, these must be re-applied:
209
2101. **stderr_group** — amber accordion for MCP init noise in `RunTranscriptView.tsx`
2112. **tool_group** — accordion for consecutive non-terminal tools (write, read, search, browser)
2123. **Dashboard excerpt** — `LatestRunCard` strips markdown, shows first 3 lines/280 chars
213
214### Plugin System
215
216PR #2218 (`feat/external-adapter-phase1`) adds external adapter support. See root `AGENTS.md` for full details.
217
218- Adapters can be loaded as external plugins via `~/.paperclip/adapter-plugins.json`
219- The plugin-loader should have ZERO hardcoded adapter imports — pure dynamic loading
220- `createServerAdapter()` must include ALL optional fields (especially `detectModel`)
221- Built-in UI adapters can shadow external plugin parsers; external override pause/resume should restore the built-in parser.
222- Reference external adapters: Droid (npm); Hermes can also be tested as an override package.
223
224## Design system
225
226`DESIGN.md` at the repo root is the source of truth for UI design decisions. The token-only rule applies to all `ui/` changes: every color, spacing, radius, type, shadow, and motion value in `ui/src/components/**` and `ui/src/pages/**` comes from the token layer in `ui/src/index.css` — no hex, raw px, arbitrary Tailwind bracket values, or raw `font-size`/`fontSize` declarations in components, outside the documented allowlist in `ui/src/index.css`. Run `pnpm check:token-gates` (`scripts/check-token-gates.mjs`) before committing UI changes — it fails on any violation not covered by that allowlist.
227
@@ −1 +1 @@
1−You are an agent at Paperclip company.
1+# AGENTS.md
22
3−## Execution Contract
3+Guidance for human and AI contributors working in this repository.
44
5−- Start actionable work in the same heartbeat. Do not stop at a plan unless the issue explicitly asks for planning.
6−- Keep the work moving until it is done. If you need QA to review it, ask them. If you need your boss to review it, ask them.
7−- Leave durable progress in task comments, documents, or work products, then update the issue to a clear final disposition before you exit.
8−- When your work produces a user-inspectable deliverable file, follow the Paperclip skill's "Generated Artifacts and Work Products" workflow before final disposition. Use `skills/paperclip/scripts/paperclip-upload-artifact.sh` when working in this repo, create/update an artifact work product when the file is the deliverable, and link the uploaded attachment in the final comment. Do not rely on local filesystem paths as the only access path. If an important file intentionally remains workspace-only, create/update a work product with `metadata.resourceRef.kind: "workspace_file"` and a workspace-relative path, then name that work product and path in the final comment. Treat browse/search as a fallback for recovering workspace files, not the preferred deliverable path.
9−- When your work produces or updates an operator-facing engineering output, create/update the matching work product: `pull_request` for opened PRs, `preview_url` for published previews, `runtime_service` for managed preview/dev services, `commit` for notable pushed commits, and `branch` when the branch itself is the handoff. A comment is not a substitute for the work product access path.
10−- Comments, documents, screenshots, work products, and `Remaining` bullets are evidence, not valid liveness paths by themselves.
11−- Final disposition checklist: mark `done` when complete and verified; use `in_review` only with a real reviewer, approval, interaction, or monitor path; use `blocked` only with first-class blockers or a named unblock owner/action; create delegated follow-up issues with blockers when another agent owns the next step; keep `in_progress` only when a live continuation path exists.
12−- Use child issues for parallel or long delegated work instead of polling agents, sessions, or processes.
13−- Create child issues directly when you know what needs to be done. If the board/user needs to choose suggested tasks, answer structured questions, or confirm a proposal first, create an issue-thread interaction on the current issue with `POST /api/issues/{issueId}/interactions` using `kind: "suggest_tasks"`, `kind: "ask_user_questions"`, or `kind: "request_confirmation"`.
14−- Use `request_confirmation` instead of asking for yes/no decisions in markdown. For plan approval, update the `plan` document first, create a confirmation bound to the latest plan revision, use an idempotency key like `confirmation:{issueId}:plan:{revisionId}`, and wait for acceptance before creating implementation subtasks.
15−- `ask_user_questions` and confirmations default `supersedeOnUserComment` to `true`, so a later board/user comment invalidates the pending request. Set it to `false` only when the request should stay open through discussion. If you wake up from a superseding comment, revise the artifact, question set, or proposal and create a fresh interaction if input is still needed.
16−- If someone needs to unblock you, assign or route the ticket with a comment that names the unblock owner and action.
17−- Respect budget, pause/cancel, approval gates, and company boundaries.
5+## 1. Purpose
186
19−Do not let work sit here. You must always update your task with a comment.
7+Paperclip is a control plane for AI-agent companies.
8+The current implementation target is V1 and is defined in `doc/SPEC-implementation.md`.
9+
10+## 2. Read This First
11+
12+Before making changes, read in this order:
13+
14+1. `doc/GOAL.md`
15+2. `doc/PRODUCT.md`
16+3. `doc/SPEC-implementation.md`
17+4. `doc/DEVELOPING.md`
18+5. `doc/DATABASE.md`
19+
20+`doc/SPEC.md` is long-horizon product context.
21+`doc/SPEC-implementation.md` is the concrete V1 build contract.
22+
23+## 3. Repo Map
24+
25+- `server/`: Express REST API and orchestration services
26+- `ui/`: React + Vite board UI
27+- `packages/db/`: Drizzle schema, migrations, DB clients
28+- `packages/shared/`: shared types, constants, validators, API path constants
29+- `packages/adapters/`: agent adapter implementations (Claude, Codex, Cursor, etc.)
30+- `packages/adapter-utils/`: shared adapter utilities
31+- `packages/plugins/`: plugin system packages
32+- `doc/`: operational and product docs
33+
34+## 4. Dev Setup (Auto DB)
35+
36+Use embedded PGlite in dev by leaving `DATABASE_URL` unset.
37+
38+```sh
39+pnpm install
40+pnpm dev
41+```
42+
43+This starts:
44+
45+- API: `http://localhost:3100`
46+- UI: `http://localhost:3100` (served by API server in dev middleware mode)
47+
48+Quick checks:
49+
50+```sh
51+curl http://localhost:3100/api/health
52+curl http://localhost:3100/api/companies
53+```
54+
55+Reset local dev DB:
56+
57+```sh
58+rm -rf data/pglite
59+pnpm dev
60+```
61+
62+## 5. Core Engineering Rules
63+
64+1. Keep changes company-scoped.
65+Every domain entity should be scoped to a company and company boundaries must be enforced in routes/services.
66+
67+2. Keep contracts synchronized.
68+If you change schema/API behavior, update all impacted layers:
69+- `packages/db` schema and exports
70+- `packages/shared` types/constants/validators
71+- `server` routes/services
72+- `ui` API clients and pages
73+
74+3. Preserve control-plane invariants.
75+- Single-assignee task model
76+- Atomic issue checkout semantics
77+- Approval gates for governed actions
78+- Budget hard-stop auto-pause behavior
79+- Activity logging for mutating actions
80+
81+4. Do not replace strategic docs wholesale unless asked.
82+Prefer additive updates. Keep `doc/SPEC.md` and `doc/SPEC-implementation.md` aligned.
83+
84+5. Keep repo plan docs dated and centralized.
85+When you are creating a plan file in the repository itself, new plan documents belong in `doc/plans/` and should use `YYYY-MM-DD-slug.md` filenames. This does not replace Paperclip issue planning: if a Paperclip issue asks for a plan, update the issue `plan` document per the `paperclip` skill instead of creating a repo markdown file.
86+
87+6. Attach inspectable generated artifacts.
88+When your task produces a user-inspectable deliverable file, follow the Paperclip skill's "Generated Artifacts and Work Products" workflow before final disposition. In this repo, prefer the self-contained skill helper at `skills/paperclip/scripts/paperclip-upload-artifact.sh` so the file is available through the Paperclip API, create/update an artifact work product when the file is the deliverable, link the uploaded artifact in the final issue comment, and then set status. Do not rely on local filesystem paths as the only access path. If an important file intentionally remains workspace-only, create/update a work product with `metadata.resourceRef.kind: "workspace_file"` and a workspace-relative path, then name that work product and path in the final comment. Treat browse/search as a fallback for recovering workspace files, not the preferred deliverable path. See `doc/AGENT-ARTIFACTS.md` for details and `.mp4`/`.webm` examples.
89+
90+## 6. Database Change Workflow
91+
92+When changing data model:
93+
94+1. Edit `packages/db/src/schema/*.ts`
95+2. Ensure new tables are exported from `packages/db/src/schema/index.ts`
96+3. Generate migration:
97+
98+```sh
99+pnpm db:generate
100+```
101+
102+4. Validate compile:
103+
104+```sh
105+pnpm -r typecheck
106+```
107+
108+Notes:
109+- `packages/db/drizzle.config.ts` reads compiled schema from `dist/schema/*.js`
110+- `pnpm db:generate` compiles `packages/db` first
111+
112+## 7. Verification Before Hand-off
113+
114+Default local/agent test path:
115+
116+```sh
117+pnpm test
118+```
119+
120+This is the cheap default and only runs the Vitest suite. Browser suites stay opt-in:
121+
122+```sh
123+pnpm test:e2e
124+pnpm test:release-smoke
125+```
126+
127+Run the browser suites only when your change touches them or when you are explicitly verifying CI/release flows.
128+
129+For normal issue work, run the smallest relevant verification first. Do not default to repo-wide typecheck/build/test on every heartbeat when a narrower check is enough to prove the change.
130+
131+Run this full check before claiming repo work done in a PR-ready hand-off, or when the change scope is broad enough that targeted checks are not sufficient:
132+
133+```sh
134+pnpm -r typecheck
135+pnpm test:run
136+pnpm build
137+```
138+
139+If anything cannot be run, explicitly report what was not run and why.
140+
141+## 8. API and Auth Expectations
142+
143+- Base path: `/api`
144+- Board access is treated as full-control operator context
145+- Agent access uses bearer API keys (`agent_api_keys`), hashed at rest
146+- Agent keys must not access other companies
147+
148+When adding endpoints:
149+
150+- apply company access checks
151+- enforce actor permissions (board vs agent)
152+- write activity log entries for mutations
153+- return consistent HTTP errors (`400/401/403/404/409/422/500`)
154+
155+## 9. UI Expectations
156+
157+- Keep routes and nav aligned with available API surface
158+- Use company selection context for company-scoped pages
159+- Surface failures clearly; do not silently ignore API errors
160+
161+## 10. Pull Request Requirements
162+
163+When creating a pull request (via `gh pr create` or any other method), you **must** read and fill in every section of [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md). Do not craft ad-hoc PR bodies — use the template as the structure for your PR description. Required sections:
164+
165+- **Thinking Path** — trace reasoning from project context to this change (see `CONTRIBUTING.md` for examples)
166+- **What Changed** — bullet list of concrete changes
167+- **Verification** — how a reviewer can confirm it works
168+- **Risks** — what could go wrong
169+- **Model Used** — the AI model that produced or assisted with the change (provider, exact model ID, context window, capabilities). Write "None — human-authored" if no AI was used.
170+- **Checklist** — all items checked
171+
172+## 11. Definition of Done
173+
174+A change is done when all are true:
175+
176+1. Behavior matches `doc/SPEC-implementation.md`
177+2. Typecheck, tests, and build pass
178+3. Contracts are synced across db/shared/server/ui
179+4. Docs updated when behavior or commands change
180+5. PR description follows the [PR template](.github/PULL_REQUEST_TEMPLATE.md) with all sections filled in (including Model Used)
181+
182+## 11. Fork-Specific: HenkDz/paperclip
183+
184+This is a fork of `paperclipai/paperclip` with QoL patches and a **built-in** Hermes adapter story on branch `feat/externalize-hermes-adapter` ([tree](https://github.com/HenkDz/paperclip/tree/feat/externalize-hermes-adapter)).
185+
186+### Branch Strategy
187+
188+- `feat/externalize-hermes-adapter` now ships `hermes_local` and `hermes_gateway` as built-in core adapters.
189+- Older fork branches may still document plugin-only Hermes; treat this file as authoritative for the current branch.
190+
191+### Hermes (built-in)
192+
193+- `hermes_local` is available without Adapter manager installation and runs the local Hermes CLI.
194+- `hermes_gateway` is available without Adapter manager installation and calls an already-running Hermes API server.
195+- Operators may still install external Hermes packages through Adapter manager to override/shadow the built-ins.
196+- Optional: `file:` entry in `~/.paperclip/adapter-plugins.json` remains useful for local development of override packages.
197+
198+### Local Dev
199+
200+- Fork runs on port 3101+ (auto-detects if 3100 is taken by upstream instance)
201+- `npx vite build` hangs on NTFS — use `node node_modules/vite/bin/vite.js build` instead
202+- Server startup from NTFS takes 30-60s — don't assume failure immediately
203+- Kill ALL paperclip processes before starting: `pkill -f "paperclip"; pkill -f "tsx.*index.ts"`
204+- Vite cache survives `rm -rf dist` — delete both: `rm -rf ui/dist ui/node_modules/.vite`
205+
206+### Fork QoL Patches (not in upstream)
207+
208+These are local modifications in the fork's UI. If re-copying source, these must be re-applied:
209+
210+1. **stderr_group** — amber accordion for MCP init noise in `RunTranscriptView.tsx`
211+2. **tool_group** — accordion for consecutive non-terminal tools (write, read, search, browser)
212+3. **Dashboard excerpt** — `LatestRunCard` strips markdown, shows first 3 lines/280 chars
213+
214+### Plugin System
215+
216+PR #2218 (`feat/external-adapter-phase1`) adds external adapter support. See root `AGENTS.md` for full details.
217+
218+- Adapters can be loaded as external plugins via `~/.paperclip/adapter-plugins.json`
219+- The plugin-loader should have ZERO hardcoded adapter imports — pure dynamic loading
220+- `createServerAdapter()` must include ALL optional fields (especially `detectModel`)
221+- Built-in UI adapters can shadow external plugin parsers; external override pause/resume should restore the built-in parser.
222+- Reference external adapters: Droid (npm); Hermes can also be tested as an override package.
223+
224+## Design system
225+
226+`DESIGN.md` at the repo root is the source of truth for UI design decisions. The token-only rule applies to all `ui/` changes: every color, spacing, radius, type, shadow, and motion value in `ui/src/components/**` and `ui/src/pages/**` comes from the token layer in `ui/src/index.css` — no hex, raw px, arbitrary Tailwind bracket values, or raw `font-size`/`fontSize` declarations in components, outside the documented allowlist in `ui/src/index.css`. Run `pnpm check:token-gates` (`scripts/check-token-gates.mjs`) before committing UI changes — it fails on any violation not covered by that allowlist.
20227
