@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/clients/cli/formatters/index.mjs

@@ -11,7 +11,8 @@
  * which fields to show and in what order.
  *
  * Constraints (deliberately narrow):
- *   - Plain ASCII only. No color, no TTY detection, no width wrapping. Output is
+ *   - Plain ASCII only. No color and no TTY detection. Long lines wrap at a
+ *     fixed {@link WRAP_WIDTH}, never at the terminal's width, so output is
  *     byte-for-byte deterministic whether printed or piped to an agent.
  *   - Renderers return an opaque {@link Block}; `emit` accepts ONLY Blocks, so a
  *     stray string can't leak onto stdout (the compiler rejects `emit('x')`).
@@ -33,6 +34,50 @@ export const BULLET = '-';
 export const ERR = '!!';
 export const WARN = '!';
 
+/** The column long human-output lines wrap at. */
+export const WRAP_WIDTH = 120;
+
+/** The widest first column an inline record pads to; a longer value overhangs. */
+const INLINE_LEAD_MAX = 32;
+
+/**
+ * Characters a terminal draws two columns wide: CJK ideographs and
+ * punctuation, kana, hangul, and fullwidth forms. A line may break between
+ * any two of them.
+ */
+const WIDE_CHAR =
+  /[\u1100-\u115f\u2e80-\u303e\u3041-\u33ff\u3400-\u4dbf\u4e00-\u9fff\ua000-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe30-\ufe4f\uff00-\uff60\uffe0-\uffe6]/u;
+
+/**
+ * How many terminal columns a string takes.
+ * @param {string} s
+ * @returns {number}
+ */
+export function displayWidth(s) {
+  let width = 0;
+  for (const ch of String(s)) width += WIDE_CHAR.test(ch) ? 2 : 1;
+  return width;
+}
+
+/**
+ * Cut a line to `width` columns, ending it with `...` when anything was cut.
+ * @param {string} line
+ * @param {number} width
+ * @returns {string}
+ */
+function truncateToWidth(line, width) {
+  if (displayWidth(line) <= width) return line;
+  let out = '';
+  let used = 0;
+  for (const ch of line) {
+    const w = WIDE_CHAR.test(ch) ? 2 : 1;
+    if (used + w > width - 3) break;
+    out += ch;
+    used += w;
+  }
+  return `${out.trimEnd()}...`;
+}
+
 /**
  * An opaque, renderer-produced block of output. Nominal via a private field:
  * nothing outside this file can construct one, so `emit` can trust that whatever
@@ -67,6 +112,13 @@ export class Block {
  * @property {Record<string, string>} [labels] - Rename a key for display.
  * @property {Record<string, (value: any) => string>} [format] - Transform a
  *   value before rendering (e.g. prefix a command with the package manager).
+ * @property {'stacked' | 'inline'} [layout] - `stacked` (the default): one
+ *   `key: value` line per field, a blank line between records. `inline`: one
+ *   record per line, the first field in a padded column and the rest joined by
+ *   ` - `, for a list a reader scans.
+ * @property {'wrap' | 'truncate'} [overflow] - What an inline record longer
+ *   than {@link WRAP_WIDTH} does: `wrap` (the default) continues under the
+ *   first column; `truncate` cuts it to one line.
  */
 
 /** @param {unknown} v @returns {boolean} */
@@ -100,9 +152,77 @@ function toAscii(s) {
     .replace(/[\u2018\u2019]/g, "'")
     .replace(/[\u201C\u201D]/g, '"')
     .replace(/\u2026/g, '...')
+    .replace(/\u2192/g, '->')
+    .replace(/\u2190/g, '<-')
     .replace(/\u00a0/g, ' ');
 }
 
