mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-11 05:11:49 +01:00
DottaandPaperclip
5e8e992df2
## Thinking Path > - Paperclip helps people manage AI agents and their work. > - The feature map describes user capabilities and verification recipes. > - Storybook holds isolated examples of those capabilities. > - Missing catalog links can hide existing examples. > - Some stories also expose shipped capabilities absent from the map. > - This pull request adds verified source associations and three paired map entries. > - Readers can find existing examples without changing their homes or URLs. ## Linked Issues or Issue Description Refs #16052, #16049 and #16046. **What existing behavior does this improve?** Storybook capability lookup and the feature/agent access maps. **Current behavior** Seventy capabilities have no example link. Some matching stories already exist. Primary-agent preferences and company decision/fast-response services appear only under broad neighboring capabilities. **Proposed behavior** Add source-supported links across 34 suites. Keep shared foundations in place while cross-listing them. Add primary-agent, decision-model and fast-response capabilities to both upstream maps. Retain explicit simulation and partial-example limits. **Reason and benefit** The catalog distinguishes missing associations from missing examples. The upstream map describes three existing product capabilities more precisely. **Breaking changes** None to product behavior, story exports, folders, sidebar titles or URLs. A shared foundation can declare a reasoned `home: "foundations"` override while referencing related capabilities. ## What Changed - Add 55 references across 34 suites. Replace primary-agent suites' reporting-line association with their own capability. - Add three source-reviewed capabilities and their API/actor boundaries to paired maps. - Preserve the shared Foundations home when cross-listing developer design examples. Add a validation regression test. - Record which exports demonstrate each association and what remains simulated or unverified. - Regenerate the catalog and capability data. Preserve all original 223 authored suites and 2,210 story IDs. Retain the two skill-removal stories added by current master, for 2,212 authored stories in total. - Reduce empty example lookups from 70 of 171 capabilities to 59 of 174. Links do not establish complete capability coverage. ## Verification - Passed: 27 catalog/generator/map tests, catalog validation, map structural checks, token gates and skill validation. - Passed: source inventory comparison preserves all authored files, titles, meta IDs and story IDs. - Passed: repository typecheck/build and Storybook build. Final built index has 2,248 entries and preserves all previous entries, including the two skills stories added by current master. - The broad local repository test run was interrupted before completion to resolve a new master conflict. A complete local suite pass is not claimed; fresh CI passed on the reconciled branch. - Browser: Design links to preserved Foundations stories; company-service sections link settings/history/journey suites; decision SetupToHistory passed 12 interaction steps; primary-agent ReplacePrimary passed four steps. No console errors in selected checks. - Greptile: 5/5 on final commit `805a8af62abe589907e7cc6ca1b415ce1e0cc3c0`, with no findings or unresolved threads. - Final-revision CI passed all 57 checks/statuses, including all eight browser shards, server and Runner tests, typecheck and build. The unchanged Cloud-auth mocked-response race seen on a superseded revision did not recur on the final commit. No test expectations were changed. - New agent-access evidence is source-only. Live provider and agent-credential verification is not established. ## Risks - Suite-level associations can represent only selected states. Notes retain those limits and existing review classifications. - In-memory connection drafts do not prove reload persistence. Resume-failure UI does not prove successful continuation. No-op budget controls do not prove relief or resumption. - Three map capabilities document existing behavior. No permission, API, provider or production component changes. ## Model Used OpenAI Codex, GPT-6 family, with reasoning, code execution and source inspection. The exact runtime model ID and context window are not exposed in this session. ## 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>
79 lines
4.6 KiB
Markdown
79 lines
4.6 KiB
Markdown
# Companies and portability
|
|
|
|
An operator can switch between companies, change their identity and settings, archive them, and preview an import or export. Each company remains a separate scope for work and agents.
|
|
|
|
Implementation: [companies](../../ui/src/pages/Companies.tsx), [settings](../../ui/src/pages/CompanySettings.tsx), [import](../../ui/src/pages/CompanyImport.tsx), [export](../../ui/src/pages/CompanyExport.tsx).
|
|
|
|
Agent access: [companion](../agent-access-map/companies.md).
|
|
|
|
## Sub-features
|
|
|
|
- `selection`: create/select a company and keep navigation in its scope.
|
|
- `identity`: update company identity and configured settings.
|
|
- `decision-models`: configure and test the company's decision model, then inspect invocation history and recorded usage.
|
|
- `fast-responses`: configure and test the experimental fast-response service, then inspect acknowledgement history, failures, and recorded usage.
|
|
- `archive`: archive and restore through the available controls without confusing archival with deletion.
|
|
- `portability`: preview a company package and inspect imported agents, projects, skills, and conflicts.
|
|
|
|
## How to get to it (user POV)
|
|
|
|
### `company-switcher`
|
|
|
|
Use the company switcher or `/companies`, then enter company Settings.
|
|
|
|
### `package-transfer`
|
|
|
|
Use `/company/export` and `/company/import` where enabled, or the corresponding CLI company commands.
|
|
|
|
### `company-ai-services`
|
|
|
|
Use Settings → Connections (`/company/settings/connections`) when fast responses
|
|
are enabled. Otherwise decision-model settings remain in Company Settings.
|
|
Open the Decisions and Fast responses tabs in Costs to inspect invocation history.
|
|
|
|
## Driving it with Playwright and the Paperclip CLI
|
|
|
|
Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Use two disposable companies and a small package fixture. Record cloud-managed restrictions and visible settings gates.
|
|
|
|
### `company-switcher`
|
|
|
|
Automated: [company list](../../ui/src/pages/Companies.test.tsx) and [archive UI](../../ui/src/pages/CompanySettingsArchive.test.tsx) cover UI behavior with mocks.
|
|
|
|
Manual: Create or select a company, rename it, and reload. Switch to the second company and back; verify tasks, agents, and settings follow the selection. Archive the disposable company and verify its visibility and offered restoration path.
|
|
|
|
### `package-transfer`
|
|
|
|
Automated: [portability routes](../../server/src/__tests__/company-portability-routes.test.ts) and [CLI import/export](../../cli/src/__tests__/company-import-export-e2e.test.ts) cover package and command behavior, not every external Git host.
|
|
|
|
Manual: Export a small company, inspect the package preview, and import into a disposable target. Verify counts, references, conflict choices, and agent configuration. Run one imported task after supplying its required local credentials. Confirm source company data is unchanged.
|
|
|
|
### `company-ai-services`
|
|
|
|
Automated: [decision settings](../../ui/src/components/decision-models/DecisionModelSettings.test.tsx),
|
|
[decision history](../../ui/src/components/decision-models/DecisionHistory.test.tsx),
|
|
[fast-response settings](../../ui/src/components/fast-responses/FastResponseSettings.test.tsx),
|
|
[decision service](../../server/src/__tests__/decision-models.test.ts), and
|
|
[fast-response service](../../server/src/__tests__/fast-responses.test.ts) cover
|
|
component and service contracts with simulated providers.
|
|
|
|
Manual: As an authorized connection manager, select a disposable shared AI
|
|
connection, save the provider/model and sponsorship options, reload, and run the
|
|
bounded Test action. Inspect success and failure receipts and their history in
|
|
Costs. Verify disabled or revoked connections remain clear and that a user
|
|
without connection-management permission cannot configure or test the service.
|
|
Use an owned provider fixture for failure states; record any actual provider usage.
|
|
|
|
## Gotchas
|
|
|
|
- Restore an archived company through `/companies` → its menu → **Unarchive**.
|
|
Archiving pauses eligible agents and cancels active runs; restoration handles
|
|
agents paused specifically for company archival.
|
|
|
|
- Package presence does not prove a runnable imported company; credentials and environment bindings need separate verification.
|
|
- Company deletion is a distinct gated operation; do not use it as the archive test.
|
|
- Settings hidden in a managed deployment should be recorded as unavailable, not bypassed.
|
|
- Decision tests and fast responses have different request and execution contracts.
|
|
A fast-response receipt is an acknowledgement, not completed agent work.
|
|
History visibility and connection-management authority are separate; task links
|
|
in history also require access to the underlying task.
|