@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/assets/docs/tree/quick-start.doc.mjs

@@ -34,20 +34,22 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'An integration starts as a normal npm package. Make a folder for it, create a package.json inside that folder, give the package a name, then install the Astryx CLI and Core for development.',
+          text: 'An integration starts as a normal npm package. Make a folder for it, create a package.json inside that folder, give the package a name, make it an ES module, then install the Astryx CLI, Core, and TypeScript for development.',
         },
         {
           type: 'code',
           lang: 'bash',
-          code: "mkdir acme-widgets && cd acme-widgets\nnpm init -y\nnpm pkg set name=@acme/astryx-widgets\nnpm pkg set 'exports={}' --json\nnpm install -D @astryxdesign/cli @astryxdesign/core",
+          code: "mkdir acme-widgets && cd acme-widgets\nnpm init -y\nnpm pkg set name=@acme/astryx-widgets type=module\nnpm pkg set 'exports={}' --json\nnpm install -D @astryxdesign/cli @astryxdesign/core typescript@6",
         },
         {
           type: 'list',
           style: 'unordered',
           items: [
+            'Set `"type": "module"`: the `.js` files the CLI generates, such as a built theme, are ES modules, and Node fails to load them in a package marked `"type": "commonjs"`, which `npm init -y` writes on npm 11.',
             'Start with `"exports": {}`: each component and template you add then writes the public import that `integration verify` resolves.',
-            'Run the CLI as `npx astryx`, which runs the `@astryxdesign/cli` you installed as a devDependency.',
+            'Run the CLI as `astryx`, which runs the `@astryxdesign/cli` you installed as a devDependency.',
             'Component commands read Core, so they need `@astryxdesign/core` installed.',
+            "The checks compare your docs with your code through TypeScript's JavaScript compiler API, which `typescript` 5.0 through 6 has. TypeScript 7 does not ship that API: on TypeScript 7, also install `@typescript/typescript6`, its TypeScript 6 API package, and the checks use it.",
           ],
         },
         {
@@ -62,7 +64,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx integration add component AcmeCarousel',
+          code: 'astryx integration add component AcmeCarousel',
         },
         {
           type: 'code',
@@ -80,12 +82,39 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx component AcmeCarousel',
+          code: 'astryx component AcmeCarousel',
         },
         {
           type: 'prose',
           text: 'You now have an integration package with one exported component.',
         },
+        {
+          type: 'heading',
+          level: 3,
+          text: 'Check it in every build (required)',
+        },
+        {
+          type: 'prose',
+          text: "Run `integration check --strict` in every build ({@link generic:checks}): a doc, prop, template, or link that drifts from the code then fails your build, not your users' apps. Set it up now, as the `typecheck` script, and run it.",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npm pkg set scripts.typecheck="astryx integration check --strict"\nnpm run typecheck',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: '[ok] 0 errors, 0 warnings, 0 skipped. Every check passed.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Run `typecheck` in CI and before every publish. When you add a `tsconfig.json`, put `tsc --noEmit && ` in front of the check so the same script checks your types.',
+            'What each check covers, and what `--strict` adds: {@link generic:checks}.',
+          ],
+        },
         {
           type: 'heading',
           level: 3,
@@ -98,7 +127,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx integration verify\nnpm pack --pack-destination ..',
+          code: 'astryx integration verify\nnpm pack --pack-destination ..',
         },
         {
           type: 'code',
@@ -107,7 +136,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: '`integration verify` packs the package, unpacks it into a temporary app, and checks that the component resolves through its public import there. It publishes nothing and leaves no `.tgz` file, so `npm pack` writes `../acme-astryx-widgets-1.0.0.tgz` for the next step.',
+          text: '`integration verify` installs the packed package in a temporary app and confirms the component resolves through its public import there ({@link generic:checks}). It publishes nothing and leaves no `.tgz` file, so `npm pack` writes `../acme-astryx-widgets-1.0.0.tgz` for the next step.',
         },
         {
           type: 'heading',
@@ -121,7 +150,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'cd ..\nmkdir my-app && cd my-app\nnpm init -y\nnpm install @astryxdesign/core @astryxdesign/cli ../acme-astryx-widgets-1.0.0.tgz\nnpx astryx component AcmeCarousel',
+          code: 'cd ..\nmkdir my-app && cd my-app\nnpm init -y\nnpm install @astryxdesign/core @astryxdesign/cli ../acme-astryx-widgets-1.0.0.tgz\nastryx component AcmeCarousel',
         },
         {
           type: 'code',
@@ -172,13 +201,13 @@ export const docs = {
             ],
             [
               '`peerDependencies`',
-              '`@astryxdesign/cli`; add `@astryxdesign/core` when your code imports it',
+              '`@astryxdesign/core` when your code imports it; `@astryxdesign/cli`, optional, when you ship a feature that needs a newer CLI ({@link generic:versioning})',
               'The app supplies these packages for your integration.',
             ],
             [
               '`devDependencies`',
-              '`@astryxdesign/cli` and `@astryxdesign/core`',
-              'Lets you run the CLI and build components while working on the integration.',
+              '`@astryxdesign/cli`, `@astryxdesign/core`, and `typescript`',
+              'Lets you run the CLI, build components, and run the checks while working on the integration.',
             ],
           ],
         },