+/**
+ * Word-wrap text at `width`, keeping its own line breaks. A word longer than
+ * the width stays whole on a line of its own. Continuation lines start with
+ * `indent`.
+ * @param {string} input
+ * @param {{width?: number, indent?: string}} [options]
+ * @returns {string}
+ */
+export function wrapText(input, {width = WRAP_WIDTH, indent = ''} = {}) {
+  return String(input)
+    .split('\n')
+    .map(line => wrapLine(line, width, indent))
+    .join('\n');
+}
+
+/**
+ * @param {string} line
+ * @param {number} width
+ * @param {string} indent
+ * @returns {string}
+ */
+function wrapLine(line, width, indent) {
+  if (displayWidth(line) <= width) return line;
+  const lead = /^\s*/.exec(line)?.[0] ?? '';
+  // Tokens a line may break between: words, and each wide character on its
+  // own, since CJK text has no spaces to break at. `gap` is what joined a
+  // token to the one before it.
+  /** @type {{text: string, gap: string}[]} */
+  const tokens = [];
+  let gap = '';
+  let word = '';
+  const flush = () => {
+    if (word === '') return;
+    tokens.push({text: word, gap});
+    gap = '';
+    word = '';
+  };
+  for (const ch of line.slice(lead.length)) {
+    if (ch === ' ') {
+      flush();
+      gap = ' ';
+    } else if (WIDE_CHAR.test(ch)) {
+      flush();
+      tokens.push({text: ch, gap});
+      gap = '';
+    } else {
+      word += ch;
+    }
+  }
+  flush();
+  /** @type {string[]} */
+  const out = [];
+  let current = lead;
+  tokens.forEach(({text: token, gap: before}, i) => {
+    const joined = i === 0 ? current + token : current + before + token;
+    if (i > 0 && displayWidth(joined) > width && current.trim() !== '') {
+      out.push(current);
+      current = indent + token;
+    } else {
+      current = joined;
+    }
+  });
+  out.push(current);
+  return out.join('\n');
+}
+
 /**
  * A group label, optionally with an explanatory subtitle rendered on the line(s)
  * directly beneath the heading (no blank line between). Whatever list/records
@@ -177,10 +297,53 @@ export function record(obj, options = {}) {
  * @returns {Block}
  */
 export function records(items, options = {}) {
+  if (options.layout === 'inline') return inlineRecords(items, options);
   const blocks = items.map(o => record(o, options).toString()).filter(Boolean);
   return new Block(blocks.join('\n\n'));
 }
 
