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.2 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
Inbox, decisions, and search
People find work that needs their attention, distinguish unread activity from required decisions, archive handled items, and search across the company.
Implementation: inbox, decisions, search.
Agent access: companion.
Sub-features
views: use Mine, Recent, Unread, Blocked, and broader task views.triage: read or archive attention items without pretending the underlying task is complete.decisions: open the source of a decision and act in the right context.search: query company work and follow a result to its original record.toasts: receive live task notifications only for personal participation or explicit mentions.
How to get to it (user POV)
inbox
Use Inbox links or the corresponding task views when the combined list is enabled.
decisions
Open /decisions, then a queue at /decisions/queues/:key and its source item.
search
Open /search or the navigation search entry.
toasts
Keep a company page open while another person or agent updates a task. See toast semantics for eligibility and suppression rules.
Driving it with Playwright and the Paperclip CLI
Preconditions: follow the baseline. Seed assigned, unread, blocked, and resolved tasks plus a pending decision. Record the combined Inbox/Tasks experimental setting.
inbox
Automated: archive routes cover server mutations. Task-list helpers cover search URLs, pagination, and presentation constants; they do not render the combined Inbox/Tasks page. Reading, archiving, and navigating that page remain manual checks.
Automated: Issue service regressions cover exclusion of historical automatic read cleanup from user participation, unread counts, and activity timestamps while retaining explicit user decisions and audit history.
Manual: Seed a scheduled routine execution owned by the current human. It stays out of Mine until an existing participation rule admits it. Verify comments, assignment, and manual routine runs admit automated tasks while reading alone does not. Inbox discovery and Blocked hide unrelated automation by default; the show agent-created tasks checkbox reveals it without subscribing the user. Reload and verify membership, unread badges, archive/resurfacing, and preference persistence.
Manual: Read an unread task, return to Unread, archive a handled item, and reload. Verify personal triage state changes while task status stays correct. Switch users and companies to check isolation.
Seed a completed task whose only activity under the viewing user is automatic read cleanup. Refresh Mine and Unread: the task must not appear through that participation, while the cleanup remains in activity history. Record an explicit user recovery decision on a separate task and verify it still counts. This browser journey remains manual.
decisions
Automated: decision queues covers route behavior. End-to-end queue-to-source navigation is manual.
Manual: Open a pending decision, follow its source, resolve it through the supported control, and reload the queue. Confirm it retires only after the decision persisted and unrelated pending items remain.
search
Automated: search page and company search service cover UI and server search separately.
Manual: Search a unique task title and content phrase, open the result, and compare the actual record. Test filters, no results, and a second company. Verify stale results do not expose inaccessible data.
toasts
Automated: persisted eligibility
checks creation, assignment, comments, mentions, deliberate edits, excluded read
activity, company isolation, local-board, and persisted run-task attribution.
Socket delivery checks
viewer-specific projection; UI delivery
checks eligibility gating, cache updates, stale callbacks, and existing suppression.
UI cache handling checks visible
comment refresh when authenticated events omit hydration metadata.
The task toasts follow personal involvement in multiplayer case in the
authenticated browser suite
exercises quiet unrelated updates, read-only visits, first/historical mentions,
self-activity, and visible-task suppression against persisted data.
Manual: Use two authenticated browser sessions in the same isolated company. Create separate tasks for each person and use one shared agent. From a company task list, verify that the other person's unrelated task updates produce no toast but still refresh the list. Comment on one of their tasks, then have them update it: a toast should appear. Repeat using assignment, a deliberate edit, and a first explicit user mention in a comment or description. Reload before a later update to prove eligibility does not depend on browser history. Mere viewing, agent ownership, responsible-user attribution, and parent participation must remain quiet. Task-linked failures follow the same participation rule; generic agent errors remain quiet. Repeat while viewing the relevant task and after switching company/account to verify suppression and isolation.
Gotchas
-
Notifications do not grant task access or change Mine membership.
-
A feature-map recipe and mocked UI tests do not prove live multiplayer behavior.
-
Combined Inbox/Tasks requires both
enableCombinedInboxTasksandenableStreamlinedUi. Standalone Inbox tests render archive/read controls and toolbars; this is not live multi-user evidence. -
Personal archival is not task cancellation or completion.
-
Legacy Inbox routes can redirect to the combined task view; record which host actually rendered.
-
Search service tests do not establish the relevance quality of every query.
Storybook verification
views
Scope: ui Storybook: Mine/Recent/Unread/Blocked and broader task views; combined versus standalone host; loading/empty/error/filter states. Production: Use persisted personal participation/read data; verify scoped counts and list navigation/reload; automatic read cleanup must not create Mine membership. Sources: Source: Inbox.tsx, Issues.tsx. Tests: Inbox.test.tsx, Issues.test.tsx, issues-service.test.ts
toasts
Scope: ui Storybook: Eligible live task toast, explicit mention, quiet unrelated event, own-action/visible-task suppression, dedupe and company/account switch. Production: Persisted participation and mentions determine per-viewer socket eligibility; quiet events still refresh caches; reload retains eligibility, unauthorized resources remain denied. Sources: Source: ToastViewport.tsx, ToastContext.tsx, LiveUpdatesProvider.tsx, task-toast-eligibility.ts. Tests: ToastContext.test.tsx, ToastViewport.test.tsx, LiveUpdatesProvider.hook.test.tsx, task-toast-eligibility.test.ts, live-events-toast.test.ts, multi-user-authenticated.spec.ts