DottaandPaperclip
2ee36a4c0a
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agent Chat lets a person assign work through a conversation. > - Feature and API maps do not prove that a natural request produces the right saved result. > - Product E2E already owns isolated fixtures, browser runs, evidence and cleanup. > - This pull request adds a chat scenario catalog and two real task workflows in that framework. > - Independent checks verify the task, its author, the saved output and the reply in chat. > - The benefit is a small executable foundation for broader chat coverage. ## Linked Issues or Issue Description **What existing behavior does this improve?** It adds real task creation and delegation coverage for Agent Chat. **Current behavior** Existing maps describe features and agent access. Existing chat evals cover specific protocols and handoffs. They do not connect a broad human-request catalog to independent saved-state checks. **Proposed behavior** Keep 244 planned scenarios across 35 feature areas. Promote two requests into the explicit-only `chat-features` suite. One saves a backlog task without starting work. The other delegates an announcement and returns the saved result to the original chat. **Reason and benefit** A successful tool call or confident reply does not prove the requested result exists. These evals check public API state, attribution and browser access after a real model run. **Breaking changes** No API or data schema changes. Chat instructions now require actual relative task links. The local E2E private-state scanner recognizes Codex account ownership metadata while continuing to reject credentials and model-visible identity leaks. **Additional context** Related prior work: #13969 and #13762. This improves verification of the existing Agent Chat roadmap item. It does not add a new core product feature. ## What Changed - Add YAML scenarios with capability IDs, starting context, user requests and expected outcomes. Validate all area files against their schema, global ID uniqueness and exact feature-map capability coverage. - Add two local native Codex subscription cells. Send the exact catalog request once through Chromium. - Seed only prerequisites through public APIs. Use shipped agent instructions and explicit disposable budget policies for unpriced subscription usage. - Check task ownership, creation audit, no premature execution, current worker-authored output, automatic completion delivery and usable links after reload. - Keep private Codex account ownership metadata distinct from bearer credentials. Scan rollout message content, all tokens and published evidence as before. - Teach normal chat instructions to use relative task links instead of invented hosts. Update tests, maps and the runbook. - Repair existing E2E contract drift: include the active Copilot identity in the image digest and update Pi profile expectations. Keep global catalog cardinality in its owning catalog test. Product E2E owns the new flow and grader. Its existing launch and report paths remain in use. The shared scanner change is limited to owner-private temporary Codex runtime metadata. Other callers retain the full secret scan. No UI, endpoint, schema or permission behavior changes. ## Verification - `node scripts/check-maps.mjs` passed: 35 areas and 191 capability IDs. - Product E2E typecheck and focused tests passed before rebase: 225 Vitest tests and 137 Node tests. Conversation service tests passed 40/40. Five existing runner turn-binding regressions passed. - Historical live measurement used real Chromium, server, database and native Codex with no automatic retries. The initial same-definition batch passed 5/6 cells. Backlog passed 3/3; delegation passed 2/3. One CEO startup failed because the runner did not receive a provider turn identity. The cause is unresolved. - An unchanged follow-up passed delegation three times and backlog twice. Combined evidence is backlog 5/5 and delegation 5/6. Each attempt passed cleanup. Later passes do not erase the earlier failure or prove a runner repair. - Earlier failed revisions exposed an invented task hostname, private account metadata false positives and missing funding for unpriced subscription usage. Those led to the specific changes above; the failed records remain retained locally. - The runbook records campaign identifiers and definition provenance. Generated result artifacts are not committed. Historical live results predate this branch rebase; fresh PR-source live evidence and final validation are recorded below. - Full workspace typecheck and production build passed on the rebased branch. Product E2E typecheck passed. - The full Product E2E support suite first reproduced four baseline failures: two missing active Copilot image-identity inputs and two stale Pi/catalog expectations. The narrow contract fixes above resolved them. The full rerun passed 4,282 Vitest tests plus 137 Node tests, with two skipped. Image checks verify mutation changes the hash, unchanged input stays stable, and an input closure without Copilot is unaffected. Original failed logs remain retained. - The repo-wide local Vitest run has reported two failures in unchanged service files. The Workspace connection test passed an isolated recheck and its full file passed 469/469 unchanged. The recovery test hit a 15-second timeout; its full file passed 89/89 unchanged. The run later hit explicit PostgreSQL `semget` resource exhaustion and was interrupted after those observed failures; no final aggregate counts or full local pass are claimed. Its complete available log is retained. No assertion or timeout was weakened. Matching remote server CI passed on the same source. - On clean PR head `39ad80b523ce194c90aafafd077d48dd9a36b4c5`, backlog passed in `local-2026-10-26T19-24-13-014Z`. The parallel delegation fixture failed during PostgreSQL initdb, before browser or model execution; its failed cleanup grade is retained. A disposable standalone initdb probe then passed. No semaphore sets or kernel settings were changed before that probe/recheck. After confirming no remaining fixture process, its private temporary files were removed. - One separate delegation recheck passed in `local-2026-10-26T19-29-24-800Z`, with one attempt, zero automatic retries and successful cleanup. Both passing current-source cells use definition `3f2c9ba2d03e3dcddde47ddab3b43bc52de977f25e256fceae0a24c9128e204b`. The earlier bootstrap failure and the historical provider startup failure remain distinct. These local results omit automatic source-SHA metadata; the clean checkout SHA is recorded here from the execution session. - The later broad local run reported `could not create semaphores: No space left on device`. A bounded cleanup removed 32 current-user PostgreSQL sets with 17 members, marker 537, a dead recorded creator and zero waiters. No live process or kernel limit was changed by that cleanup. The test process group was subsequently stopped; no broad rerun is planned. This direct later resource failure does not prove the precise cause of the earlier live initdb failure. - Review follow-up adds only static catalog validation and documentation of the existing five-minute journey bound. The executable definition is unchanged. Focused catalog/oracle tests passed 28/28; no redundant live run is claimed. - Final head `30fcb36ac9ae1f0270a589dbfafcec91ca6a03f3` passed all required and underlying CI checks in [run 40391402347](https://github.com/paperclipai/paperclip/actions/runs/40391402347), including `ci / verify` and `ci / e2e`. Greptile and Paperclip Review both scored this head 5/5, with all review threads resolved. The static follow-up leaves every executable definition input byte-identical to the live-tested source at `39ad80b`. Normal squash auto-merge is enabled. Actual merge is pending eligible code-owner approval for the owned dependency manifest; no protection is bypassed. ## Risks - Live model behavior can vary. One missing turn-start event remains unexplained; this PR does not claim provider reliability or broad catalog qualification. - Subscription costs are unpriced. Explicit fixture funding admits that usage. Run counts and deadlines remain bounded, but the dollar limit cannot cap unknown cost. - Account identity exceptions apply only to known private Codex runtime files. Token reuse, unknown files and model-visible rollout content remain blocking findings. - Deterministic checks establish saved state, output structure, required brief facts and access. They do not score all prose quality. Initial samples also require human inspection. ## Model Used OpenAI Codex, GPT-6 family, with reasoning, code execution, browser and repository tools. The precise model revision and context window are not exposed to this session. Live eval agents used `gpt-5.6-sol`; that is the evaluated model, not a claim about the authoring model. ## 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 local tests; focused suites pass and the interrupted full-run failures are documented above - [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: Paperclip <noreply@paperclip.ing>
17 KiB
Paperclip feature map
Start here when reproducing a user-facing bug, verifying a change, or deciding which surfaces a fix must cover. Each recipe describes what a person can do, where they can do it, the expected result, and the evidence needed to verify it. Product behavior is still governed by the implementation spec.
The sibling agent access map records APIs, agent entry points and permission boundaries for the same capability IDs. Follow the shared map contract when maintaining either map.
The chat scenario catalog describes how people might request these capabilities in conversation, including setup and permission branches. These are planned Product E2E journeys, not live coverage results.
IDs and references
Use the existing IDs in issues, PRs, Storybook annotations, tests, and verification evidence:
| Reference | Example | Defined by |
|---|---|---|
| Feature ID | onboarding |
The recipe filename without .md. |
| Capability ID | onboarding/company |
The feature ID plus a key from its Sub-features list, separated by /. |
| Entry-point reference | onboarding.md#web-wizard | The recipe filename plus its entry-point heading. The local entry-point ID is web-wizard. |
For example, report verifying onboarding/company through web-wizard.
Capabilities describe behavior; entry points identify the surface used to exercise
it. Entry-point IDs are separate from generated capability IDs. Both maps and
Storybook use the same full capability IDs. Each child page states its feature
ID; recipe bullets show the full capability ID beside the local key, and access
companions show it beneath the local heading. Local keys remain unchanged for
parsing and existing anchors.
Keep recipe filenames, sub-feature keys, and entry-point keys stable when changing display titles or navigation. Renaming a filename or key changes its references. The section headings below are navigation labels, not additional IDs.
Browse features
Use this index to open a recipe or copy its feature and full capability IDs.
Getting started and access
| Feature ID | Recipe | Capability IDs |
|---|---|---|
onboarding |
Onboarding and first work | onboarding/instance, onboarding/company, onboarding/adapter, onboarding/first-task, onboarding/resume |
access |
Login, invitations, and access | access/login, access/invitations, access/membership, access/resources, access/cli-auth |
companies |
Companies and portability | companies/selection, companies/identity, companies/decision-models, companies/prompt-injection-prevention, companies/fast-responses, companies/agent-observability, companies/archive, companies/portability |
Tasks and conversations
| Feature ID | Recipe | Capability IDs |
|---|---|---|
tasks |
Task creation and lifecycle | tasks/create, tasks/organize, tasks/properties, tasks/discussion, tasks/completion, tasks/privacy |
task-coordination |
Delegation, dependencies, and signoff | task-coordination/delegation, task-coordination/dependencies, task-coordination/signoff, task-coordination/tree-control |
inbox-search |
Inbox, decisions, and search | inbox-search/views, inbox-search/triage, inbox-search/decisions, inbox-search/search, inbox-search/toasts |
agent-chat |
Agent conversations and project handoff | agent-chat/discovery, agent-chat/history, agent-chat/handoff, agent-chat/conference-room |
questions-and-approvals |
Questions and approvals | questions-and-approvals/questions, questions-and-approvals/dismiss-and-reopen, questions-and-approvals/confirmations, questions-and-approvals/plan-review, questions-and-approvals/audience, questions-and-approvals/governance, questions-and-approvals/tool-review, questions-and-approvals/continuation |
steering |
Steering and queued messages | steering/queue, steering/edit-order-discard, steering/steer, steering/interrupt, steering/stop-and-pause, steering/drafts, steering/approval-queue |
documents-artifacts |
Documents, attachments, and work products | documents-artifacts/documents, documents-artifacts/annotations, documents-artifacts/attachments, documents-artifacts/work-products, documents-artifacts/library |
Agents and reusable capabilities
| Feature ID | Recipe | Capability IDs |
|---|---|---|
agents |
Hiring, configuration, and organization | agents/hire, agents/grok-bot, agents/instructions, agents/organization, agents/primary-agent, agents/lifecycle, agents/built-in, agents/api-keys, agents/managed-agent-setup |
runs-adapters |
Runs, harnesses, and model accounts | runs-adapters/availability, runs-adapters/validation, runs-adapters/runs, runs-adapters/session |
skills |
Skills and Skill Studio | skills/discovery, skills/authoring, skills/versions, skills/policy, skills/testing |
teams |
Team packages and installation | teams/discovery, teams/preview, teams/install, teams/configuration |
Projects and execution
| Feature ID | Recipe | Capability IDs |
|---|---|---|
projects |
Projects and repositories | projects/lifecycle, projects/task-context, projects/repositories, projects/defaults, projects/privacy |
goals |
Goals and work alignment | goals/hierarchy, goals/alignment, goals/navigation |
workspaces |
Workspaces, services, and files | workspaces/binding, workspaces/provisioning, workspaces/services, workspaces/files-git, workspaces/closure |
execution-environments |
Execution environments | execution-environments/configuration, execution-environments/capabilities, execution-environments/probe, execution-environments/assignment, execution-environments/images |
recovery |
Recovery | recovery/diagnosis, recovery/bounded-continuation, recovery/source-action, recovery/exhaustion, recovery/workspace, recovery/unknown-outcome, recovery/user-continuation, recovery/reconnect |
Apps, channels, and extensions
| Feature ID | Recipe | Capability IDs |
|---|---|---|
connection-setup |
Connection setup | connection-setup/catalog, connection-setup/identity-and-access, connection-setup/credentials, connection-setup/handoff, connection-setup/draft-recovery, connection-setup/task-request, connection-setup/channel-setup, connection-setup/failure |
assistant-connections |
Assistant connections (MCP) | assistant-connections/setup, assistant-connections/consent, assistant-connections/device-login, assistant-connections/client-use, assistant-connections/revocation |
app-permissions |
App access and action permissions | app-permissions/agent-access, app-permissions/action-policy, app-permissions/catalog-change, app-permissions/test-action, app-permissions/account-maintenance |
chat-channels |
External chat and email | chat-channels/providers, chat-channels/identity, chat-channels/conversation, chat-channels/attachments, chat-channels/lifecycle, chat-channels/outbound-email |
gateways-profiles |
Tool gateways and access profiles | gateways-profiles/gateway, gateways-profiles/profiles, gateways-profiles/client-connect, gateways-profiles/tokens, gateways-profiles/activity |
secrets |
Secrets and proposals | secrets/company-secrets, secrets/user-secrets, secrets/proposals, secrets/vault-import, secrets/runtime-delivery |
plugins |
Plugins | plugins/installation, plugins/configuration, plugins/contributions, plugins/lifecycle |
Automation and structured work
| Feature ID | Recipe | Capability IDs |
|---|---|---|
routines |
Routines, schedules, and triggers | routines/definition, routines/triggers, routines/run-now, routines/history, routines/management |
cases |
Cases | cases/browse, cases/structure, cases/history, cases/task-links, cases/handoffs |
status-cards |
Status cards | status-cards/authoring, status-cards/generation, status-cards/inspection, status-cards/archive |
Oversight and operation
| Feature ID | Recipe | Capability IDs |
|---|---|---|
budgets-costs |
Costs and budgets | budgets-costs/cost-reporting, budgets-costs/budgets, budgets-costs/incidents, budgets-costs/resolution, budgets-costs/subscriptions, budgets-costs/accounting-recovery |
activity |
Dashboards and audit trails | activity/overview, activity/activity, activity/runs, activity/routine-audit, activity/timeline, activity/agent-commentary |
navigation-preferences |
Navigation, profile, and announcements | navigation-preferences/navigation, navigation-preferences/preferences, navigation-preferences/profile, navigation-preferences/announcements, navigation-preferences/fallbacks, navigation-preferences/command-palette |
instance-operations |
Instance operations | instance-operations/install-update, instance-operations/server-service, instance-operations/configuration, instance-operations/diagnostics, instance-operations/backup, instance-operations/runtime-setup |
cli-operations |
CLI/API and local worktrees | cli-operations/context, cli-operations/domain-commands, cli-operations/outputs, cli-operations/run-controls, cli-operations/worktree-instances, cli-operations/feedback-export |
Contributor surfaces
| Feature ID | Recipe | Capability IDs |
|---|---|---|
developer-labs |
Developer previews and diagnostic labs | developer-labs/design, developer-labs/interaction-labs, developer-labs/performance, developer-labs/route-gates |
Open the published Storybook guide for the assembled feature and capability index. The Markdown recipes in this directory are the authored source. Each has a same-named agent-access companion.
Run node scripts/storybook-catalog.mjs to generate local navigation in
maps/generated/feature-map.md, maps/generated/agent-access-map.md, and the
Storybook guide. Recipes are discovered automatically from their navigation
metadata; generation does not depend on this high-level index.
Before driving a journey
- Use this checkout's isolated test drive for manual product checks. It creates a temporary instance and prints its URL and data directory. Do not guess that a server on port 3100 belongs to you.
- Record the commit, URL, company, login role, relevant experimental settings, adapter, runtime mode, and live versus simulated dependencies. Use disposable tasks and provider resources. A fresh test drive creates a company and CEO, but no task or first run.
- Use the current navigation and company prefix. Paths in recipes omit that prefix. Record whether the streamlined or production shell is selected; Agent Chat, chat connectors, and the combined Inbox/Tasks view have separate gates. A hidden surface is an unmet prerequisite, not a successful test.
- Run the smallest relevant test first. Vitest commands below run from the repository root after installing dependencies. Playwright recipes use their named configuration and its isolated environment, not an unrelated running instance. Reserve expensive runner/provider tests for the behavior at issue.
- Exercise the actual user action, inspect its result, reload, and verify the persisted state or continuation. Use read-only API checks to corroborate UI evidence; creating state through the API does not prove the creation UI.
For agent-driven acceptance work, start with the Paperclip verification skill for an isolated launch, ownership/readiness checks, browser driving, evidence, and cleanup. It uses this directory as its feature map. The existing dev-workspace run/verify skill and evaluation skill describe runtime ownership and evidence handling. Reuse them; this map introduces no environment launcher, credentials, scheduled job, or second test framework.
Evidence contract
Report each entry point as passed, failed, blocked (with its missing
prerequisite), or not run. Include the feature ID, full capability IDs and
entry-point ID (for example, onboarding/company through web-wizard), plus the
recipe link, commit/environment, user action, expected and observed result,
command/exit code, and evidence links. Screenshots or traces should show both the
action and the discriminating result. Include task/run/request IDs when relevant,
without secrets.
A fix is verified across its affected surfaces only when each has evidence or an explicit reason it does not apply. Shared code alone does not prove parity. Keep product regressions visible; do not change the recipe to bless a failure. For Paperclip-assigned work, attach evidence through the artifact workflow.
Inventory and remaining depth
The generated maps/generated/coverage.json lists the current non-test TSX page
modules and the recipes that directly reference each one. An unreferenced module
is a documentation candidate, not proof that its feature is absent or untested.
Remaining workflow limits live in each recipe. Inventory and example associations
describe documentation scope, not runtime health.
Maintaining the reference
The map documents user journeys. It does not execute them automatically; generated inventories record documentation scope rather than live test health. Product E2E reports reuse these capability IDs through the journey associations. Their coverage view shows which scenarios in a campaign are linked to each capability and the associated test results. An association or passing scenario does not certify the whole capability; unselected and unmapped journeys remain distinct.
When maintaining a recipe, compare its entry points and expected results with
the current source. Check that linked tests still exercise the stated behavior
and that local references still exist. Keep the same-named agent access companion
and stable sub-feature IDs aligned when behavior or access changes. Source-only
access inventory remains distinct from live verification. Run
node scripts/check-maps.mjs after map edits for structural/reference checks;
follow the shared contract for the source and behavioral checks it cannot perform.
Each recipe starts with a small frontmatter navigation record, then an H1:
---
navigation: {"section":"Tasks and conversations","sectionOrder":20,"order":10}
---
The H1 supplies the feature title, and the first paragraph supplies its summary. Orders are local to the section; leave gaps for additions. Equal orders use the stable filename as a tie-breaker. Keep a section's name/order consistent across its recipes. Discovery uses the recipe and companion; keep the readable ID index above aligned when features or capability IDs change.
Optional ### Storybook verification guidance lives inside the recipe's Gotchas
section. Each level-four heading contains a backtick-quoted capability key and
has Scope (ui, cli, or browser),
Storybook, Production, and Sources fields. These are verification instructions
and intentional scope limits, not run results or a required story for every API.
The generated gap report combines this guidance with current story associations.
After frontmatter, each recipe starts with an H1 and a user-visible description, then exactly:
- Sub-features — stable backticked local keys, full capability IDs, and observable behavior/states,
such as
- `company`: `onboarding/company` — create a company. - How to get to it (user POV) — one H3 backticked entry-point ID per surface.
- Driving it with — starts with
Preconditions:; repeat each entry-point H3, withAutomated:andManual:paragraphs. Name test scope and gaps honestly. - Gotchas — misleading look-alikes, feature gates, and invalid evidence.
New or updated entries follow
Poteto's feature-map examples.
Existing entries with a Driving it heading can adopt the named harness when
their recipes are updated. The original format was inspired by
Omnigent's feature map.
Paperclip's recipes and checks follow its own task model and test infrastructure.