+/**
+ * @param {any[]} items
+ * @param {RecordOptions} options
+ * @returns {Block}
+ */
+function inlineRecords(items, options) {
+  const [lead, ...rest] = (options.fields ?? Object.keys(items[0] ?? {})).filter(
+    k => !options.omit?.includes(k),
+  );
+  if (lead == null) return new Block('');
+  /** @param {any} o @param {string} k */
+  const value = (o, k) => {
+    const fmt = options.format?.[k];
+    return fmt ? fmt(o[k]) : renderValue(o[k]);
+  };
+  const leads = items.map(o => (isEmpty(o[lead]) ? '' : value(o, lead)));
+  const column = Math.min(
+    Math.max(0, ...leads.map(l => displayWidth(l))),
+    INLINE_LEAD_MAX,
+  );
+  const indent = ' '.repeat(column + 2);
+  const lines = items.map((o, i) => {
+    const tail = toAscii(
+      rest
+        .filter(k => !isEmpty(o[k]))
+        .map(k => value(o, k))
+        .join(' - '),
+    );
+    if (tail === '') return toAscii(leads[i]);
+    const head = toAscii(`${leads[i].padEnd(column)}  `);
+    if (options.overflow === 'truncate') {
+      return truncateToWidth(head + tail, WRAP_WIDTH);
+    }
+    // Wrap only the tail, so the padded first column survives the wrap.
+    const [first, ...more] = wrapText(tail, {
+      width: Math.max(20, WRAP_WIDTH - displayWidth(head)),
+    }).split('\n');
+    return [head + first, ...more.map(line => indent + line)].join('\n');
+  });
+  return new Block(lines.join('\n'));
+}
+
 /**
  * A verbatim block — source dumps, layout skeletons, or a markdown doc. Output
  * is byte-for-byte (NOT ASCII-normalized), so it survives piping

package/clients/cli/formatters/index.test.mjs

@@ -8,6 +8,9 @@ import {
   list,
   record,
   records,
+  wrapText,
+  displayWidth,
+  WRAP_WIDTH,
   code,
   Block,
   BULLET,
@@ -114,6 +117,12 @@ describe('ASCII normalization', () => {
     expect(list(['Avatar \u2014 Group']).toString()).toBe('- Avatar - Group');
   });
 
+  it('converts Unicode arrows to ASCII arrows', () => {
+    expect(text('Rename items \u2192 options').toString()).toBe('Rename items -> options');
+    expect(text('options \u2190 items').toString()).toBe('options <- items');
+    expect(record({title: 'a \u2192 b'}).toString()).toBe('title: a -> b');
+  });
+
   it('leaves code verbatim (no normalization)', () => {
     expect(code('a \u2014 b').toString()).toBe('a \u2014 b');
   });
@@ -148,3 +157,91 @@ describe('emit', () => {
     expect(spy).not.toHaveBeenCalled();
   });
 });
+
+describe('wrapText', () => {
+  it('leaves short lines and its own line breaks alone', () => {
+    expect(wrapText('a b\nc')).toBe('a b\nc');
+  });
+
+  it('wraps at the width with a hanging indent', () => {
+    expect(wrapText('aaa bbb ccc', {width: 7, indent: '  '})).toBe('aaa bbb\n  ccc');
+  });
+
+  it('keeps a word longer than the width whole', () => {
+    expect(wrapText('x '.concat('y'.repeat(20)), {width: 10})).toBe(
+      `x\n${'y'.repeat(20)}`,
+    );
+  });
+});
+
+describe('records inline layout', () => {
+  const items = [
+    {id: 'a', title: 'Alpha', summary: 'First.'},
+    {id: 'bbb', title: 'Beta', summary: ''},
+  ];
+
+  it('puts one record on each line under a padded first column', () => {
+    expect(
+      records(items, {fields: ['id', 'title', 'summary'], layout: 'inline'}).toString(),
+    ).toBe('a    Alpha - First.\nbbb  Beta');
+  });
+
+  it('wraps a long record under the first column', () => {
+    const out = records([{id: 'a', text: 'word '.repeat(40).trim()}], {
+      layout: 'inline',
+    }).toString();
+    expect(out.split('\n').length).toBeGreaterThan(1);
+    expect(out.split('\n').every(line => line.length <= WRAP_WIDTH)).toBe(true);
+    expect(out.split('\n')[1].startsWith('   word')).toBe(true);
+  });
+
+  it('keeps the first column padded on a record that wraps', () => {
+    const out = records(
+      [
+        {id: 'a', text: 'word '.repeat(40).trim()},
+        {id: 'longer', text: 'x'},
+      ],
+      {layout: 'inline'},
+    ).toString();
+    const lines = out.split('\n');
+    expect(lines[0].startsWith(`a${' '.repeat(7)}word`)).toBe(true);
+    expect(lines[1].startsWith(' '.repeat(8) + 'word')).toBe(true);
+    expect(lines.at(-1)).toBe('longer  x');
+    expect(lines.every(line => line.length <= WRAP_WIDTH)).toBe(true);
+  });
+
+  it('cuts a long record to one line when asked', () => {
+    const out = records([{id: 'a', text: 'word '.repeat(40).trim()}], {
+      layout: 'inline',
+      overflow: 'truncate',
+    }).toString();
+    expect(out.includes('\n')).toBe(false);
+    expect(out.length).toBeLessThanOrEqual(WRAP_WIDTH);
+    expect(out.endsWith('...')).toBe(true);
+  });
+});
+
+describe('wide characters', () => {
+  it('counts CJK characters as two columns', () => {
+    expect(displayWidth('亮/暗模式')).toBe(9);
+  });
+
+  it('wraps CJK text, which has no spaces, by columns', () => {
+    const out = wrapText('中'.repeat(100), {width: 20});
+    expect(out.split('\n').every(line => displayWidth(line) <= 20)).toBe(true);
+    expect(out.split('\n')).toHaveLength(10);
+  });
+
+  it('keeps spaces between Latin words next to CJK', () => {
+    expect(wrapText('运行 astryx docs 查看', {width: 200})).toBe('运行 astryx docs 查看');
+  });
+
+  it('cuts an inline record to columns, not characters', () => {
+    const out = records([{id: 'a', text: '中'.repeat(100)}], {
+      layout: 'inline',
+      overflow: 'truncate',
+    }).toString();
+    expect(displayWidth(out)).toBeLessThanOrEqual(WRAP_WIDTH);
+    expect(out.endsWith('...')).toBe(true);
+  });
+});

package/clients/cli/index.mjs

@@ -16,7 +16,6 @@ import {Command, Option} from 'commander';
 import {fileURLToPath} from 'node:url';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {checkForUpdate} from './lib/update-check.mjs';
 import {getCliInvocation} from '../../foundation/env/package-manager.mjs';
 import {API_VERSION, setJsonMode} from '../../foundation/response/json.mjs';
 import {buildManifest} from './lib/manifest.mjs';
@@ -25,7 +24,8 @@ import {emit, section, text, records} from './formatters/index.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {installJsonShim} from './lib/json-shim.mjs';
-import {markReportsResult} from './lib/define-command.mjs';
+import {addDocHelp, markReportsResult} from './lib/define-command.mjs';
+import {doc as manifestDoc} from './commands/manifest.doc.mjs';
 import {isAstryxInitialized} from '../../foundation/agent-docs/agent-docs.mjs';
 import * as debug from '../../foundation/debug/index.mjs';
 
@@ -95,6 +95,7 @@ export const JSON_SUPPORTED = new Set([
   'theme targets',
   'theme palette generate',
   'integration add',
+  'integration verify',
   'integration pack',
   'upgrade',
   'manifest',
@@ -275,8 +276,13 @@ const commands = [
   {name: 'doctor', path: './commands/doctor.mjs', register: 'registerDoctor'},
 ];
 
-const UPDATE_HINT_COMMANDS = new Set(['component', 'docs']);
 const SETUP_NUDGE_EXEMPT = new Set(['init', 'agent-docs']);
+/** An integration package's manifest: the package is not an app to set up. */
+const INTEGRATION_MANIFEST_FILES = [
+  'astryx.integration.ts',
+  'astryx.integration.mjs',
+  'astryx.integration.js',
+];
 
 /**
  * Build a fresh, fully-wired Astryx CLI program (root options, hooks, all
@@ -337,22 +343,30 @@ export async function createProgram() {
     .name('astryx')
     .description('Design system CLI — components, themes, and tooling')
     .version(pkg.version)
-    .option('--zh', 'Output docs in Chinese Simplified')
-    .option('--dense', 'Output docs in compressed dense format (token-efficient)')
+    // These four change only the reads named in their text; every other
+    // command ignores them.
+    .option(
+      '--zh',
+      'Simplified Chinese for component reads and for docs topics that have a translation (English otherwise)',
+    )
+    .option('--dense', 'Token-efficient dense text for component <Name> and docs <topic> reads')
     .addOption(
       new Option(
         '--lang <locale>',
-        'Output docs in specified language/format (en, zh, dense)',
+        'Language or format for component and docs reads: en (default), zh (as --zh), or dense (as --dense)',
       ).choices(['en', 'zh', 'dense']),
     )
     .addOption(
-      new Option('--detail <level>', 'Output detail level (full, compact, brief)')
+      new Option(
+        '--detail <level>',
+        'Detail level for component, hook, and docs tree reads (e.g. docs cli/commands/build). Lists default to brief',
+      )
         .choices(['full', 'compact', 'brief'])
         .default('full'),
     )
     .option(
       '--json',
-      'Output as typed JSON. Success envelope: { type, data }. Error envelope: { error, suggestions? }.',
+      'Output as typed JSON. Success envelope: { apiVersion, type, data, meta? }. Error envelope: { apiVersion, error, code, suggestions? }.',
     )
     .addHelpCommand('help', 'Show all commands')
     .action((options, cmd) => {
@@ -466,6 +480,19 @@ export async function createProgram() {
     const fullName = fullCommandName(actionCommand, program);
     if (JSON_SUPPORTED.has(fullName)) return;
     process.__xdsJsonHandled = true;
+    // A group given a word it does not have reports an unknown subcommand and
+    // lists the ones it has, in JSON as in text, even when a flag follows it.
+    const extras = actionCommand.commands.length > 0 ? actionCommand.args : [];
+    const unknown = extras.find(arg => !String(arg).startsWith('-'));
+    if (unknown != null) {
+      cliError(`unknown subcommand '${fullName} ${unknown}'`, {
+        code: ERROR_CODES.ERR_UNKNOWN_SUBCOMMAND,
+        suggestions: actionCommand.commands.map(child => ({
+          name: child.name(),
+          reason: 'available subcommand',
+        })),
+      });
+    }
     debug.setOutcome('rejected', {
       exitCode: 1,
       code: ERROR_CODES.ERR_INVALID_OPTION,
@@ -499,25 +526,6 @@ export async function createProgram() {
     process.exit(1);
   });
 
-  /**
-   * Post-action hook: print update hint after any command output.
-   * Only fires for commands that produce output agents read (component, docs, etc.).
-   * Suppressed when --json is active to avoid contaminating stdout.
-   */
-  program.hook('postAction', (thisCommand, actionCommand) => {
-    if (program.opts().json) return;
-    try {
-      if (UPDATE_HINT_COMMANDS.has(actionCommand.name())) {
-        const hint = checkForUpdate();
-        if (hint) {
-          console.error(`\n${hint}`);
-        }
-      }
-    } catch {
-      // Never let update check break the CLI
-    }
-  });
-
   /**
    * Enforcement layer 3 — setup nudge. If this project hasn't run `astryx init`
    * yet (no Astryx marker in any agent-doc file — see isAstryxInitialized), remind
@@ -539,6 +547,8 @@ export async function createProgram() {
       if (SETUP_NUDGE_EXEMPT.has(actionCommand.name())) return;
       const cwd = process.cwd();
       if (!fs.existsSync(path.join(cwd, 'package.json'))) return; // not a project
+      // An integration package is not an app: `init` is not its next step.
+      if (INTEGRATION_MANIFEST_FILES.some(file => fs.existsSync(path.join(cwd, file)))) return;
       if (isAstryxInitialized(cwd)) return; // already set up — stay quiet
       // Same wording as the core/cli postinstall nudges. #4151's getCliInvocation()
       // renders the correct form for THIS project — scoped `npx @astryxdesign/cli`
@@ -557,16 +567,18 @@ export async function createProgram() {
       mod[cmd.register](program);
     } catch (e) {
       // Command fails to load but CLI still works
+      const reason = /** @type {any} */ (e).message;
       const stub = program
         .command(cmd.name)
