Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Compact the generated agent-docs block (#7124)

Joey58e62bc493a4
diff --git a/.changeset/compact-agent-docs-block.md b/.changeset/compact-agent-docs-block.md
new file mode 100644
index 0000000000..feb4f8970b
--- /dev/null
+++ b/.changeset/compact-agent-docs-block.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] Compact the generated agent-docs block: fewer lines, same behavioral coverage
+
+@josephfarina
diff --git a/packages/cli/foundation/agent-docs/agent-docs.mjs b/packages/cli/foundation/agent-docs/agent-docs.mjs
index 2fe56539f9..c1c91f50ef 100644
--- a/packages/cli/foundation/agent-docs/agent-docs.mjs
+++ b/packages/cli/foundation/agent-docs/agent-docs.mjs
@@ -424,58 +424,57 @@ export function generateCompressedIndex(
// Required setup — components ship precompiled CSS; without these imports
// everything renders unstyled. Theme is optional (a default ships in astryx.css).
- lines.push('SETUP (once, in your app entry e.g. main.tsx) — without these, components render unstyled:');
+ lines.push('SETUP (once, in app entry e.g. main.tsx) — without these, components render unstyled:');
lines.push(' import "@astryxdesign/core/reset.css";');
lines.push(' import "@astryxdesign/core/astryx.css";');
lines.push('');
// Workflow — `build` is the front door, and every page starts from the
- // template it names.
- lines.push('WORKFLOW — start every page from a template. Never lay out a page from scratch:');
- lines.push('1. `astryx build "<idea>"` — START HERE: names the [page] template to start from (always one: the closest match, or the app shell), two other templates, and the [block]s + [component]s for parts it lacks. No args = full playbook.');
- lines.push('2. `astryx template <name> <path>` — scaffold that template into your project. Keep its frame, gap and padding; replace its data, copy and sections; delete sections you do not need.');
- lines.push('3. `astryx template <Block>` for a part the template lacks; `astryx component <Name>` for props + examples before you use or change a component.');
- lines.push('Changing a page you already have? Keep it: skip step 2 and add blocks and components inside its sections.');
+ // template it names. build/template/component are covered here, so they are
+ // intentionally omitted from the command reference below.
+ lines.push('WORKFLOW — start every page from a template, never from scratch:');
+ lines.push('1. `astryx build "<idea>"` — names the template to scaffold from and the parts it lacks.');
+ lines.push('2. `astryx template <name> <path>` — scaffold it; keep its frame, gap and padding; replace the content.');
+ lines.push('3. `astryx template <Block>` for parts it lacks; `astryx component <Name>` to read props before using one.');
+ lines.push('Changing an existing page? Keep it: skip step 2 and add blocks/components inside its sections.');
lines.push('');
// Rules — the top error-preventers.
lines.push('RULES:');
- lines.push('- No <div> — components do all layout/spacing, page frame included.');
- lines.push('- Frame first: the template you scaffold sets the page frame. Read `astryx docs layout` for the principles — region widths, breakpoint behavior.');
- lines.push('- Dense data = rows (Table, List/Item), never Card-wrapped list items; Card is for standalone widgets. Status = StatusDot/Token; Badge = counts only.');
+ lines.push('- No <div> — components handle all layout and spacing.');
+ lines.push('- Read `astryx docs layout` before changing a template\'s frame.');
+ lines.push('- Dense data = rows (Table, List/Item), not Card-wrapped lists. Badge = counts only.');
// Styling guidance tailored to the project's configured system — never
// recommend a path that isn't compiled here (xstyle needs the StyleX compiler;
// utilities need Tailwind). Tokens are always the source of truth.
if (stylingSystem === 'stylex') {
- lines.push('- Custom styling: component props first; else the xstyle prop / StyleX tokens (@astryxdesign/core/theme/tokens.stylex). No raw hex/px.');
+ lines.push('- Style with component props first, then the xstyle prop / StyleX tokens. No raw hex/px.');
} else if (stylingSystem === 'tailwind') {
- lines.push('- Custom styling: component props first; else Tailwind utilities backed by tokens (bg-surface, text-primary, rounded-lg) via tailwind-theme.css. No raw hex/px.');
+ lines.push('- Style with component props first, then Tailwind utilities backed by tokens. No raw hex/px.');
} else {
- lines.push("- Custom styling: component props first; else style/className with tokens — var(--color-*|--spacing-*|--radius-*). No raw hex/px. (No StyleX/Tailwind compiler here — don't use xstyle/utility classes.)");
+ lines.push("- Style with component props first, then tokens (var(--color-*|--spacing-*|--radius-*)). No raw hex/px. No StyleX/Tailwind compiler here — don't use xstyle/utility classes.");
}
- lines.push('- Tokens for every value (`astryx docs tokens`). Brand/accent belongs in the theme. Run `astryx theme list`, install a package, and `theme add <slug> --import` to import its built theme through the generated app module. Extend that theme to customize it. Use `theme eject <slug>` only to fork source and `astryx theme template` for a new theme — never override --color-* in :root.');
+ lines.push('- Palettes and custom colors go through the theme, never :root overrides. See `astryx docs theme`.');
// Self-check — post-generation pass. Validated via vibe tests (internal/vibe-tests/
// prompt-purity-test): on complex multi-step UIs the rules above alone still leave raw
// CSS in ~11-13% of runs; a re-read-and-fix pass cuts that ~4x at negligible token cost.
- // The fix names the sanctioned escape hatch for the configured system.
const selfCheckFix = {
stylex:
- 'replace any className=, style={{…}}, raw <div>/<span> layout, imported .css/@apply, or hardcoded #hex/px with the component or the xstyle prop + a token',
+ 'replace any className=, style={{…}}, raw <div>/<span>, imported .css/@apply, or hardcoded #hex/px with the component or the xstyle prop + a token',
tailwind:
- 'replace any style={{…}}, raw <div>/<span> layout, imported .css/@apply, or hardcoded/arbitrary value (e.g. bg-[#fff], p-[13px]) with the component or a token-backed utility',
- css: 'replace any raw <div>/<span> layout, imported .css/@apply, or hardcoded value (#hex, 16px) with the component or a token (var(--color-*|--spacing-*|…))',
+ 'replace any style={{…}}, raw <div>/<span>, imported .css/@apply, or hardcoded/arbitrary value (bg-[#fff], p-[13px]) with the component or a token-backed utility',
+ css: 'replace any raw <div>/<span>, imported .css/@apply, or hardcoded #hex/px with the component or a token',
};
lines.push(
- `- SELF-CHECK before you finish: re-read the file and ${selfCheckFix[stylingSystem] ?? selfCheckFix.css}. Confirm the page kept its template's frame, gap and padding. If unsure a component/prop exists, run \`astryx component <Name>\` / \`astryx search "<thing>"\`; don't hand-roll CSS.`,
+ `- SELF-CHECK: re-read the file; ${selfCheckFix[stylingSystem] ?? selfCheckFix.css}.`,
);
lines.push('');
- // Command reference — build/template/component are covered in WORKFLOW above.
- lines.push('MORE CLI:');
- lines.push(' search "<query>" find any component / hook / doc / template / block / theme');
- lines.push(' discover <words> integrations you could add, and the ones you have');
- lines.push(` component --list ${componentCount} components by category`);
- lines.push(' template --list page + block recipes');
+ // build/template/component are covered in WORKFLOW above and intentionally
+ // omitted here. `astryx help` is the full reference.
+ lines.push('`astryx help` lists every command. Key ones beyond the workflow:');
+ lines.push(' search "<query>" find any component / hook / doc / template');
+ lines.push(' discover <words> integrations you could add');
const docsDir = path.join(CLI_ROOT, 'assets', 'docs');
const resolvedTopics =
topics ??
@@ -488,11 +487,14 @@ export function generateCompressedIndex(
.sort()
: []);
if (resolvedTopics.length > 0) {
- lines.push(` docs <topic> ${resolvedTopics.join(', ')}`);
+ // Show key topics inline, point at `astryx docs` for the full list.
+ const keyTopics = ['getting-started', 'principles', 'tokens', 'theme'];
+ const shown = keyTopics.filter(t => resolvedTopics.includes(t));
+ const suffix = resolvedTopics.length > shown.length ? ' …' : '';
+ lines.push(` docs <topic> ${shown.join(', ')}${suffix} (\`astryx docs\` lists all)`);
}
- lines.push(' docs cli commands, API reference, integration authoring (one level at a time)');
- lines.push(' swizzle <Name> eject component source for deep customization');
- lines.push(' upgrade --from <old version> --apply run after any Astryx or integration dependency bump');
+ lines.push(' docs cli commands, API reference, integration authoring');
+ lines.push(' upgrade --from <old version> --apply run after a dependency bump');
const appendCount = agentDocs.reduce(
(count, contribution) => count + contribution.append.length,
0,
diff --git a/packages/cli/foundation/agent-docs/agent-docs.test.mjs b/packages/cli/foundation/agent-docs/agent-docs.test.mjs
index 797ca865a4..2b87ba05eb 100644
--- a/packages/cli/foundation/agent-docs/agent-docs.test.mjs
+++ b/packages/cli/foundation/agent-docs/agent-docs.test.mjs
@@ -43,14 +43,14 @@ describe('generateCompressedIndex', () => {
it('includes theme nudge rule', () => {
const result = generateCompressedIndex('1.0.0');
- expect(result).toMatch(/astryx theme/);
- expect(result).toMatch(/never override --color-/);
+ expect(result).toMatch(/astryx docs theme/);
+ expect(result).toMatch(/never :root/);
});
it('sends frame choice to the layout doc rather than naming a shell', () => {
const result = generateCompressedIndex('1.0.0');
- const frameRule = result.split('\n').find(l => l.includes('Frame first'));
- expect(frameRule).toContain('astryx docs layout');
+ const frameRule = result.split('\n').find(l => l.includes('astryx docs layout'));
+ expect(frameRule).toBeDefined();
expect(result).not.toMatch(/AppShell/);
expect(frameRule).not.toMatch(/https?:/);
});
@@ -60,24 +60,22 @@ describe('generateCompressedIndex', () => {
const workflow = lines.findIndex(l => l.startsWith('WORKFLOW'));
expect(lines[workflow]).toMatch(/start every page from a template/);
expect(lines[workflow + 1]).toMatch(/^1\. `astryx build /);
- expect(lines[workflow + 2]).toMatch(/^2\. `astryx template <name> <path>`/);
+ expect(lines[workflow + 2]).toMatch(/^2\. .*keep its frame, gap and padding/);
expect(lines.join('\n')).not.toMatch(/reference code/);
});
it('includes the post-generation self-check rule', () => {
const result = generateCompressedIndex('1.0.0');
- expect(result).toContain('SELF-CHECK before you finish');
+ expect(result).toContain('SELF-CHECK');
expect(result).toMatch(/re-read the file/);
- expect(result).toMatch(/don't hand-roll CSS/);
+ expect(result).toMatch(/component or a token/);
});
it('tailors the self-check to the styling system (xstyle for StyleX, not className for Tailwind)', () => {
- // StyleX path: className/inline style are veers; the fix is the xstyle prop + a token
const stylex = generateCompressedIndex('1.0.0', {stylingSystem: 'stylex'});
const stylexSelfCheck = stylex.split('\n').find(l => l.includes('SELF-CHECK'));
expect(stylexSelfCheck).toMatch(/xstyle/);
expect(stylexSelfCheck).toMatch(/className=/);
- // className IS the system in Tailwind — it must NOT be flagged
const tailwind = generateCompressedIndex('1.0.0', {stylingSystem: 'tailwind'});
const tailwindSelfCheck = tailwind.split('\n').find(l => l.includes('SELF-CHECK'));
expect(tailwindSelfCheck).toBeDefined();
@@ -86,10 +84,11 @@ describe('generateCompressedIndex', () => {
it('defaults to the CSS-variable styling path (no compiler)', () => {
const result = generateCompressedIndex('1.0.0');
- expect(result).toMatch(/style\/className with tokens/);
- expect(result).toMatch(/var\(--color-\*/);
+ expect(result).toMatch(/tokens.*var\(--color-/);
// Must NOT push xstyle when no StyleX compiler is present.
expect(result).not.toMatch(/xstyle prop/);
+ // Must warn that no compiler is present.
+ expect(result).toMatch(/No StyleX\/Tailwind compiler/);
});
it('recommends xstyle when StyleX is configured', () => {
@@ -99,23 +98,22 @@ describe('generateCompressedIndex', () => {
it('recommends Tailwind utilities when Tailwind is configured', () => {
const result = generateCompressedIndex('1.0.0', {stylingSystem: 'tailwind'});
- expect(result).toMatch(/Tailwind utilities backed by tokens/);
- expect(result).toMatch(/tailwind-theme\.css/);
+ expect(result).toMatch(/Tailwind utilities/);
});
it('includes upgrade command and migration rule', () => {
const result = generateCompressedIndex('1.0.0');
// `upgrade --apply` alone stops with "Missing required --from".
expect(result).toContain('upgrade --from <old version> --apply');
- expect(result).toMatch(/after any Astryx or integration dependency bump/);
+ expect(result).toMatch(/after a dependency bump/);
});
it('points agents at discover for integrations they could add', () => {
const result = generateCompressedIndex('1.0.0');
// Without this line no surface an agent reads names `discover`, and agents
// look for a theme in the package registry instead.
- expect(result).toMatch(/^ {2}discover <words> {3}integrations you could add, and the ones you have$/m);
- expect(result).toMatch(/^ {2}search "<query>" .*\/ theme$/m);
+ expect(result).toMatch(/^ {2}discover <words> {3}integrations you could add$/m);
+ expect(result).toMatch(/^ {2}search "<query>"/m);
});
it('states the invocation once in the CLI header (yarn)', () => {
@@ -144,20 +142,14 @@ describe('generateCompressedIndex', () => {
);
}
- it('names the hyphenated topics, which the scan used to drop', () => {
- // The fallback scan matched `\w+`, which does not match `-`, so five real
- // topics were missing from every block ever written. An agent cannot ask
- // for a topic it was never told about, and `getting-started` — the one it
- // should reach for first — was one of them.
+ it('keeps hyphenated key topics visible and points at astryx docs for the rest', () => {
+ // The compact block shows key topics inline; the full list is via
+ // `astryx docs`. `getting-started` is a hyphenated key topic that the old
+ // \w+ scan used to drop — it must stay visible.
const line = topicLine(generateCompressedIndex('1.0.0'));
- for (const topic of [
- 'getting-started',
- 'browser-support',
- 'styling-libraries',
- 'working-with-ai',
- ]) {
- expect(line).toContain(topic);
- }
+ expect(line).toContain('getting-started');
+ expect(line).toContain('principles');
+ expect(line).toContain('astryx docs');
});
it('points to the CLI docs tree on a line of its own', () => {
@@ -165,19 +157,22 @@ describe('generateCompressedIndex', () => {
// the topic line no longer names it; the tree's entry point does.
const block = generateCompressedIndex('1.0.0');
expect(block).toContain(
- ' docs cli commands, API reference, integration authoring (one level at a time)',
+ ' docs cli commands, API reference, integration authoring',
);
expect(topicLine(block)).not.toContain('cli-integrations');
});
- it('lists the topics it is given, so an integration’s reach the agent', () => {
+ it('shows key topics from the given list and points at astryx docs for the rest', () => {
const line = topicLine(
generateCompressedIndex('1.0.0', {topics: ['tokens', 'deploying']}),
);
- expect(line).toContain('tokens, deploying');
- // The project's catalog replaces the built-in scan rather than adding to it:
- // a topic an integration replaced must not also be listed under its old name.
+ // 'tokens' is a key topic present in the given list, so it appears inline.
+ expect(line).toContain('tokens');
+ // The project's catalog replaces the built-in scan: a built-in topic not
+ // in the given list must not appear.
expect(line).not.toContain('typography');
+ // Agents reach the full list via 'astryx docs'.
+ expect(line).toContain('astryx docs');
});
it('omits the line entirely when the project has no topics', () => {
diff --git a/packages/cli/foundation/agent-docs/app-theme-workflow.test.mjs b/packages/cli/foundation/agent-docs/app-theme-workflow.test.mjs
index 51e8978069..610cbc1090 100644
--- a/packages/cli/foundation/agent-docs/app-theme-workflow.test.mjs
+++ b/packages/cli/foundation/agent-docs/app-theme-workflow.test.mjs
@@ -4,13 +4,10 @@ import {describe, expect, it} from 'vitest';
import {generateCompressedIndex} from './agent-docs.mjs';
describe('generated agent docs app-theme workflow', () => {
- it('keeps the add, extend, and eject guidance together', () => {
+ it('points agents at the theme doc and guards :root overrides', () => {
const result = generateCompressedIndex('1.0.0');
- expect(result).toContain('theme add <slug> --import');
- expect(result).toContain('generated app module');
- expect(result).toContain('Extend that theme');
- expect(result).toContain('theme eject <slug>` only to fork source');
- expect(result).toContain('never override --color-');
+ expect(result).toContain('astryx docs theme');
+ expect(result).toContain('never :root overrides');
});
});
diff --git a/packages/cli/test/docs-graph.test.mjs b/packages/cli/test/docs-graph.test.mjs
index 5c4d7b9e39..0f0fe5c224 100644
--- a/packages/cli/test/docs-graph.test.mjs
+++ b/packages/cli/test/docs-graph.test.mjs
@@ -562,14 +562,17 @@ describe('the docs graph', () => {
for (const each of shownCommands(block)) {
if (!shown.has(each)) shown.set(each, 'the agent prompt in AGENTS.md');
}
- // The block `astryx init` writes into an app's AGENTS.md. Its MORE CLI
+ // The block `astryx init` writes into an app's AGENTS.md. Its key-commands
// lines are bare subcommands, each followed by its description.
const appBlock = generateCompressedIndex('0.0.0', {invocation: 'npx astryx'});
for (const each of shownCommands(appBlock)) {
if (!shown.has(each)) shown.set(each, 'the agent block astryx init writes');
}
- const more = (appBlock.split('MORE CLI:')[1] ?? '').split(/\n\s*\n/)[0];
- const bare = [...more.matchAll(/^ {2}(\S.*?)(?: {3,}|$)/gm)].map(m => `astryx ${m[1]}`);
+ // The compact block lists key commands after a prose lead-in, indented by
+ // two spaces. build/template/component are intentionally omitted because
+ // they are covered in the WORKFLOW section above the command list.
+ const keySection = (appBlock.split('Key ones beyond the workflow:')[1] ?? '').split(/\n\s*\n/)[0];
+ const bare = [...keySection.matchAll(/^ {2}(\S.*?)(?: {3,}|$)/gm)].map(m => `astryx ${m[1]}`);
expect(bare.length).toBeGreaterThan(3);
for (const each of bare) {
if (!shown.has(each)) shown.set(each, 'the agent block astryx init writes');