@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/assets/docs/tree/codemods.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/codemods`: add codemods to an
+ * @file `astryx docs cli/integrations/building-blocks/codemods`: add codemods to an
  * integration package, and know which of them `astryx upgrade` runs in an app.
  */
 
@@ -27,7 +27,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx integration add codemod rename-delay --to 0.7.0',
+          code: 'astryx integration add codemod rename-delay --to 0.7.0',
         },
         {
           type: 'code',
@@ -82,7 +82,7 @@ export default {
         },
         {
           type: 'prose',
-          text: "`type: 'code'` rewrites the app's source files that match `fileExtensions`. `type: 'config'` rewrites the app's `astryx.config` file instead, and runs before code codemods. `title` shows in the upgrade output, and `api.jscodeshift` is a jscodeshift instance for the file. Every field is in {@link generic:authoring}.",
+          text: "`type: 'code'` rewrites the app's source files that match `fileExtensions`. `type: 'config'` rewrites the app's `astryx.config` file instead, and runs before code codemods. `title` shows in the upgrade output, and `api.jscodeshift` is a jscodeshift instance for the file. Every field is in {@link schema:codemod}.",
         },
       ],
     },
@@ -116,22 +116,22 @@ export default {
           type: 'code',
           lang: 'bash',
           code: `# Preview each codemod and the files it would change
-npx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets
+astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets
 # Write the changes
-npx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets --apply`,
+astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets --apply`,
         },
         {
           type: 'code',
           lang: 'text',
           code: `Integrations: @acme/astryx-widgets
-1 codemod to run (dry run)
+<n> codemods to run (dry run)
 Applying integration codemods...
   Rename AcmeCarousel delay to interval (v0.7.0, @acme/astryx-widgets)
 !     ~ src/Hero.tsx (would change)`,
         },
         {
           type: 'prose',
-          text: "The count includes Core's codemods for the same versions, which run first and print above `Integrations:`. To run only yours, as when you test it, add `--codemod rename-delay`.",
+          text: "`<n>` counts Core's codemods for the same versions too: they run first and print above `Integrations:`. To run only yours, as when you test it, add `--codemod rename-delay`.",
         },
         {
           type: 'prose',
@@ -143,5 +143,15 @@ Applying integration codemods...
         },
       ],
     },
+    {
+      id: 'global-mode',
+      title: 'In global mode',
+      content: [
+        {
+          type: 'prose',
+          text: "In global mode: inside an app, `upgrade` runs with the release equal to the app's Core, whichever copy of the CLI the user starts, and only the codemods of integrations the app installs run. Outside a project, `upgrade` lists codemods and migrates nothing. See {@link namespace:global} and {@link command:upgrade}.",
+        },
+      ],
+    },
   ],
 };

package/assets/docs/tree/commands.doc.mjs

@@ -13,7 +13,7 @@ export const docs = {
   name: 'commands',
   title: 'Commands',
   summary:
-    'Every command and subcommand: usage, options, examples, and exit codes.',
+    'Every command and subcommand: usage, options, examples, exit codes, and what it does outside a project.',
   keywords: ['commands', 'usage', 'options', 'flags'],
   placement: {parent: 'namespace:cli', slot: 'reference', order: 10},
   slots: {
@@ -22,4 +22,10 @@ export const docs = {
   adopts: [
     {source: {group: 'cli/commands', kinds: ['command']}, into: 'commands'},
   ],
+  blocks: [
+    {
+      type: 'prose',
+      text: "In global mode: each command declares its behavior outside projects (`outsideProject`). Most answer like a new project; some write nothing and name the project they need; `doctor`, `init`, and `upgrade` behave differently. Commands with different behavior describe it in their `In global mode:` note, and CLI tests run each command in an empty folder against its declared value. Inside a project, the project's Astryx release runs every command, whichever astryx command you type. See {@link namespace:global}.",
+    },
+  ],
 };

package/assets/docs/tree/component-family.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/describe-the-component/component-family`:
+ * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/component-family`:
  * author one ComponentDoc for several public exports in a component family.
  */
 
@@ -38,10 +38,8 @@ export const docs = {
           ],
         },
         {
-          type: 'reference',
-          target: 'schema:component-doc',
-          projection: {fields: ['components']},
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:component-doc}.',
         },
       ],
     },

