@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/assets/discover/official-packages.json

@@ -0,0 +1,367 @@
+{
+  "packages": [
+    {
+      "package": "@astryxdesign/charts",
+      "description": "Astryx charts — a config-model data visualization library (d3-based). Published to npm only under the @canary dist-tag for early testing; never released as a stable (latest) version.",
+      "canaryOnly": true,
+      "contributions": [
+        {
+          "kind": "component",
+          "name": "Chart"
+        },
+        {
+          "kind": "component",
+          "name": "ChartAxis"
+        },
+        {
+          "kind": "component",
+          "name": "ChartGrid"
+        },
+        {
+          "kind": "component",
+          "name": "ChartLegend"
+        },
+        {
+          "kind": "component",
+          "name": "ChartSwatch"
+        },
+        {
+          "kind": "component",
+          "name": "ChartTooltip"
+        },
+        {
+          "kind": "template",
+          "name": "ChartShowcase"
+        },
+        {
+          "kind": "template",
+          "name": "ChartTrendComparison"
+        }
+      ]
+    },
+    {
+      "package": "@astryxdesign/lab",
+      "description": "Experimental Astryx components — published to npm only under the @canary dist-tag for early testing; never released as a stable (latest) version.",
+      "canaryOnly": true,
+      "contributions": [
+        {
+          "kind": "component",
+          "name": "ChartArea"
+        },
+        {
+          "kind": "component",
+          "name": "ChartBar"
+        },
+        {
+          "kind": "component",
+          "name": "ChartCandlestick"
+        },
+        {
+          "kind": "component",
+          "name": "ChartDot"
+        },
+        {
+          "kind": "component",
+          "name": "ChartDotGL"
+        },
+        {
+          "kind": "component",
+          "name": "ChartDotGLInteractive"
+        },
+        {
+          "kind": "component",
+          "name": "ChartHeatmapGL"
+        },
+        {
+          "kind": "component",
+          "name": "ChartLine"
+        },
+        {
+          "kind": "component",
+          "name": "ChartStreamGL"
+        },
+        {
+          "kind": "component",
+          "name": "ChatEmojiPicker"
+        },
+        {
+          "kind": "component",
+          "name": "ChatReactionBar"
+        },
+        {
+          "kind": "component",
+          "name": "ChatReasoning"
+        },
+        {
+          "kind": "component",
+          "name": "ChatTypingIndicator"
+        },
+        {
+          "kind": "component",
+          "name": "ChatUnreadDivider"
+        },
+        {
+          "kind": "component",
+          "name": "CircularProgress"
+        },
+        {
+          "kind": "component",
+          "name": "CodeEditor"
+        },
+        {
+          "kind": "component",
+          "name": "CommentComposer"
+        },
+        {
+          "kind": "component",
+          "name": "CommentPin"
+        },
+        {
+          "kind": "component",
+          "name": "Comments"
+        },
+        {
+          "kind": "component",
+          "name": "CommentThread"
+        },
+        {
+          "kind": "component",
+          "name": "DiffViewer"
+        },
+        {
+          "kind": "component",
+          "name": "EmojiPicker"
+        },
+        {
+          "kind": "component",
+          "name": "InfoTip"
+        },
+        {
+          "kind": "component",
+          "name": "ListInput"
+        },
+        {
+          "kind": "component",
+          "name": "LogStream"
+        },
+        {
+          "kind": "component",
+          "name": "MobileTokenizer"
+        },
+        {
+          "kind": "component",
+          "name": "RadialChart"
+        },
+        {
+          "kind": "component",
+          "name": "SankeyChart"
+        },
+        {
+          "kind": "component",
+          "name": "Schedule"
+        },
+        {
+          "kind": "component",
+          "name": "Stat"
+        },
+        {
+          "kind": "component",
+          "name": "SVGIcon"
+        },
+        {
+          "kind": "component",
+          "name": "ThreeDBar"
+        },
+        {
+          "kind": "component",
+          "name": "ThreeDChart"
+        },
+        {
+          "kind": "component",
+          "name": "ThreeDScatter"
+        },
+        {
+          "kind": "component",
+          "name": "ThreeDScatterGL"
+        },
+        {
+          "kind": "component",
+          "name": "ThreeDSurface"
+        },
+        {
+          "kind": "component",
+          "name": "Tour"
+        },
+        {
+          "kind": "component",
+          "name": "TourStep"
+        },
+        {
+          "kind": "component",
+          "name": "TransferList"
+        },
+        {
+          "kind": "template",
+          "name": "CommentComposerShowcase"
+        },
+        {
+          "kind": "template",
+          "name": "CommentPinInMargin"
+        },
+        {
+          "kind": "template",
+          "name": "CommentPinShowcase"
+        },
+        {
+          "kind": "template",
+          "name": "CommentsInCard"
+        },
+        {
+          "kind": "template",
+          "name": "CommentsInline"
+        },
+        {
+          "kind": "template",
+          "name": "CommentsShowcase"
+        },
+        {
+          "kind": "template",
+          "name": "CommentThreadInPopover"
+        },
+        {
+          "kind": "template",
+          "name": "CommentThreadShowcase"
+        },
+        {
+          "kind": "template",
+          "name": "DiffViewerShowcase"
+        },
+        {
+          "kind": "template",
+          "name": "EmojiPickerInPopover"
+        },
+        {
+          "kind": "template",
+          "name": "EmojiPickerShowcase"
+        }
+      ]
+    },
+    {
+      "package": "@astryxdesign/richtext",
+      "description": "Astryx rich text — a Lexical-based rich text editor and viewer, styled with Astryx design tokens.",
+      "releasedWithCore": true,
+      "contributions": [
+        {
+          "kind": "component",
+          "name": "RichTextEditor"
+        },
+        {
+          "kind": "template",
+          "name": "RichTextEditorShowcase"
+        }
+      ]
+    },
+    {
+      "package": "@astryxdesign/theme-butter",
+      "description": "Warm, creamy yellows with a friendly blue accent. Playful enough for consumer surfaces, soft enough to stay readable.",
+      "releasedWithCore": true,
+      "contributions": [
+        {
+          "kind": "theme",
+          "name": "butter",
+          "title": "Butter",
+          "summary": "Warm, creamy yellows with a friendly blue accent. Playful enough for consumer surfaces, soft enough to stay readable."
+        }
+      ]
+    },
+    {
+      "package": "@astryxdesign/theme-chocolate",
+      "description": "Warm chocolate theme for Astryx — rich brown palette with Fraunces headings, Albert Sans body, and Lucide icons",
+      "releasedWithCore": true,
+      "contributions": [
+        {
+          "kind": "theme",
+          "name": "chocolate",
+          "title": "Chocolate",
+          "summary": "Warm chocolate theme for Astryx — rich brown palette with Fraunces headings, Albert Sans body, and Lucide icons"
+        }
+      ]
+    },
+    {
+      "package": "@astryxdesign/theme-gothic",
+      "description": "Deep blue-grays and a signature display serif. Dramatic and editorial, for surfaces that want to be remembered.",
+      "releasedWithCore": true,
+      "contributions": [
+        {
+          "kind": "theme",
+          "name": "gothic",
+          "title": "Gothic",
+          "summary": "Deep blue-grays and a signature display serif. Dramatic and editorial, for surfaces that want to be remembered."
+        }
+      ]
+    },
+    {
+      "package": "@astryxdesign/theme-matcha",
+      "description": "Earthy greens with a calm, organic feel. Naturalistic and grounded, great for wellness or content-first apps.",
+      "releasedWithCore": true,
+      "contributions": [
+        {
+          "kind": "theme",
+          "name": "matcha",
+          "title": "Matcha",
+          "summary": "Earthy greens with a calm, organic feel. Naturalistic and grounded, great for wellness or content-first apps."
+        }
+      ]
+    },
+    {
+      "package": "@astryxdesign/theme-neutral",
+      "description": "Restrained warm grays. Minimal and quiet, so the content stays the focus.",
+      "releasedWithCore": true,
+      "contributions": [
+        {
+          "kind": "theme",
+          "name": "neutral",
+          "title": "Neutral",
+          "summary": "Restrained warm grays. Minimal and quiet, so the content stays the focus."
+        }
+      ]
+    },
+    {
+      "package": "@astryxdesign/theme-stone",
+      "description": "Warm stone and slate, earthy and understated, with just enough character to feel handcrafted.",
+      "releasedWithCore": true,
+      "contributions": [
+        {
+          "kind": "theme",
+          "name": "stone",
+          "title": "Stone",
+          "summary": "Warm stone and slate, earthy and understated, with just enough character to feel handcrafted."
+        }
+      ]
+    },
+    {
+      "package": "@astryxdesign/theme-y2k",
+      "description": "Hot pinks, lime greens, and Poppins. Bubbly, playful, and unmistakably retro.",
+      "releasedWithCore": true,
+      "contributions": [
+        {
+          "kind": "theme",
+          "name": "y2k",
+          "title": "Y2K",
+          "summary": "Hot pinks, lime greens, and Poppins. Bubbly, playful, and unmistakably retro."
+        }
+      ]
+    },
+    {
+      "package": "@astryxdesign/vega",
+      "description": "Astryx Vega wrapper — chart and data visualization components. Published to npm only under the @canary dist-tag for early testing; never released as a stable (latest) version.",
+      "canaryOnly": true,
+      "contributions": [
+        {
+          "kind": "component",
+          "name": "VegaChart"
+        }
+      ]
+    }
+  ]
+}

