mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-06 19:35:04 +02:00
7e40ed8c43
## Thinking Path > - Paperclip is the open source control plane people use to manage AI-agent companies. > - Operators need a board-level way to monitor a changing slice of company work without repeatedly rebuilding filters or reading raw task threads. > - Existing summaries are useful snapshots, but they do not provide a dedicated query-backed card with refresh policy, change tracking, update history, and per-update cost visibility. > - The capability needs to be safe to evaluate before it becomes part of the default product surface. > - This pull request adds end-to-end experimental Status Cards, from schema and query compilation through update orchestration and operator UI. > - The entire feature is gated behind the `enableStatusCards` experimental toggle, including its route and sidebar entry. > - The benefit is a governed, inspectable way to keep focused operational rollups current while preserving explicit controls over refresh frequency and spend. ## Linked Issues or Issue Description ### Subsystem affected Cross-cutting (`packages/db`, `packages/shared`, `server/`, `ui/`, and bundled skills/docs). ### Problem or motivation Operators cannot currently define a reusable natural-language view of company work, compile it into an inspectable query, and keep its summary current as matching issues change. Rebuilding filters and rereading task threads makes board-level monitoring repetitive and hides the relationship between source changes, refresh cost, and the resulting summary. ### Proposed solution Add experimental Status Cards that compile operator intent into a query, summarize matched work, record each update, expose manual/interval/reactive refresh policies and costs, and preserve the last good result across stale, updating, paused, and error states. The capability is off by default and fully gated behind `enableStatusCards`, including its route and navigation entry. ### Alternatives considered - Extend existing one-off summaries: rejected because status cards require persistent query provenance, refresh policy, update history, and card-specific cost controls. - Add a dashboard-only filter widget: rejected because it would not provide governed background refresh, an update ledger, or an inspectable compile pipeline. - Ship the surface by default: rejected in favor of an experimental toggle while behavior and operator value are evaluated. ### Roadmap alignment This advances Paperclip’s board-level execution visibility and output-first product goals. `ROADMAP.md` was checked and no duplicate status-card initiative was found. ### Additional context No related open PR was found in the public GitHub search for status cards. The PR-only design wireframes were removed from the repository after review; the published prototype remains external to the production source tree. ## What Changed - Added company-scoped status-card schema, CRUD APIs, compile provenance, update ledger, shared contracts, validators, and OpenAPI coverage. - Added the text-to-query compile pipeline, bundled `status-card-query` agent skill, query versioning, and authorized write-back flow. - Added the experimental board, create flow, lifecycle tiles, detail/settings/debug drawers, archived view, routing, navigation, and instance setting. - Added a change-gated update engine with manual, interval, and reactive refresh policies, trigger selection, active hours, and daily token caps. - Added per-update token/cost recording, today and lifetime rollups, and policy-derived cost previews. - Added operator documentation and agent-authoring hardening for compile and update behavior. - Added PR-prep integration coverage for settings/startup wiring and replaced raw UI values with design-system tokens. - Removed the PR-only `design/pap-15023-status-cards` wireframe artifacts so the repository contains only production feature assets. ## Verification - `pnpm -r typecheck` — passes on the PR head; includes `ui` `tsc -b` passing. The UI compile gate was also independently recorded as passing at `6d7f3cf96b` on July 23, 2026. - `pnpm build` — passes. - `pnpm check:token-gates` — passes with all three gates clean. - `pnpm test:run` — 2,880 tests passed and 1 skipped; the sole failure was an unrelated 10-second `afterAll` database-cleanup timeout in `execution-workspaces-service.test.ts`. - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/execution-workspaces-service.test.ts` — passes on immediate focused rerun (25/25). - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/instance-settings-service.test.ts src/__tests__/server-startup-feedback-export.test.ts` — passes (31/31). - `pnpm --filter @paperclipai/ui exec vitest run src/pages/StatusCards/StatusCardSettingsForm.test.tsx src/pages/StatusCards/StatusCardTile.test.tsx src/pages/StatusCards/format.test.ts src/lib/status-card-state.test.ts` — passes (26/26). - Recorded pre-PR QA: compile-pipeline e2e PASS; full lifecycle and cost QA PASS; security re-review PASS after write-back hardening; UX approved. - `pnpm exec vitest run packages/db/src/status-card-migrations.test.ts` — passes; reapplies migrations `0185`–`0189` against an already-migrated embedded Postgres database. - `pnpm --filter /db check:migrations` — passes migration numbering and safety checks. - `pnpm --filter /db typecheck` — passes. - Merged current `origin/master` on July 24, 2026 with no conflicts; migrations `0185`–`0189` remain unclaimed on master. ## Risks - The feature introduces five database migrations and a new background update path; all new DDL is repeat-safe after partial application, migration numbering/safety checks pass, and update execution is company-scoped and change-gated. - Natural-language compilation can produce invalid or overly broad queries; compile provenance, query validation, debug visibility, and version history make failures inspectable and recoverable. - Reactive or interval refresh could increase spend; active hours, max refresh frequency, daily token caps, per-update cost records, and budget-paused states bound and expose that risk. - The branch name contains an internal execution identifier because it is a fixed handoff branch; it was intentionally not renamed or rebased per the release handoff instructions. - Overall rollout risk is limited because the route, navigation, services, and UI are disabled by default behind `enableStatusCards`. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex using GPT-5.5 with reasoning, repository tool use, shell execution, GitHub CLI, and test/build execution. The runtime did not expose a context-window size. ## 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; the fixed execution-workspace identifier is documented as an authorized handoff exception - [x] I have run tests locally and they pass, with the one cleanup timeout passing on focused rerun - [x] 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 - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: Paperclip <noreply@paperclip.ing>
153 lines
4.2 KiB
JSON
153 lines
4.2 KiB
JSON
{
|
|
"$schema": "https://mintlify.com/docs.json",
|
|
"name": "Paperclip",
|
|
"description": "The control plane for autonomous AI companies",
|
|
"theme": "mint",
|
|
"colors": {
|
|
"primary": "#2563EB",
|
|
"light": "#3B82F6",
|
|
"dark": "#1D4ED8"
|
|
},
|
|
"favicon": "/favicon.svg",
|
|
"logo": {
|
|
"dark": "/images/logo-dark.svg",
|
|
"light": "/images/logo-light.svg"
|
|
},
|
|
"topbarLinks": [
|
|
{
|
|
"name": "GitHub",
|
|
"url": "https://github.com/paperclip-ai/paperclip"
|
|
}
|
|
],
|
|
"navigation": {
|
|
"tabs": [
|
|
{
|
|
"tab": "Get Started",
|
|
"groups": [
|
|
{
|
|
"group": "Introduction",
|
|
"pages": [
|
|
"start/what-is-paperclip",
|
|
"start/quickstart",
|
|
"start/core-concepts",
|
|
"start/architecture"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"tab": "Guides",
|
|
"groups": [
|
|
{
|
|
"group": "Board Operator",
|
|
"pages": [
|
|
"guides/board-operator/dashboard",
|
|
"guides/board-operator/creating-a-company",
|
|
"guides/board-operator/managing-agents",
|
|
"guides/board-operator/org-structure",
|
|
"guides/board-operator/managing-tasks",
|
|
"guides/board-operator/execution-workspaces-and-runtime-services",
|
|
"guides/board-operator/delegation",
|
|
"guides/board-operator/execution-workspaces-and-runtime-services",
|
|
"guides/board-operator/delegation",
|
|
"guides/board-operator/experimental-features",
|
|
"guides/board-operator/status-cards",
|
|
"guides/board-operator/approvals",
|
|
"guides/board-operator/costs-and-budgets",
|
|
"guides/board-operator/activity-log",
|
|
"guides/board-operator/importing-and-exporting"
|
|
]
|
|
},
|
|
{
|
|
"group": "Agent Developer",
|
|
"pages": [
|
|
"guides/agent-developer/how-agents-work",
|
|
"guides/agent-developer/heartbeat-protocol",
|
|
"guides/agent-developer/writing-a-skill",
|
|
"guides/agent-developer/skills-store",
|
|
"guides/agent-developer/task-workflow",
|
|
"guides/agent-developer/comments-and-communication",
|
|
"guides/agent-developer/handling-approvals",
|
|
"guides/agent-developer/cost-reporting"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"tab": "Deploy",
|
|
"groups": [
|
|
{
|
|
"group": "Deployment",
|
|
"pages": [
|
|
"deploy/overview",
|
|
"deploy/local-development",
|
|
"deploy/tailscale-private-access",
|
|
"deploy/docker",
|
|
"deploy/deployment-modes",
|
|
"deploy/database",
|
|
"deploy/secrets",
|
|
"deploy/storage",
|
|
"deploy/environment-variables"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"tab": "Adapters",
|
|
"groups": [
|
|
{
|
|
"group": "Agent Adapters",
|
|
"pages": [
|
|
"adapters/overview",
|
|
"adapters/claude-local",
|
|
"adapters/codex-local",
|
|
"adapters/process",
|
|
"adapters/http",
|
|
"adapters/external-adapters",
|
|
"adapters/adapter-ui-parser",
|
|
"adapters/creating-an-adapter"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"tab": "API Reference",
|
|
"groups": [
|
|
{
|
|
"group": "REST API",
|
|
"pages": [
|
|
"api/overview",
|
|
"api/authentication",
|
|
"api/companies",
|
|
"api/agents",
|
|
"api/issues",
|
|
"api/approvals",
|
|
"api/goals-and-projects",
|
|
"api/costs",
|
|
"api/secrets",
|
|
"api/activity",
|
|
"api/dashboard"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"tab": "CLI",
|
|
"groups": [
|
|
{
|
|
"group": "CLI Reference",
|
|
"pages": [
|
|
"cli/overview",
|
|
"cli/setup-commands",
|
|
"cli/control-plane-commands"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
},
|
|
"footerSocials": {
|
|
"github": "https://github.com/paperclip-ai/paperclip"
|
|
}
|
|
}
|