@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

package/assets/docs/tree/template-styles.doc.mjs

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-styles`:
+ * style a template with Astryx first, keep editable styles in the file, and
+ * ship shared CSS from the package.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'template-styles',
+  placement: {
+    parent: 'namespace:template-assets',
+    slot: 'guides',
+    order: 20,
+  },
+  title: 'Styles',
+  category: 'guide',
+  description:
+    "Keep the copied UI on the app's theme: use Astryx props and tokens first, keep editable styles in the file, and ship shared CSS from your package.",
+  sections: [
+    {
+      id: 'start-with-astryx',
+      title: 'Start with Astryx',
+      content: [
+        {
+          type: 'prose',
+          text: 'Use Astryx component props, layout primitives, and design tokens before writing custom CSS. This keeps the copied result aligned with the host theme and reduces the styling contract an app inherits.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Use Stack and Grid spacing props instead of margins between children.',
+            'Use component variants, sizes, padding, and alignment props before restyling internals.',
+            'Use public theme token exports for a value that Astryx does not expose as a prop.',
+            'Do not copy private generated class names or target component internals with selectors.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'keep-editable-styles-with-the-source',
+      title: 'Keep editable styles with the source',
+      content: [
+        {
+          type: 'prose',
+          text: 'When a style belongs to the editable starting point, define it in the template file.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          code: `import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '@astryxdesign/core/theme/tokens.stylex';
+
+const styles = stylex.create({
+  trend: {
+    color: colorVars['--color-success'],
+    minWidth: 0,
+  },
+});
+
+// Later: <Text xstyle={styles.trend}>Up 12%</Text>`,
+        },
+        {
+          type: 'prose',
+          text: 'Use custom declarations only when no Astryx prop or token fits. Each one counts in the Custom CSS category of {@link generic:template-grading-rubric}.',
+        },
+      ],
+    },
+    {
+      id: 'publish-shared-css',
+      title: 'Publish shared CSS deliberately',
+      content: [
+        {
+          type: 'prose',
+          text: 'When a stylesheet must stay package-owned, import it from the template by its public package path.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'templates/acme-dashboard.tsx',
+          code: "import '@acme/astryx-widgets/styles/acme-dashboard.css';",
+        },
+        {
+          type: 'prose',
+          text: 'Then export that path and include the file in the package ({@link generic:export-template-assets}). In a TypeScript app, this import type-checks only when the app declares `*.css` modules.',
+        },
+      ],
+    },
+  ],
+};

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

