Document where an AI Catalog item definition is stored

What does this MR do?

Documents where an AI Catalog agent or flow definition is stored, and how to keep one in version control.

The AI Catalog documentation does not currently say where a definition lives. Readers reasonably assume a repository file, because that is how every other GitLab configuration works, and then cannot find the path. The answer is that the definition is stored in the catalog and edited through the catalog, which is worth stating plainly on the page that introduces it.

It also points to the AI Catalog CI/CD component, which publishes definitions from a repository to the catalog and is not referenced anywhere in the documentation today.

flowchart LR
    Y["YAML in agents/ and flows/"] --> MR["Merge request"]
    MR -->|merge, then tag| P["Tag pipeline runs components/ai-catalog"]
    P -->|publishes| C[("AI Catalog<br/>stores the definition")]
    E["AI Catalog editor"] -->|takes effect at once| C
    C --> R["Agent Platform reads<br/>when a flow runs"]

Both write paths land in the catalog. An edit in the AI Catalog editor stays until the repository file changes, and the next publish then overwrites it.

Two corrections outside the new section, found while verifying these claims:

• Lines 127 and 129 said "manager project", where the line above them says "the project that manages the item" and the AI Catalog labels the field Managed by. They now match.
• Foundational agents and flows have no managing project, so the new section says so rather than implying every item has one.

Claims were verified against product source rather than against other documentation pages. The load-bearing ones:

• A definition persists in the definition jsonb column of ai_catalog_item_versions (ee/app/models/ai/catalog/item_version.rb).
• An edit forks a new version rather than mutating one, because should_create_new_version? is definition_changed? && released? and v1.0.0 is released at creation (ee/app/services/ai/catalog/items/base_update_service.rb, base_create_service.rb).
• A flow reads its definition from the catalog at execution time (ee/app/services/ai/catalog/flows/execute_service.rb).
• The component's agent_directory and flow_directory inputs default to agents and flows, and its sync job runs on tag pipelines (templates/catalog-sync.yml).

This MR deliberately does not describe repository-backed authoring, which is proposed rather than available, so the page describes only what works today.

Topic type: concept, extending an existing page rather than adding one.

Related issues

Related to #587004, which asks for the component to be documented as the standard approach, and was opened by the component's maintainer.

Related to #608460 and https://gitlab.com/gitlab-org/gitlab/-/issues/577946, which come from the same gap.

Author's checklist

• Optional. Consider taking the GitLab Technical Writing Fundamentals course.
• Follow the:
  • Documentation process.
  • Documentation guidelines.
  • Style Guide.
• If you're adding a new page, add the product availability details under the H1 topic title. Not a new page.
• If you are a GitLab team member, request a review based on:
  • The documentation page's metadata.
  • The associated Technical Writer.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

• If the content requires it, ensure the information is reviewed by a subject matter expert.
• Technical writer review items:
  • Ensure docs metadata is present and up-to-date.
  • Ensure the appropriate labels are added to this MR.
  • Ensure a release milestone is set.
  • If relevant to this MR, ensure content topic type principles are in use, including:
    • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
    • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
    • Any task steps should be written as a numbered list.
    • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
• Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.

AI disclosure: parts of this merge request were drafted with assistance from Claude Code. The content was verified against product source as listed above, and checked against the documentation style guide.