@astryxdesign/cli 0.1.7-canary.cecb773 → 0.1.7-canary.d91c851

package/src/commands/upgrade.test.mjs

@@ -6,6 +6,7 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import {Command} from 'commander';
 import {registerUpgrade} from './upgrade.mjs';
+import {generateCompressedIndex} from './agent-docs.mjs';
 
 let tmpDir;
 let originalCwd;
@@ -158,3 +159,156 @@ describe('upgrade --list dedup', () => {
     expect(names.length).toBe(unique.size);
   });
 });
+
+// Issue #4168 — `upgrade` must refresh the managed agent-docs block after a
+// version bump, on EVERY path (the block documents the installed library, not
+// the codemod outcome), and must NOT write during a dry run.
+describe('upgrade agent-docs refresh (#4168)', () => {
+  /** Write an agent-doc file with a managed block generated for `version`. */
+  function writeAgentBlock(rel, version) {
+    const filePath = path.join(tmpDir, rel);
+    fs.mkdirSync(path.dirname(filePath), {recursive: true});
+    fs.writeFileSync(filePath, `# Doc\n\n${generateCompressedIndex(version)}\n`);
+  }
+
+  it('refreshes a stale block with --apply, even when there are no codemods (up-to-date path)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeAgentBlock('AGENTS.md', '0.0.1');
+
+    // --from == installed → up-to-date short-circuit: no codemods run, yet the
+    // stale block must still be brought current. This is the exact gap in #4168.
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.type).toBe('upgrade.status');
+    expect(result.data.status).toBe('up_to_date');
+    expect(result.data.agentDocs.status).toBe('stale');
+    expect(result.data.agentDocs.action).toBe('refreshed');
+    expect(result.data.agentDocs.refreshed).toBe(true);
+    expect(result.data.agentDocs.fromVersions).toEqual(['0.0.1']);
+    expect(result.data.agentDocs.files).toContain('AGENTS.md');
+
+    const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+    expect(content).toMatch(/Astryx v0\.0\.15 ·/);
+    expect(content).not.toMatch(/Astryx v0\.0\.1 ·/);
+  });
+
+  it('reports a stale block on a dry run WITHOUT writing', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeAgentBlock('AGENTS.md', '0.0.1');
+    const before = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15']); // no --apply
+
+    expect(result.data.agentDocs.status).toBe('stale');
+    expect(result.data.agentDocs.action).toBe('would-refresh');
+    expect(result.data.agentDocs.refreshed).toBe(false);
+    // The file must be untouched by a dry run.
+    expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toBe(before);
+  });
+
+  it('refreshes a stale block on the no-codemods path (--apply)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.11'); // (0.0.10, 0.0.11] has no registered codemods
+    writeSourceFile();
+    writeAgentBlock('CLAUDE.md', '0.0.1');
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.10', '--apply', '--path', 'src']);
+
+    expect(result.type).toBe('upgrade.status');
+    expect(result.data.status).toBe('no_codemods');
+    expect(result.data.agentDocs.refreshed).toBe(true);
+    expect(fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8')).toMatch(/Astryx v0\.0\.11 ·/);
+  });
+
+  it('nudges to run init when core is installed but no managed block exists', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    // No agent-doc files at all.
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('missing');
+    expect(result.data.agentDocs.action).toBe('nudge-init');
+    expect(result.data.agentDocs.refreshed).toBe(false);
+    // Must NOT silently create docs during an upgrade.
+    expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
+  });
+
+  it('treats an agent file without our markers as "never initialized" (missing)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n\nHand-written, no astryx block.\n');
+    const before = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('missing');
+    expect(result.data.agentDocs.action).toBe('nudge-init');
+    // An unmarked file is left exactly as-is.
+    expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toBe(before);
+  });
+
+  it('does not silently no-op a stale block with malformed markers (START without END)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    // A corrupted block: START + version header but no matching END marker, so
+    // the writer can't safely splice it. This must not crash, corrupt the file,
+    // or falsely claim success — it should surface an error and nudge re-init.
+    const corrupted =
+      '# A\n\n<!-- ASTRYX:START -->\nAstryx v0.0.1 · 9 components\nguidance, but no end marker\n';
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), corrupted);
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('stale');
+    expect(result.data.agentDocs.action).toBe('error');
+    expect(result.data.agentDocs.refreshed).toBe(false);
+    // File left byte-for-byte intact — never corrupted.
+    expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toBe(corrupted);
+  });
+
+  it('stays silent when the block already matches the installed version', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeAgentBlock('AGENTS.md', '0.0.15');
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('current');
+    expect(result.data.agentDocs.action).toBe('none');
+    expect(result.data.agentDocs.refreshed).toBe(false);
+  });
+
+  it('migrates a legacy XDS block to the current Astryx block (--apply)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    fs.writeFileSync(
+      path.join(tmpDir, 'CLAUDE.md'),
+      '# Claude\n\n<!-- XDS:START -->\nlegacy index\n<!-- XDS:END -->\n\nMore rules.\n',
+    );
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('stale');
+    expect(result.data.agentDocs.refreshed).toBe(true);
+    const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+    expect(content).toContain('<!-- ASTRYX:START -->');
+    expect(content).toMatch(/Astryx v0\.0\.15 ·/);
+    expect(content).not.toContain('legacy index');
+    expect(content).toContain('More rules.');
+  });
+
+  it('surfaces agentDocs in the human output on the up-to-date path', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeAgentBlock('AGENTS.md', '0.0.1');
+
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', 'upgrade', '--from', '0.0.15', '--apply']);
+    const output = stdoutCalls.join('') + logCalls.join('\n');
+    expect(output).toMatch(/Agent docs refreshed/i);
+  });
+});