package/assets/docs/tree/component-imports.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/component-imports`: make an
+ * @file `astryx docs cli/integrations/building-blocks/components/component-imports`: make an
  * integration component's documented import resolve from the packed package.
  */
 
@@ -51,12 +51,12 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: '`integration verify` installs the packed package in a temporary app, resolves each documented import, and checks that the module exports the documented component name.',
+          text: '`integration verify` unpacks the packed package into a temporary app, resolves each documented import, and checks that the module exports the documented component name. Its `--json` output names each failure by code.',
         },
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx integration verify',
+          code: 'astryx integration verify',
         },
         {
           type: 'list',
@@ -73,5 +73,15 @@ export const docs = {
         },
       ],
     },
+    {
+      id: 'global-mode',
+      title: 'In global mode',
+      content: [
+        {
+          type: 'prose',
+          text: "In global mode: outside a project, imports the CLI prints name packages installed for the computer, which a new app must install before it can build them; inside a project, only packages the project installs are printed. See {@link namespace:global} and {@link generic:global-integrations}.",
+        },
+      ],
+    },
   ],
 };

package/assets/docs/tree/components.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components`: guides for adding and
+ * @file `astryx docs cli/integrations/building-blocks/components`: guides for adding and
  * documenting components in an integration package.
  */
 
@@ -20,4 +20,10 @@ export const docs = {
       accepts: {kinds: ['generic', 'namespace']},
     },
   },
+  blocks: [
+    {
+      type: 'prose',
+      text: 'In global mode: components from an integration installed for the computer show up outside projects; inside a project, only components from integrations the project installs. See {@link namespace:global} and {@link generic:global-integrations}.',
+    },
+  ],
 };

package/assets/docs/tree/computer-agent-guide.doc.mjs