package/assets/docs/README.md

@@ -51,6 +51,16 @@ The material is usually good; the finding is placement, not quality. It goes in
 
 Worked example: a responsive-and-interaction readiness rubric is grading criteria → **Component-Audit-Rubric**, or **Component-Lifecycle** if it is a promotion gate.
 
+## Imports in code samples
+
+Import each Core export from the path `astryx component <Name>` prints: the
+component's own entry when Core has one (`@astryxdesign/core/VStack`,
+`@astryxdesign/core/Heading`), and `@astryxdesign/core/theme` for `Theme`,
+`defineTheme` and the rest of the theme API. A reader copies one sample and then
+reads `astryx component`, and two paths for one export read as two different
+things. The no-build CDN page is the exception: its import map names only the
+package root.
+
 ## Sections are read one at a time
 
 `astryx docs <topic> --index` lists a topic's sections, and readers then open

package/assets/docs/author-a-theme.doc.mjs

@@ -17,14 +17,14 @@ export const docs = {
         {type: 'prose', text: "Use an installed built theme as the base for ordinary customization. Import it into your source and pass it as `extends` to `defineTheme({extends: importedTheme, ...})`. Build the result, then add the local slug. Only eject when you need to own and maintain a full source fork."},
         {type: 'code', lang: 'bash', label: 'Add to use, eject to fork', code: 'astryx theme list\nastryx theme add stone\nastryx theme eject stone\nastryx theme build src/themes/stone/stoneTheme.ts\nastryx theme add stone'},
         {type: 'prose', text: "For an annotated map of the whole surface (every defineTheme field, the token families, and the component override syntax, each with the CLI command that prints its reference), run `astryx theme template`. It writes `theme.template.ts` into your project to read and copy from (`astryx init --features theme` writes it as part of project setup)."},
-        {type: 'prose', text: 'To apply a theme you created, see {@link generic:use-a-theme}. To generate colors from seed values, see the Palette section below. Use `theme eject` only when you want an independent source fork that no longer receives the package owner\u2019s updates.'},
+        {type: 'prose', text: 'To apply a theme you created, see {@link generic:use-a-theme}. To generate colors from seed values, see the Palette section below. Before you eject a package theme instead, see when that fits in {@link generic:use-a-theme}.'},
       ],
     },
     {
       id: 'palette',
       title: 'Generate a palette',
       content: [
-        {type: 'prose', text: 'A theme needs dozens of related colors for backgrounds, borders, text, and states, in both light and dark mode. Rather than pick each by hand, name a few seed colors and generate the rest.'},
+        {type: 'prose', text: 'Name a few seed colors and generate every shade a theme needs, light and dark; {@link generic:generate-a-palette} explains what a palette holds.'},
         {type: 'code', lang: 'json', label: 'Minimal palette config (palette.config.json)', code: '{"families": [{"id": "ocean", "seed": "#0074e2"}]}'},
         {type: 'code', lang: 'bash', label: 'Generate and preview', code: '# Print the palette without writing files\nastryx theme palette generate palette.config.json\n\n# Write palette + receipt, and open a visual preview\nastryx theme palette generate palette.config.json \\\n  --out src/themes/ocean/tokens/ocean.palette.ts \\\n  --preview preview.html'},
         {type: 'prose', text: "The command writes a `.ts` file exporting 21 shades (stops 0–100) for both light and dark, plus a `.receipt.json` to regenerate later. Point your theme's tokens at the palette, then run defineTheme (see below)."},
@@ -120,7 +120,7 @@ export const docs = {
           ['ocean.variants.d.ts', "(Optional) Module augmentations for custom component prop values"],
         ]},
         {type: 'prose', text: 'The `__built: true` flag tells Theme to skip runtime `<style>` injection; the CSS file handles it. Load the generated CSS wherever you load the module.'},
-        {type: 'code', lang: 'tsx', label: 'Using a custom built theme', code: "import {Theme} from '@astryxdesign/core';\nimport {oceanTheme} from './themes/ocean';\nimport './themes/ocean.css';\n\n<Theme theme={oceanTheme}>\n  <App />\n</Theme>"},
+        {type: 'code', lang: 'tsx', label: 'Using a custom built theme', code: "import {Theme} from '@astryxdesign/core/theme';\nimport {oceanTheme} from './themes/ocean';\nimport './themes/ocean.css';\n\n<Theme theme={oceanTheme}>\n  <App />\n</Theme>"},
         {type: 'prose', text: "After upgrading Astryx, rerun `astryx theme build` for every custom prebuilt theme. Deploy the regenerated files together. The runtime intentionally trusts `__built: true` and will not repair stale CSS from an older build. The build also warns when the theme names font families it does not load. See {@link generic:font-setup} for the full recipe."},
         {type: 'prose', text: 'For the runtime vs built tradeoff, see the Runtime vs Built section of {@link generic:use-a-theme}.'},
       ],

package/assets/docs/browser-support.doc.mjs

@@ -149,7 +149,7 @@ export const docs = {
           type: 'list',
           style: 'ordered',
           items: [
-            'Polyfill anchor positioning. Load a CSS anchor positioning polyfill conditionally behind an `@supports` check so it costs nothing on Tier 1. This is the lowest-effort way to get correct positioning; note that polyfills may not cover every position-fallback feature.',
+            'Polyfill anchor positioning. Load a CSS anchor positioning polyfill conditionally behind an `@supports` check so it costs nothing on Tier 1. This is the lowest-effort way to get correct positioning; polyfills may not cover every position-fallback feature.',
             'Provide a JS positioning fallback. Detect missing support with `CSS.supports("anchor-name", "--x")` and position layers with a measurement-based library (e.g. a floating-element positioner) when it returns false. More code, full control.',
             'Accept degraded positioning. Document for your users that on Tier 2 browsers, layered surfaces open correctly but may not sit next to their trigger. Cheapest, and often fine for internal tools on evergreen browsers.',
           ],

package/assets/docs/getting-started.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
           type: 'code',
           lang: 'text',
           label: 'Set up the design system',
-          code: 'Install @astryxdesign/core, @stylexjs/stylex, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project, then run `npx @astryxdesign/cli init` to set up agent docs. Read the generated files to learn the conventions.',
+          code: 'Install @astryxdesign/core, @stylexjs/stylex, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project, then run `astryx init` to set up agent docs. Read the generated files to learn the conventions.',
         },
         {
           type: 'prose',
@@ -31,7 +31,7 @@ export const docs = {
           type: 'code',
           lang: 'text',
           label: 'Give it a look',
-          code: 'Ask me what look and feel this app should have. Run `npx @astryxdesign/cli theme list`, install the closest theme package, and run `theme add <slug>`; use `--package` when owners share a slug. Import `themes` and `defaultThemeSlug` from the generated module once and pass `themes[defaultThemeSlug]` to `<Theme>`. Customize with `defineTheme({extends: importedTheme, ...})`. Use `theme eject` only when I ask for an independent source fork. Default to neutral if I have no preference, and show me the result before moving on.',
+          code: 'Ask me what look and feel this app should have. Run `astryx theme list`, install the closest theme package, and run `theme add <slug>`; use `--package` when owners share a slug. Import `themes` and `defaultThemeSlug` from the generated module once and pass `themes[defaultThemeSlug]` to `<Theme>`. Customize with `defineTheme({extends: importedTheme, ...})`. Use `theme eject` only when I ask for an independent source fork. Default to neutral if I have no preference, and show me the result before moving on.',
         },
       ],
     },
@@ -60,7 +60,27 @@ export const docs = {
           type: 'code',
           lang: 'bash',
           label: 'Terminal',
-          code: `npx astryx init`,
+          code: `astryx init`,
+        },
+      ],
+    },
+    {
+      id: 'install-once',
+      title: 'Install once, use everywhere',
+      content: [
+        {
+          type: 'prose',
+          text: "Install the CLI once for your computer too, and the astryx command works in any folder, for you and for any coding agent, even before a project exists. Inside a project, the project's own version still answers, so a global install never changes what your team and CI get. Keep it in the project as well; that is the recommended setup.",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Terminal',
+          code: `npm i -g @astryxdesign/cli`,
+        },
+        {
+          type: 'prose',
+          text: 'Project, global, or both: {@link generic:project-global-or-both}. Everything else about global mode: {@link namespace:global}.',
         },
       ],
     },
@@ -86,7 +106,7 @@ export const docs = {
           type: 'code',
           lang: 'tsx',
           label: 'App root',
-          code: `import {Theme} from '@astryxdesign/core';
+          code: `import {Theme} from '@astryxdesign/core/theme';
 import {themes, defaultThemeSlug} from './astryx-themes';
 
 <Theme theme={themes[defaultThemeSlug]}><App /></Theme>`,
@@ -119,14 +139,14 @@ import {themes, defaultThemeSlug} from './astryx-themes';
       content: [
         {
           type: 'prose',
-          text: 'Components are imported from per-category subpath entrypoints. This keeps bundles small and makes intent clear.',
+          text: 'Import each component from its own entry, the path `astryx component <Name>` prints. This keeps bundles small and makes intent clear.',
         },
         {
           type: 'code',
           lang: 'tsx',
           label: 'app/page.tsx',
           code: `import {Button} from '@astryxdesign/core/Button';
-import {VStack} from '@astryxdesign/core/Layout';
+import {VStack} from '@astryxdesign/core/VStack';
 
 export default function Page() {
   return (

package/assets/docs/styling-overview.doc.mjs

@@ -158,7 +158,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'If a swizzled component renders with no styles and no error, a missing compiler is almost always why. See the StyleX Build Setup section of {@link generic:tokens-and-setup} for bundler config examples.',
+          text: 'If a swizzled component fails at runtime with a `stylex.create` error, the app is missing a StyleX compiler: see the StyleX Build Setup section of {@link generic:tokens-and-setup}.',
         },
       ],
     },

package/assets/docs/theme.doc.dense.mjs

@@ -9,7 +9,7 @@ export const docsDense = {
       section: 'Wrap your app in a theme',
       title: 'Quick start',
       content: [
-        {type: 'prose', text: "Install a theme, wrap in `<Theme>` (`import {Theme} from '@astryxdesign/core'`). {@link generic:use-a-theme} for full guide."},
+        {type: 'prose', text: "Install a theme, wrap in `<Theme>` (`import {Theme} from '@astryxdesign/core/theme'`). {@link generic:use-a-theme} for full guide."},
       ],
     },
     {

package/assets/docs/theme.doc.mjs

@@ -23,7 +23,7 @@ export const docs = {
           type: 'code',
           lang: 'tsx',
           label: 'Wire the generated module once',
-          code: "import {Theme} from '@astryxdesign/core';\nimport {themes, defaultThemeSlug} from './astryx-themes';\n\nfunction App() {\n  return (\n    <Theme theme={themes[defaultThemeSlug]}>\n      <YourApp />\n    </Theme>\n  );\n}",
+          code: "import {Theme} from '@astryxdesign/core/theme';\nimport {themes, defaultThemeSlug} from './astryx-themes';\n\nfunction App() {\n  return (\n    <Theme theme={themes[defaultThemeSlug]}>\n      <YourApp />\n    </Theme>\n  );\n}",
         },
       ],
     },
