DottaandPaperclip
433d94ee0b
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Feature recipes and Storybook help contributors find behavior, examples, and verification steps. > - Independent feature changes currently update shared catalogs, indexes, and review hashes. > - Those shared files cause merge conflicts and repeated bookkeeping during parallel work. > - This pull request stores metadata in each feature recipe and story, then generates the combined views. > - Contributors can merge independent work without editing a common index. Git and PR evidence retain change and review history. ## Linked Issues or Issue Description **What existing behavior does this improve?** Maintaining the product, agent-access, and Storybook maps while multiple agents change different features. **Current behavior** A story or recipe change can update `catalog.json`, `INDEX.md`, review hashes, verification tables, and tracked generated navigation. Two unrelated changes then conflict in the same files. **Proposed behavior** Each story declares capability links and classification in `parameters.paperclip`. Each feature recipe declares its navigation and optional verification guidance. Startup, build, and UI typechecking discover these sources and generate ignored indexes and Storybook pages. **Reason and benefit** A routine change edits its own source files. Aggregate metadata is rebuilt from the merged checkout. There is no sidecar registry, shared review journal, or hash acknowledgment to maintain. **Breaking changes** The tracked Storybook catalog and index paths are retired. Consumers use `ui/storybook/generated/` or `maps/generated/` after generation. Contributor instructions and the existing feature-gap browser suite use the new paths. Story and overview IDs remain stable. ## What Changed - Move the existing annotations into 262 story files. Preserve classifications, capability associations, exports, and explicit IDs. - Discover all 35 feature recipes. Store section/order beside each recipe and move durable verification routes out of the shared table. - Remove tracked catalogs, inventories, overview pages, and inline preview ordering. Keep authored preview behavior in `preview-base.tsx`. - Generate the Storybook guide, feature/access Markdown indexes, gap report, page-reference inventory, and preview wrapper automatically. - Update the map contracts and maintenance skills to use Git history and revision-specific PR/CI evidence. - Add schema, identity, regeneration, and actual Git merge tests. Run these through the existing UI Vitest suite. Add focused browser navigation checks. This is one coordinated migration. Most of the 367 changed files contain only moved metadata or deleted generated content. Review the generator scripts, map contracts, Storybook configuration, and tests first. No product API or authorization behavior changes. ## Verification Passed: - `node scripts/check-maps.mjs`: 35 paired areas and 175 capabilities. - `node scripts/storybook-catalog.mjs --check`: 262 suites and 2,485 authored stories after incorporating current master. - `node --test scripts/check-maps.test.mjs scripts/storybook-catalog.test.mjs scripts/storybook-feature-index.test.mjs`: 28 tests, including independent branches merged in both orders with identical generated output and no tracked changes. - `pnpm --filter @paperclipai/ui exec vitest run storybook/map-tooling.test.ts`: the CI entrypoint runs those map tests. - `pnpm check:token-gates`. - `pnpm -r typecheck` and `pnpm build` before the final master rebase. - `pnpm build-storybook`: all 2,517 original story/docs URLs retained. Current master contributes exactly four additional recovery stories. - Focused Playwright navigation checks: search and open a feature without examples; expand verification guidance and check source links; retain capability order and follow a related Foundations suite. The final clean Storybook build passed after deleting every ignored map output. Post-rebase UI typechecking and both browser tests passed. The working tree stays clean after generation. The concurrent-cleanup regression fails with `ENOENT` without the fix and passes with it. All GitHub CI gates passed on `00fc7ec18e`, which also received Greptile 5/5 with no unresolved findings. The final merge commit `1c3c5143a6` incorporates master and resolves only the two modify/delete conflicts by retaining removal of the aggregate index and catalog. Master’s new workspace feature and access guidance is preserved. Map validation, catalog generation, overview generation, all 28 map tests, and diff checks pass after conflict resolution. The maintainer explicitly requested merging without another Greptile review. CI has not been rerun to completion on this merge commit. The local repository-wide `pnpm test:run` was stopped before completion after the earlier CI matrix passed; it is not reported as a local pass. No screenshot baselines or production acceptance are claimed. To repeat the browser check against an owned Storybook server: ```sh PAPERCLIP_GAP_STORYBOOK_URL=http://127.0.0.1:6136 pnpm exec playwright test --config tests/storybook-visual/feature-gap-stories.config.ts map-navigation.spec.ts ``` ## Risks - Existing branches need a one-time rebase to move their catalog changes into local annotations. The PR incorporates the recovery changes from current master. - Changing the same story or capability can still produce a meaningful conflict. This removes the shared aggregate bottleneck. - The generator uses Storybook's existing CSF parser. Literal-only annotations and parser regression tests protect the current contract. - Generated Markdown is available after running the generator; the published Storybook provides a browsable guide. - Shared source changes still require review. Removing hashes removes mechanical acknowledgments; it does not establish runtime parity. ## Model Used OpenAI Codex, based on GPT-6, with repository inspection, code execution, and browser-test tools. The exact deployment model ID and context window were 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 on the previously reviewed head `00fc7ec18e`; final conflict-resolution checks are documented above - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups on `00fc7ec18e`; another review was waived by the maintainer - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
8.8 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
Connection setup
People connect an app or account, choose who may use it, and recover incomplete setup from either Apps or a task that needs access. A saved draft, a completed provider login, a usable connection, and a resumed task are separate checkpoints. Chat channels additionally require an endpoint and linked sender identity.
Agent access: companion.
Sub-features
catalog: find a provider, inspect its available methods, and open setup; unavailable methods explain their prerequisite rather than silently switching.identity-and-access: select personal/shared identity and eligible agents; an empty explicit selection and company-wide access must not be confused.credentials: provider sign-in, key, or generic MCP URL follows its supported setup method; credentials are not retained in browser draft storage.handoff: provider popup/full-page callback returns to the correct setup host with the original task intent and identity choice intact.draft-recovery: cancel, Back, Save & exit, reload, Finish setup, and reconnect preserve the exact draft rather than creating duplicate connections.task-request: only the addressed person resolves the requested connection; usable access releases the pending task request through normal continuation.channel-setup: provider endpoint, represented agent, linked sender, and communication instructions are configured before an external message is used.failure: denied login, unreachable/private URL, expired credentials, and permission errors leave an actionable state rather than a false success.
How to get to it (user POV)
apps-catalog
Open Apps (/apps), choose an app, and connect from its landing page. Select an
available method and access, then complete setup. Existing connections open
their details; unfinished ones offer a way to finish setup.
mcp-link
Use Connect with a link or /apps/byo for a generic MCP server. Paste its
URL, select access, and follow the probe's sign-in/key guidance. Provider-specific
catalog setup and a generic endpoint may use different flows.
task-request
Open the task's pending connection request and its setup action as the named user. Setup can open in a task dialog and may use an OAuth popup. Follow the request's original link if setup falls back to a standalone page.
resume-connection
From Apps or connection details, use Finish setup, reconnect, or the offered authentication recovery action. Reload or return from the provider before checking whether the same saved connection became usable.
chat-channel
With chat connectors enabled, select a supported chat/email provider in Apps
or open /apps/chat/connect. Complete that provider's endpoint setup, then
open its settings (/apps/chat/:endpointId/settings). Follow identity linking
as the intended sender before messaging the agent externally.
Driving it with Playwright and the Paperclip CLI
Preconditions: follow the baseline. Choose a disposable provider account/resource and record its auth method, deployment mode, account ownership, and access selection. For live setup, use the provider's documented prerequisites in the connector playbook. Automated fixtures do not establish OAuth registration, public callbacks, or production provider access.
apps-catalog
Automated: Browse, unconnected app, and AppsConnect cover catalog entry, access selection, provider-specific method choices, and setup failures with mocked APIs. Connection intents drives store and task setup against one fake provider through a useful continuation:
pnpm exec vitest run ui/src/pages/apps/Browse.test.tsx ui/src/pages/apps/AppsConnect.test.tsx
pnpm exec playwright test -c tests/e2e/playwright.config.ts tests/e2e/connection-intents.spec.ts
Manual: connect from an unconnected provider landing. Select the intended identity and agent access, complete authentication, reload, and inspect the saved connection. Run a permitted read-only action with an eligible agent and verify its useful result. Try an ineligible agent and confirm denial. Repeat with a user who cannot install company-wide; the UI must not imply broad access.
mcp-link
Automated: AppsConnect's generic MCP cases cover probe-driven auth, private or unreachable endpoints, preregistered clients, secret-backed headers, and unsafe authorization URLs. These are component/API mocks, not remote provider proof.
Manual: connect a known test MCP URL through the link flow, verify its saved endpoint and a read-only action, then repeat with a bad URL and wrong credential. The error should explain the next action and preserve non-secret setup context. Test no-auth and authenticated endpoints separately; never infer one from the other.
task-request
Automated: interaction card checks addressed-user controls. AppsConnect tests cover page/dialog parity, task-bound OAuth, popup handoff, and verifying a saved connection before closing. The connection-intents browser suite above exercises fixture-backed continuation.
Manual: ask an agent to use an unavailable app, open its request as the named user, and complete setup in the dialog. Verify the card settles, the exact task resumes, and the agent returns a useful provider result. Repeat the page-host fallback and denied OAuth path. As another user, confirm that merely seeing the task does not grant the right to resolve the request.
resume-connection
Automated: AppsConnect tests cover exact-draft resume, declined OAuth, reconnect lookup failure/retry, response-lost creation, archived connection revival, and saved account reuse. App detail covers the connection host. These tests do not complete a real provider login.
Manual: leave setup through its footer, reload Apps, choose Finish setup, and confirm the same connection is resumed. Decline provider login and recover from that checkpoint. Reconnect an expired disposable account and verify a permitted action afterwards. Count connections before/after to catch accidental duplicates.
chat-channel
Automated: setup routing, saved setup state, email setup, and identity confirmation cover shared UI logic with fixtures. Provider-specific live setup is not implied.
Channel integration also covers bounded Telegram subscription recovery at startup and after committed configuration changes, saved retry deadlines, rollback, and parking pending repair while an endpoint or connection is inactive. The provider responses are fixtures. Settled maintenance leaves no discovery timer or database scans.
Manual: complete setup for one named provider, reload endpoint settings, link the intended sender, and send a disposable message. Verify one task and a useful reply in the originating conversation. Inspect an unlinked sender's denial and the endpoint's pause behavior. Repeat independently for each provider at issue; Slack setup does not qualify Discord, Telegram, GitHub, email, or iMessage.
Gotchas
-
Private endpoint rejection depends on deployment: owned loopback MCP servers are supported in local-trusted/private instances. Public authenticated deployments apply the private-network restriction.
-
A successful OAuth callback is not proof of saved connection access or task continuation. Verify all three checkpoints.
-
Personal identity, shared account access, and per-agent access are distinct. Connecting an account does not waive an Off action or Ask first review.
-
A tool app connection is not a chat endpoint. The same provider can offer both.
-
Old Apps/Connections URLs can redirect to Apps. Use the current navigation and record the actual destination rather than documenting an obsolete screen.
-
Full provider matrix, AI-account selection, gateway/profile administration, and account revocation lifecycles remain outside this seed recipe.
-
For governed actions after setup, use questions and approvals.
Documentation scope: App catalog and connection setup
Provider-specific authentication/revocation, credential-only accounts, and aggregator administrative variants still need their own detailed matrices.