-        .description(`(failed to load: ${/** @type {any} */ (e).message})`)
+        .description(`(failed to load: ${reason})`)
         .action(() => {
           // Nothing loaded, so nothing was answered — say that rather than
           // leaving the run's result unreported.
           debug.recordCommandResult(debug.NO_RESULT_SET);
-          console.error(`Command "${cmd.name}" failed to load:`);
-          console.error(/** @type {any} */ (e).message);
-          process.exit(1);
+          // cliError, so --json still gets its one envelope.
+          cliError(`Command "${cmd.name}" failed to load: ${reason}`, {
+            code: ERROR_CODES.ERR_UNKNOWN,
+          });
         });
       markReportsResult(stub);
     }
@@ -601,20 +613,21 @@ export async function createProgram() {
       }
       // Human-readable summary as greppable records (agents should use --json).
       // One record per command: name, whether it supports --json, and the
-      // description.
+      // description. Field names are the manifest entry's own keys.
       emit(
         section(`${manifest.name} v${manifest.version} (${manifest.commands.length} commands)`),
         records(
           manifest.commands.map(c => ({
-            command: c.name,
+            name: c.name,
             json: c.json ? 'yes' : '',
             description: c.description || '',
           })),
-          {fields: ['command', 'json', 'description']},
+          {fields: ['name', 'json', 'description']},
         ),
         text(`Run \`${getCliInvocation()} manifest --json\` for the full structured manifest.`),
       );
     });
