Collector metadata.yaml: The Page The User Reads

metadata.yaml is the source of the integration page on Learn and of the catalog row that leads to it. Users open that page to decide whether to run the collector, what they will get, what it needs, and what it costs. Every field in it is product copy for an operator, not developer documentation. This skill owns what each field says and how it reads.

Use By Task

• Explain a field: read its family below and the shared reading/Markdown rules.
• Review metadata or page content: apply the relevant field contracts and checklist to the assigned scope. A full page review uses all five families. Loading this skill does not authorize edits or generation in the checkout.
• Edit content: verify claims against current source, then use the lifecycle validation and isolated preview routes. ibm.d changes must reach the generated metadata through its producer; editing module.yaml alone does not refresh it.
• Review a collector through another lens: load the affected family when wording, permissions, defaults, cost, or operator behavior matters to that lens; this does not expand the assigned review scope.

Ownership

• This skill: the content of every collector metadata.yaml field: what it answers, in what order, in what shape, for whom. Rules are cross-plugin. ibm.d metadata is generated by docgen and never edited: module.yaml holds the identity, overview description, and explicit page page_description; contexts.yaml holds the metric rows. Other fields (method, permissions, default behavior, option rows, prerequisites, examples, troubleshooting) use docgen's metadata template (src/go/plugin/ibm.d/docgen/main.go, see integrations-lifecycle/ibm-d.md), so applying these rules there means changing the template. Keywords derive from the module name; page_description becomes meta.monitored_instance.description. config.go feeds the schema and README, not the options table.
• .agents/skills/integrations-lifecycle/: mechanics. JSON schemas, generators, validation commands, artifacts and banners, the ibm.d generation chain, and the cross-type page meta-description derivation contract (description-authoring.md).
• .agents/skills/collectors-go-design/config-schema.md: the DynCfg form. Option wording shared between the form and the options table has one owner there (sections 7 and 8); this skill points to it.
• .agents/skills/collectors-go-design/operator-surface.md: which options exist and what an operator decides. Decided before this skill applies.

How The Page Is Rendered

Facts every rule below relies on (integrations/templates/overview/collector.md and siblings):

• The template owns the heading hierarchy (h1 title; h2 Overview, Setup, Troubleshooting, Alerts, Metrics, and Live Data when the collector has Functions; h3 to h6 inside them, down to one h5 per option depth block and one h6 per example). Field text is inserted under those headings as-is.
• Field text is Markdown rendered by Docusaurus on Learn. Paragraphs, lists, tables, inline code, fenced code, links, and ::: admonitions (note, tip, caution) pass through the generator untouched.
• Some empty fields are not empty on the page. auto_detection, limits, and performance_impact render a template placeholder sentence that asserts something about the collector (see overview.md). An empty field is a claim.
• The first sentence of metrics_description supplies the catalog row. Page meta descriptions have separate override-first resolution and length rules in integrations-lifecycle/description-authoring.md.
• Generated pages under integrations/ and the README.md symlink are outputs. Fix the source; never edit them.

The Reading Model

• The reader is an operator scanning a page, deciding in this order: what is this, what do I get, what do I need, what does it cost, how do I set it up, what went wrong. Fields are ordered that way by the template; write each field for the question it sits under.
• Readers stop when they have enough. The first paragraph of every field MUST stand alone; detail follows in decreasing importance.
• metrics_description and method_description carry the page. They sit above the fold, most visitors read no further, and the first sentence of metrics_description becomes the catalog row that decides whether anyone opens the page at all. When writing or reviewing time is short, spend it on those two.
• Readers skip walls of text ("I ain't reading all that"). Long content is fine when it is structured: one idea per paragraph, lists for enumerations, tables for items that share attributes, an admonition for what must not be missed. Length is a symptom to check, not the rule; an unstructured 120-word paragraph fails, a 400-word field made of a table and three short paragraphs may pass.
• Paragraph breaks are not structure, and no shape test decides this. A field can sit under every length bound, break cleanly into four paragraphs, and still be a wall, because the reader must read all of it to find the part that concerns them; redfish shipped exactly that (overview.md section 3). Conversely s3check's method_description is three plain paragraphs, the longest 114 words, and passes, because every sentence in it is a consequence the operator can act on. Judge the field by the question it answers and by what the reader can do with each sentence, never by its silhouette.
• Operator voice. The page describes what the collector does as the operator sees it: connections, requests, commands, files, permissions, what it creates and deletes, what it never touches. Unexplained implementation mechanics that do not affect operation MUST NOT appear. Preserve operator-visible terms and exact public names (for example journal storage or snapshot APIs); define unfamiliar terms at first use.