@@ -0,0 +1,34 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates`: guides for adding,
+ * documenting, packaging, and testing templates in an integration package.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'templates',
+  placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 20},
+  title: 'Templates',
+  summary:
+    'Templates are ready-made UI pages or page sections built with Astryx. Apps copy them into their code and adapt them to their product.',
+  keywords: [
+    'integration template',
+    'template quality',
+    'template grading',
+    'template assets',
+    'template package',
+    'replace a core template',
+  ],
+  slots: {
+    build: {
+      title: 'Build',
+      accepts: {kinds: ['generic', 'namespace']},
+    },
+    quality: {
+      title: 'Quality',
+      accepts: {kinds: ['namespace']},
+    },
+  },
+};

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

@@ -0,0 +1,115 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/test-in-an-app`: install the packed
+ * package in an app and run the commands its users run.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'test-in-an-app',
+  placement: {parent: 'namespace:ship', slot: 'guides', order: 10},
+  title: 'Test an integration in an app',
+  category: 'guide',
+  keywords: ['test an integration locally', 'try an integration in an app'],
+  description:
+    'Install your packed package in an app and run the commands its users will run.',
+  sections: [
+    {
+      id: 'install-the-packed-package',
+      title: 'Install the packed package in an app',
+      content: [
+        {
+          type: 'prose',
+          text: 'Pack the package beside its folder, so the next pack does not ship it, then install it in an app together with Core and the CLI. The app loads your package because it is a dependency.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: '# In the package\nnpm pack --pack-destination ..\n\n# In an app folder beside it\nnpm install @astryxdesign/core @astryxdesign/cli ../acme-astryx-widgets-1.0.0.tgz',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "Install the CLI in the app too: `npx astryx` runs the CLI from the app's `node_modules`.",
+            'The app holds a copy, not a link. After each change, pack again and run the same `npm install`.',
+            'Reading your work inside the package shows your source. The app shows what npm would publish.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'check-what-the-app-sees',
+      title: 'Check what the app sees',
+      content: [
+        {
+          type: 'prose',
+          text: 'From the app folder, run the commands your users run. Each should show your contribution under your package name.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx component AcmeCarousel\nnpx astryx template --list --package @acme/astryx-widgets\nnpx astryx theme list --package @acme/astryx-widgets\nnpx astryx docs acme\nnpx astryx search deploying --type doc',
+        },
+        {
+          type: 'table',
+          headers: ['Command', 'Look for'],
+          rows: [
+            [
+              '`component AcmeCarousel`',
+              "`import {AcmeCarousel} from '@acme/astryx-widgets/components/AcmeCarousel';`",
+            ],
+            [
+              '`template --list --package`',
+              'An `acme-dashboard` entry with `package: @acme/astryx-widgets`',
+            ],
+            [
+              '`theme list --package`',
+              '`- ocean (maintained, @acme/astryx-widgets)`',
+            ],
+            ['`docs acme`', 'Your section, with guides such as `deploying`'],
+            [
+              '`search deploying --type doc`',
+              '`acme/deploying` as the first result',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: "`--package` narrows `template --list` and `theme list` to one package. `component --list` ignores it and lists Core too, so look a component up by name. Last, import `AcmeCarousel` in the app's code and build the app, as your users will.",
+        },
+      ],
+    },
+    {
+      id: 'run-doctor-in-the-app',
+      title: 'Run doctor in the app',
+      content: [
+        {
+          type: 'prose',
+          text: '`npx astryx doctor` checks the whole app, including every package it loaded. `doctor integration validate` checks your package as the app installed it.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx doctor\nnpx astryx doctor integration validate @acme/astryx-widgets',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'id:      implicit-integrations\nstatus:  [info]\nlabel:   Implicitly linked integrations\nmessage: 1 integration loaded from installed dependencies with no astryx.config entry: @acme/astryx-widgets@1.0.0 from dependencies, contributing components, templates, themes, docs, codemods.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'The `implicit-integrations` row names each package the app loads with no config. `[info]` is expected.',
+            'The `docs-progressive-disclosure` row warns when one of your doc sections is over 32 KB. The `doctor integration` checks do not measure size.',
+            '`doctor integration validate @acme/astryx-widgets` prints `[ok] No integration issues found.` when the installed copy is sound.',
+          ],
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/test-template-in-app.doc.mjs

@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/build-the-template/package-and-test/test-template-in-app`:
+ * copy the packed template into a clean app, build it, and render it the way
+ * apps will.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'test-template-in-app',
+  placement: {
+    parent: 'namespace:package-and-test',
+    slot: 'guides',
+    order: 30,
+  },
+  title: 'Test in an app',
+  category: 'guide',
+  description:
+    'Prove the template works the way apps use it: installed from the packed package, copied, built, and rendered.',
+  sections: [
+    {
+      id: 'install-the-packed-package',
+      title: 'Install the packed package',
+      content: [
+        {
+          type: 'prose',
+          text: 'Install the packed package in a clean app as described in {@link generic:test-in-an-app}. Also install every library the copied source imports, such as its icon library. Pack and reinstall after every change.',
+        },
+      ],
+    },
+    {
+      id: 'copy-the-template',
+      title: 'Copy the template',
+      content: [
+        {
+          type: 'code',
+          lang: 'bash',
+          code: `# Confirm discovery and metadata
+npx astryx --json template --list --package @acme/astryx-widgets
+
+# Inspect source without writing
+npx astryx template acme-dashboard --package @acme/astryx-widgets
+
+# Copy a page and a block to their real app locations
+npx astryx template acme-dashboard --package @acme/astryx-widgets src/app/acme-dashboard
+npx astryx template acme-stat-card --package @acme/astryx-widgets src/components`,
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Confirm the copied files: `src/app/acme-dashboard/page.tsx` and `src/components/acme-stat-card.tsx`.',
+            'Inspect the copied source for placeholder substitutions and relative references.',
+            'Import the copied block into a real page. A file that is never imported has not been tested.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'build-every-supported-app',
+      title: 'Build every supported app',
+      content: [
+        {
+          type: 'prose',
+          text: "Run the type check (`npx tsc --noEmit`, or the app's own script) and the production build in every framework or bundler the integration supports. One toolchain passing does not prove another.",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: `npx tsc --noEmit
+npm run build`,
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Every import resolves from the copied location.',
+            'Production builds keep required side-effect CSS.',
+            'No import bypasses `exports`, and no dependency resolves only through workspace hoisting.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'render-the-behavior-matrix',
+      title: 'Render the behavior matrix',
+      content: [
+        {
+          type: 'table',
+          headers: ['Dimension', 'Required checks'],
+          rows: [
+            ['Width', 'Wide and narrow; include the smallest supported viewport'],
+            ['Color', 'Every supported color mode and theme'],
+            ['Input', 'Keyboard and pointer for the primary task'],
+            [
+              'Content',
+              'Realistic, empty, long, loading, and error states that the pattern supports',
+            ],
+            [
+              'Assets',
+              'Successful CSS, font, icon, image, poster, and video requests',
+            ],
+            [
+              'Runtime',
+              'No console error, hydration mismatch, or missing-provider failure',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Check the rendered hierarchy, reading order, focus order, clipping, overflow, and fallback states. A screenshot of one default state is not a complete test.',
+        },
+      ],
+    },
+    {
+      id: 'grade-the-result',
+      title: 'Grade the result',
+      content: [
+        {
+          type: 'prose',
+          text: 'Grade the exact packed revision using the evidence from this test ({@link namespace:write-good-templates}).',
+        },
+      ],
+    },
+  ],
+};

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

@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/themes`: author a theme
+ * in an integration; apps install, apply, and extend it like any theme.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'themes',
+  placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 30},
+  title: 'Themes',
+  summary:
+    'Author a theme in your integration; apps install, apply, and extend it like any theme.',
+  keywords: [
+    'integration theme',
+    'ship a theme',
+    'define theme',
+    'theme palette',
+    'extend a theme',
+  ],
+  blocks: [
+    {
+      type: 'prose',
+      text: 'A theme is an editable `defineTheme` source with a generated color palette. An integration ships a theme the same way a standalone theme package does: an app installs the package, applies the theme with `<Theme>`, and customizes it with `extends`. An integration theme and a standalone theme package are the same shape.',
+    },
+    {
+      type: 'prose',
+      text: 'These guides cover authoring a theme inside an integration — scaffold it, generate its palette, define its tokens, ship its fonts, and document it. Using a theme, applying and extending it, is the same for every theme; see {@link generic:theme}.',
+    },
+  ],
+  slots: {
+    guides: {
+      title: 'Guides',
+      accepts: {kinds: ['generic']},
+    },
+  },
+};

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

@@ -0,0 +1,149 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/troubleshooting`: the messages the CLI
+ * prints while you build, verify, and install an integration, and the fix
+ * for each.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'troubleshooting',
+  placement: {parent: 'namespace:help', slot: 'guides', order: 10},
+  title: 'Troubleshooting',
+  category: 'guide',
+  keywords: ['integration error', 'integration not loading'],
+  description:
+    'Find the message the CLI printed while you build, verify, or install an integration, and apply its fix.',
+  sections: [
+    {
+      id: 'fix-setup-errors',
+      title: 'Fix setup errors',
+      content: [
+        {
+          type: 'prose',
+          text: 'These appear while you start the package or run the CLI in it. Each row quotes what the CLI prints.',
+        },
+        {
+          type: 'table',
+          headers: ['Message', 'Fix'],
+          rows: [
+            [
+              '`No package.json found. Run this command inside an integration package.`',
+              'Run `npm init -y` and `npm pkg set name=@acme/astryx-widgets` first, in the package folder.',
+            ],
+            [
+              '`Error: Could not find @astryxdesign/core package`',
+              'Component commands read Core. Run `npm install -D @astryxdesign/core` in the package.',
+            ],
+            [
+              '`core_not_found`: `Could not resolve @astryxdesign/core, so component names could not be checked.`',
+              'Same fix. The check exits 1.',
+            ],
+            [
+              "`Error: unknown subcommand 'integration verify'`, or `Error: Pass --check to verify the integration tarball.`",
+              'Your CLI is older than `integration verify`. Run `npm install -D @astryxdesign/cli@latest`. On the older CLI, the same check is `integration pack --check`.',
+            ],
+            [
+              'Note: `integration pack --check` is deprecated.',
+              'The old name still runs the same check. Switch to `npx astryx integration verify`; the old name will be removed in a later release.',
+            ],
+          ],
+        },
+      ],
+    },
+    {
+      id: 'fix-verify-failures',
+      title: 'Fix integration verify failures',
+      content: [
+        {
+          type: 'prose',
+          text: '`npx astryx integration verify` prints each failure as a `[fail]` line. Add `--json` to see its issue code, such as `component_export_missing`.',
+        },
+        {
+          type: 'table',
+          headers: ['Message', 'Fix'],
+          rows: [
+            [
+              '`component_export_missing`: `Component "AcmeCarousel" advertises import "@acme/astryx-widgets/components/AcmeCarousel", but that packed module does not export "AcmeCarousel".`',
+              "package.json has no `exports` map, or the module does not export the name. Keep `export function AcmeCarousel`, and add the entry: `npm pkg set 'exports[./components/AcmeCarousel]=./components/AcmeCarousel.tsx'`.",
+            ],
+            [
+              '`template_export_missing`: `Template "acme-dashboard" public import "@acme/astryx-widgets/templates/acme-dashboard" does not have a default export.`',
+              'Run `npm pkg set \'exports[./templates/acme-dashboard]=./templates/acme-dashboard.tsx\'`, and keep `export default` in the source. Start new packages with `"exports": {}` so each add writes these.',
+            ],
+            [
+              '`component_import_unresolvable` or `template_import_unresolvable`: `…Package subpath \'./components/AcmeCarousel\' is not defined by "exports"…`',
+              "The `exports` map has no entry for it. Run `npm pkg set 'exports[./components/AcmeCarousel]=./components/AcmeCarousel.tsx'`, or `'exports[./templates/acme-dashboard]=./templates/acme-dashboard.tsx'` for a template.",
+            ],
+            [
+              '`component_import_unresolvable`: `…but a consumer cannot resolve it: Cannot find package \'@acme/old-name\'`',
+              "You renamed the package after the add wrote each doc's `import`. Change `import` in every component doc to the new name.",
+            ],
+            [
+              '`Declared templates root "templates" has 0 of 2 expected files in the pack list. Add "templates" to "files" in package.json.`',
+              "Run `npm pkg set 'files[]=templates'`.",
+            ],
+            [
+              '`docs_tree_needs_cli`: `The package ships a namespace doc or a placed guide but declares no @astryxdesign/cli peer.`',
+              "Run `npm pkg set 'peerDependencies.@astryxdesign/cli=>=0.7.0'` and `npm pkg set 'peerDependenciesMeta.@astryxdesign/cli.optional=true' --json`.",
+            ],
+            [
+              '`replaces_needs_cli`: The package has a template that sets `replaces` but declares no @astryxdesign/cli peer.',
+              'Same fix: an older CLI rejects `replaces`, drops that template, and hides your doc topics.',
+            ],
+            [
+              '`themes_need_cli`: The package ships a theme but declares no @astryxdesign/cli peer.',
+              'Same fix: an older CLI cannot read typed theme descriptors, so it drops your themes and can hide your doc topics.',
+            ],
+            [
+              '`section_ids_need_cli`: The package has a doc section that sets `id` but declares no @astryxdesign/cli peer.',
+              'Same fix, or drop the section `id`s: an older CLI rejects them and hides your doc topics.',
+            ],
+          ],
+        },
+      ],
+    },
+    {
+      id: 'fix-problems-in-an-app',
+      title: 'Fix problems in an app',
+      content: [
+        {
+          type: 'prose',
+          text: 'These appear in an app that installs your package, or in the doctor checks that predict them.',
+        },
+        {
+          type: 'table',
+          headers: ['Symptom', 'Fix'],
+          rows: [
+            [
+              '`Error: Template "dashboard" is ambiguous — narrow it with --type and/or --package.`',
+              "Your template id matches a Core id. Rename it, such as `acme-dashboard`, or set `replaces: 'dashboard'` to take its place. `npx astryx doctor integration templates` warns about this before you publish.",
+            ],
+            [
+              '`invalid_doc_graph`: `placement.parent "namespace:nope" names no namespace; @acme/astryx-widgets declares "acme".`',
+              'The guide stays hidden until its `placement` names a namespace and slot your package declares. For `"…" names no doc`, fix the link target.',
+            ],
+            [
+              'Error: Unknown topic "acme". The docs of @acme/astryx-widgets did not load; run `astryx doctor integration docs` in that package to see why.',
+              'One invalid doc hides all of your docs. Run `npx astryx doctor integration docs` in the package and fix the `invalid_doc` it names.',
+            ],
+            [
+              '`npx astryx upgrade` runs none of your codemods',
+              'The app must list your package in `integrations` in `astryx.config`, or pass `--integration @acme/astryx-widgets`. It runs a codemod folder only when its version is after `--from` and at most the installed `@astryxdesign/core`.',
+            ],
+            [
+              'Your docs section, templates, or themes are missing only in some apps',
+              'Those apps run a stable CLI before 0.7.0. Update `@astryxdesign/cli` there, and keep your optional `@astryxdesign/cli` peer so npm warns about an old CLI.',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'What each check catches is in {@link generic:checks}.',
+        },
+      ],
+    },
+  ],
+};

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

