What's New

Release notes and changelog for all packages.

0.7.7

New Components
  • astryx discover no longer lists InfoTip among the components @astryxdesign/lab contributes: InfoTip is a Core component now, described by astryx component InfoTip.
Performance
  • With TypeScript 5.3 or later, validateIntegration(), integrationComponentConflicts() and integrationCheck() from @astryxdesign/cli/api, and the commands that run them, reuse each TypeScript file a check parsed for later checks in the same process that parse it the same way, while the file is unchanged, instead of parsing it again for every check. Their results are unchanged.
Documentation
  • Hook docs for useOutlineFromMarkdown, so astryx hook useOutlineFromMarkdown and astryx search return it, and a useOutlineFromMarkdown — Docs Article example block: a Markdown article and an Outline built from the same string through the hook, with a button that adds a section and its linked entry.
  • The usePressFeedback — Pressable Card example now shows a small card in real playing-card proportions, with corner indices, a full face and a patterned back, and a line under it that says what to try: press and hold to see the press, tap, click, Enter or Space to flip. Copying the example (astryx template, the docsite's Code tab and Install) still gives you only the hook on a Card (width={120}, padding={1}) with one <Text> placeholder: the hint line is left out, not replaced.
  • A new useCombobox — Assign To Field example block spreads the field, listbox and option props from useCombobox onto a TextInput and a list of Item rows: typing filters a list of teammates, ArrowUp and ArrowDown move the active option while focus stays in the input, Enter or a press picks one, and Escape closes the list. Copy it with astryx template useComboboxHookUsage <path>.
  • A new useGridFocus — Color Swatch Grid example block wires useGridFocus to a color swatch picker in rows of eight: the grid has one Tab stop, the arrow keys move focus cell to cell, Home and End jump within a row, Ctrl+Home and Ctrl+End jump to the corners. Each swatch is a button, so Enter or a click picks it. Copy it with astryx template useGridFocusHookUsage <path>.
  • A new useListFocus — Recent Files example block gives a list of buttons keyboard navigation from useListFocus: ArrowUp and ArrowDown move between rows, Home and End jump to the first and last row, focus wraps at the ends, and only one row is in the tab order. Copy it with astryx template useListFocusHookUsage <path>.
  • A new useOverflow — Editor Toolbar example block shows the hook on its own: eight toolbar actions sit in a card you can resize, a hidden copy of the row holds every action plus the More menu marked data-overflow-indicator, and the actions that do not fit move into the More menu with no flicker. Copy it with astryx template useOverflowHookUsage <path>.
Contributors
Thanks to everyone who contributed to this release:

0.7.6

New Features
  • When a template imports Astryx's docs-only demo content, astryx template <name> <path>, astryx template <name>, astryx template <name> --skeleton, and astryx component <Name> --showcase replace each demo-content element with a marked <Text>Card content</Text> placeholder and remove the demo-content import, so the code they hand out never imports a module that only Astryx's own previews have. The placeholder uses the file's own Astryx Text import when that import is in scope, and otherwise imports Text, under an alias when the file already uses that name. template.copy and template.show gain demoContentReplaced (0 when the template carried none), their text output says how many elements became placeholders, and the components that template.show and template.skeleton list are the components of the returned source. No shipped template uses demo content yet, so every current template is copied, shown, and outlined exactly as before. The docsite's shadcn install of a block or page applies the same replacement and also replaces demo media, each with a marked placeholder: a placeholder image for an image and a data:,placeholder-video-add-your-own source for a video. The item's description says how many references and elements were replaced. The adjacent .astryx/<item>.json receipt keeps its current shape, so every released astryx upgrade still reads it. (#9430)
  • A theme's motion takes two knobs beside the duration scale: tempo (0.75–1.5) scales every motion duration, and character ('crisp', 'standard' or 'expressive') sets the new --ease-entrance and --ease-move tokens; --ease-exit stays the same at every character. Their types, ThemeMotionConfig, ThemeMotionKnobs and MotionCharacter, are exported. A theme without them renders exactly as before; a duration scale and explicit tokens win over the knobs, Spinner's and Skeleton's loops keep their timing under every tempo, and the press release fade follows tempo up to the 200 ms Reduce Motion cap under the person's setting. Springs don't read the knobs yet. The motion, token and theme-authoring docs and the theme template describe the knobs. (#8661)
Fixes
  • BottomSheet checklist examples use CheckboxList so the whole row toggles, not just the label (#9533)
  • The motion guide now says that under Reduce Motion, components cross-fade under a finger and change at once under a mouse, and that a value changing in place, such as a progress fill, takes its new value at once under any pointer (design:reduced-motion DR1–DR3). (#8615)
  • Published packages no longer include repository test and benchmark files, reducing install size without changing exports. (#9153)
Performance
  • Calling integrationComponentConflicts() or integrationCheck() from @astryxdesign/cli/api more than once in one process now reads each TypeScript file a package's tsconfig.json includes once while the file is unchanged, instead of on every call. A single astryx doctor integration components or astryx integration check run is unchanged. (#9422)
  • search() shares a catalog gather that is still running: searches that start together in one long-running process, such as a docs site's search right after it starts, now gather once instead of once each (#9460)
Documentation
  • A new useCollator — Locale-aware Name Sort example block sorts a list of names with the compare function from useCollator: accented and lowercase names land where a reader expects, and switching the provider locale to Swedish moves Å and Ö after Z. Copy it with astryx template useCollatorHookUsage <path>. (#9510)
  • A new usePressFeedback — Pressable Card example block shows the hook on an Astryx Card: the hook's marker and the interactionOverlayStyles.backgroundImage overlay go straight on the Card, so pressing the card darkens it the way every Astryx pressable does, under a finger or a mouse (Enter or Space flips it), and focusOutlineStyles.focusVisible gives keyboard users the shared Astryx focus ring on it. Copy it with astryx template usePressFeedbackHookUsage <path>; the docs-only playing card it shows becomes a <Text> placeholder for your own content. (#9431)
  • A new useToast — Settings Saved example block calls the function from useToast on a settings form: Save shows a "Settings saved" toast with an Undo action, its uniqueID makes a second Save replace the toast instead of stacking another, and a failed save shows an error toast instead. Copy it with astryx template useToastHookUsage <path>. (#9512)
  • A new useTranslator — Load More Footer example block gets a list footer's "Load more" label and its "Showing 3 of 9" count from the function useTranslator returns. The app's own message keys are supplied per locale through InternationalizationProvider, so switching the provider to French changes both strings. Copy it with astryx template useTranslatorHookUsage <path>. (#9573)
Other Changes
  • Preserved the v0.7.5 upgrade codemod registry when the release outputs returned to main (#9086), so the v0.7.6 CLI continues to offer that migration.
Contributors
Thanks to everyone who contributed to this release:

0.7.5

Experimental APIs
  • New command astryx experimental render <page> turns a page built with your installed Astryx components into one self-contained HTML file. The file needs no network and no scripts, follows light and dark mode, and carries the page's source; astryx experimental render --reverse <file.html> writes that source back. Warnings point out anything that may not look as intended. Experimental commands may change or be removed in any patch release. Guide: astryx docs cli/experimental/render-pages.
  • Building an icon-set package from an icon library takes fewer steps and fewer guesses. Only the experimental icon commands, the icon-set guide, and astryx template in a project that sets experimental.iconSet change; without that opt-in, stable commands behave as before, and only the experimental group's summary in astryx help and astryx manifest now mentions icon sets.
    • experimental icon new-set. --from maps a definition only when an icon has its exact name and lists those for review; likely matches come back as at most three suggestions each, never written. It saves the library and version, copies the library's license notices, keeps your --exclude list across refreshes, and its receipt names the package entry, peer dependencies, and typecheck script to add. --variants, --default-variant, --display-name, and --description fill in the set. A refresh changes only the icons that library supplies, keeps each icon's export name, and lists renamed icons. A 1,600-icon library is read in about two seconds.
    • experimental icon add and map. add --variant <name> --from <module> --all adds a variant for every icon at once, and map --pairs a=b,c=d writes many entries in one checked step.
    • Icon commands now refuse options that conflict instead of silently ignoring one (ERR_INVALID_OPTION), leave every file as it was when they fail partway (ERR_WRITE_FAILED), and report a missing or withdrawn set the same way everywhere (ERR_NOT_FOUND).
    • experimental icon --set <set> --all-icons lists every icon in a set, and --definitions lists every Astryx icon definition.
    • Templates drop a mapped icon library's sizing props (size, strokeWidth, absoluteStrokeWidth) and keep comments on rewritten imports.
    • Thirteen new icon definitions: rotate, flipHorizontal, flipVertical, alignStart, alignCenter, alignEnd, panelLeft, panelRight, gitBranch, gitFork, scale, cpu, and textCase. Definitions gain common glyph names as search words; seven optional definitions lose a word that named a different thing: star (bookmark), database (table), raiseHand (stop), redo (forward), activity (monitor), archive (store), mobile (device).
    • integration check suggests icons by the same rule, describes each optional definition, and its version-drift warning gives the refresh command.
New Features
  • Status colors are readable everywhere they appear, and Info is a status of its own. Each status (info, success, warning, error) now has a strong fill (--color-<status>) with content on it (--color-on-<status>, at least 4.5:1), a pale fill (--color-<status>-muted) with its content (--color-on-<status>-muted), and readable text for the page and cards (--color-text-<status>). Status icons (--color-icon-<status>) and borders (--color-border-<status>) default to the readable text color. The Info roles (--color-info, --color-on-info, --color-info-muted, …) are new and no longer borrow your accent color.
    --color-success, --color-warning, and --color-error and bg-<status> keep their meaning as the strong fills. In Tailwind, bg-info, bg-info-muted, text-on-<status>, text-on-<status>-muted, and text-status-<status> are new; text-, decoration-, placeholder-, and caret-<status> now use the readable text shade, and border-, divide-, outline-, and ring-<status> use the border shade, while bg-, accent-, fill-, stroke-<status>, shadows, and gradients keep the strong fill. For example, Core's light text-warning is now [#753](https://github.com/meta/astryx/pull/753)F07 instead of #E9AF08. To keep the fill color on text, write text-[var(--color-warning)].
    What changes on screen:
    • Core's dark Error content (--color-on-error) is now [#0](https://github.com/meta/astryx/pull/0)A1317 instead of white, so text on dark-mode error fills reaches 4.5:1. Core's Info Badge uses [#0064](https://github.com/meta/astryx/pull/0064)E0 instead of the accent ([#2694](https://github.com/meta/astryx/pull/2694)FE in dark mode).
    • Status icons (Icon color="info|success|warning|error"), Stepper status glyphs, and Chat tool-call status icons use the readable shades. Core's light success icon is now [#09441](https://github.com/meta/astryx/pull/09441)F instead of [#0](https://github.com/meta/astryx/pull/0)D8626.
    • Input and FileInput status borders use the border shades. Core's light warning border is now [#753](https://github.com/meta/astryx/pull/753)F07 instead of #E9AF08, and Butter's light success and warning input borders reach 3:1.
    • Banner draws its title, description, icon, and controls in the on-muted colors, and fills Info with --color-info-muted.
    • Status fills keep a visible edge in forced-colors mode.
    • Content on Chocolate and Matcha success and error fills, and on Stone success, warning, and error fills, now reaches 4.5:1.
    • Every first-party theme sets a blue Info. Chocolate and Matcha Info Badges move from the accent to that blue; Butter keeps its own Info Badge colors.
    • Neutral's --color-success, --color-warning, and --color-error are now the fills its Badges already showed, and its --color-info is [#0074](https://github.com/meta/astryx/pull/0074)E2 ([#6](https://github.com/meta/astryx/pull/6)D9CFE in dark mode). Its Badges, StatusDots, progress fills, and Stepper badges look the same; its accent ProgressBar, StatusDot, and Stepper now use Neutral's accent instead of blue.
    • Neutral no longer defines its undocumented local status tokens. Use the standard roles instead: --astryx-theme-neutral-color-status-fill-success, -status-fill-warning, and -status-fill-error → --color-success, --color-warning, --color-error; -status-muted-accent → --color-info-muted; -on-tint-neutral → --color-neutral; the -on-tint-overlay-* and -destructive-overlay-* tokens → --color-overlay-hover and --color-overlay-pressed. --astryx-theme-neutral-color-status-fill-accent keeps its value but is deprecated.
    Custom themes get the content and text roles they don't set: they are derived from the theme's status fills. To keep a component's previous color, set the matching role, for example --color-icon-success to your old --color-success.
  • CodeBlock's tokenizer prop is deprecated in favor of a custom language: pass language={createCodeLanguage({name, identifiers, tokenize})} with the same function. The prop still works. astryx upgrade rewrites it when the block has a fixed language, and leaves a TODO comment where it can't safely rewrite it.
  • Icon takes an optional variant to ask the active theme for alternate artwork, for example <Icon icon="info" variant="filled" />. The theme's icon receives the variant only when the theme lists it in iconVariants; otherwise it draws its normal artwork. Icons you pass as components never receive variant, and it is never written to the page. Icons without variant render as before.
  • A theme icon can now pick its artwork by size: an entry in defineTheme({icons}) or registerIcons() can be a function of {size, variant}, and Icon calls it with the size it renders at. Returning null draws no icon. getIcon, getExtendedIcon, getIconRegistry, useIcon, and a theme's icons field still return nodes, reading a function at {size: 'md'}. Existing icon entries are unchanged.
  • A theme can list the icon variants it supports, such as filled, with defineTheme({iconVariants}), and read them back from theme.iconVariants. Child themes inherit the list unless they set their own. @astryxdesign/core/Icon exports IconVariantMap and IconVariant for typing variants. Themes without iconVariants are unchanged.
  • astryx theme build keeps function icons and icon variant lists, so a built theme draws each icon at the same size and variant as the live theme, including icons inherited from another theme. A theme that lists iconVariants gets matching types in <theme>.variants.d.ts. Themes without these features build exactly as before.
  • Themes can set the real size of each Icon size: width and height in px or rem on components.icon['size:sm'] (or xsm, md, lg) now resize the glyph itself, for named icons and SVG components, in live and built themes. Before, they sized only the box around the icon. Sizes a theme does not style still render at 12, 16, 20, or 24px at a 16px root. astryx docs theme gains an Icon sizes section.
  • New --ease-exit motion token for things leaving the screen, beside --ease-standard for things arriving. BottomSheet already closes on it, so nothing looks different, but a theme can now tune the exit. astryx docs motion and the theme template list it.
  • astryx upgrade finishes instead of failing when it finds code it can't migrate safely: each spot is listed in declinedCandidates with its file, line, and a reason starting manual migration needed (<codemod>):, and the run exits 0. Generated files that need rebuilding, such as stale theme CSS, are listed in a new regenerate field with their rebuild command until they are rebuilt; a hooks.postCodemod that rebuilds them clears the entry. Protected generated files still stop the run as before, now with the rebuild command listed.
  • The two Bottom Sheet flow templates (BottomSheetSwitcherShowcase, BottomSheetSwitcherReviewFlow) now show the standalone-step pattern that replaces BottomSheetSwitcher, and are also listed under BottomSheet. Template names and ids are unchanged.
Fixes
  • Projects that compile StyleX with @stylexjs/unplugin (the standard Vite setup) are detected as StyleX projects.
  • The Tokenizer showcase template's search returns matching tags again, so the live example on the Tokenizer docs page works.
  • astryx integration verify no longer fails with "npm pack failed" when another npm wrapper comes first on your PATH.
  • astryx upgrade skips vendored, generated, or ignored files it can't parse, lists them in declinedCandidates, and finishes the rest of the upgrade.
  • astryx upgrade no longer spends minutes reading symlinked node_modules folders or package stores.
  • astryx upgrade --from a version before 0.7.0 no longer fails on var(--color-data-*) without a fallback. Source builds that read raw data colors should import dataVars from @astryxdesign/core/theme/dataTokens.stylex.
  • Tools that call the CLI API repeatedly, such as a docs site search, now see doc edits without restarting.
  • Component families list the same members whether or not the package has been built, so Lab's TourStep now appears in the official package list.
  • astryx upgrade handles an astryx.config written as const config = {...}; export default config;.
  • astryx component <name> suggests the right component when you type a wrapped or prefixed name.
  • When astryx component, astryx template, or astryx docs finds nothing, its suggestions stop where the matches get weak instead of listing unrelated entries.
  • astryx upgrade to 0.7 no longer turns your own MetadataList class into a data-columns selector that never matches.
  • astryx discover lists the experimental MobilePowerSearch component from @astryxdesign/lab.
  • astryx theme build reports a theme file that fails to load instead of guessing the theme from its text.
  • astryx theme build fails with a clear error when your project's @astryxdesign/core can't load, instead of silently building with the CLI's own copy.
  • astryx upgrade to 0.7 leaves other libraries' theme objects alone.
  • A failed astryx upgrade now lists the files it already changed: its --json error includes a receipt with modifiedFiles, errors, protectedFiles, complete: false, and errorCode. The error code and exit code are unchanged.
Documentation
  • The Tokenizer templates size their field to fit phone screens.
  • The CodeBlock snippet example shows one-line commands with Copy beside them.
  • Package links now point to the project's GitHub home, meta/astryx.
  • TabList's description no longer promises a built-in "more" menu (a narrow tab strip scrolls), and the library page template describes MobileNav as the slide-out drawer it is.
  • The theme guide and generated theme files explain that an extending theme's motion settings inherit field by field.
  • The disabled Thumbnail template now describes its buttons correctly: they stay focusable and are announced as disabled.
Contributors
Thanks to everyone who contributed to this release:

0.7.4

Experimental APIs
  • Icon sets: an integration can ship an icon set, agents find icons by meaning and get the exact import line, and copied templates use the project's icons. Everything here is experimental and may change or be removed in a patch release; a project that does not set experimental.iconSet sees no change in any stable command, apart from: the marked experimental group in help and in astryx manifest (its command, and its responseTypes and jsonSupported entries); the marked experimental entries in the astryx docs cli listings; and a search for "experimental", which also finds the new stable stability field of the field reference. astryx search returns no icon and no experimental doc. With a package that ships icon sets installed and no opt-in, the warnings an older CLI gives about the manifest key experimental (in astryx doctor and astryx doctor integration validate <package>, and the one-line nudge other commands print to stderr) are gone, and doctor integration checks that package's icon sets only in a project that sets experimental.iconSet; and astryx integration check reports icon-set findings for a package that declares experimental.iconSets (below). (#7759)
New Features
  • Keep Butter's released butterPalettes object byte-identical while moving the maintained Light/Dark theme to reviewed named palette stops. Signature Blue [#225](https://github.com/meta/astryx/pull/225)BFF, Butter Yellow #FDEE8C, and warm body surfaces remain exact; status fills move from success [#91](https://github.com/meta/astryx/pull/91)D143 to [#7](https://github.com/meta/astryx/pull/7)BBF7A, warning #FFC502 to #DFCF5B, error #FC473B to #E56241, and info [#4883](https://github.com/meta/astryx/pull/4883)FD to [#4](https://github.com/meta/astryx/pull/4)D82FF. Info and error content changes from white to warm Neutral [#1](https://github.com/meta/astryx/pull/1)D1C11, the neutral Badge uses Blue [#194](https://github.com/meta/astryx/pull/194)CE8, and light TopNav items use Blue [#225](https://github.com/meta/astryx/pull/225)BFF / [#194](https://github.com/meta/astryx/pull/194)CE8; these palette-first pairs clear normal-text AA. Consumers that need the former appearance can extend butterTheme and override the affected color, syntax, shadow, and component values with their previous values. The CLI template ships the same private palette request, receipt, and runtime-sized references. (#7672)
  • Docs can mark an experimental surface: every doc type except ThemeDoc and IconSetDoc, and every schema field and enum value, accepts stability: 'experimental'. A marked command shows [experimental] in help, a marked schema field or enum value is left out of its stable table so its feature's own docs describe it, and astryx search leaves out a marked doc, which is read on its own route. For the package being authored, doctor integration validate (and so integration check) adds olderCliNotes, each {file, kind, field, message}: a template or namespace doc that sets stability, or a template that declares icons, while the package's CLI peer range admits a release before 0.7.4, which drops that descriptor. A note is never an error or a warning and never fails a check, under --strict or --next; text output prints "Notes for older CLIs". Docs and findings that use none of these read exactly as before. (#7759)
  • Docs can write commands so every reader sees their own: {@command docs theme} for an Astryx command, {@pm install @acme/widgets --dev} for a package-manager step, and {@pm-only npm "<reason>" pkg set name=x} for a step only one package manager can do. The CLI shows each one with the reader's runner and package manager (npm, pnpm, Yarn 1, Yarn 2 and newer, or Bun), and {@@…} shows a token as written. astryx docs authoring/building-blocks/docs/doc-syntax documents them. doctor integration validate lists each command a topic writes for one package manager (package_manager_command), bare (plain_command) or with a runner (runner_command), and each token that does not parse (doc_token), each with the token to write. (#7868) integration check --next counts the findings the next minor release turns into warnings, the notes marked next, as warnings now, so --strict --next fails on them. Every run says how many there are. Without --next, integration check --strict exits as before.
  • An integration's doc can now replace or extend one of the CLI's guides by its route, such as replaces: 'authoring/quick-start' or extends: 'authoring/quick-start', so a package changes the guide agents already read for every app that installs it. An extension's section can set before or after to a section's key to go there instead of at the end; an older CLI rejects those fields, so integration verify warns when the package's @astryxdesign/cli peer range admits one. Every read names the replacing or extending package: package on the guide and on each section, and a replaced topic or guide now also carries replacedPackage beside replaces (in docs, docs --index, the topic list, and a namespace's children), with a replaces <package>'s <topic> line in text. A name that holds no topic or guide (such as a namespace) changes nothing, and a before or after key that names no section adds the section at the end: integration validate lists each as a note (doc_target_not_found, doc_section_unplaced), and two docs of one package that replace one guide as duplicate_guide_replacement; none fails anything until the next minor release. (#7936)
  • astryx doctor --built <path> checks a finished build before you deliver it: a project folder, a build output folder, or one built HTML file. built-astryx-usage fails when the path holds no import from an Astryx package (any @astryxdesign/* package, or an integration the project installs: a declared dependency whose installed copy has an integration manifest), no component imported from one, and no Astryx styles in built CSS or HTML, and names the template-first way to rebuild it. built-astryx-purity warns with the source check of astryx docs is-my-code-good: raw elements Astryx has a component for, raw SVG and icon-library icons, inline styles, classes, stylex.create and imported stylesheets, each with its file and line, or says the source was not inspected when the path holds no source with JSX, such as a bundle. The files under the path and that package.json are only read; nothing in them runs. Without --built, astryx doctor runs exactly as before. (#7886)
  • Keep Gothic's released flat gothicPalettes compatibility export unchanged while moving the maintained dark theme to a reproducible generated palette and named stop mappings. The card changes from [#1](https://github.com/meta/astryx/pull/1)A1D20 to [#191](https://github.com/meta/astryx/pull/191)D20; Gray background and border from [#3](https://github.com/meta/astryx/pull/3)D4248 / [#5](https://github.com/meta/astryx/pull/5)D646B to [#3](https://github.com/meta/astryx/pull/3)E454B / [#5](https://github.com/meta/astryx/pull/5)E676E; syntax comment and punctuation from [#6](https://github.com/meta/astryx/pull/6)B7079 / [#7](https://github.com/meta/astryx/pull/7)A8290 to [#7](https://github.com/meta/astryx/pull/7)E8791 / [#7](https://github.com/meta/astryx/pull/7)E8791; and diff backgrounds from [#081408](https://github.com/meta/astryx/pull/081408) / [#1](https://github.com/meta/astryx/pull/1)E0A0A to [#071607](https://github.com/meta/astryx/pull/071607) / [#220806](https://github.com/meta/astryx/pull/220806). Success, warning, and error inset rings move from [#87](https://github.com/meta/astryx/pull/87)B06A50 / #D6B56A50 / #D4485150 to [#869](https://github.com/meta/astryx/pull/869)B7250 / #D3C49050 / #C6A6A250. Yellow text moves from [#6](https://github.com/meta/astryx/pull/6)C5010 to [#573](https://github.com/meta/astryx/pull/573)F0B, and Pink text from [#71223](https://github.com/meta/astryx/pull/71223)C to [#5](https://github.com/meta/astryx/pull/5)C182F; both darker named stops clear 4.5:1 on their categorical surfaces. Consumers that need the former appearance can extend gothicTheme and override these color, syntax, shadow, and component tokens with their previous values. The CLI template ships the same request, receipt, and runtime-sized references. (#7670)
  • doctor integration validate, and so integration check, lists what a package's examples need to work everywhere they are shown, as notes for the next minor release (integration check --strict --next fails on them now): (#7891)
  • Move Matcha's existing color roles onto its reviewed light and dark ramps, including Tea Gold. Warning and Yellow move from #FFB600 / #FFC940 to #F2C000 / #F6D066; related syntax colors and warning inset rings follow the same palette. Consumers that need the former appearance can extend matchaTheme and override the affected color, syntax, shadow, and component tokens with their previous values. The complete Matcha palette remains private authoring data, and the CLI template ships the same request, receipt, and runtime-sized references. (#7671)
  • astryx theme palette generate receipts now name the generator implementation (generatorVersion: 'palette-generator-v1') and the format of the candidate bytes they hash (candidateFormatVersion: 'palette-typescript-v1' for a .ts output, 'palette-json-v1' for a .json output or a printed candidate). candidateSha256 and every other receipt field keep their meaning, values, and order, so existing readers keep working. (#7678)
  • Replace Stone's internal shared-ramp mapping with reviewed light and dark ramps while preserving the public numbered palette lookups and hue/chroma metadata. The light canvas moves from #F3F3F5 to #F0F0F7, the dark popover from [#25252](https://github.com/meta/astryx/pull/25252)A to [#302](https://github.com/meta/astryx/pull/302)F36, and Green, Yellow, Teal, and Cyan use re-seeded midtones (including Green [#667](https://github.com/meta/astryx/pull/667)D65 to [#528](https://github.com/meta/astryx/pull/528)B49). Seven families' light stop-90 surfaces, syntax colors, and input status rims shift; the mapped success and warning rims use [#609757](https://github.com/meta/astryx/pull/609757) and #A08C36, and syntax attribute uses [#736419](https://github.com/meta/astryx/pull/736419), keeping the required contrast floors. Existing apps can keep the former appearance by extending stoneTheme and overriding the affected color, syntax, shadow, and component tokens with their previous values. The CLI template ships the same reproducible request, receipt, and runtime-sized references. (#7669)
  • When the project's installed CLI (its own, or its workspace's) has astryx doctor --built (0.7.4 and later), the agent docs astryx init writes tell agents to run it before they deliver a build, and not to deliver a build that fails it. Before install, or on an older CLI, the line is left out; the next init or upgrade --apply adds it. (#7944)
  • Keep Y2K's released y2kPalettes object byte-identical while moving the maintained Light/Dark theme to reviewed named palette stops. Periwinkle #CCCFFA and Neon Green #C5E17A remain exact; syntax becomes brighter, the dark code background moves from [#190](https://github.com/meta/astryx/pull/190)F00 to [#0](https://github.com/meta/astryx/pull/0)E0F1A, and dark Gray background moves from #EDE0D4 to #DFE2F3. The necessary dark input and unchecked-selection outline moves from the released [#3](https://github.com/meta/astryx/pull/3)A3F5E to Neutral Dark 45 [#636889](https://github.com/meta/astryx/pull/636889), raising contrast on the input surface from 1.71:1 to 3.23:1. Consumers that need the former appearance can extend y2kTheme and override the affected color, syntax, shadow, and component values with their previous values. The CLI template ships the same private palette request, receipt, and runtime-sized references. (#7675)
Fixes
  • astryx doctor --built no longer counts a type-only Astryx import (import type, import {type X}, export type … from) as Astryx use, since the build erases it. (#7945)
  • Discover results name their source package and tolerate typos. (#7147) Every discover JSON result now names its package per the provenance rule: single-artifact responses (discover.detail, discover.detail.doc, discover.item) carry package in the envelope, and list entries (discover.list, and each entry of its meta.available) carry package. Text output matches: an opened doc prints its package: line on stdout.
    discover <words> now has the same typo tolerance as search: a near-miss name (edit distance 1–3, with minimum-length guards) returns results instead of "not found". Previously discover Geodetics said "not found" while search Geodetics found geodesic.
  • astryx search finds a family member by its name spelled out, as its own description spells it ("vertical stack" is VStack), and lists a member named by its head word after single letters (VStack, HStack) for that word ("stack"). (#7927)
  • astryx search lists the first three members a family's doc names for a query that is the family's name ("table" lists three Table parts after Table; "chat" lists Chat parts though no Chat component exists), for Core and integration families alike. (#7955)
  • astryx search orders results the matcher scored the same by fit instead of by name: below the first result, a part of it leads (BadgeCountBadges after Badge), then the result matching the query's rarer words. Scores and the first result are unchanged. (#7959)
  • astryx integration verify works on npm 8 for a scoped package: npm 8 names the tarball @scope/name-1.0.0.tgz in its pack output but writes scope-name-1.0.0.tgz, so verify reads the file npm wrote instead of failing to find it. (#7933)
Documentation
  • Four block templates (MetadataListItemBasic, SegmentedControlItemBasic, VisuallyHiddenSupplementaryContext, ItemWithMetadata) now describe what each one shows and when to use it, written from what the block renders. (#7963)
  • The BottomSheetSwitcher template docs (BottomSheetSwitcherShowcase, BottomSheetSwitcherReviewFlow) describe each step as its own native dialog under one scrim, as the component now renders, instead of "one shared dialog". (#7720)
  • The CommandPaletteItem showcase block now describes what it renders, an inline command palette whose items pair each label with its keyboard shortcut, and lists only the components it uses. (#7967)
  • Discover data: list the Lab ListInput blocks (the Tag options showcase and the Mailing list, Budget allocation, and Family member declaration examples) as templates. (#7953)
  • Six guide titles read more plainly and use the same sentence case as the rest: Theme System is now Theming, Styling Components is Styling components, Browser Support is Browser support, Migration Guide is Migration, Styling Library Interop is Other styling libraries, and Looking up components is Component lookups. Only the titles changed: every route still opens the same doc (astryx docs theme, astryx docs styling-libraries, astryx docs cli/component-lookups), and searching by an old title still finds it. (#7934)
Other Changes
  • Commands. The new astryx experimental group holds experimental commands; icon sets are its first. astryx experimental icon <words> ranks icons across the installed sets (icon.search), <set>/<id> reads one icon with every variant's import line (icon.detail), and --list lists each set with its definition coverage (icon.list). Authoring: experimental icon new-set <name> starts a set (--from <module> wraps every icon a library exports, --exclude drops exports that are not icons), experimental icon new-definition <name> adds a set's own icon definition, experimental icon add <Export> --from <module> verifies an export and lists the definitions that fit it or adds and maps it (--variant <name> adds it as a variant the set declares, a named look such as solid; size comes from CSS), experimental icon map <definition> <icon> edits one map entry, and experimental icon use <set> picks the project's set. The API gains icon, iconAdd, iconMap, iconUse, iconNewSet, and iconNewDefinition, all marked @experimental.
  • Configuration. The project's set is experimental.iconSet in astryx.config; an integration declares its sets folder as experimental.iconSets in its manifest. Each set has a typed <name>.doc.mjs (IconSetDoc), a <name>.icons.json data file, and an optional definitions/ folder; @astryxdesign/cli/authoring exports IconSetDoc, IconSetData, IconDefinitionDoc, and their parsers. An older CLI warns that experimental is a manifest key it does not know, and a CLI before 0.7.4 refuses an astryx.config that sets experimental.iconSet ("Unrecognized key"), so commands that load the project configuration, such as doctor and discover, fail in that project; astryx experimental icon use says so in its receipt (warning) when the project's @astryxdesign/cli range admits such a release.
  • Where icon sets show up. Icon lookup by meaning is only astryx experimental icon: astryx search never returns icons or experimental docs, with or without a set. A project that sets experimental.iconSet also gets astryx template replacing each icon a template declares in its new icons field (a named import by the name it imports, a default import by its local name) with that set's icon, every key reported as mapped or kept in an icons receipt field, astryx discover reading icon-set as a kind (--type icon-set, and catalog entries of that kind), and an icon-sets check in astryx doctor. Without it, none of these change: templates are copied as they are, --type icon-set is an unknown type and catalog icon-set entries are ignored, and Doctor reports nothing about icon sets, even an invalid one. astryx integration check reports icon-set findings for a package that declares experimental.iconSets, and lists, in the validate result's additive iconSets field, the optional Astryx definitions each set leaves unmapped, with the icons that fit, and what it cannot judge (unchecked: an icon whose module is an exports target not built yet, an icon or adapter export it cannot prove either way, such as one behind a re-export it cannot follow or bound to a default import, and a theme map or entry it cannot read; only an export it proves absent fails), printed under "Not checked"; neither list is ever counted or fails a check, even under --strict or --next. It also notes each template icons key the template's source never imports (template_icon_not_imported), which fails nothing, under --next too.
  • Docs. The guide and every icon definition live under astryx docs cli/experimental, and every icon-set doc is marked stability: 'experimental'. The experimental icon-definitions namespace adopts definition docs from every package (source.packages: 'all', read only on a CLI namespace marked experimental).
  • component_without_example: a published component that no block template shows with exampleFor: '<Name>' and isShowcase: true (or alsoShowcaseFor). A block named like a showcase that sets neither does not count. Hidden docs, family members, docs with isHiddenFromOverview and Utility components are exempt. The note carries a template doc to paste.
  • template_category: a template category written as a path, such as components/X, with a "<Group> - <Variant>" one to write.
  • showcase_not_standalone: a showcase (a block with isShowcase: true or alsoShowcaseFor names) that imports what a browser cannot load (server-only, next/headers, next/server, next/cache, a Node built-in) or reads process.env past NODE_ENV. Type-only imports and comments don't count, and live data through the app is fine.
  • template_asset_not_packed: a file or folder a template loads with new URL(…, import.meta.url) that does not exist, sits outside the package, or that npm leaves out of the package: by files in package.json (the note names a ! entry that excludes it), or by a .npmignore or .gitignore line (the note names the line). What npm pack --dry-run packs decides; when npm cannot answer, an asset it may pack is listed under data.exampleAssets as not checked.
Contributors
Thanks to everyone who contributed to this release:

0.7.3

New Features
  • astryx build names the right block first far more often. It ranks every block in the catalog by what the request means, read from each block's own name, description, and component, so a block that word matching missed can still come first, with its own score and reason; and the block picker's fixed values are refitted on a larger, more varied set of written example requests, which helps most with requests worded in a product's own terms. A block the request names by its exact name, and a block from an integration, keep their place. The kit never lists more blocks than before, and its fields, page call, start template, and alternatives are unchanged.
  • astryx search puts the entry you are after first more often: it orders the matches inside each score band, every result keeps its match score and reason, and a query that is an entry's exact name still answers with that entry first (#7752).
  • astryx doctor integration validate and astryx integration check check the component names a package's docs and blocks give, and list what they find as notes beside validate's issues, each with its fix. Nothing counts a note and integration check --strict does not fail on them; they become failing warnings in the next minor release:
    • doc_name_mismatch lists a component doc whose name is not the name the component is listed under when the module its printed import names (the doc's import, the published subpath, or the package root) provably does not export that name, so astryx component would print a broken import. The Fix: proposes the file name when that module exports it, otherwise the component it exports. A name that module's exports cannot prove or rule out (a re-export from another package, export =, a destructured binding, a namespace, an import that resolves to no file, or, when no import can be resolved, a source that only exports a default) is listed as not checked, with the reason, in validate's new docNames report.
    • unknown_block_component lists a name a template's exampleFor or componentsUsed gives that neither the package nor Core has (every doc astryx component resolves in Core counts) and the template does not import it. Imports the template's local helpers make count too, including through a barrel such as parts/index.ts. A name is judged only where the template reaches components solely through named imports and re-exports from Core, React, StyleX, local helpers read in full, or the package's own name (followed through its exports like a helper). Anything else is listed as not checked in validate's new blockComponents report: an import from another package, which may render other components; any default binding other than React's or StyleX's; a namespace import; an alias of or member read off an imported binding; a component held in a variable; require(); a dynamic import(); a file that does not parse cleanly; a local module this check cannot read; and, without Core installed, any name only Core could resolve.
    integration check --strict does not fail on anything listed as not checked.
  • New @astryxdesign/cli/host entry for tools that carry the CLI: runHostedCli runs the CLI once per process, with the command name that tool's users type (printed commands start with it) and, when the tool skipped the project's own CLI, the reason, so that CLI is never run.
    js
    import {runHostedCli} from '@astryxdesign/cli/host';
    ​
    const result = await runHostedCli({
    argv: ['search', 'button'],
    cliCommand: 'acme astryx',
    });
  • astryx doctor integration validate now notes, from source and without a build, what an integration package tells apps to import that they cannot import, the way it lists an ignored cliCommand. Each note is in data.notes and names its fix, such as the exact exports entry to add. Notes are listed only: neither doctor integration validate nor astryx integration check --strict counts or fails on them in 0.7.3, and they become failing warnings in the next minor release, so fix them now. It notes:
    • a component's import (the doc's import, or the one the CLI derives when the doc has none) or a template's public import whose subpath package.json exports does not declare, or that names another package. A subpath is not declared by a missing key, a key whose only conditions an ES module import does not load (such as require or types), an exports that is a single string, a wildcard that does not match, or an empty exports map;
    • a component example that imports a subpath the package does not declare;
    • a template that imports a relative path outside the templates root, or a path its own package or Core does not export.
    A subpath is judged from its exports declaration alone, never by its target file, so exports may point at build output that does not exist yet; whether that module exports the names an import asks for is the next entry's check. Wildcards and condition objects with import or default pass. An import of a subpath whose exports entry has only types targets, or that an ES module import reaches only through types (such as types beside require), is never judged as a run-time import: it passes when it is import type, when every binding is an inline type, or when every name it imports is one the types file declares as a type, and is listed under unchecked otherwise. A types target under require does not count, and a package with no exports keeps its deep paths to files it ships. What it cannot judge (in a package with no exports, a deep path into build output not built yet, such as dist/; a template import of Core when @astryxdesign/core is not installed beside the package; every import of the package's own name when package.json has no name) is listed under unchecked in a new publicImports report on the result ({status: 'checked', findings: [], unchecked: [{file, specifier, reason}]}), which integration check counts as not compared.
  • astryx doctor integration validate now also notes, from source and without a build, an import that names something its module does not export (in data.notes, each with its fix). These notes are listed only in 0.7.3 too, and become failing warnings in the next minor release. It notes:
    • a component's import (the doc's import, or the one the CLI derives) that leads to a module that does not export the component, naming the subpath that does or the exports entry to add;
    • a component example or a template that imports a name the package does not export;
    • a template source with no default export (astryx template still copies it, but its public import and anything that renders it get nothing), suggesting an exported PascalCase function, class or const, never a hook such as useAccount, a helper such as formatBalance, an ALL-CAPS constant or a type; with none, the fix stays generic.
    A name is judged only when a file the exports entry names is there to read in full. export * is followed, cycles included; a built module's declaration file (x.d.ts beside x.js, and the .d.ts files its export * names) is read for the types it exports; export import Alias = Inner.Value counts as an export; TypeScript source resolves a ./x.js specifier to ./x.ts; and a declaration file that is a module exports every top-level declaration unless it has an export list, export *, export = or a default export of an expression, as TypeScript does. Whatever the reader does not fully model is listed under unchecked in the publicImports report instead of as a note: a file the exports entry names that does not exist yet; a module whose list cannot be read in full (CommonJS, export * from another package); a declaration file with no import or export (a global script); a name missing from a JavaScript module with no declaration file, which may be a type; and every name it would report, other than a component doc's own component, while a TypeScript file in the package (outside node_modules) has a parsed declare module block for a relative path, the package's own name or a subpath of it, since that can add names to the module. The reason names that file; declare global, a wildcard spec such as '*.css', another package's name and a declare module in a comment do not count, and a file with declare module in its text that cannot be parsed counts. astryx docs authoring/ship/checks explains each check.
  • A failed astryx component, template or docs lookup lists the entry you most likely meant first. Components that tie on match score are ordered by how early the name you typed appears in their keywords and by how close their names are, instead of alphabetically; among the suggestions offered, a component one of whose other names was typed (including another library's name for it, such as MUI TextField, with or without the library's name) comes first; a compound name that does not exist (a family part named with other words, or without one of its family's words) suggests the real part or its family. Templates are ordered by how closely their id or title matches the name you typed, and unknown docs routes by how closely the route matches. Suggestion lists never get longer, every suggestion is a real entry, and a name that resolved before still resolves to the same entry.
  • Integration docs that tell readers to run an Astryx command through a package runner now get a runner_command note from doctor integration validate (and so integration check) in data.notes, with its file, line and the bare astryx <command> to write instead. A note fails nothing, so integration check --strict exits as before. The unscoped name after a download runner (npx astryx) always counts, because it fetches an unrelated package; the scoped npx @astryxdesign/cli, for install steps, does not.
Fixes
  • astryx build starts from a page template its word weights do not list (an integration's template, or one added since the weights were fit) only when the request names as many words of that template's own display name, category and keywords (search's stopwords aside) as of the best listed template, or names that template's family (the first part of its category) before the listed template's family and at most two fewer of its words; otherwise it starts from that listed template and offers the other as the first alternative.
  • The CLI finds the project's @astryxdesign/core from any folder inside the project, so component, hook, build, search, swizzle, theme targets and doctor now work five or more folders deep, in workspace members whose Core the workspace installs at its root, and in Yarn Plug'n'Play projects. They still search the folders they searched before, and past them continue up to the workspace root of the nearest folder whose package.json declares an Astryx package.
    • upgrade --from run from any folder in a project upgrades that project: the nearest folder whose package.json declares an Astryx package or that an Astryx workspace lists, found without passing a repository root or counting the home folder. It targets only the project's own Core (the one in its node_modules, or for a member its workspace lists, the one the workspace installs), scans the project's src by default, reads a --path you type from the folder you ran in, names the files in its --json result relative to that folder, refreshes the project's agent docs, and names the project root and the source folder it scans before it changes anything. With no such project, upgrade reads only the current folder, as before.
    • An upgrade run in a folder that installs Core but declares no Astryx package now upgrades the Astryx project above it instead of that folder alone, since such a folder was never a separate upgrade root. To keep a sub-folder that installs Core its own project, declare an Astryx package in that folder's package.json.
    • A packages/core folder that holds another package is no longer read as Core, and an integration named in astryx.config now loads when the workspace installs it at its root, as an autolinked one already did.
  • The CLI's install advice no longer adds a package to a package.json that is not an Astryx project's. This covers the daily hint, the setup reminder, the update notice, astryx doctor's version-alignment and integration fixes, and astryx discover's install command for an integration installed for the computer. The project is the nearest folder whose package.json declares an Astryx package, or a member its workspace lists, never the home folder and never past a repository root.
    • From a folder inside such a project whose own package.json is not the project's, such as a tool folder that installs its own @astryxdesign/core, the daily hint that matches a project's CLI to its Core, the setup reminder and astryx doctor's version-alignment fix used to name a command that added the CLI to that folder's package.json, making it a separate Astryx project. They still compare the CLI with the Core the run reads, and when the two differ they say to run from the project's folder, or to declare an Astryx package in that folder; the update notice upgrades the project from its folder, with the project's release.
    • For an integration installed for the computer, astryx discover gives no install command from such a folder, and astryx doctor's fix says to run from the project's folder, where the command adds it for the project; in a folder that belongs to no project, neither names a command.
    • In a folder that belongs to no Astryx project, the hint, the setup reminder and the update notice no longer print, and astryx doctor's fix says how to reach a project.
    • Unchanged: the official packages astryx discover lists and the theme packages astryx doctor suggests still use the folder the command runs in; a member its workspace lists keeps its own advice; in a folder whose package.json declares an Astryx package, the advice is the same. No JSON shape or exit code changes.
  • astryx doctor integration validate, astryx integration check and astryx integration verify catch more package mistakes, and each new finding ends in a Fix: that clears it. Findings that 0.7.2 did not fail on are listed as notes beside validate's issues, which nothing counts, until the next minor:
    • Two docs for one component (AcmeWidget.doc.mjs and AcmeWidget.doc.js) are listed as duplicate_component_doc, naming the one read; discovery now always reads the same one.
    • A component doc whose file name differs from its source only in letter case is one finding that says which file to rename: an error where the pair fails (Linux), a listed source_without_component_doc where it still pairs (a case-insensitive disk); a hidden doc that does not pair keeps the source warning it had.
    • A root reached through a symlinked folder is listed as symlinked_root: npm pack does not follow it.
    • An absolute root says roots are relative and gives the relative path; a root that is a file is reported by every check instead of crashing it.
    • A package.json without name or version is listed with a fix, instead of a crash; verify fails on it. A package whose name and manifest providerId give no provider ID is listed as no_provider_id.
    • A contribution file Astryx cannot read is listed as unreadable_file, before npm pack fails on it.
    astryx integration check --strict does not fail on these pairing, root and package.json notes either; they become failures in the next minor. astryx integration verify still fails on a package.json npm cannot pack.
  • astryx doctor integration validate, astryx integration check and astryx integration verify say more plainly what is wrong in findings they already reported, and how to fix it:
    • An empty doc or manifest, or one with no default export, says so and names what it does export, instead of "(root): Invalid input".
    • A manifest key one or two letters off a known key asks "did you mean components?" before suggesting a newer CLI.
    • A theme descriptor named for the built file (ocean.doc.mjs beside a built ocean.js that lacks the ocean export) says it must share its stem with the defineTheme source, naming that source when the built module's Source: line or the source's defineTheme name confirms it.
    • A template doc with no source, a theme descriptor with no source, a theme source with no descriptor, and a component whose source is .jsx get a Fix:.
    • A theme source named for its theme (brand.ts) beside the module the build writes (brand.js) is told to take the brandTheme stem.
    • verify names packed files by their path in the package, not the scratch copy's; says npm pack does not follow a symlinked root instead of asking for a files entry; and, when a theme's defineTheme name differs from the files its package exports, says a rebuild writes files under the new name.
  • Integration authors now learn when the running CLI is outside their package's @astryxdesign/cli peer range: astryx doctor integration validate and astryx integration check list a cli_peer_version note naming the package, the range and the running version. Below the range the note gives the project's commands to install a newer @astryxdesign/core and @astryxdesign/cli together (as dev dependencies in the package's own folder) and then run astryx upgrade --from <version> --apply. Above the range it asks for a release of an installed package that supports this CLI, or asks the author of the package in the current folder to test with this CLI and widen the range. A note fails nothing: --strict, integration verify, doctor, and exit codes are unchanged.
  • astryx component <Member> --package @astryxdesign/core now answers with that member, as the unscoped lookup does. A Core component documented in its family's doc (HStack and VStack in the Stack doc) used to come back as the family doc, named after the family and with no props.
  • The agent guide that global mode writes to the home folder now tells agents to deliver a page built with Astryx, not only how to find things. Before, agents that found the right template could still build the page with a tool that cannot install packages and deliver a page with no Astryx in it. The guide now tells agents to work in a project folder (creating one if there is none); add @astryxdesign/core and @astryxdesign/cli to a new project or one without Core, or, in a project that already has @astryxdesign/core, the CLI at the same version; run astryx init there; follow the same template-first workflow and self-check the project agent docs give; and end by building the project and delivering that build. The guide stays version-free and names only commands every release keeps. The project agent docs are unchanged, and so is what @astryxdesign/core's install script prints: its copy of the shared agent-docs file only gains the same workflow lines.
  • Agents that follow the guide global mode writes to the home folder now know what to do when astryx is not found: run the command that installed the CLI for the computer first, with the same package manager and folder, such as npm i -g @astryxdesign/cli or pnpm add -g @astryxdesign/cli. On machines that keep the home folder but reset system folders on restart, the guide outlived the CLI installed for the computer and told agents to run a command that was gone. Outside a project, when the guide names astryx and no astryx command is on the search path, apart from a package runner's own copy, astryx doctor now says so and names the install step the guide records, or npm's when it records none. The global-mode guide for CI and containers explains how to keep the CLI across restarts. A guide written for a host's own command is unchanged. No JSON shape or exit code changes.
  • The butter, stone, and y2k themes no longer show the secondary hover fill on a disabled ComplexSelector trigger, whether the trigger is natively disabled or exposes aria-disabled="true", the focusable form every disabled control now uses. Before, the guard only recognized a natively disabled trigger. The themes astryx theme eject copies carry the same guard.
  • Apps that use Core's prebuilt CSS without a StyleX build step now get the default data colors: the prebuilt CSS defines the canonical dataVars defaults, so compiled imports and raw CSS references paint correctly.
  • astryx init writes the agent docs at the project root, in files the project commits, so Codex, Gemini CLI, Copilot CLI and Claude Code all read the block from the project root or any folder below it (#7497). It no longer writes agent docs into a project's subfolder, the home folder, or a settings folder in it such as ~/.gemini.
    • AGENTS.md holds the block, created when missing. Before, a project with only CLAUDE.md got the block only there, so Codex and Gemini CLI never saw it.
    • Claude Code skips AGENTS.md in a folder that has a CLAUDE.md or .claude/CLAUDE.md, so the Claude Code file the project already has keeps a full copy: root CLAUDE.md, else .claude/CLAUDE.md. It keeps the copy even when it imports AGENTS.md, because Claude Code does not follow that import in a session started in a subfolder; started at the root, Claude Code then reads two. When both exist, the copy goes in root CLAUDE.md, which projects commit even when they ignore .claude/, and a block in .claude/CLAUDE.md is removed. Init creates no Claude file. astryx upgrade refreshes every copy, except in a project at the top of a home settings folder (see the next entry).
    • Gemini CLI reads only GEMINI.md: init adds a one-line import, @./AGENTS.md, creating GEMINI.md when it is missing. It adds none when GEMINI.md already imports AGENTS.md, inline or on its own line. It adds the import even when the project's .gemini/settings.json has Gemini read AGENTS.md through context.fileName: Gemini loads those settings only when it starts at the project root, so a session started in a subfolder would otherwise get no copy. Started at the root, Gemini then reads two.
    • The project root is the nearest folder at or above where init runs whose package.json declares an @astryxdesign package, else the nearest with any package.json. The search stops at a repository root and never counts the home folder. With no package.json found, init writes where it runs, as before. docsWritten still lists each file relative to where init ran, for example ../../AGENTS.md.
    • A GEMINI.md that resolves outside the project, for example a link to a shared file, is skipped and reported in docsError with one note (not an error line), in the default layout and in a project's own layout; the rest is written and init exits 0.
    • The managed block belongs to Astryx: init and astryx upgrade write, refresh, and remove only the block, whatever ignore rules or generated markers say, as 0.7.1 did, and never change the text around it. Every write stays inside the project: run in the folder 0.7.1 wrote, an agent file 0.7.1 wrote there whose path leaves the project still refuses the run with exit 1. The project's Claude Code file (root CLAUDE.md, or .claude/CLAUDE.md when there is no root one) that resolves outside the project and is a block-less import of an existing AGENTS.md, which 0.7.1 left alone, is skipped and reported in docsError with one note, and init exits 0. Run from a folder below the project root, where 0.7.1 wrote in that folder instead, a project-root file whose path leaves the project is skipped and reported in docsError with one note, the rest is written, and init exits 0.
    • While root CLAUDE.md is untracked and ignored by the repository's ignore rules (any ignore file from the repository root down, such as a monorepo's root .gitignore, the local exclude file, or configured excludes; init asks git, Sapling or Mercurial), a .claude/CLAUDE.md the project commits gets the copy too, so a fresh clone still gives Claude Code a copy; --agent claude and --agent all write it there as well. A file the repository tracks counts as committed whatever the ignore rules say, as git and Mercurial ignore only untracked files, and when the repository cannot answer, the copy is kept, on the first run as on later ones. Such a copy that resolves outside the project refuses the run with exit 1 where 0.7.1 wrote it too; one 0.7.1 did not write (the one --agent claude adds, or a block-less import of an existing AGENTS.md) is skipped and reported in docsError with one note, and init exits 0. So is a .claude/CLAUDE.md whose block --agent claude would remove beside a CLAUDE.md, since 0.7.1's claude preset wrote only CLAUDE.md there. Beside a committed root CLAUDE.md, with .claude linked outside the project, three cases that 0.7.1 refused now exit 0 with nothing written: the default with a .claude/CLAUDE.md of plain text, and --agent all with one of plain text or a block-less import of AGENTS.md; root CLAUDE.md holds the copy, so no write leaves the project. In a project that keeps its own layout, a GEMINI.md that imports no agent file now gets a copy, as the other agent files do.
    • The copy in .claude/CLAUDE.md is removed only once root CLAUDE.md holds the same block, and only the managed block between its markers: the rest of the file stays, and the file is deleted only when nothing but whitespace is left. astryx init --remove-agents deletes a file it created only when nothing but whitespace or init's own heading is left; 0.7.0 also deleted a file whose remaining text had a heading and any line with the word "guidance".
    • astryx init --remove-agents removes the block at the project root, where init writes it, and in the folder it runs in. Run from a subfolder, it removes what init wrote at the root, and a block an earlier version left in that subfolder; a root agent file with a block that resolves outside the project is left as it is with a note, and the run exits 0, as 0.7.1 did when it touched only the subfolder. Exit codes and the JSON shape are unchanged.
    • --agent claude and --agent all never leave a block in both CLAUDE.md and .claude/CLAUDE.md, unless the project ignores CLAUDE.md: when CLAUDE.md gets the block, a block in .claude/CLAUDE.md is removed. --agent all keeps the GEMINI.md import. The --agent help and the working-with-AI guide say so. --agent-docs-path writes where init runs, as before.
    • astryx doctor fails when the GEMINI.md import points at an AGENTS.md with no block. The setup check in the CLI and in @astryxdesign/core no longer counts that import as set up, and looks at GEMINI.md. The reminder to run init that commands print looks at the project root too, so it stops once init has run in a nested package.
  • astryx init and astryx upgrade no longer write agent docs into your home folder, or into a settings folder in it such as ~/.gemini or ~/.claude outside a project. Agents read the files in those folders in every project, so a block there reached unrelated work. This follows the CLI's existing rules that no command writes agent docs into those folders and that a write outside a command's own folder is refused before anything is written.
    • Refused by init: the home folder itself, and the top of any folder in it whose name starts with a dot (every such folder is a settings folder), even when it holds a package.json. A folder below it with its own package.json is a project and is set up normally, such as an agent worktree in ~/.codex/worktrees/ or ~/.cursor/worktrees/, and astryx upgrade refreshes it. With --agent-docs-path, each file's own folder is checked: from the home folder, notes/AI.md is written as before, while AI.md or .claude/CLAUDE.md is refused.
    • What init does instead: it writes no agent docs, reports docsError as install-failed with the reason, and exits 0, as before.
    • Refused by upgrade: refreshing a block in a project whose root is the home folder or the top of a settings folder, such as ~/.dotfiles with a package.json, with or without --apply. It leaves the block as it is, sets agentDocs.action to error (never would-refresh), and warns with the folder and why; its other steps and its exit status are as before. With no block there, it gives the same reason instead of suggesting astryx init. astryx doctor's agent-docs fix does the same, and the setup reminder after each command stays quiet.
    • Migration: run astryx init from the project's own folder, or add the block to the file by hand. Move a project rooted at the home folder or a settings folder into a folder of its own, or update or remove its block by hand. To remove a block an earlier version wrote into ~/.claude/CLAUDE.md, run astryx init --remove-agents in the home folder.
  • Repeated searches in one process answer faster: astryx search reuses its entry index while the catalog is unchanged, and ties that reuse to one list of the fields the index reads, so the index is never reused after any of them changes. Every answer is unchanged.
  • Tools that bundle the CLI into a server function no longer pack their whole project folder into it: one path in integration check's import checks was built in a way file tracers cannot follow. The path and its results are unchanged.
  • search() from @astryxdesign/cli/api answers faster when one process searches again: it reuses the components, docs, templates and themes it gathered for the same folder and type while no file it read, and no folder it listed, has changed since (a linked workspace package included). To see those reads, the first such search in a process wraps node:fs's read functions for that process; outside a search they behave exactly as before. Results are unchanged. Short-lived runs are unaffected: each astryx search command gathers once, as before (#7830).
  • astryx search and astryx build find a block by its authored display name when that name has two words or more and holds every word of the component the block shows: a query naming it, such as "rich text editor" for an integration's Rich Text Editor block, ranks it first. A display name that labels only the variant, such as "Inside a card", is not read.
Documentation
  • astryx docs cli/commands/postinstall now documents the hidden postinstall hook, astryx docs cli/commands lists it, and astryx postinstall --help shows its exit code and an example. The summary of astryx docs cli/commands/manifest (text and --json) drops its final period, so it matches the description the manifest has always printed. What each command prints when it runs, its JSON and its exit codes are unchanged.
  • Everything an integration author reads now lives under one home, astryx docs authoring: the integration guides' routes moved from cli/integrations/… to authoring/… (for example, cli/integrations/quick-start is now authoring/quick-start), beside the field reference at astryx docs authoring/field-reference. astryx docs authoring <name> still opens one field reference section, and an old cli/integrations/… route's error names its new route. The loose topics now sit in Guides or Foundations instead of Unorganized, under the same names: astryx docs getting-started still opens, and its Up is astryx docs guides.
  • A new guide, astryx docs is-my-code-good, checks component use, icons, custom styles, layout, assets, and code health from source and rendered evidence, in one page you can share. It includes an agent prompt and requires missing evidence to stay visible. The template grading rubric now links each category to these shared criteria instead of repeating them, and keeps its own weights, counting rules, and version 1.4.
  • Questions like "add an integration" or "install a package" now find a guide for app builders first. Added a "Use integrations" guide (use-integrations.doc.mjs) that covers discovering, installing, and using integration packages in an app; open it with astryx docs use-integrations. Search ranks it above authoring and API-function docs for those questions, while queries like "build an integration" still rank authoring content first.
Contributors
Thanks to everyone who contributed to this release: