@astryxdesign/cli 0.7.2-canary.fdd384f → 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/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)."},

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}.',
         },
       ],
     },

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.mjs

@@ -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/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',
@@ -81,5 +81,15 @@ Declare component root ./components 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 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}.',
+        },
+      ],
+    },
   ],
 };

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

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/docs/add-a-topic`: add a doc topic to an
- * integration package, write its sections, and pick the doc kind for each
- * thing the package ships.
+ * @file `astryx docs cli/integrations/building-blocks/docs/add-a-topic`: add a
+ * doc topic to an integration package, write its sections, and pick the doc
+ * kind for each thing the package ships.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -27,7 +27,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx integration add doc deploying\n# Read it the way an app will\nnpx astryx docs deploying',
+          code: 'astryx integration add doc deploying\n# Read it the way an app will\nastryx docs deploying',
         },
         {
           type: 'code',
@@ -40,7 +40,7 @@ export const docs = {
           items: [
             'Name the topic in lowercase kebab-case, such as `deploying`. Readers type the name as a command argument, so it holds only letters, digits, `_`, and `-`.',
             'Keep the name stable: readers and links find the topic by it.',
-            'Pick a name no Core topic uses. To take over or add to a Core topic, see {@link generic:extend-or-replace}.',
+            'Pick a name `astryx docs` does not already list: no Core topic, and no section such as `tokens` or `layout`. To take over or add to a Core topic, see {@link generic:extend-or-replace}.',
           ],
         },
       ],
@@ -59,13 +59,48 @@ export const docs = {
           label: 'docs/deploying.doc.mjs',
           code: "/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */\nexport default {\n  type: 'generic',\n  name: 'deploying',\n  title: 'Deploying',\n  description: 'Ship an app built with Acme widgets.',\n  sections: [{\n    id: 'build-before-you-ship',\n    title: 'Build before you ship',\n    content: [\n      {type: 'prose', text: 'Build the app, then upload the `dist` folder.'},\n      {type: 'code', lang: 'bash', code: 'npm run build'},\n      {type: 'list', style: 'unordered', items: ['Keep `dist` out of git.']},\n      {type: 'table', headers: ['Variable', 'Value'], rows: [['`NODE_ENV`', '`production`']]},\n    ],\n  }],\n};",
         },
+        {
+          type: 'prose',
+          text: 'The sample sets a section `id`, so `package.json` needs the CLI peer `"@astryxdesign/cli": ">=0.6.4"`. Published 0.6.3 and earlier reject `id` and hide every doc topic your package ships, and `integration verify` fails without that peer; see {@link generic:versioning}.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Replace the `Overview` placeholder `integration add` writes.',
+            'Every field is in {@link schema:reference-doc}.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'write-commands-without-a-runner',
+      title: 'Write commands without a runner',
+      content: [
+        {
+          type: 'prose',
+          text: 'Start every CLI command in a doc with the word astryx alone, with no runner such as npx or pnpm exec in front. The CLI prefixes each one when it prints the doc, with the command the reader runs: `pnpm exec astryx` or `yarn astryx` from their package manager, or the `cliCommand` an integration sets. See {@link generic:cli-command}.',
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          label: 'docs/deploying.doc.mjs',
+          code: "{type: 'prose', text: 'Check the app with `astryx doctor` before you ship.'},\n{type: 'code', lang: 'bash', code: 'astryx doctor'},",
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          label:
+            "Read in an app whose integration sets cliCommand: 'acme astryx'",
+          code: 'Check the app with `acme astryx doctor` before you ship.\n\n```bash\nacme astryx doctor\n```',
+        },
         {
           type: 'list',
           style: 'unordered',
           items: [
-            'Content blocks are `prose`, `code`, `list`, and `table`, as shown; `heading`, with a `level` from 3 to 6 and a `text`; and `token-ref`, which inlines a token table from another topic.',
-            '`id` is optional: a stable key for the section. Without it, the key comes from the title. A stable CLI before 0.6.4 cannot read `id`; see {@link generic:versioning}.',
-            'Replace the `Overview` placeholder that `integration add` writes. Every field is in {@link generic:authoring}.',
+            'The CLI prefixes an inline code span that starts with the word astryx, a command at the start of a line, or after `&&`, `||`, `;` or `|`, in a `bash`, `sh`, `shell`, `zsh`, `console`, `text` or `markdown` code block or one with no language, and a table cell that holds only a command.',
+            'Code in other languages, such as a `js` example, and the word astryx in plain prose stay as written.',
+            '`--json` returns the doc as written, so a reader that shows it prefixes the commands itself.',
           ],
         },
       ],
@@ -135,10 +170,20 @@ export const docs = {
           items: [
             'Readers open a topic by its `name`, not its file name. Name the file after the doc, `<name>.doc.mjs`, so each one is easy to find.',
             'A topic with no `placement` is a flat topic: the docs list shows it under Topics, and readers open it by its name.',
-            'To give your package its own section in the docs tree instead, see {@link generic:sections-and-placement}.',
+            'For a section of your own in the docs tree, see {@link generic:sections-and-placement}.',
           ],
         },
       ],
     },
+    {
+      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 doc topics 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}.',
+        },
+      ],
+    },
   ],
 };