@@ -226,21 +255,8 @@ export const docs = {
           text: 'The file tells the CLI where this package keeps its integration items. Edit it only when you want a custom root or another optional setting. Paths are relative to package.json, and later adds keep a custom path you already set.',
         },
         {
-          type: 'reference',
-          target: 'schema:integration',
-          projection: {
-            fields: [
-              'providerId',
-              'components',
-              'templates',
-              'codemods',
-              'docs',
-              'themes',
-              'agentDocs',
-              'issuesUrl',
-            ],
-          },
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:integration}.',
         },
         {
           type: 'heading',
@@ -268,5 +284,15 @@ export const docs = {
         },
       ],
     },
+    {
+      id: 'global-mode',
+      title: 'In global mode',
+      content: [
+        {
+          type: 'prose',
+          text: 'In global mode: users can also install your package for their computer, beside the global CLI (`npm i -g @astryxdesign/cli your-package`). It then applies in folders outside any project, and inside a project only if the project installs it. See {@link namespace:global} and {@link generic:global-integrations}.',
+        },
+      ],
+    },
   ],
 };

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

@@ -0,0 +1,192 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs global/reference`: every folder, environment variable, JSON
+ * field, and error code of global mode, and a short glossary (spec AST-081).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'reference',
+  placement: {
+    parent: 'namespace:global',
+    slot: 'guides',
+    order: 11,
+  },
+  title: 'Global mode reference',
+  category: 'guide',
+  keywords: [
+    'reference',
+    'paths',
+    'folders',
+    'environment variables',
+    'env vars',
+    'XDG_CACHE_HOME',
+    'XDG_CONFIG_HOME',
+    'LOCALAPPDATA',
+    'APPDATA',
+    'meta.available',
+    'error codes',
+    'glossary',
+    'state.json',
+    'settings.json',
+  ],
+  description:
+    'Every folder global mode uses on each system, the environment variables it reads, the JSON fields it adds, its error codes, and a short glossary.',
+  sections: [
+    {
+      id: 'paths',
+      title: 'Folders and files',
+      content: [
+        {
+          type: 'table',
+          headers: ['What', 'Linux', 'macOS', 'Windows'],
+          rows: [
+            [
+              'Cache folder',
+              '`~/.cache/astryx` (or `$XDG_CACHE_HOME/astryx`)',
+              '`~/Library/Caches/astryx`',
+              '`%LOCALAPPDATA%\\astryx\\Cache`',
+            ],
+            [
+              'Versions for projects',
+              '`<cache>/releases/<version>`',
+              '`<cache>/releases/<version>`',
+              '`<cache>\\releases\\<version>`',
+            ],
+            [
+              'Settings folder',
+              '`~/.config/astryx` (or `$XDG_CONFIG_HOME/astryx`)',
+              '`~/Library/Application Support/astryx`',
+              '`%APPDATA%\\astryx`',
+            ],
+            [
+              'Update checks and notices, and why the last notice or check did not happen (for `astryx doctor` only)',
+              '`<settings>/state.json`',
+              '`<settings>/state.json`',
+              '`<settings>\\state.json`',
+            ],
+            [
+              'Agent guide setting, and the links Astryx made',
+              '`<settings>/settings.json`',
+              '`<settings>/settings.json`',
+              '`<settings>\\settings.json`',
+            ],
+            [
+              'Agent guide',
+              '`~/.agents/skills/astryx/SKILL.md`, linked from `~/.claude/skills/astryx` and others',
+              'the same',
+              'the same, under `%USERPROFILE%`',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Every folder the agent guide is linked into: {@link generic:computer-agent-guide}.',
+        },
+      ],
+    },
+    {
+      id: 'env',
+      title: 'Environment variables',
+      content: [
+        {
+          type: 'table',
+          headers: ['Variable', 'Effect'],
+          rows: [
+            [
+              '`CI`',
+              'Set to anything but empty, `0`, or `false`: no update check and no notice.',
+            ],
+            [
+              '`NO_UPDATE_NOTIFIER`',
+              'Set to anything: no update check and no notice.',
+            ],
+            [
+              '`XDG_CACHE_HOME`, `XDG_CONFIG_HOME`',
+              'On Linux, move the cache and settings folders; used only when absolute.',
+            ],
+            [
+              '`LOCALAPPDATA`, `APPDATA`',
+              'On Windows, the cache and settings folders; used only when absolute.',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: "Astryx reads no environment variable of its own. npm's own settings, such as its registry and proxy, apply to the versions it installs for projects.",
+        },
+      ],
+    },
+    {
+      id: 'json',
+      title: 'JSON fields',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "`meta.answeredBy` on every successful `--json` result: `cli` (the version that answered), `core` (the Core it used, or `null`), and `copy`: `project` (the project's own CLI), `starting` (the astryx command you started, in a project with no CLI of its own), `matched` (the CLI version equal to the project's Core, when the project's own CLI cannot start), `carried` (outside a project), or `fallback` (that version could not be obtained, so the astryx command you started answered instead).",
+            '`meta.available` entries from `astryx discover` with `source: "installed for this computer"`: an integration installed next to your global install that the project could add, with its install command in `install`.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'errors',
+      title: 'Error codes',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`ERR_VERSIONS_UNAVAILABLE`: nothing can answer, such as a command that needs Core outside a project that cannot install it. When only the matching version is missing, the run answers anyway, with a warning. {@link generic:problems}',
+            '`ERR_PROJECT_REQUIRED`: a command that only works in a project ran outside one. Commands released before global mode keep the codes they already used: `theme use`, `theme remove`, and `theme add <slug>` use `ERR_THEME_INVALID`, `integration add` uses `ERR_FILE_NOT_FOUND`, `swizzle` uses `ERR_CORE_NOT_FOUND`, and `upgrade` uses `ERR_VERSION_DETECT`.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'changes',
+      title: 'What changes in global mode',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "Which version answers: in a project, the project's own CLI (with only Core, the astryx command you started); outside one, your global version. {@link generic:who-answers}",
+            'Commands that change a project write nothing outside one; `doctor`, `init`, and `theme add` do something else there. {@link namespace:commands}',
+            'Integrations installed globally work only outside projects. {@link generic:computer-integrations}',
+            'The programmatic API runs in your process with the package you import and never hands off to another version; with `cwd` outside a project, its functions answer as the commands do there. {@link namespace:api}',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'glossary',
+      title: 'Glossary',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '**Global install**: the CLI installed for your computer with `npm i -g` or another package manager.',
+            "**The project's version**: the project's own CLI; it answers every command in that project. A project with only Core has none, so the astryx command you started answers.",
+            '**Cache**: the folder where Astryx keeps versions projects need but do not install.',
+          ],
+        },
+      ],
+    },
+    {
+      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.',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/replace-a-core-component.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/replace-a-core-component`:
+ * @file `astryx docs cli/integrations/building-blocks/components/replace-a-core-component`:
  * intentionally make an integration component the default for a Core identity.
  */
 
