Document the theme

Give your theme a doc topic that extends the core theme topic, so an app that lists your package sees your theme at the end of astryx docs theme. Add it with extends: 'theme' (astryx docs cli/integrations/building-blocks/docs/extend-or-replace).

javascript
// docs/ocean-theme.doc.mjs
/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
export default {
  type: 'generic',
  name: 'ocean-theme',
  extends: 'theme',
  title: 'Ocean theme',
  description: 'Use the Ocean theme from @acme/astryx-widgets.',
  sections: [
    {
      id: 'use-the-ocean-theme',
      title: 'Use the Ocean theme',
      content: [
        {
          type: 'prose',
          text: 'Install @acme/astryx-widgets, then run astryx theme add ocean --import --package @acme/astryx-widgets and apply it from the generated app theme module.',
        },
      ],
    },
  ],
};

Keep the section short: how to install the package, run theme add --import, apply the generated module (astryx docs cli/integrations/building-blocks/themes/use-a-theme-in-an-app), and customize with extends. When the theme uses a custom font, name the families and the optional exported font stylesheet that theme add --import imports (astryx docs cli/integrations/building-blocks/themes/fonts-and-assets). Extend theme rather than a topic another package replaces, or an app that lists that package first drops your section.

Do not put theme usage in agentDocs. Agent lines land in every app's agent file and are for guidance needed every session; a theme's install-and-use steps belong in a doc topic that people and agents read on demand. See astryx docs cli/integrations/building-blocks/configuration/agent-guidance.