Files
PaperClipAI/maps/storybook-map
9bd820e687 feat(storybook): mirror the complete feature-map index (#16052)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The feature map describes its user-facing capabilities and
verification recipes.
> - Storybook provides isolated UI examples for those capabilities.
> - The previous organization showed only features with primary story
suites.
> - This pull request derives the complete Storybook index from the
upstream map.
> - Readers can find the same features in both places and see related
examples or explicit gaps.

## Linked Issues or Issue Description

Refs #16046 and #16049.

**What existing behavior does this improve?**

Storybook navigation and the downstream feature catalog.

**Current behavior**

The sidebar has 28 primary feature homes. The feature map lists 35. The
main guide groups suites alphabetically by area slug. Related examples
can live under a different feature.

**Proposed behavior**

Use the feature map's eight sections and 35 features in the same order.
Give each feature an Overview page with all its capabilities, related
example links, and missing-example messages. Keep shared foundations
outside the product index. Preserve all existing stories and URLs.

**Reason and benefit**

Readers can move between the feature map and Storybook without learning
a second index. A feature without cataloged examples remains visible.

**Breaking changes**

None to existing story IDs or product behavior. Storybook start and
build now reject stale generated feature pages and ordering. Run the
catalog generator after upstream changes, inspect the output, and review
affected source fingerprints.

## What Changed

- Generate 35 feature Overview stories and capability data from the
upstream map. Generate the inline sidebar order required by Storybook.
- Replace the main guide with the full ordered feature index and search.
Link all related suites from feature pages, even across primary homes.
- Preserve all 223 authored files, 2,210 story IDs, and the existing
docs ID. Keep status, implementation, and fixture classifications
visible.
- Put the generated Markdown catalog in feature-map order. Keep
generated guides outside example counts.
- Update maintenance and review skills, documentation, and generator
tests. Keep the feature map independent of Storybook.

## Verification

- Passed: 16 catalog and generator tests; map checks; token gates; both
skill validators.
- Passed: `pnpm -r typecheck`, `pnpm build`, and the Storybook build.
- Built-index comparison preserved all 2,211 previous entries and added
only 35 feature overviews. Feature order matches the map.
- Browser: inspected the complete index and sidebar, searched for Goals,
opened its overview, and followed a related suite under Projects. The
original suite renders.
- Passed: all 8,170 UI tests in 728 files. Browser checks also covered
empty search, capability-ID search, missing-example pages, the original
editable-text bookmark, the CLI sidebar label, and searching/opening
shared foundations.
- The broad local `pnpm test:run` was stopped after a failure in the
unchanged GitHub chat test `authorizes description edits as the editor,
never inheriting the original author's access`. That exact test passed
alone without code or expectation changes. A complete local repository
suite pass is not established.
- Original revision CI passed after one runner retry. The merged
revision `5ca01c70716f23974680a8019ddc613035d11bc4` passed fresh CI.
Local UI typecheck, catalog checks, 16 generator tests, map checks and
token gates pass.
- Greptile: 5/5 on final commit
`5ca01c70716f23974680a8019ddc613035d11bc4`, with all findings resolved.
- Master merge: inspected source drift in 61 catalog entries and
regenerated INDEX, preserving upstream notes. Marked the sidebar suite
that mounts IssueDetail unreviewed for the new activity query; recorded
limits for composer and channel-default changes. No stories removed.
- Final Storybook build passed. Browser filename searches for
`new-task-composer` and `forms-editors` return the expected feature and
shared example.
- No visual-baseline or full production acceptance claim. The deeper
authored scenario groups remain intact.

## Risks

- The parser depends on the feature-map Markdown contract. It rejects
unknown index rows, omitted feature recipes, and unexpected generated
files.
- A suite can reference several capabilities. A link proves catalog
association, not complete behavior coverage or production parity.
- Storybook treats `/` as a folder separator. Sidebar labels use a comma
for that character; the guide and page headings retain the upstream
name.
- No database, API, authorization, or production component changes.

## Model Used

OpenAI Codex, GPT-6 family, with reasoning, code execution, and browser
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>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
2026-10-13 07:01:29 -05:00
..

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 authored story file. INDEX.md is generated from it, the upstream feature map, 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. Every indexed feature has an Overview page, even when it has no cataloged examples. The main guide and these pages use the same section, feature, and capability order as the upstream map. Related suite links cross primary homes without copying stories. Sidebar labels replace / with , because Storybook treats slashes as folders; the index and page heading retain the original feature name. Missing examples are explicit; historical examples and guides do not imply current behavioral coverage.

ui/storybook/generated/ contains the derived index and one CSF Overview per feature. The inline storySort.order in the preview config is also generated: Storybook's indexer requires a literal there. Regenerate these outputs with the catalog command; do not edit them or add them to the authored inventory. Their stable IDs use feature-map-<area>--overview. Generated pages are explanatory guides and do not increase example-suite counts. Storybook start/build checks this output for drift. The generator fails on unexpected files rather than silently deleting them.

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 scripts/storybook-feature-index.test.mjs

The checker rejects unaccounted or deleted stories, invalid capability references, duplicate entries/IDs, missing review sources, changed fingerprints and a stale generated indexes and feature pages. --write only regenerates these outputs; 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. Feature outputs are regenerated before fingerprints are checked. If those writes change a review source, the command fails with the affected review entries. Inspect the generated change before updating those fingerprints and rerunning the command.

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.