The rules live once, in a shared core, and run two ways: one interactive in Storybook, one headless in CI. Each README below has the full install, usage, and options:
Where to look
The rules are shared, so they are documented in docs/ rather than in either package. This applies whether you run the CLI or the addon:
Layout
docs/ the rules, and how to satisfy them, shared by both packages
packages/
core/ oversight-core, the rules engine (pure, private, bundled into the addon and the CLI)
storybook-addon-oversight/ the Storybook addon (panel + Docs block)
cli/ oversight-lint, the CI linter
agent-view/ records what the MCP serves an agent (private, tests only)
.storybook/ stories/ the demo Storybook that dogfoods the addon
oversight-core holds every rule as pure functions with zero Storybook or React imports. The addon and the CLI each bundle it, so the two can never disagree about what a finding is. It is never published on its own.
oversight-agent-view publishes nothing either, and ships no rules. It calls Storybook's MCP server over a manifest and snapshots what comes back, one variant per failure mode, so the rules can be judged against the text an agent receives rather than against the manifest they read. When the server changes what it serves, a test fails instead of a rule's justification quietly ceasing to be true. What the agent actually receives is what it produced.
Development
pnpm install
pnpm exec playwright install chromium # once, for the browser checks
pnpm -r build # build every package (tsc typecheck + tsup bundle)
pnpm test # unit projects, then the built Storybook, then the demo's stories
pnpm test:unit # just the unit projects, no build, no browser
pnpm built-storybook-checks # just the Docs block and panel, against the last build
pnpm lint
pnpm build-storybook # build the addon, then the demo Storybook
pnpm storybook # run the demo at http://localhost:6006
The demo ships a handful of components each engineered to trip one rule. Open a component's story to see the addon panel, or its Docs page for the inline block. Run oversight storybook-static/manifests/components.json after pnpm build-storybook to see the CLI report the same findings.
Changes land through pull requests; see CONTRIBUTING.md.
Per-package release history: storybook-addon-oversight and oversight-lint.
License
MIT