+  addDocHelp(manifestCommand, manifestDoc);
   markReportsResult(manifestCommand);
 
   // Hidden command used by package.json postinstall scripts

package/clients/cli/latest-version-env.test.mjs

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ASTRYX_LATEST_VERSION is not a CLI control: setting it changes nothing
+ * a command prints. It used to append an update hint to `component` and
+ * `docs`.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {runCli} from '../../test-utils/run-cli.mjs';
+
+const VARIABLE = 'ASTRYX_LATEST_VERSION';
+
+/** @type {string} */
+let dir;
+/** @type {string | undefined} */
+let saved;
+
+beforeEach(() => {
+  saved = process.env[VARIABLE];
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-latest-version-'));
+  // A project on an old core, so a "newer version" hint would have a reason to fire.
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name: 'app', private: true, dependencies: {'@astryxdesign/core': '^0.0.1'}}),
+  );
+});
+
+afterEach(() => {
+  if (saved === undefined) delete process.env[VARIABLE];
+  else process.env[VARIABLE] = saved;
+  fs.rmSync(dir, {recursive: true, force: true});
+});
+
+describe('ASTRYX_LATEST_VERSION', () => {
+  it('does not change what astryx docs prints', async () => {
+    delete process.env[VARIABLE];
+    const without = await runCli(['docs'], {cwd: dir});
+    process.env[VARIABLE] = '999.0.0';
+    const withVariable = await runCli(['docs'], {cwd: dir});
+
+    expect(withVariable.status).toBe(without.status);
+    expect(withVariable.stdout).toBe(without.stdout);
+    expect(withVariable.stderr).toBe(without.stderr);
+    expect(withVariable.stderr).not.toMatch(/newer version/i);
+  });
+});