@@ -59,7 +59,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "Use [light, dark] tuples in token values for automatic mode switching. Use mode='system' (default) on Theme to follow OS preference. Full guide: {@link generic:use-a-theme}.",
+          text: 'Light, dark, and system modes: {@link generic:use-a-theme}.',
         },
         {
           type: 'code',

package/assets/docs/theme.doc.zh.mjs

@@ -11,7 +11,7 @@ export const docsZh = {
       content: [
         {
           type: 'prose',
-          text: "安装主题包，用 `<Theme>`（`import {Theme} from '@astryxdesign/core'`）包裹应用，选择浅色或深色模式。完整指南——可用主题、集成主题、深色模式、嵌套主题和生产构建——请参阅 {@link generic:use-a-theme}。",
+          text: "安装主题包，用 `<Theme>`（`import {Theme} from '@astryxdesign/core/theme'`）包裹应用，选择浅色或深色模式。完整指南——可用主题、集成主题、深色模式、嵌套主题和生产构建——请参阅 {@link generic:use-a-theme}。",
         },
       ],
     },

package/assets/docs/tree/add-a-component.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/add-a-component`: choose a
+ * @file `astryx docs cli/integrations/building-blocks/components/add-a-component`: choose a
  * component name and generate its first source and doc files.
  */
 
@@ -45,7 +45,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx integration add component AcmeCarousel',
+          code: 'astryx integration add component AcmeCarousel',
         },
         {
           type: 'code',
@@ -71,5 +71,25 @@ Declare component root ./components in astryx.integration.mjs.
         },
       ],
     },
+    {
+      id: 'document-an-existing-component',
+      title: 'Document a component you already have',
+      content: [
+        {
+          type: 'prose',
+          text: "To document a component your package already has, write its doc beside the source file and name the doc after that file, such as `acme-gallery.doc.mjs` beside `acme-gallery.tsx`. Set `name` to the export apps import, such as `name: 'AcmeGallery'`, and keep both files inside the components root that `astryx.integration.mjs` declares. The file does not have to be named after the component; {@link generic:component-imports} shows how apps then find it.",
+        },
+      ],
+    },
+    {
+      id: 'global-mode',
+      title: 'In global mode',
+      content: [
+        {
+          type: 'prose',
+          text: "In global mode: when users install your package for their computer, beside the global CLI, your components show up in folders outside any project; inside a project, only if the project installs your package. See {@link namespace:global} and {@link generic:global-integrations}.",
+        },
+      ],
+    },
   ],
 };

package/assets/docs/tree/add-a-theme.doc.mjs

@@ -26,7 +26,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx integration add theme ocean',
+          code: 'astryx integration add theme ocean',
         },
         {
           type: 'code',
@@ -44,7 +44,7 @@ Declare theme root ./themes in astryx.integration.mjs.
         },
         {
           type: 'prose',
-          text: "`oceanTheme.ts` exports `oceanTheme`, a `defineTheme` source. `oceanTheme.doc.mjs` describes it with `type: 'theme'`, `name`, `displayName`, `description`, and `maintained`; `theme list` shows its `name`, `description`, and `maintained`. The command also declares `./themes/ocean` and `./themes/ocean.css` package exports. Every descriptor field is in {@link generic:authoring}.",
+          text: '`oceanTheme.ts` exports `oceanTheme`, a `defineTheme` source, and `oceanTheme.doc.mjs` is the descriptor that `theme list` reads. The command also declares `./themes/ocean` and `./themes/ocean.css` package exports. Every field is in {@link schema:theme-doc}.',
         },
         {
           type: 'prose',
@@ -63,7 +63,7 @@ Declare theme root ./themes in astryx.integration.mjs.
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx integration add theme ocean --from neutral',
+          code: 'astryx integration add theme ocean --from neutral',
         },
         {
           type: 'prose',
@@ -85,5 +85,15 @@ Declare theme root ./themes in astryx.integration.mjs.
         },
       ],
     },
+    {
+      id: 'global-mode',
+      title: 'In global mode',
+      content: [
+        {
+          type: 'prose',
+          text: 'In global mode: when users install your package for their computer, beside the global CLI, your themes are listed in folders outside any project, where `theme add` lists but writes nothing; inside a project, only if the project installs your package. See {@link namespace:global} and {@link generic:global-integrations}.',
+        },
+      ],
+    },
   ],
 };