Agent guidance

Add a few lines of guidance that apps put in front of the AI agents working in their code.

Add a line of guidance

integration add agent-doc adds one line for AI agents that work in apps using your package. Apps show it in their agent file, such as AGENTS.md.

bash
npx astryx integration add agent-doc 'Use AcmeCarousel for rotating content.'

The line lands in agentDocs.append in your manifest:

js
// astryx.integration.mjs
export default {
  components: './components',
  agentDocs: {
    append: ['Use AcmeCarousel for rotating content.'],
  },
};

Adding the same line again changes nothing. To reword or remove a line, edit agentDocs.append by hand.

Keep within the limits

Every line costs space in each app's agent file, so the CLI keeps guidance short and few. Put detail in your docs instead.

Limit	What happens past it
8 lines per package	`integration add` fails: `append may contain at most 8 lines`.
240 characters per line	`integration add` fails: `must contain at most 240 Unicode code points`.
32 lines per app, from all its packages	`init` writes no agent block and prints `Could not install agent docs.`

A line is one line of plain text. Line breaks, control characters, spaces at either end, and managed-block markers such as  are rejected.

See what agents read

An app's astryx init writes your lines at the end of its managed agent block, each labeled with your package name. The CLI owns the heading, the labels, and the markers.

bash
npx astryx init --features agents

text
INTEGRATIONS:
- `@acme/astryx-widgets`: Use AcmeCarousel for rotating content.
<!-- ASTRYX:END -->

The block collects lines from every integration the app has installed, with or without an astryx.config entry.

Refresh the block in an app

The block changes only when the app runs init, or upgrade --from <version> --apply. After an app installs a version of your package with new lines, it runs one of them.

bash
npx astryx init --features agents
# Or: --from takes the Core version the app had before
npx astryx upgrade --from 0.7.0 --apply

text
[ok] Agent docs refreshed -> AGENTS.md

upgrade --apply prints that line; init prints [ok] AI agent docs installed -> AGENTS.md. Without --apply, upgrade only reports Agent docs differ from the installed Astryx and integration configuration. It refreshes the block even when Core did not change. See astryx docs cli/commands/upgrade.