@@ -65,10 +65,8 @@ export default {
 };`,
         },
         {
-          type: 'reference',
-          target: 'schema:component-doc',
-          projection: {fields: ['replaces']},
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:component-doc}.',
         },
         {
           type: 'prose',
@@ -87,7 +85,7 @@ export default {
           type: 'list',
           style: 'unordered',
           items: [
-            'Any `@astryxdesign/cli` range that starts at that release or later turns it on, including the `>=0.7.0` that earlier `integration add theme` and `integration add doc --parent` wrote.',
+            'Any `@astryxdesign/cli` range that starts at that release or later turns it on, including the `>=0.7.0` that `integration add doc --parent` wrote in published 0.6.4 and 0.6.5, and `integration add theme` in published 0.6.5.',
             'Without such a range, the component keeps its own name, the Core component stays selected (a component named like its target stays ambiguous by that bare name, as before), and `doctor integration components` warns with the range to add. Apps that load such a package see no change.',
             '`replaces` names the Core `ComponentDoc` identity, not its display label, import path, or a standalone hook.',
             'Your component may keep a distinct name or use the same name as the target. A distinct name remains directly addressable on older CLIs that ignore `replaces`.',
@@ -105,7 +103,7 @@ export default {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx doctor integration components\nnpx astryx component SideNav\nnpx astryx component AcmeSideNav\nnpx astryx component SideNav --package @astryxdesign/core',
+          code: 'astryx doctor integration components\nastryx component SideNav\nastryx component AcmeSideNav\nastryx component SideNav --package @astryxdesign/core',
         },
         {
           type: 'list',
@@ -117,5 +115,15 @@ export default {
         },
       ],
     },
+    {
+      id: 'global-mode',
+      title: 'In global mode',
+      content: [
+        {
+          type: 'prose',
+          text: 'In global mode: a replacement from a package installed for the computer applies in folders outside any project; inside a project, only replacements from packages the project installs apply. See {@link namespace:global} and {@link generic:global-integrations}.',
+        },
+      ],
+    },
   ],
 };

package/assets/docs/tree/replace-a-core-template.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/document-the-template/replace-a-core-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/replace-a-core-template`:
  * deliberately replace one Core template through template metadata.
  */
 
