DottaandPaperclip
88bf4c6c1d
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The feature map describes product areas and verification entry points. > - Storybook has 223 story suites that show production components, proposals, and retained history. > - The parent PR maps those suites to features, but their folders and sidebar still use unrelated groups. > - This pull request puts the existing suites under feature folders and uses the feature map's names and order in the sidebar. > - Explicit meta IDs preserve existing story links while the titles change. > - Contributors can find stories through the same product structure without losing examples. ## Linked Issues or Issue Description Refs #16046. This is the requested follow-up. Parent #16046 is merged. This PR now targets master, with its single follow-up commit rebased onto the parent squash merge. The Storybook implementation is unchanged by that rebase. Related open Storybook PRs were checked; this change organizes existing suites and adds no product capability. ## What Changed - Move all 223 story files into folders named for their primary feature area. Keep useful scenario groups below the feature's sidebar label. - Order the sidebar by the eight feature-map sections. Put Overview first and shared Foundations last. Leave areas with no stories out of the sidebar. - Move 19 support files into `ui/storybook/support/` and update relative imports and active documentation. - Preserve all 2,210 story IDs and the single docs ID through explicit CSF meta IDs. Keep all entry names and story exports. - Record stable IDs and sidebar titles in the downstream catalog. Validate feature folders, title prefixes, and IDs. Update the maintenance skill and review evidence. ## Verification - Storybook build passed. Built index comparison against parent `75bd3c977cd828d5222823850339e8204f40eb47` found the same 2,211 entries, IDs, and names. - UI typecheck passed (`ui/node_modules/.bin/tsc -b` from `ui`, invoked as `./node_modules/.bin/tsc -b`). - UI Vitest project: 728 files and 8,176 tests passed. - Catalog checker and its nine tests passed. Feature-map checks, token gates, and the maintenance-skill validator passed. - Chromium: nine existing play cases and one render case reached `storyFinished: success` with no page exceptions. The guide rendered, sidebar sections followed map order, and a search for `steering/queue` opened its preserved story link. - Source comparison found only meta title/ID changes, rebased relative references, and updated fixture path text in story files. - To inspect: build Storybook, start `node scripts/serve-storybook-static.mjs --port 6136`, and open the Overview guide. Expand feature folders and use existing story links. - The complete repository suite was not repeated for this organization change. The parent records a backend timeout that passed in isolation, without a complete broad-suite pass. Visual comparisons remain blocked by the unpublished empty baseline. The separate fixture-server story was not run. ## Risks - Open branches that add stories under old paths will need to choose a feature folder and update the catalog. Cross-feature suites have one primary home and retain related capability references. - Sidebar paths change; story and docs IDs remain stable. Automated references to source paths may need the new location. - This is one requested follow-up with 258 changed files, mostly moves. It exceeds the usual review-size guideline because splitting it would leave the sidebar and folder convention partly migrated. - Browser verification samples ten stories, not all 2,210. Existing production/prototype classifications and review gaps remain unchanged. - Required CI gates and a 5/5 review passed on the original head. Fresh checks and review are running for the rebased head. Catalog validation and all nine checker tests passed after rebase; UI, map, skill, and checker contents are identical to the original reviewed head. ## Model Used - OpenAI Codex, GPT-6. The exact runtime model ID and context-window size are not exposed in this session. Used reasoning, repository inspection, code execution, and local browser automation. ## 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 - [ ] All Paperclip CI gates are green - [ ] 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>
Storybook map
The feature index connects the existing Storybook to stable capability
IDs from the upstream feature map. Story files remain
in ui/storybook/. The feature map and its maintenance skill do not depend on
this catalog. New capabilities or upstream recipe drift are reported to their
maintainer; this catalog does not redefine product behavior or permissions.
Ownership
- maintain-storybook owns story alignment, fixture corrections, classification, and this catalog.
- review-storybook consumes it to select and exercise examples, then reports evidence and drift.
- DESIGN.md governs design. Production verification remains with the existing product recipes and verification tools.
Catalog contract
catalog.json is the maintained inventory, with one entry per story file.
INDEX.md is generated from it and the installed Storybook CSF parser. Titles,
export filtering, story counts and IDs come from source, not filename guesses.
All examples are retained, including historical suites. A file's first capability
is its primary home; remaining capabilities are lookup references, not copies.
Foundations/guides and proposals without a mapped capability need an exception
reason. An absent story is not automatically a feature gap.
Folders and sidebar
Story files live in ui/storybook/stories/<primary-feature-area>/, using the first
capability's area slug. Related capabilities still point to the same story. Shared
fixture modules and assets live in ui/storybook/support/; production wrappers in
ui/storybook/prototypes/ retain their existing ownership.
The sidebar follows the section and feature names in the feature-map README, then retains each suite's useful scenario grouping. Foundations contains shared component examples with no primary product capability. Overview contains the catalog guide. Areas with no stories do not get empty sidebar folders.
Each suite declares an explicit CSF id, recorded as stableId in the catalog.
The sidebarTitle can change without changing that identity. Existing story and
autodocs URLs and screenshot names remain valid. Do not derive a replacement ID
from a newly organized title. The checker rejects missing or changed explicit IDs,
incorrect feature folders, and sidebar titles outside their primary feature home.
Each entry records purpose, capability references, review sources/date/fingerprint, notes, and three independent dimensions:
| Dimension | Values |
|---|---|
| Product status | current: source comparison supports the named subject; proposed: intentional alternate design; historical: superseded reference retained for its original purpose; mixed: suite combines these; unreviewed: parity has not been established |
| Implementation | production: shipped subject with fixture/layout wrappers; prototype: locally implemented subject, even if it uses shared primitives; mixed: both subjects; guide: explanatory documentation |
| Data boundary | fixtures: props, callbacks, caches or API responses are simulated; fixture-server: requires a separately owned local API/database fixture with simulated upstream providers; static: explanatory/static examples |
current is a source-review classification, not a promise that every state renders
or that APIs, gates, persistence and providers passed live tests. unreviewed
entries still have an inventory/classification review; notes explain the deeper
parity work outstanding. Mixed files retain a note naming the important split.
Production components can legitimately use mock data. A prototype directory name
does not establish implementation: some wrappers there re-export shipped UI.
Review sources include the story, relevant local support and production subjects. Include directly rendered subjects regardless of import spelling, and primitives when the suite demonstrates them. Do not truncate the list to a fixed source count. Fingerprints make changes to those declared dependencies visible. They do not follow every transitive production import or infer semantic correctness. Shared preview/config/fixture changes have a separate fingerprint and require reviewing affected callers. Update fingerprints only after reviewing the change, and add missing dependencies when discovered. Date/revision context for the initial pass and executed evidence belong in REVIEW.md.
Maintenance commands
After installing workspace dependencies:
node scripts/storybook-catalog.mjs
node scripts/storybook-catalog.mjs --write
node --test scripts/storybook-catalog.test.mjs
The checker rejects unaccounted or deleted stories, invalid capability references,
duplicate entries/IDs, missing review sources, changed fingerprints and a stale
generated index. --write only regenerates the index; it never refreshes review
fingerprints or blesses drift. Preserve IDs when changing titles or moving files;
compare the existing built Storybook index before and after such changes.
Use the existing Storybook workflow for builds,
browser review, and visual tests. Report source inspection, rendering, play
assertions, visual comparisons and production acceptance separately. Do not publish
new visual baselines just to make catalog maintenance pass.