mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-06 05:56:19 +01:00
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>
92 lines
5.3 KiB
Markdown
92 lines
5.3 KiB
Markdown
# Storybook map
|
|
|
|
The [feature index](INDEX.md) connects the existing Storybook to stable capability
|
|
IDs from the upstream [feature map](../feature-map/README.md). 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](../../.agents/skills/maintain-storybook/SKILL.md) owns story
|
|
alignment, fixture corrections, classification, and this catalog.
|
|
- [review-storybook](../../.agents/skills/review-storybook/SKILL.md) consumes it to
|
|
select and exercise examples, then reports evidence and drift.
|
|
- [DESIGN.md](../../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](REVIEW.md).
|
|
|
|
## Maintenance commands
|
|
|
|
After installing workspace dependencies:
|
|
|
|
```sh
|
|
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](../../doc/DEVELOPING.md#storybook) 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.
|