@@ -48,7 +48,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx --json template --list --package @astryxdesign/core',
+          code: 'astryx --json template --list --package @astryxdesign/core',
         },
         {
           type: 'code',
@@ -67,10 +67,8 @@ export default {
 };`,
         },
         {
-          type: 'reference',
-          target: 'schema:template-doc',
-          projection: {fields: ['replaces']},
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:template-doc}.',
         },
         {
           type: 'prose',
@@ -84,7 +82,7 @@ export default {
       content: [
         {
           type: 'prose',
-          text: 'Declare the CLI floor from the field above as an optional peer ({@link generic:versioning}).',
+          text: 'Declare the CLI floor that `integration verify` names as an optional peer ({@link generic:versioning}).',
         },
         {
           type: 'code',
@@ -103,7 +101,7 @@ export default {
         },
         {
           type: 'prose',
-          text: '`integration verify` reports `replaces_needs_cli` when that peer is missing or too old. Without it, an older CLI drops that template and hides your doc topics.',
+          text: '`integration verify` reports `replaces_needs_cli` when that peer is missing or too old. Without it, published 0.6.3 and earlier drop that template and hide your doc topics.',
         },
       ],
     },
@@ -115,10 +113,10 @@ export default {
           type: 'code',
           lang: 'bash',
           code: `# Receives the active replacement
-npx astryx template shell-side-nav src/app
+astryx template shell-side-nav src/app
 
 # Receives the original Core template
-npx astryx template shell-side-nav --package @astryxdesign/core src/app`,
+astryx template shell-side-nav --package @astryxdesign/core src/app`,
         },
         {
           type: 'prose',
@@ -142,7 +140,7 @@ npx astryx template shell-side-nav --package @astryxdesign/core src/app`,
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx doctor integration templates',
+          code: 'astryx doctor integration templates',
         },
         {
           type: 'table',

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

@@ -132,7 +132,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Verify: you can state the reason in one sentence, and the choice still holds if the nav doubles in size. `npx astryx build "<idea>"` names the template to start from; scaffold it and the pairing is already wired up.',
+          text: 'Verify: you can state the reason in one sentence, and the choice still holds if the nav doubles in size. `astryx build "<idea>"` names the template to start from; scaffold it and the pairing is already wired up.',
         },
       ],
     },

package/assets/docs/tree/sections-and-placement.doc.mjs

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/docs/sections-and-placement`: give an
- * integration package its own section in the docs tree, place guides in it,
- * and fix a placement that fails.
+ * @file `astryx docs cli/integrations/building-blocks/docs/sections-and-placement`:
+ * give an integration package its own section in the docs tree, place guides
+ * in it, and fix a placement that fails.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -26,7 +26,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx integration add doc deploying --parent acme\n# Open your section\nnpx astryx docs acme',
+          code: 'astryx integration add doc deploying --parent acme\n# Open your section\nastryx docs acme',
         },
         {
           type: 'code',
@@ -62,16 +62,14 @@ export const docs = {
           type: 'list',
           style: 'unordered',
           items: [
-            "`parent` is `namespace:<name>`, a namespace that your own package ships. You cannot place a doc in the CLI's sections or in another package's.",
-            "`slot` is a slot that the namespace declares for the doc's kind. You can leave it out when the namespace has only one slot.",
-            '`order` is an integer that sorts the guides in the slot and sets their Previous and Next moves. Guides without one come last, by name.',
+            'Every field is in {@link schema:authored-doc-graph-fields}.',
             'A placed guide opens only by its route, `acme/deploying`. Its bare name no longer opens it.',
           ],
         },
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx docs acme/deploying',
+          code: 'astryx docs acme/deploying',
         },
       ],
     },
