DottaandPaperclip
3bbc2104b6
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The feature map records product entry points and verification recipes. > - The paired agent access map records APIs and permission boundaries for the same capability IDs. > - The new index in #16987 made several missing capabilities easier to find. > - Those gaps hid existing assistant, privacy, cost, and operator workflows. > - This pull request adds 15 capabilities with source references, test scope, and manual checks. > - Readers can find these workflows without treating documentation or structural checks as live proof. ## Linked Issues or Issue Description Refs: #16987. Related map work: #16025 and #16214. A search of related pull requests found no duplicate of these additions. **Issue type** Missing documentation. **Where is the issue?** `maps/feature-map/` and `maps/agent-access-map/`. **What's wrong?** The maps omit public assistant MCP connections, private task and project sharing, subscription fees, cost-recording recovery, agent API keys, keyboard entry points, and several operator CLI workflows. **Suggested fix** Add product recipes and matching access records. Show the full capability IDs in the README index and each page. Keep the existing ID format and all 175 existing IDs. Exclude AI account pools. ## What Changed - Add the `assistant-connections` family with setup, consent, device login, client use, and revocation. - Add `tasks/privacy`, `projects/privacy`, `budgets-costs/subscriptions`, and `budgets-costs/accounting-recovery`. - Add `agents/api-keys`, `agents/managed-agent-setup`, and `navigation-preferences/command-palette`. - Add `cli-operations/feedback-export`, `chat-channels/outbound-email`, and `instance-operations/runtime-setup`. - Pair all 15 additions with access rules, source evidence, manual checks, and explicit coverage gaps. Update the visible index to 35 families and 190 capability IDs. - Add cross-links from existing access, connection setup, search, and CLI recipes. Do not change the schema or add AI account pools. - Clarify that the task Share sheet displays direct and inherited access. Manage inherited access at its ancestor or project source. ## Verification - `node scripts/check-maps.mjs` passes: 35 areas and 190 paired capability IDs, with valid references and contract fields. - `node --test scripts/check-maps.test.mjs scripts/storybook-feature-index.test.mjs` passes: 17 tests. - `node scripts/storybook-feature-index.mjs` and `git diff --check` pass. - A comparison with the base confirms all 175 existing IDs remain and exactly the intended 15 IDs were added. The README index matches the discovered feature metadata. - `node scripts/storybook-catalog.mjs` cannot run because this checkout lacks `storybook/internal/csf-tools` and installed workspace dependencies. - `pnpm -r typecheck`, `pnpm test:run`, and `pnpm build` were attempted. All stopped before their task ran: the pnpm 9.15.4 bootstrap could not fetch and verify its registry packages in this environment. - Source review covers the documented UI, CLI, routes, services, and existing tests. No live browser, provider, or authorization journey was run. New access records remain `baseline`, `source-only`, and `not-run`. - Greptile and the Paperclip reviewer both rate current commit `bb8eb797b0a1dc26256faf2f0e57cbe7abc9adcf` 5/5. The inherited-access review thread is resolved. - [GitHub CI](https://github.com/paperclipai/paperclip/actions/runs/39466772379) passes for that commit, including typecheck, build, unit tests, Runner checks, and browser tests. Browser shard 7 passed after one retry for a runner shutdown. All PR checks are successful, neutral, or skipped. ## Risks - Low runtime risk: this change only edits maps. No application behavior, API, dependency, or schema changes. - Source-reviewed recipes can drift or miss deployment-specific behavior. The records state their limits and require live checks before a capability is marked verified. > 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, model ID `gpt-6.1-sol`, 475,000-token context window, xhigh reasoning effort, with tool use and code execution. ## 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 - [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>
9.3 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
CLI/API and local worktrees
Operators and agents can work through explicit CLI/API context, manage domain resources, inspect runs, and create isolated local worktree instances for development.
Feature ID: cli-operations.
Implementation: command registry, client context, worktree commands.
Agent access: companion.
Sub-features
context:cli-operations/context— choose instance/API base, profile, identity, and company explicitly.domain-commands:cli-operations/domain-commands— read/write tasks, agents, projects, goals, approvals, routines, and other registered resources.outputs:cli-operations/outputs— work with documents/assets/skills and inspect machine-readable results.run-controls:cli-operations/run-controls— invoke/inspect supported runs and observe actual outcomes.worktree-instances:cli-operations/worktree-instances— initialize, seed, diagnose, and clean up only an owned development instance.feedback-export:cli-operations/feedback-export— inspect feedback votes and traces, then export a local report bundle without changing remote sharing state.
How to get to it (user POV)
client-context
Use paperclipai context show/list/use/set, auth/connect, and the registered resource command help.
subresources-and-runs
Use issue subresource, asset/skill, and run/heartbeat commands exposed by the CLI help.
worktree-instance
Use the documented worktree/test-drive commands in an owned checkout; inspect paperclipai worktree --help first.
Inspect root help too: worktree:make/list/merge-history/cleanup are top-level
commands rather than subcommands of worktree.
feedback-report-export
Use paperclipai feedback report --company-id <company-id> --json, feedback trace <trace-id> --json, or feedback bundle <trace-id> --json. Export with paperclipai feedback export --company-id <company-id> --out <empty-owned-directory> --json. Select the intended board context/profile and use report/export filters such as --vote, --status, --issue-id, --project-id, --from, --to, or --shared-only.
Driving it with the Paperclip CLI
Preconditions: follow the baseline. Use --help from the checked-out CLI to discover exact arguments. Select a disposable company and isolated context; do not inherit an unknown API target.
Pass the server origin to --api-base (without appending /api); the commands
already include the API path. issue create requires explicit --company-id
even when a profile stores a company. A persona label is not authentication proof.
client-context
Automated: context, HTTP client, and operations parity cover client contracts, not every live endpoint.
Manual: Inspect the selected context and identity, list the disposable company’s resources, create a harmless task through the supported command, and verify it in the browser. Exercise an invalid token and wrong-company resource. Inspect JSON output and nonzero errors rather than only printed success text.
subresources-and-runs
Automated: issue subresources and asset/skill parity cover command/API contracts.
Manual: Write a small task document or attach a fixture using the supported command, open it in the UI, and compare contents. Invoke eligible test work, inspect the resulting run ID/status/output, and verify denial when the actor lacks permission.
worktree-instance
Automated: worktree commands and test drive cover isolation/setup contracts.
Manual: Initialize an owned disposable worktree instance, inspect its printed paths and ports, verify health and login, and confirm any seed data belongs to the intended source. Stop and clean up only that instance; inspect preserved work before deleting any checkout.
feedback-report-export
Automated: CLI feedback tests filters, report, and archive construction. Feedback routes, service, and redaction cover board/company authorization and payload handling. They do not prove every trace format in a live export.
Manual: Use a disposable company with distinguishable up/down feedback and an empty owned output directory. Compare filtered report counts and trace IDs with individual trace/bundle reads. Export and inspect index.json, votes/, traces/, full-traces/, and the resulting ZIP; compare IDs and retained/redacted content with the requested filters. Repeat with another company or inaccessible trace and with an agent bearer. Inspect file contents and exit codes, and verify that report/export did not upload files or change any feedback-sharing state.
Sources: Feedback CLI, company trace list, trace detail/bundle routes, and feedback service.
Gotchas
-
Personal MCP login/proxy is covered by assistant connections; outbound mail by chat channels; managed-profile setup by agents; verified runtime installation/import by instance operations.
-
Feedback export can contain detailed traces. Use an owned output directory and the actual permitted board identity; --shared-only is a read filter, not an upload or consent action.
-
API success proves its contract, not the equivalent browser creation journey.
-
The CLI command registry is broader than the UI page inventory; new command families need a recipe review.
-
See instance operations for install/update/backup and feature-specific recipes for domain behavior.
Storybook verification
context
Capability ID: cli-operations/context.
Scope: cli Storybook: No authored story required for CLI profile/context selection. Production: Verify selected API origin, identity and company, JSON output and invalid-token/wrong-company failures. A persona label is not authentication. Sources: Source: context.ts. Tests: context.test.ts, http.test.ts
domain-commands
Capability ID: cli-operations/domain-commands.
Scope: cli Storybook: No authored story required for command parsing and domain API execution; corresponding product UI keeps its own story needs. Production: Discover registered help, use a disposable company, assert persisted mutations and denied operations with the actual actor. Command parity is not every endpoint passing live. Sources: Source: index.ts, issue.ts. Tests: operations-parity.test.ts
outputs
Capability ID: cli-operations/outputs.
Scope: cli Storybook: No authored story required for CLI document/asset/skill IO or machine-readable output. Production: Assert payload/schema, exit code, written contents, authorization and file integrity. Open the resulting document/asset in the product for cross-surface acceptance. Sources: Source: issue.ts, asset.ts, skill.ts. Tests: issue-subresources.test.ts, admin-asset-skill-parity.test.ts
run-controls
Capability ID: cli-operations/run-controls.
Scope: cli Storybook: No authored story required for invoke/list/get/cancel/events/log command execution. Production: Assert the real run ID, event/log output and resulting state, eligible actor and cancellation denial. Printed success does not prove provider completion. Sources: Source: run.ts, heartbeat-run.ts. Tests: operations-parity.test.ts
worktree-instances
Capability ID: cli-operations/worktree-instances.
Scope: cli Storybook: No authored story required for worktree initialize/seed/repair/cleanup commands. Production: Use only an owned isolated checkout/instance; verify paths, ports, health, login and seed provenance, then cleanup ownership. Capture evidence before teardown. Sources: Source: worktree.ts, test-drive.ts. Tests: worktree.test.ts, test-drive.test.ts