Routing By Field Family

Depth Boundary

Content that does not answer its field's question does not stay in the field. Route it:

• Another field on the page owns it (a permission belongs in additional_permissions, a knob in its option row's detailed_description, a failure in troubleshooting, a chart in its metric description).
• The collector's profile format documentation (profile-format.md) owns it, for profile-driven collectors.
• A docs/guides page owns it when it is an operator procedure spanning several products.
• It is developer content (internal stages, caches, bounds nobody configures, ownership resolution). It belongs in the collector's ARCHITECTURE.md or in code, is never linked from the page, and leaves the page.
• Nothing owns it: cut it.

Noticing is the hard part, because the content feels relevant while you are writing it — you are describing the collector you just built. Hold the draft against these four shapes. They are developer notes nearly every time they appear in a field, at any length:

• Failure narration. What happens on an error, how many times it retries, when it gives up.
• State between runs. What is kept, discarded, replayed, or invalidated from one collection to the next.
• Algorithm. Preference order, evaluation rules, dwell and hysteresis, bounds the code applies to itself.
• Internal vocabulary. A term that appears nowhere the operator can see: not an option name, not a chart, not a log message, not a label in the UI. Public protocol and API names (ServiceRoot, a vendor operation) are the exception and stay.

An operator-visible consequence of any of these can belong on the page; the mechanism behind it does not. "Some charts skip a cycle when the walk overruns" is a consequence and lives in limits. How the walk resumes afterwards is the mechanism, and leaves.

Safety Of The Markdown

Field text travels through the generator into MDX. Check these common rendering hazards:

• Placeholders in angle brackets (<service-name>, <region>) parse as JSX. Put them in backticks, like every other code-shaped expression (option names, paths, values).
• Generics and any other angle-bracket syntax in prose (Vec<u32>, HashMap<K,V>) parse the same way. Backticks.
• A bare < before a digit (<100 ms) fails the build. Write "under 100 ms" (or < when the symbol must stay).
• Balance backticks. Use ASCII quotes in executable examples; prose typography is not a universal MDX error.
• Tables need a header separator row and the same number of cells on every row; an admonition needs its closing ::: on its own line.
• test_collector_metadata checks selected prose keys for common Markdown patterns and missing service-discovery claims, with explicit exceptions. It does not compile MDX or verify editorial quality and factual truth. Learn-side parsing and ingest rules belong to .agents/skills/docs-learn-site-structure/mdx-rules.md.

Review Checklist

For content review, apply these checks to the assigned fields and report findings. For authorized content changes, complete the validation and preview before committing:

1. Read the rendered page top to bottom as an operator. Use integrations-lifecycle/how-tos/preview-collector-page.md for an isolated preview of current inputs. For a read-only review, inspect provided artifacts and source; report stale or missing preview evidence rather than regenerating in the checkout. Producer prerequisites, validation commands, and preview limits live in that owner.
2. Every field answers its own question (the family file's contract), leads with what matters, and would survive the reader stopping after its first paragraph.
3. No field is over-scoped: no headings, at most two or three bold captions, at most one admonition, no glossary before the reader knows what the collector does. Apply the explicit cost carve-out in overview.md when relevant.
4. Empty auto_detection, limits, or performance_impact only where the placeholder sentence is true. A collector covered by a service-discovery rule, or with a cardinality cap or a metered API, fills them.
5. No irrelevant implementation mechanics; unfamiliar operator terms defined at first use; no developer links (ARCHITECTURE.md, source files). The test is per sentence, not per field: ask what the operator does differently for having read it. "Nothing" means it belongs to another field, to ARCHITECTURE.md, or nowhere — see the worked routing example in overview.md section 3. A field can pass every length and structure check and still fail this one, which is the failure mode that reaches production.
6. Statements verified against the code, not against the previous prose: permissions, defaults, what is created or deleted, limits, addresses probed.
7. Markdown safety items above; for authorized changes run python3 -m unittest integrations.tests.test_collector_metadata (selected mechanical checks) and the pipeline validation in integrations-lifecycle/description-authoring.md (gen_docs_integrations.py --check, test_descriptions).
8. Generated hunks under integrations/ are not part of the commit; the post-merge regeneration owns them.