feat(core): docs.mjs redirects to the CLI (converge agents on init)#4207
Merged
Conversation
…docs core's bundled docs.mjs was a self-sufficient off-ramp: agents (and humans) got component docs from it and never reached the CLI or ran `astryx init` — which is what installs the full component guide + design rules + tokens into AGENTS.md/CLAUDE.md. It was also a shallower view than the CLI (e.g. Button: 82 lines here vs 269 via `astryx component Button` — no Import, no Variants, terser). Redirect docs.mjs to the CLI so everyone converges on the current, richer source and gets init: - any invocation now prints how to install + run the CLI, using the scoped `npx @astryxdesign/cli` form (never the bare `npx astryx` footgun — see #4151). - README "Component Docs" section updated to point at the CLI. Validated in the fresh-install harness (Opus 4.8 + Sonnet 5): agents converge on the CLI + init; docs.mjs is no longer a dead-end off-ramp.
josephfarina
requested review from
cixzhang,
ejhammond and
imdreamrunner
as code owners
July 22, 2026 19:36
meta-cla
Bot
added
the
CLA Signed
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
PR Analysis Report📚 Storybook PreviewView Storybook for this PR 🧪 Sandbox PreviewView Sandbox for this PR No new or modified components detected. Bundle Size Summary
Accessibility AuditStatus: 68 accessibility violation(s) found — 6 critical, 56 serious, 6 moderate. AppShell - 1 issue(s)
Avatar - 1 issue(s)
AvatarGroup - 1 issue(s)
Badge - 1 issue(s)
Banner - 1 issue(s)
Card - 1 issue(s)
Carousel - 1 issue(s)
Chat - 1 issue(s)
ChatComposer - 1 issue(s)
ChatComposerInput - 2 issue(s)
ChatLayout - 1 issue(s)
ChatReasoning - 1 issue(s)
ChatToolCalls - 1 issue(s)
CheckboxList - 1 issue(s)
ClickableCard - 1 issue(s)
CodeEditor - 2 issue(s)
CodeEditorPerf - 2 issue(s)
CodeEditorTheme - 1 issue(s)
CodeTheme - 1 issue(s)
Collapsible - 1 issue(s)
DateRangeInput - 1 issue(s)
FileInput - 3 issue(s)
Grid - 1 issue(s)
GridMasonry - 1 issue(s)
Heading - 1 issue(s)
Icon - 1 issue(s)
InputGroup - 1 issue(s)
Item - 2 issue(s)
Kbd - 1 issue(s)
Layout - 2 issue(s)
List - 2 issue(s)
LogStream - 1 issue(s)
Outline - 1 issue(s)
OverflowList - 1 issue(s)
Overlay - 1 issue(s)
Pagination - 1 issue(s)
PowerSearch - 1 issue(s)
ProgressBar - 1 issue(s)
RadioList - 1 issue(s)
Schedule - 1 issue(s)
Section - 1 issue(s)
SegmentedControl - 1 issue(s)
SelectableCard - 1 issue(s)
Stack - 1 issue(s)
Stepper - 1 issue(s)
TabList - 1 issue(s)
Table - 1 issue(s)
TableGroupedRows - 2 issue(s)
TablePagination - 1 issue(s)
TableTree - 1 issue(s)
Text - 1 issue(s)
Theme - 1 issue(s)
PopArt - 1 issue(s)
Thumbnail - 1 issue(s)
Timestamp - 1 issue(s)
Token - 1 issue(s)
Tokenizer - 1 issue(s)
Toolbar - 1 issue(s)
ToolbarEdgeCompensation - 1 issue(s)
Generated by PR Enrichment workflow | Storybook | Sandbox | View full report |
docs.mjs now redirects to the Astryx CLI instead of printing a component catalog / per-component docs, so assert the redirect banner + exit 0 regardless of args rather than the old catalog output. Co-authored-by: Cursor <cursoragent@cursor.com>
cixzhang
added a commit
that referenced
this pull request
Jul 22, 2026
Seven published-behavior PRs merged since v0.1.7 without a changeset, which would leave their contributors uncredited in the CHANGELOG. Add changesets so the v0.1.8 bump credits them: - core docs.mjs redirect to the CLI (#4207) - Table tree-data plugin: useTableTreeState / useTableTreeData (#3789) - Table tree expander aria-label localization (#4149) - foolproof init: postinstall nudges + non-interactive init (#4147, #4153, #4154, #4155)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
@astryxdesign/coreshipsdocs.mjs, a zero-install component-docs script. In fresh-install testing it turned out to be a self-sufficient off-ramp: agents get "what components exist + how to use them" from it and never reach the CLI or runastryx init— which is what actually installs the full component guide + design rules + tokens intoAGENTS.md/CLAUDE.md.It's also a shallower view than the CLI. Same component, side by side:
node docs.mjs Button→ 82 linesnpx @astryxdesign/cli component Button→ 269 lines (addsImport,Variants, fuller anatomy/best-practices)So an agent that stops at
docs.mjsgets less and skips setup.Change
docs.mjsnow redirects to the CLI instead of printing docs — for any invocation:@astryxdesign/cliform only — never the barenpx astryxfootgun (see 4/n astryx init foolproof: scope CLI invocation (no barenpx astryxfootgun) #4151).docs.mjsor greps it (redirect in both the banner and the file header).Why this is safe
Across the install harness (Opus 4.8 ×3, Sonnet 5 ×3) agents converge on the CLI +
initvia the README regardless —docs.mjsis rarely the path taken. This change closes the off-ramp for the cases that do land there (weaker models, greppers) and routes them to the current, richer source. Net: the doc surface everyone lands on is the maintained one.Trade-off: removes the bundled zero-install doc dump. Deliberate — the CLI is the canonical, current source and
component/buildcover the same ground with more detail.