@@ -0,0 +1,103 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/upgrading`: update an integration
+ * package for each Astryx release, and the command apps run to upgrade with
+ * it.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'upgrading',
+  placement: {parent: 'namespace:ship', slot: 'guides', order: 50},
+  title: 'Upgrading',
+  category: 'guide',
+  keywords: ['upgrade apps', 'release notes'],
+  description:
+    'Update your package for each Astryx release, and help apps upgrade with it.',
+  sections: [
+    {
+      id: 'update-for-a-new-astryx-release',
+      title: 'Update for a new Astryx release',
+      content: [
+        {
+          type: 'prose',
+          text: 'When Astryx ships a release, bump your devDependencies, rerun the checks, widen your peer ranges, and ship a codemod for each change that breaks apps.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: "# 1. Build and test against the new release\nnpm install -D @astryxdesign/cli@latest @astryxdesign/core@latest\n# 2. Rerun the checks\nnpx astryx doctor integration validate\nnpx astryx doctor integration docs\nnpx astryx integration verify\n# 3. Admit the new Core once the checks pass\nnpm pkg set 'peerDependencies.@astryxdesign/core=^0.6.0 || ^0.7.0'\n# 4. Migrate apps across a change that breaks them\nnpx astryx integration add codemod rename-delay --to 0.7.0",
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Run every check in {@link generic:checks}, not only the ones shown.',
+            'Name each codemod folder after the Core version whose upgrade should run it; see {@link generic:codemods}.',
+            'Release the result as a new version of your package; see {@link generic:publishing}.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'upgrade-an-app',
+      title: 'Upgrade an app',
+      content: [
+        {
+          type: 'prose',
+          text: 'After an app installs a new Core, `astryx upgrade` runs the codemods for the versions it crossed. It is a dry run by default; `--apply` writes the changes.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: '# Preview what would change; nothing is written\nnpx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets\n# Write the changes\nnpx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets --apply',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'Integrations: @acme/astryx-widgets\n1 codemod to run\nApplying integration codemods...\n  Rename AcmeCarousel delay to interval (v0.7.0, @acme/astryx-widgets)\n[ok]     [ok] src/Hero.tsx',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`--from` is the `@astryxdesign/core` version the app had before, and the target is the installed Core.',
+            '`--integration` names your package. Without it, or an `integrations` entry in `astryx.config`, the upgrade skips your codemods, even when the app has your package installed.',
+            "The count includes Core's codemods for the same versions, which run first.",
+            'Put this command in your release notes.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'know-which-files-upgrades-skip',
+      title: 'Know which files upgrades skip',
+      content: [
+        {
+          type: 'prose',
+          text: 'Upgrades never write files that the app marks as generated, vendored, or ignored. When such a file still needs a codemod change, the upgrade stops with `ERR_CODEMOD_PROTECTED` and exit code 1.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Generated: an `@generated` comment at the top of the file, or `linguist-generated` in `.gitattributes`.',
+            'Vendored: `linguist-vendored` in `.gitattributes`.',
+            'Ignored: a match in `.gitignore` or `.hgignore`.',
+          ],
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: '!     ! src/gen/Gen.tsx - protected by @generated in the leading comment block\nERR_CODEMOD_PROTECTED: 1 protected file still requires a codemod change:\n  src/gen/Gen.tsx — @generated in the leading comment block\nUpgrade incomplete: protected changes remain',
+        },
+        {
+          type: 'prose',
+          text: 'The upgrade still writes every other file. Its options and exit codes are in {@link command:upgrade}.',
+        },
+      ],
+    },
+  ],
+};