package/src/types/upgrade.d.ts

@@ -23,6 +23,31 @@ export interface UpgradeListEntry {
   version: string;
 }
 
+/**
+ * State of the managed agent-docs block (`<!-- ASTRYX:START --> … END -->`)
+ * relative to the installed core version, plus what `upgrade` did about it.
+ * Present on every upgrade response (run, status, and the codemod/config error
+ * envelopes) because the block is refreshed independently of codemods.
+ *
+ * - `refreshed`     — a stale block was rewritten (`--apply` only).
+ * - `would-refresh` — a stale block was detected in dry-run; nothing written.
+ * - `nudge-init`    — no managed block exists; user should run `init`.
+ * - `error`         — refresh was attempted but writing failed.
+ * - `none`          — nothing to do (block already current).
+ */
+export interface AgentDocsSummary {
+  status: 'missing' | 'stale' | 'current';
+  /** Installed core version the block should reflect. */
+  installedVersion: string;
+  /** Distinct stale block versions found (the "from" side of the refresh). */
+  fromVersions: string[];
+  /** Files rewritten (apply) or that would be rewritten (dry-run). */
+  files: string[];
+  /** True only when a block was actually rewritten (apply mode). */
+  refreshed: boolean;
+  action: 'refreshed' | 'would-refresh' | 'nudge-init' | 'error' | 'none';
+}
+
 /** xds --json upgrade [--apply] */
 export interface UpgradeRunResponse {
   type: 'upgrade.run';
@@ -32,6 +57,7 @@ export interface UpgradeRunResponse {
     codemods: number;
     depsUpdated: string[];
     agentDocsRefreshed: boolean;
+    agentDocs: AgentDocsSummary;
   };
 }
 
