| 1 | # How-tos -- INDEX |
| 2 | |
| 3 | Live catalog of analysis-derived how-tos for the |
| 4 | integrations-lifecycle skill. |
| 5 | |
| 6 | **Live-catalog rule** (also stated in `../SKILL.md` and |
| 7 | `../recipes/INDEX.md`): if an assistant is asked a concrete |
| 8 | question about the integrations pipeline that requires |
| 9 | non-trivial analysis (multiple file reads, running the |
| 10 | pipeline, cross-referencing schemas) AND the answer is not |
| 11 | already documented under one of the per-domain guides |
| 12 | (`../pipeline.md`, `../schema-reference.md`, `../per-type-matrix.md`, |
| 13 | `../artifacts-and-banners.md`, `../ibm-d.md`, |
| 14 | `../consistency.md`, `../in-app-contract.md`, |
| 15 | `../gotchas.md`) or the recipes (`../recipes/`), the |
| 16 | assistant MUST author a new `how-tos/<slug>.md` and add a |
| 17 | one-line entry to this INDEX BEFORE completing the task. |
| 18 | |
| 19 | This is a durable rule. Skipping it means the next assistant |
| 20 | repeats the same analysis from scratch -- a framework |
| 21 | violation. |
| 22 | |
| 23 | ## Catalog |
| 24 | |
| 25 | | Topic | Slug | Notes | |
| 26 | |---|---|---| |
| 27 | | 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. | |
| 28 | | 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. | |
| 29 | | 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. | |
| 30 | | 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. | |
| 31 | |
| 32 | Description authoring rules live in `../description-authoring.md` |
| 33 | because they apply to all metadata authors, not only to one |
| 34 | analysis how-to. |
| 35 | |
| 36 | ## How to add a how-to |
| 37 | |
| 38 | 1. Create `how-tos/<slug>.md` with: |
| 39 | - A one-line summary at the top (the question being |
| 40 | answered). |
| 41 | - The answer with file:line citations into this repo. |
| 42 | - A "How I figured this out" footer naming the files |
| 43 | read and the commands run, so the next assistant can |
| 44 | verify or extend. |
| 45 | 2. Add a row to the table above with topic, slug, and short |
| 46 | notes. |
| 47 | 3. Commit alongside the work that prompted the analysis. |
| 48 | |
| 49 | ## When NOT to add a how-to |
| 50 | |
| 51 | - The question is already covered by an existing per-domain |
| 52 | guide or recipe -- update that guide instead. |
| 53 | - The answer is a one-liner that doesn't require analysis |
| 54 | (e.g. "where does X live?" -> just look it up; not how-to |
| 55 | worthy). |
| 56 | - The answer is highly speculative or version-specific (e.g. |
| 57 | about a feature that may change in the next release). In |
| 58 | that case, note it in the conversation but don't bake into |
| 59 | the durable catalog. |