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: "Add `@acme/astryx-widgets` to the app's dependencies and apply the Ocean theme with `<Theme theme={oceanTheme}>`.",
        },
      ],
    },
  ],
};

Keep the section short: how to add the package, apply the theme (astryx docs cli/integrations/building-blocks/themes/use-a-theme-in-an-app), and — if the theme uses a custom font — which fonts the app must load (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.