@@ -86,7 +84,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx doctor integration docs',
+          code: 'astryx doctor integration docs',
         },
         {
           type: 'code',
@@ -97,8 +95,8 @@ export const docs = {
           type: 'list',
           style: 'unordered',
           items: [
-            'A `parent` that your package does not ship, such as `namespace:cli`, "names no namespace".',
-            'A `slot` that the namespace does not declare "is not a slot of namespace"; the message lists the slots it does declare.',
+            'A `parent` your package does not ship, such as `namespace:cli`, "names no namespace".',
+            'A `slot` the namespace does not declare "is not a slot of namespace"; the message lists the declared slots.',
             'The check exits 1; see {@link generic:check-your-docs}.',
           ],
         },

package/assets/docs/tree/see-it-in-an-app.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/see-it-in-an-app`: inspect an
+ * @file `astryx docs cli/integrations/building-blocks/components/see-it-in-an-app`: inspect an
  * integration component from an app that installs the package.
  */
 
@@ -26,14 +26,16 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: `npx astryx component AcmeCarousel
-npx astryx component --list
-npx astryx search carousel`,
+          code: `astryx component AcmeCarousel
+astryx component --list
+astryx search carousel`,
         },
         {
           type: 'code',
           lang: 'text',
-          code: `# AcmeCarousel
+          code: `package: @acme/astryx-widgets
+
+# AcmeCarousel
 
 Cycles through slides one at a time. Use it for a small set of related cards.
 
@@ -55,5 +57,15 @@ Cycles through slides one at a time. Use it for a small set of related cards.
         },
       ],
     },
+    {
+      id: 'global-mode',
+      title: 'In global mode',
+      content: [
+        {
+          type: 'prose',
+          text: 'In global mode: to check your package in an app, install it in that app; a copy installed for your computer is not used inside a project. To check it outside projects, install it for your computer beside the CLI. See {@link namespace:global} and {@link generic:global-integrations}.',
+        },
+      ],
+    },
   ],
 };

package/assets/docs/tree/short-and-findable.doc.mjs

@@ -1,8 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/docs/short-and-findable`: keep each read
- * short, lead each section with its summary, and write docs that search finds.
+ * @file `astryx docs cli/integrations/building-blocks/docs/short-and-findable`:
+ * keep each read short, lead each section with its summary, and write docs
+ * that search finds.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -20,7 +21,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Readers open one section at a time, so give each section one idea and keep it to about 30 lines. `npx astryx doctor` warns on any read over 32 KB.',
+          text: 'Readers open one section at a time, so give each section one idea and keep it to about 30 lines. `astryx doctor` warns on any read over 32 KB.',
         },
         {
           type: 'list',
@@ -34,7 +35,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: '# The section list\nnpx astryx docs acme/deploying\n# One section\nnpx astryx docs acme/deploying check-before-you-ship\n# Everything\nnpx astryx docs acme/deploying --full',
+          code: '# The section list\nastryx docs acme/deploying\n# One section\nastryx docs acme/deploying check-before-you-ship\n# Everything\nastryx docs acme/deploying --full',
         },
       ],
     },
@@ -58,7 +59,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'text',
-          code: 'build-before-you-ship  Build before you ship - Build the app, then upload the `dist` folder to your host.',
+          code: 'build-before-you-ship  Build before you ship - Build the app, then upload the `dist` folder.',
         },
       ],
     },
@@ -68,14 +69,14 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Search ranks a query that matches a whole title, or an identifier in backticks, above words in body text. Title each section with the task a reader searches for.',
+          text: 'In a topic with more than one section, search ranks a section whose title matches the query, or that names it in backticks, above words in body text. Title each section with the task a reader searches for.',
         },
         {
           type: 'list',
           style: 'unordered',
           items: [
             'Name the task in the words a reader types, such as "Deploy to production". Avoid titles such as "Overview" or "Details".',
-            'Write field names, file names, and error codes in backticks, such as `deployTarget`: search treats each one as a keyword.',
+            'Write field names, file names, and error codes in backticks, such as `deployTarget`: in a topic with more than one section, search treats each one as a keyword.',
             'Other words in the summary and body match too, but rank below titles and identifiers. The summary shows under each hit, so make it answer the query.',
           ],
         },
@@ -92,7 +93,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx search "place a doc" --type doc',
+          code: 'astryx search "place a doc" --type doc',
         },
         {
           type: 'list',