# 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. |

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.