@@ -0,0 +1,160 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs global/computer-agent-guide`: the one skill file the global
+ * install keeps for the whole computer, its links, and `init --user` (spec
+ * AST-081 FR8).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'computer-agent-guide',
+  placement: {
+    parent: 'namespace:global',
+    slot: 'guides',
+    order: 5,
+  },
+  title: 'The agent guide on your computer',
+  category: 'guide',
+  keywords: [
+    'agent guide',
+    'init --user',
+    'SKILL.md',
+    'skills',
+    'remove-agents',
+    'claude',
+    'codex',
+    'cursor',
+    'agents',
+    'other agents',
+    'symlink',
+    'link skills',
+  ],
+  description:
+    'Your global install keeps one short Astryx skill in your home folder and links it into the folders agent tools read, so agents anywhere know Astryx is there. `astryx init --user` writes it now or turns it off.',
+  sections: [
+    {
+      id: 'what',
+      title: 'What it is',
+      content: [
+        {
+          type: 'prose',
+          text: "A project's agent docs reach only agents working in that project. Your global install also keeps one skill file, `~/.agents/skills/astryx/SKILL.md`, which most coding agents read. It tells agents that Astryx is on this computer, when it is relevant (building or changing UI), and to start with `astryx search`. It names no version, so it never goes stale. Inside a project, the project's own agent docs come first.",
+        },
+        {
+          type: 'prose',
+          text: 'It is written in the background on the first run and again after you upgrade, so no command waits for it. Installing the package does not write it, because some package managers skip install scripts.',
+        },
+      ],
+    },
+    {
+      id: 'where',
+      title: 'Where agents find it',
+      content: [
+        {
+          type: 'prose',
+          text: "Agents that read only their own skills folder get a link to the skill's folder, so they read the same one file: a folder symlink with a relative target (a junction on Windows, or a copy where neither can be made). Continue's scanner skips links, so it gets a copy, refreshed with the file:",
+        },
+        {
+          type: 'table',
+          headers: ['Folder', 'When'],
+          rows: [
+            ['`~/.claude/skills/astryx`', 'Always'],
+            ['`~/.kiro/skills/astryx`', 'When `~/.kiro` exists'],
+            [
+              '`~/.codeium/windsurf/skills/astryx`',
+              'When `~/.codeium/windsurf` exists',
+            ],
+            ['`~/.letta/skills/astryx`', 'When `~/.letta` exists'],
+            [
+              '`~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/skills/astryx`',
+              "When Xcode's coding assistant folder exists",
+            ],
+            [
+              '`~/.config/agents/skills/astryx`',
+              'When `~/.config/agents/skills` exists',
+            ],
+            [
+              '`~/.continue/skills/astryx` (a copy)',
+              'When `~/.continue` exists',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: "Astryx never replaces anything it did not create at one of these folders, and never writes a folder another tool manages; `astryx doctor` names any it skipped, and any link whose skill folder is missing, as in a container that mounts only one agent's folder.",
+        },
+      ],
+    },
+    {
+      id: 'cloud-and-apps',
+      title: 'Cloud agents and apps',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "Cloud and background agents read only the repository, so the project's own agent docs, the block `astryx init` writes into AGENTS.md or CLAUDE.md, are what reach them.",
+            'Apps that take an uploaded skill: upload `~/.agents/skills/astryx/SKILL.md`, or a zip of its folder.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'other-agents',
+      title: 'Other agents',
+      content: [
+        {
+          type: 'prose',
+          text: 'If your agent reads skills from another folder, link it to the skill:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: "ln -s ~/.agents/skills/astryx <your agent's skills folder>/astryx",
+        },
+        {
+          type: 'prose',
+          text: 'On Windows, in PowerShell:',
+        },
+        {
+          type: 'code',
+          lang: 'powershell',
+          code: 'New-Item -ItemType Junction -Path "<your agent\'s skills folder>\\astryx" -Target "$HOME\\.agents\\skills\\astryx"',
+        },
+      ],
+    },
+    {
+      id: 'choose',
+      title: 'Write it now, or turn it off',
+      content: [
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'astryx init --user\nastryx init --user --remove-agents',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`init --user` writes the file and the links now.',
+            '`--remove-agents` removes the file and every link Astryx made, and turns it off until you run `astryx init --user` again.',
+            'A file you edited is never overwritten or removed; delete it to get the current text.',
+            'Outside a project, `astryx doctor` says whether the skill is there, current, edited, or turned off, and where it is linked.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'more',
+      title: 'More on global mode',
+      content: [
+        {
+          type: 'prose',
+          text: "This page is part of {@link namespace:global}, which explains what global mode is and how each part works. A project's own agent docs: {@link command:init}.",
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/computer-integrations.doc.mjs

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs global/computer-integrations`: integrations installed next to the
+ * global install, where they work, and how to see them (spec AST-081 FR12).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'computer-integrations',
+  placement: {
+    parent: 'namespace:global',
+    slot: 'guides',
+    order: 6,
+  },
+  title: 'Integrations installed globally',
+  category: 'guide',
+  keywords: [
+    'global integration',
+    'install an integration globally',
+    'npm i -g integration',
+    'integration outside a project',
+    'installed for this computer',
+  ],
+  description:
+    'Integrations installed next to your global install work in folders outside any project. Inside a project, only the integrations the project installs work, and the others are listed as ones you could add.',
+  sections: [
+    {
+      id: 'install',
+      title: 'Install one globally',
+      content: [
+        {
+          type: 'prose',
+          text: 'Install the integration the same way you installed the CLI, so the two sit side by side:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npm i -g @astryxdesign/cli @acme/widgets\n# or: pnpm add -g · yarn global add · bun add -g',
+        },
+        {
+          type: 'prose',
+          text: 'A tool that installs the CLI together with integrations in one folder, and runs the CLI from there, counts the same way. `npx` and the cache of project versions never count.',
+        },
+      ],
+    },
+    {
+      id: 'outside',
+      title: 'Outside a project, they work',
+      content: [
+        {
+          type: 'prose',
+          text: 'In a folder outside any project, Astryx loads each integration installed next to your global install the way a project loads its own: its components, templates, docs, themes, and discover source show up, and a command name it declares starts the commands Astryx prints. One whose `@astryxdesign/core` or `@astryxdesign/cli` peer range leaves out your global version is skipped, and `astryx doctor` says why.',
+        },
+      ],
+    },
+    {
+      id: 'inside',
+      title: "Inside a project, only the project's",
+      content: [
+        {
+          type: 'prose',
+          text: "A project's answers must match what it installs: a component from a package it does not install would not build. So inside a project, an integration installed only globally adds nothing. `astryx discover` lists it among the packages the project could add, with the project's install command, when it supports the project's version and loads. When the project installs the same integration, the project's copy is the one used.",
+        },
+      ],
+    },
+    {
+      id: 'check',
+      title: 'See which ones work',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Outside a project, `astryx doctor` lists the global integrations it uses and warns about each it skips.',
+            'Inside a project, `astryx doctor` and `astryx discover` list the ones the project could add.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'more',
+      title: 'More on global mode',
+      content: [
+        {
+          type: 'prose',
+          text: 'This page is part of {@link namespace:global}, which explains what global mode is and how each part works. Building an integration: {@link generic:global-integrations}.',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/configuration.doc.mjs

@@ -9,15 +9,19 @@ export const docs = {
   placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 60},
   title: 'Configuration',
   summary:
-    'Set how your integration behaves in an app: agent guidance, debug and gap reports, and more as it grows.',
-  keywords: ['configuration', 'agent guidance', 'debug', 'gap reports'],
+    'Set how your integration behaves in an app: agent guidance, the command your users run, debug and gap reports, and more as it grows.',
+  keywords: ['configuration', 'agent guidance', 'cliCommand', 'debug', 'gap reports'],
   slots: {
     guides: {title: 'Configuration', accepts: {kinds: ['generic', 'namespace']}},
   },
   blocks: [
     {
       type: 'prose',
-      text: 'Beyond the things you ship, an integration can set how it behaves in an app: the guidance it gives the AI agents working there, and the record it keeps of each CLI run. Open one below to set it up.',
+      text: "In global mode: installed for the computer, beside the global CLI, your package's manifest is read as it is in a project and applies in folders outside any project; peer ranges are checked against the global CLI's release. See {@link namespace:global} and {@link generic:global-integrations}.",
+    },
+    {
+      type: 'prose',
+      text: 'Beyond the things you ship, an integration can set how it behaves in an app: the guidance it gives the AI agents working there, the command its users run the CLI with, and the record it keeps of each CLI run. Open one below to set it up.',
     },
   ],
 };

package/assets/docs/tree/debug-and-gap-reports.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/debug-and-gap-reports`: receive a record
+ * @file `astryx docs cli/integrations/building-blocks/configuration/debug-and-gap-reports`: receive a record
  * of each CLI run with `debug`, and handle `astryx gap-report` with
  * `gapReport`, both named exports of the integration manifest.
  */
@@ -23,7 +23,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Export a `debug` function from `astryx.integration.mjs`, and the CLI calls it once for each command run in an app that loads your package.',
+          text: 'Export a `debug` function from `astryx.integration.mjs`; the CLI calls it once per command run in an app loading your package.',
         },
         {
           type: 'code',
@@ -44,7 +44,7 @@ export default {
         },
         {
           type: 'prose',
-          text: 'The event is a `DebugEvent` with `command`, `outcome`, `exitCode`, `durationMs`, `error`, and more, its values scrubbed (`redacted: true`). Every field is in {@link generic:authoring}.',
+          text: 'The event is a `DebugEvent` with `command`, `outcome`, `exitCode`, `durationMs`, `error`, and more, its values scrubbed (`redacted: true`). Every field is in {@link schema:debug-event}.',
         },
         {
           type: 'prose',
@@ -52,11 +52,11 @@ export default {
         },
         {
           type: 'prose',
-          text: "An app records every command only when its `astryx.config` names `integrations` or `debug`, as listing your package does. Otherwise your handler runs only for commands that load the app's project, such as `component` and `docs`, and not for `--version` or a mistyped command. In an app whose config names neither word, each of those commands also prints a warning on stderr.",
+          text: "An app records every command only when its `astryx.config` names `integrations` or `debug`, as listing your package does. Otherwise your handler runs only for commands loading the app's project, such as `component` and `docs`, never for `--version` or a mistyped command. In an app whose config names neither word, those commands also print a stderr warning.",
         },
         {
           type: 'prose',
-          text: '`debug` is a named export, not a manifest field, so a CLI that does not know it ignores it and loads the rest of your manifest.',
+          text: '`debug` is a named export, not a manifest field, so an older CLI ignores it and loads the rest of your manifest.',
         },
       ],
     },
@@ -75,7 +75,7 @@ export default {
         },
         {
           type: 'prose',
-          text: 'From then on, your handler no longer runs in that app.',
+          text: 'Your handler then no longer runs in that app.',
         },
       ],
     },
@@ -104,22 +104,11 @@ export const gapReport = {
         },
         {
           type: 'prose',
-          text: 'Every handler in the app gets every report, so check `report.target.package` and skip reports about other packages. The receipt `status` is one of:',
+          text: 'Every handler in the app gets every report, so check `report.target.package` and skip reports about other packages.',
         },
         {
-          type: 'table',
-          headers: ['`status`', 'Meaning'],
-          rows: [
-            [
-              '`filed`',
-              'You created or queued the report. Return `url` or `message`.',
-            ],
-            [
-              '`routed_only`',
-              'You point the caller to where to file it. `url` is required.',
-            ],
-            ['`skipped`', 'You chose not to act, for example on a duplicate.'],
-          ],
+          type: 'prose',
+          text: 'Every field is in {@link schema:gap-report-handler}.',
         },
         {
           type: 'prose',
@@ -138,7 +127,7 @@ export const gapReport = {
         {
           type: 'code',
           lang: 'bash',
-          code: "npx astryx gap-report AcmeCarousel --category missing_variant --reason 'Need a vertical layout'",
+          code: "astryx gap-report AcmeCarousel --category missing_variant --reason 'Need a vertical layout'",
         },
         {
           type: 'code',
@@ -161,7 +150,7 @@ message:     Rerun with --confirm-public to file this report.`,
       content: [
         {
           type: 'prose',
-          text: "When the app has no `gapReport` handler at all, the CLI routes the report to the target package's `issuesUrl` from its manifest instead.",
+          text: "With no `gapReport` handler in the app, the CLI routes the report to the target package's manifest `issuesUrl`.",
         },
         {
           type: 'list',
@@ -178,5 +167,35 @@ message:     Rerun with --confirm-public to file this report.`,
         },
       ],
     },
+    {
+      id: 'choose-a-destination',
+      title: 'Let the person choose where a report goes',
+      content: [
+        {
+          type: 'prose',
+          text: 'When an app loads packages naming their own `issuesUrl`, a report can go to the default (the handlers, or the fallback above) or to one of those packages. `astryx gap-report --list-categories` and the receipt of a report filed without `--to` list every destination, with a line telling the agent to ask the person.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'An agent asks the person where to file. It never picks a package destination on its own.',
+            "`--to <package>` carries the person's choice: the report goes only to that package's `issuesUrl`, under the same `--confirm-public` rule, and no handler runs.",
+            'Without a choice, leave out `--to`; the report goes to the default.',
+            'A `--to` that names no destination fails before anything is sent and lists the destinations.',
+          ],
+        },
+      ],
+    },
+    {
+      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, its `debug` function receives runs in folders outside any project too; inside a project, only if the project installs it. See {@link namespace:global} and {@link generic:global-integrations}.',
+        },
+      ],
+    },
   ],
 };

package/assets/docs/tree/define-the-theme.doc.mjs

@@ -45,7 +45,7 @@ export const oceanTheme = defineTheme({
         },
         {
           type: 'prose',
-          text: 'Local imports must stay inside the theme folder. One that leaves it, such as `../../shared/colors`, fails with `invalid_theme`, and the theme disappears from `theme list`. `npx astryx theme template` writes a file that explains every `defineTheme` field. For the full token set, scope selectors, and component theming, read {@link generic:author-a-theme}.',
+          text: 'Local imports must stay inside the theme folder. One that leaves it, such as `../../shared/colors`, fails with `invalid_theme`, and every theme in the package disappears from `theme list`. `astryx theme template` writes a file that explains every `defineTheme` field. For the full token set and component theming, read {@link generic:author-a-theme}.',
         },
       ],
     },
@@ -55,13 +55,14 @@ export const oceanTheme = defineTheme({
       content: [
         {
           type: 'prose',
-          text: 'To base a theme on an existing one, `extends` it: import the base theme and override only the tokens you change. The derived theme keeps a live link to the base and inherits its later changes — unlike `--from`, which forks a copy ({@link generic:add-a-theme}).',
+          text: 'To base a theme on an existing one, `extends` it: import the base theme and override only the tokens you change. Add the derived theme with `integration add theme ocean-contrast`, and import the base from its built package export, since local imports cannot leave the theme folder. The derived theme keeps a live link to the base and picks up its later changes when you rebuild it — unlike `--from`, which forks a copy ({@link generic:add-a-theme}).',
         },
         {
           type: 'code',
           lang: 'ts',
-          code: `import {defineTheme} from '@astryxdesign/core/theme';
-import {oceanTheme} from './oceanTheme';
+          code: `// themes/ocean-contrast/oceanContrastTheme.ts
+import {defineTheme} from '@astryxdesign/core/theme';
+import {oceanTheme} from '@acme/astryx-widgets/themes/ocean';
 
 export const oceanContrastTheme = defineTheme({
   name: 'ocean-contrast',
@@ -79,7 +80,7 @@ export const oceanContrastTheme = defineTheme({
       content: [
         {
           type: 'prose',
-          text: 'Each `[light, dark]` pair compiles to a `light-dark()` value, which switches only colors. Give it colors. For a value that is not a plain color — a gradient — put `light-dark()` on each color stop, not around the whole value: a browser without `light-dark()` drops the declaration, and the stop form is the one that degrades safely.',
+          text: 'Each `[light, dark]` pair compiles to a `light-dark()` value, which switches only colors. Give it colors. For a value that is not a plain color — a gradient — put `light-dark()` on each color stop, not around the whole value: `light-dark()` takes two colors, so wrapping whole gradients makes the value invalid where the token is used, and `theme build` does not warn.',
         },
       ],
     },

package/assets/docs/tree/describe-the-component.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/describe-the-component`:
+ * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component`:
  * choose and maintain the ComponentDoc shape that matches a component's public
  * source.
  */
@@ -51,7 +51,7 @@ export const docs = {
     {
       type: 'code',
       lang: 'bash',
-      code: 'npx astryx component AcmeCarousel',
+      code: 'astryx component AcmeCarousel',
     },
   ],
 };

package/assets/docs/tree/docs.doc.mjs

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/docs`: the guides to writing docs for an
- * integration package, which join the same docs tree as the CLI's own
- * (spec:AST-046, spec:AST-047).
+ * @file `astryx docs cli/integrations/building-blocks/docs`: the guides to
+ * writing docs for an integration package, which join the same docs tree as
+ * the CLI's own (spec:AST-046, spec:AST-047).
  */
 
 /** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
@@ -18,4 +18,10 @@ export const docs = {
   slots: {
     guides: {title: 'Guides', accepts: {kinds: ['generic']}},
   },
+  blocks: [
+    {
+      type: 'prose',
+      text: 'In global mode: docs from an integration installed for the computer show up outside projects; inside a project, only docs from integrations the project installs. See {@link namespace:global} and {@link generic:global-integrations}.',
+    },
+  ],
 };