# 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](adding-new-integration-type.md) | 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](auditing-metadata-learn-links.md) | 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](monitor-anything-network-flows.md) | 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](prometheus-profile-metadata.md) | 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](npm-catalog-generation.md) | 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](taxonomy-yaml-to-taxonomy-json.md) | 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.