package/clients/cli/lib/cli-error.test.mjs

@@ -133,6 +133,13 @@ describe('cliError — JSON mode', () => {
     expect(env.suggestions).toEqual([{name: 'Button', reason: 'closest match'}]);
   });
 
+  it('replaces an unregistered code with ERR_UNKNOWN', () => {
+    expect(() =>
+      cliError('EACCES: permission denied', {code: 'EACCES'}),
+    ).toThrow('__exit_1__');
+    expect(JSON.parse(stdout[0]).code).toBe('ERR_UNKNOWN');
+  });
+
   it('always exits 1 in JSON mode (custom exitCode is ignored — contract)', () => {
     expect(() => cliError('msg', {exitCode: 2})).toThrow('__exit_1__');
     expect(exitCode).toBe(1);

package/clients/cli/lib/component-format.mjs

@@ -71,7 +71,7 @@ function formatPropsTable(props) {
   lines.push('| Prop | Type | Default | Description |');
   lines.push('|------|------|---------|-------------|');
   for (const p of props) {
-    const def = p.default ? `\`${mdCell(p.default)}\`` : '—';
+    const def = p.default ? `\`${mdCell(p.default)}\`` : '-';
     const req = p.required ? ' **(required)**' : '';
     lines.push(
       `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req} |`,
@@ -190,11 +190,11 @@ function formatTargetsTable(docs, themeData) {
       ...themeVariants.map((/** @type {string} */ v) => `${v}*`),
     ];
 
-    const variantsStr = variantParts.length > 0 ? variantParts.join(', ') : '—';
-    const statesStr = states.length > 0 ? states.join(', ') : '—';
+    const variantsStr = variantParts.length > 0 ? variantParts.join(', ') : '-';
+    const statesStr = states.length > 0 ? states.join(', ') : '-';
     const dataAttrs = getTargetDataAttributes(target);
     const dataAttrsStr =
-      dataAttrs.length > 0 ? dataAttrs.map(attr => `\`${attr}\``).join(', ') : '—';
+      dataAttrs.length > 0 ? dataAttrs.map(attr => `\`${attr}\``).join(', ') : '-';
 
     const className = target.deprecatedFor
       ? `\`${target.className}\` _(deprecated; use \`${target.deprecatedFor}\`)_`
@@ -342,7 +342,7 @@ export function formatFull(docs, options = {}) {
       const publicVars = docs.theming.vars.filter((/** @type {any} */ v) => !v.private && !v.derived);
 
       if (publicVars.length > 0) {
-        sections.push('**Themeable CSS variables** — additional properties that can be overridden in `defineTheme` component overrides.\n');
+        sections.push('**Themeable CSS variables** - additional properties that can be overridden in `defineTheme` component overrides.\n');
         const varLines = [];
         varLines.push('| CSS Variable | Default | Description |');
         varLines.push('|-------------|---------|-------------|');
@@ -544,7 +544,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
     signatureProps.length > 0
       ? `${displayName}(${signatureProps.join(', ')})`
       : displayName;
-  output.push(importHint ? `${sigStr}  ← from '${importHint}'` : sigStr);
+  output.push(importHint ? `${sigStr}  <- from '${importHint}'` : sigStr);
 
   // Description (shortened)
   if (description) {
@@ -569,7 +569,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
   // Derived properties (if any)
   if (docs.theming?.derived?.length) {
     const derivedNames = docs.theming.derived
-      .map((/** @type {any} */ d) => d.expand === 'container' ? `${d.property} → container tokens` : `${d.property} → ${(d.vars || []).join(', ')}`)
+      .map((/** @type {any} */ d) => d.expand === 'container' ? `${d.property} -> container tokens` : `${d.property} -> ${(d.vars || []).join(', ')}`)
       .join('; ');
     output.push(`  Derived: ${derivedNames}`);
   }
@@ -579,7 +579,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
     const { themeData = null } = options;
     const targetParts = docs.theming.targets.map((/** @type {any} */ t) => {
       const parts = [t.className];
-      if (t.deprecatedFor) parts.push(`deprecated→${t.deprecatedFor}`);
+      if (t.deprecatedFor) parts.push(`deprecated->${t.deprecatedFor}`);
       const dataAttrs = getTargetDataAttributes(t);
       if (dataAttrs.length) parts.push(`preferred attrs: ${dataAttrs.join(', ')}`);
       if (t.visualProps?.length) parts.push(`variants: ${t.visualProps.join(', ')}`);
@@ -595,7 +595,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
 
   // Other props
   if (otherProps.length > 0) {
-    output.push(`  ${otherProps.join(' · ')}`);
+    output.push(`  ${otherProps.join(', ')}`);
   }
 
   // First code example

package/clients/cli/lib/component-format.test.mjs

@@ -157,7 +157,7 @@ describe('deprecated theming target guidance', () => {
 
   it('keeps the replacement in brief agent guidance', () => {
     expect(formatBrief(docs, 'Example')).toContain(
-      'astryx-old-target deprecated→new-target',
+      'astryx-old-target deprecated->new-target',
     );
   });
 });