feat(core): make the CLI visible where agents read

[josephfarina]

Summary

• generate a CLI search hint at the top of every shipped component doc
• stamp every generated TypeScript declaration during the core build
• append a copyable CLI search to development warnings while keeping production error text unchanged
• keep docs and tests out of runtime component audit scopes, so generated comments do not fan out visual, RTL, or accessibility jobs
• fail check:repo when checked-in source hints drift

This closes the gap where an agent can read the package's rich docs or types without ever discovering the Astryx CLI.

Test plan

• pnpm lint:strict
• pnpm exec vitest run --maxWorkers=4 --reporter=dot
• pnpm -F @astryxdesign/core build
• pnpm -F @astryxdesign/core typecheck
• packed @astryxdesign/core and verified all 227 component docs and 598 declarations contain guidance
• ran all 235 unique generated CLI searches and verified every query returns results

Try it

pnpm generate:cli-discovery-hints --check
pnpm -F @astryxdesign/core build
sed -n '1,8p' packages/core/dist/Button/Button.d.ts
NODE_ENV=development node --input-type=module -e 'import("./packages/core/dist/utils/devWarning.js").then(({devWarn}) => devWarn("Button", "bad prop"))'

Expect the declaration to start with npx @astryxdesign/cli search "Button". The warning prints the original message followed by the same CLI lookup.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 2, 2026 10:50pm UTC

[github-actions]

PR Analysis Report

Preview availability: Storybook and Sandbox were not published for this CI run.

Modified Components

Breadcrumbs _{(@astryxdesign/core)}

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	634	-
Complexity	N/A	Very High (49)	-

Stepper _{(@astryxdesign/core)}

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	1285	-
Complexity	N/A	Very High (136)	-

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.8KB	1.2KB

Accessibility Audit

Status: 1 accessibility violation(s) found — 1 serious.

Stepper - 1 issue(s)

• 🟠 serious: Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds
  • Rule: color-contrast · Affects 1/28 stories · Learn more
  • WCAG: 1.4.3 (Level AA)

Visual Regression

Status: Skipped — Broad stable scope is deferred to the daily release gate. It covers 4332 trusted baseline shots instead of recapturing them for this PR. View the report

---

_{Generated by PR Enrichment workflow | View full report}