@@ -49,8 +75,18 @@ export interface UpgradeRunResponse {
 export interface UpgradeStatusResponse {
   type: 'upgrade.status';
   data:
-    | {status: 'up_to_date'; from: string; to: string}
-    | {status: 'no_codemods'; from: string; to: string}
+    | {
+        status: 'up_to_date';
+        from: string;
+        to: string;
+        agentDocs: AgentDocsSummary;
+      }
+    | {
+        status: 'no_codemods';
+        from: string;
+        to: string;
+        agentDocs: AgentDocsSummary;
+      }
     | {
         status: 'config_fixable';
         from: string;
@@ -60,5 +96,6 @@ export interface UpgradeStatusResponse {
         suggestedCommand: string;
         message: string;
         note: string;
+        agentDocs: AgentDocsSummary;
       };
 }

package/templates/blocks/components/Avatar/AvatarFallbackChain.tsx

@@ -13,7 +13,7 @@ export default function AvatarFallbackChain() {
         <Avatar
           src="https://lookaside.facebook.com/assets/astryx/DATA-Daniela-Gimenez.png"
           name="Daniela Gimenez"
-          size="medium"
+          size="lg"
         />
         <Text type="supporting">Valid src</Text>
       </HStack>
@@ -22,7 +22,7 @@ export default function AvatarFallbackChain() {
           src="https://lookaside.facebook.com/assets/astryx/does-not-exist-primary.jpg"
           fallbackSrc="https://lookaside.facebook.com/assets/astryx/DATA-Ami-Pena.png"
           name="Invalid User"
-          size="medium"
+          size="lg"
         />
         <Text type="supporting">Invalid src, valid fallbackSrc</Text>
       </HStack>
@@ -31,14 +31,14 @@ export default function AvatarFallbackChain() {
           src="https://lookaside.facebook.com/assets/astryx/does-not-exist-primary.jpg"
           fallbackSrc="https://lookaside.facebook.com/assets/astryx/does-not-exist-fallback.jpg"
           name="Test User"
-          size="medium"
+          size="lg"
         />
         <Text type="supporting">Both invalid, has name</Text>
       </HStack>
       <HStack gap={3} vAlign="center">
         <Avatar
           src="https://lookaside.facebook.com/assets/astryx/does-not-exist-primary.jpg"
-          size="medium"
+          size="lg"
         />
         <Text type="supporting">All invalid, no name</Text>
       </HStack>

package/templates/blocks/components/Avatar/AvatarGroup.tsx

@@ -37,7 +37,7 @@ export default function AvatarGroupBlock() {
         <Text type="supporting" color="secondary">
           Team members
         </Text>
-        <AvatarGroup size="medium">
+        <AvatarGroup size="lg">
           {USERS.map(user => (
             <Avatar key={user.name} src={user.src} name={user.name} />
           ))}
@@ -48,7 +48,7 @@ export default function AvatarGroupBlock() {
         <Text type="supporting" color="secondary">
           Larger group
         </Text>
-        <AvatarGroup size="medium">
+        <AvatarGroup size="lg">
           {USERS.slice(0, 3).map(user => (
             <Avatar key={user.name} src={user.src} name={user.name} />
           ))}

package/templates/blocks/components/Avatar/AvatarInitialsFallback.tsx

@@ -18,7 +18,7 @@ export default function AvatarInitialsFallback() {
     <Stack direction="horizontal" gap={6} vAlign="center">
       {NAMES.map(({name, note}) => (
         <Stack key={name} direction="vertical" gap={2} hAlign="center">
-          <Avatar name={name} size="medium" />
+          <Avatar name={name} size="lg" />
           <Text type="supporting" color="secondary">
             {note}
           </Text>

package/templates/blocks/components/Avatar/AvatarShowcase.tsx

@@ -11,23 +11,23 @@ export default function AvatarShowcase() {
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Ana-Thomas.png"
         name="Ana Thomas"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="success" label="Online" />}
       />
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Drew-Young.png"
         name="Drew Young"
-        size="large"
+        size="xl"
       />
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Jihoo-Song.png"
         name="Jihoo Song"
-        size="large"
+        size="xl"
       />
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Nam-Tran.png"
         name="Nam Tran"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="error" label="Online" />}
       />
     </Stack>

package/templates/blocks/components/Avatar/AvatarUserCard.tsx

@@ -35,7 +35,7 @@ export default function AvatarUserCard() {
           <Avatar
             src={user.src}
             name={user.name}
-            size="medium"
+            size="lg"
             status={
               <AvatarStatusDot variant={user.variant} label={user.variant} />
             }

package/templates/blocks/components/Avatar/AvatarWithImage.tsx

@@ -11,22 +11,22 @@ export default function AvatarWithImage() {
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Ami-Pena.png"
         name="Ami Pena"
-        size="tiny"
+        size="xsm"
       />
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Ana-Thomas.png"
         name="Ana Thomas"
-        size="small"
+        size="md"
       />
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Daniela-Gimenez.png"
         name="Daniela Gimenez"
-        size="medium"
+        size="lg"
       />
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Gabriela-Fernandez.png"
         name="Gabriela Fernandez"
-        size="large"
+        size="xl"
       />
     </Stack>
   );

package/templates/blocks/components/Avatar/AvatarWithStatus.tsx

@@ -11,19 +11,19 @@ export default function AvatarWithStatus() {
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Itai-Jordaan.png"
         name="Itai Jordaan"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="success" label="Online" />}
       />
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Margot-Schroder.png"
         name="Margot Schroder"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="neutral" label="Offline" />}
       />
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Pablo-Morales.png"
         name="Pablo Morales"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="error" label="Busy" />}
       />
     </Stack>

package/templates/blocks/components/AvatarGroup/AvatarGroupShowcase.tsx

@@ -36,7 +36,7 @@ export default function AvatarGroupShowcase() {
         <Text type="supporting" color="secondary">
           Team members
         </Text>
-        <AvatarGroup size="medium">
+        <AvatarGroup size="lg">
           {USERS.map(u => (
             <Avatar key={u.key} name={u.name} />
           ))}
@@ -46,7 +46,7 @@ export default function AvatarGroupShowcase() {
         <Text type="supporting" color="secondary">
           With overflow
         </Text>
-        <AvatarGroup size="medium">
+        <AvatarGroup size="lg">
           {USERS.slice(0, 3).map(u => (
             <Avatar key={u.key} name={u.name} />
           ))}

package/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowCustomText.tsx

@@ -24,7 +24,7 @@ export default function AvatarGroupOverflowCustomText() {
       <Text type="supporting" color="secondary">
         Team members
       </Text>
-      <AvatarGroup size="medium">
+      <AvatarGroup size="lg">
         {TEAM.map(member => (
           <Avatar key={member.name} name={member.name} />
         ))}

package/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowDefault.tsx

@@ -24,7 +24,7 @@ export default function AvatarGroupOverflowDefault() {
       <Text type="supporting" color="secondary">
         Reviewers
       </Text>
-      <AvatarGroup size="medium">
+      <AvatarGroup size="lg">
         {REVIEWERS.map(reviewer => (
           <Avatar key={reviewer.name} name={reviewer.name} />
         ))}

package/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowShowcase.tsx

@@ -25,7 +25,7 @@ export default function AvatarGroupOverflowShowcase() {
         <Text type="supporting" color="secondary">
           Default overflow
         </Text>
-        <AvatarGroup size="medium">
+        <AvatarGroup size="lg">
           {USERS.map(user => (
             <Avatar key={user.name} name={user.name} />
           ))}
@@ -36,7 +36,7 @@ export default function AvatarGroupOverflowShowcase() {
         <Text type="supporting" color="secondary">
           Custom count text
         </Text>
-        <AvatarGroup size="medium">
+        <AvatarGroup size="lg">
           {USERS.slice(0, 2).map(user => (
             <Avatar key={user.name} name={user.name} />
           ))}

package/templates/blocks/components/AvatarStatusDot/AvatarStatusDotShowcase.tsx

@@ -10,17 +10,17 @@ export default function AvatarStatusDotShowcase() {
     <HStack gap={4} vAlign="center">
       <Avatar
         name="Online User"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="success" label="Online" />}
       />
       <Avatar
         name="Away User"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="neutral" label="Away" />}
       />
       <Avatar
         name="Busy User"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="error" label="Busy" />}
       />
     </HStack>

package/templates/blocks/components/AvatarStatusDot/AvatarStatusDotVariants.tsx

@@ -10,17 +10,17 @@ export default function AvatarStatusDotVariants() {
     <HStack gap={4} vAlign="center">
       <Avatar
         name="Ana Silva"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="success" label="Online" />}
       />
       <Avatar
         name="Ben Okafor"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="neutral" label="Away" />}
       />
       <Avatar
         name="Cleo Marsh"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="error" label="Do not disturb" />}
       />
     </HStack>

package/templates/blocks/components/Carousel/CarouselSnap.tsx

@@ -27,7 +27,7 @@ export default function CarouselSnap() {
         {TEAM.map(person => (
           <Card key={person.name} width={180} minHeight={140}>
             <Stack direction="vertical" gap={3} hAlign="center">
-              <Avatar name={person.name} size="medium" />
+              <Avatar name={person.name} size="lg" />
               <Stack direction="vertical" gap={1} hAlign="center">
                 <Text type="body" weight="bold">
                   {person.name}

package/templates/blocks/components/ChatMessage/ChatMessageAvatarName.tsx

@@ -17,7 +17,7 @@ export default function ChatMessageAvatarName() {
     <ChatMessageList style={{maxWidth: 500}}>
       <ChatMessage
         sender="assistant"
-        avatar={<Avatar name="Agent" size="small" />}>
+        avatar={<Avatar name="Agent" size="md" />}>
         <ChatMessageBubble
           name={
             <Text type="supporting" weight="semibold" color="secondary">
@@ -50,7 +50,7 @@ export default function ChatMessageAvatarName() {
       </ChatMessage>
       <ChatMessage
         sender="assistant"
-        avatar={<Avatar name="Agent" size="small" />}>
+        avatar={<Avatar name="Agent" size="md" />}>
         <ChatMessageBubble
           name={
             <Text type="supporting" weight="semibold" color="secondary">

package/templates/blocks/components/ChatMessage/ChatMessageMultiBubble.tsx

@@ -37,7 +37,7 @@ export default function ChatMessageMultiBubble() {
       </ChatMessage>
       <ChatMessage
         sender="assistant"
-        avatar={<Avatar name="Agent" size="small" />}>
+        avatar={<Avatar name="Agent" size="md" />}>
         <ChatMessageBubble
           group="first"
           name={

package/templates/blocks/components/ChatMessageBubble/ChatMessageBubbleGrouping.tsx

@@ -17,7 +17,7 @@ export default function ChatMessageBubbleGrouping() {
     <ChatMessageList style={{maxWidth: 500}}>
       <ChatMessage
         sender="assistant"
-        avatar={<Avatar name="Agent" size="small" />}>
+        avatar={<Avatar name="Agent" size="md" />}>
         <ChatMessageBubble
           group="first"
           name={

package/templates/blocks/components/ChatMessageBubble/ChatMessageBubbleMetadata.tsx

@@ -20,7 +20,7 @@ export default function ChatMessageBubbleMetadata() {
     <ChatMessageList style={{maxWidth: 500}}>
       <ChatMessage
         sender="assistant"
-        avatar={<Avatar name="Agent" size="small" />}>
+        avatar={<Avatar name="Agent" size="md" />}>
         <ChatMessageBubble
           name={
             <Text type="supporting" weight="semibold" color="secondary">

package/templates/blocks/components/ChatMessageList/ChatMessageListDensity.tsx

@@ -16,9 +16,9 @@ import {Fragment} from 'react';
 const DENSITIES = ['compact', 'balanced', 'spacious'] as const;
 
 const AVATAR_SIZE = {
-  compact: 'xsmall' as const,
-  balanced: 'small' as const,
-  spacious: 'small' as const,
+  compact: 'sm' as const,
+  balanced: 'md' as const,
+  spacious: 'md' as const,
 };
 
 export default function ChatMessageListDensity() {
@@ -34,15 +34,11 @@ export default function ChatMessageListDensity() {
             <VStack style={{flex: 1, minHeight: 0}}>
               <ChatMessageList density={density}>
                 <ChatMessage sender="user">
-                  <ChatMessageBubble>
-                    How does density work?
-                  </ChatMessageBubble>
+                  <ChatMessageBubble>How does density work?</ChatMessageBubble>
                 </ChatMessage>
                 <ChatMessage
                   sender="assistant"
-                  avatar={
-                    <Avatar name="Agent" size={AVATAR_SIZE[density]} />
-                  }>
+                  avatar={<Avatar name="Agent" size={AVATAR_SIZE[density]} />}>
                   <ChatMessageBubble>
                     Density provides default spacing at every level — message
                     gap, bubble padding, and gap between child elements. Use gap

package/templates/blocks/components/ChatMessageList/ChatMessageListFullFeatured.tsx

@@ -42,7 +42,7 @@ export default function ChatMessageListFullFeatured() {
 
         <ChatMessage
           sender="assistant"
-          avatar={<Avatar name="Agent" size="small" />}>
+          avatar={<Avatar name="Agent" size="md" />}>
           <ChatMessageBubble group="first">
             <Markdown density="compact">
               {`Sure! Here's the key pattern from **useReducer.ts**:`}

package/templates/blocks/components/HoverCard/HoverCardShowcase.tsx

@@ -15,7 +15,7 @@ export default function HoverCardShowcase() {
       content={
         <Stack direction="vertical" gap={2} style={{width: 240}}>
           <Stack direction="horizontal" gap={2} vAlign="center">
-            <Avatar name="Jane Doe" size="medium" />
+            <Avatar name="Jane Doe" size="lg" />
             <Stack direction="vertical" gap={0}>
               <Heading level={5}>Jane Doe</Heading>
               <Text type="supporting" color="secondary">

package/templates/blocks/components/Item/ItemWithMedia.tsx

@@ -13,14 +13,14 @@ export default function ItemWithMedia() {
   return (
     <Stack gap={0}>
       <Item
-        startContent={<Avatar name="Ada Lovelace" size="xsmall" />}
+        startContent={<Avatar name="Ada Lovelace" size="sm" />}
         label="Ada Lovelace"
         description="Design systems engineer"
         endContent={<Badge label="Owner" variant="purple" />}
         onClick={() => {}}
       />
       <Item
-        startContent={<Avatar name="Grace Hopper" size="xsmall" />}
+        startContent={<Avatar name="Grace Hopper" size="sm" />}
         label="Grace Hopper"
         description="Compiler platform"
         endContent={<Text color="secondary">Online</Text>}

package/templates/blocks/components/ListItem/ListItemWithMedia.tsx

@@ -13,14 +13,14 @@ export default function ListItemWithMedia() {
       <ListItem
         label="Ada Lovelace"
         description="Design systems engineer"
-        startContent={<Avatar name="Ada Lovelace" size="xsmall" />}
+        startContent={<Avatar name="Ada Lovelace" size="sm" />}
         endContent={<Badge label="Owner" variant="purple" />}
         onClick={() => {}}
       />
       <ListItem
         label="Grace Hopper"
         description="Platform infrastructure"
-        startContent={<Avatar name="Grace Hopper" size="xsmall" />}
+        startContent={<Avatar name="Grace Hopper" size="sm" />}
         endContent={<Badge label="On call" variant="blue" />}
         onClick={() => {}}
       />