How-tos -- INDEX

Live catalog of analysis-derived how-tos for the integrations-lifecycle skill.

Live-catalog rule (also stated in ../SKILL.md and ../recipes/INDEX.md): if an assistant is asked a concrete question about the integrations pipeline that requires non-trivial analysis (multiple file reads, running the pipeline, cross-referencing schemas) AND the answer is not already documented under one of the per-domain guides (../pipeline.md, ../schema-reference.md, ../per-type-matrix.md, ../artifacts-and-banners.md, ../ibm-d.md, ../consistency.md, ../in-app-contract.md, ../gotchas.md) or the recipes (../recipes/), the assistant MUST author a new how-tos/<slug>.md and add a one-line entry to this INDEX BEFORE completing the task.

This is a durable rule. Skipping it means the next assistant repeats the same analysis from scratch -- a framework violation.

Catalog

Topic	Slug	Notes
Adding a new top-level integration_type (peer of collector, logs, exporter, etc.)	adding-new-integration-type	8-step recipe: schema, pipeline, templates, categories.yaml, map.yaml, source metadata, downstream repos. Covers what to clone from existing types, the hardcoded-vs-derived learn_rel_path distinction, and the integration_placeholder mechanism.
Auditing metadata.yaml links to Learn	auditing-metadata-learn-links	Commands and repair rules for finding absolute Learn URL drift, validating fragments, and checking source-relative metadata links.
Keeping Network Flows on the Learn "Monitor anything" page	monitor-anything-network-flows	Explains that src/collectors/COLLECTORS.md is generated by gen_doc_collector_page.py, why top-level flows must be treated as a section, and how to validate the generated Network Flows section.
Relating stock Prometheus profiles to integration metadata	prometheus-profile-metadata	Explains why profiles do not generate metadata, the catalog-aware disposition, operator-model brief, and regeneration checks.
Regenerating the NPM catalog (gen_npm_catalog.py)	npm-catalog-generation	The second-order generator chain (profiles -> metadata.yaml -> pages), the CI gap (gen_npm_catalog.py is NOT run by CI), the ruamel YAML-anchor sharing trap that made non-SNMP producers render SNMP setup, and how to verify a generator change did not disturb the other ~990 entries.
Understanding collector taxonomy generation	taxonomy-yaml-to-taxonomy-json	General flow from collector metadata.yaml + taxonomy.yaml through validation to generated integrations/taxonomy.json, with references to the executable source of truth.

Description authoring rules live in ../description-authoring.md because they apply to all metadata authors, not only to one analysis how-to.

How to add a how-to

1. Create how-tos/<slug>.md with:
   • A one-line summary at the top (the question being answered).
   • The answer with file:line citations into this repo.
   • A "How I figured this out" footer naming the files read and the commands run, so the next assistant can verify or extend.
2. Add a row to the table above with topic, slug, and short notes.
3. Commit alongside the work that prompted the analysis.

When NOT to add a how-to

• The question is already covered by an existing per-domain guide or recipe -- update that guide instead.
• The answer is a one-liner that doesn't require analysis (e.g. "where does X live?" -> just look it up; not how-to worthy).
• The answer is highly speculative or version-specific (e.g. about a feature that may change in the next release). In that case, note it in the conversation but don't bake into the durable catalog.