jetson-generate-kb — Claude Code skill: what it does, how to install

---
name: jetson-generate-kb
description: >-
  Build a per-target knowledge-base markdown next to the active
  profile by walking the BSP root and source tree. Use after
  init-image / init-source; not for editing profile fields.
version: 0.0.1
license: "Apache-2.0"
metadata:
  data-classification: public
  author: "Jetson Team"
  tags:
    - target-platform
    - knowledge-base
    - documentation
    - meta
  domain: meta
---

# Generate Target Knowledge Base

## Overview

This skill produces a **per-profile** markdown reference at
`target-platform/<profile-stem>.md` (sibling to the profile YAML). It
bundles three things into one file so a future Claude session — or the
user — can see the shape of the active target without re-walking the
filesystem:

1. **BSP image layout** — top-level directories under
   `bsp_image.root_path`, presence of canonical subtrees (`rootfs/`,
   `bootloader/`, `source/`, …), and the nvpmodel variants matching
   the active module SKU.
2. **Source tree layout** — top-level subtrees under
   `source.root_path` (`kernel-jammy-src/`, `hardware/nvidia/`,
   `nvidia-oot/`, etc.) and devicetree files matching the chip family.
3. **Documents** — the `documents.*` references recorded in the
   profile, with local-path existence checks and one-line descriptions.

The KB is a **snapshot**, dated in its header. Re-run this skill
whenever the underlying data changes — it is intentionally
re-runnable and overwrites the previous KB on each run.

## When to invoke

- After `jetson-init-image` prepares the BSP for a freshly authored
  profile.
- After re-extracting a BSP archive or applying patches under
  `bsp_image.root_path`.
- After updating the source tree at `source.root_path`.
- After editing `bsp_image.*` or `documents.*` in the profile YAML.
- When a downstream skill asks "where is X in this BSP?" and you'd
  rather check the KB than re-walk the tree.

## Procedure

### Resolve the active target

Resolve the active profile per the contract in
[`../../context/target-platform-contract.md`](../../context/target-platform-contract.md);
cache it in memory — the rest of the skill consumes only this
profile. Record `<profile-stem>` (the bare filename minus `.yaml`)
as the KB output filename stem.

### Validate inputs

| Field | Required for KB? | If missing |
|---|---|---|
| `bsp_image.root_path` | **yes** | Refuse. A KB with no BSP root to scan is just a YAML restatement; tell the user to run `jetson-init-image` or hand-edit the profile. |
| `source.root_path` | no | Skip the source-tree section; note "source_root not recorded" in the KB. |
| `documents.*` | no | Render an empty Documents table with a "no documents recorded" note. |

If `bsp_image.root_path` is set but the directory does not exist on disk,
refuse with a clear message — do not fabricate a layout for a path
that isn't there.

### BSP discovery (under `bsp_image.root_path`)

Run **only** the following cheap operations — no recursive scans, no
file content reads beyond directory listings:

1. `ls -1` of `bsp_image.root_path` (one level deep). Record which
   directories are present.
2. For each canonical subtree below, mark present/absent:
   `rootfs/`, `bootloader/`, `kernel/`, `source/`, `tools/`,
   `nv_tegra/`.
3. Verify the active `flash_config` file exists at
   `<bsp_image.root_path>/<flash_config>`. Record its path or
   `(missing)`.
4. List `rootfs/etc/nvpmodel/` and filter to filenames matching
   `nvpmodel_<module.id>_<module.sku>*.conf`. Record each match.
   Use the lower-case module id (e.g. `p3767`) and the YAML-quoted
   sku string (e.g. `0001`).

### Source tree discovery (under `source.root_path`)

Skip this step entirely if `source.root_path` is `NA` or missing.
Otherwise, run only:

1. `ls -1` of `source.root_path` (one level deep).
2. For each canonical subtree below, mark present/absent:
   `kernel-jammy-src/`, `hardware/nvidia/`, `nvidia-oot/`, `nvgpu/`,
   `nvethernetrm/`, `nvdisplay/`, `hwpm/`, `kernel-devicetree/`.
3. If `kernel-devicetree/generic-dts/dts/` exists, list filenames
   matching `tegra<chip>*` where `<chip>` is the chip-family numeric
   prefix (see chip-family map below). Record up to 30 hits; if more,
   record the count and a "showing first 30" note.

#### Chip-family map (used in the "BSP discovery" and "Source tree discovery" steps)

Derive `<chip>` from `module.id`:

| `module.id` | Chip family | `<chip>` prefix |
|---|---|---|
| `p3701`, `p3767` | T234 — Orin | `234` |
| `p3834` | T264 — Thor | `264` |

If `module.id` is not in this table, record the chip as
`unknown (module.id=<value>)` and skip the chip-prefixed devicetree
filter.

### Documents pass

For each field in `documents.*` from the loaded profile:

1. Classify the value as **URL** (starts with `http://`, `https://`,
   or `ftp://`) or **local path** (anything else).
2. For URLs: record verbatim. **Do not fetch the URL** — KB
   generation must remain offline. (A future skill can promote to deep
   indexing.)
3. For local paths: check `os.path.exists`. Record the path; if
   missing on disk, append ` (missing)`.

The one-line description for each field comes from the marker in
[`../../references/platform_template.yaml`](../../references/platform_template.yaml)
— strip the `<OPTIONAL: …>` wrapper and use the inner text.

If the profile has no `documents:` block, render the section with a
single line: `_No documents recorded — run `jetson-link-docs`
or hand-edit the profile to add references._`

### Render and write the KB

Render the markdown using the structure below. Use today's date
(YYYY-MM-DD) in the header. Always overwrite any existing KB file at
the destination — do not prompt before overwriting; re-runs are the
intended use.

Destination: `target-platform/<profile-stem>.md`.

#### Rendered structure

```markdown
# Target knowledge base — <profile-stem>

> Generated <YYYY-MM-DD> from `<bsp_image.root_path>` (BSP version `<bsp_image.version>`).
> Re-run `jetson-generate-kb` after extracting a new BSP, applying
> patches, or editing profile fields. This file is a regenerated
> snapshot — do not hand-edit.

## Profile facts

- **Reference devkit:** `<reference_devkit.name>`
- **Module:** `<module.id>-<module.sku>` (`<chip family label>`)
- **Reference carrier:** `<carrier.id>-<carrier.sku>`
- **Custom carrier:** `<custom_carrier.name>` (`<custom_carrier.id>-<custom_carrier.sku>`)  _← omit this row if Case 1_
- **Active flash conf:** `<flash_config>`
- **BSP path:** `<bsp_image.root_path>`
- **BSP version:** `<bsp_image.version>`
- **Source root:** `<source.root_path>`  _← or "_not recorded_" if NA_

## BSP image layout

Top-level directories under `<bsp_image.root_path>`:

| Directory | Present | Purpose |
|---|---|---|
| `rootfs/`     | ✓ / ✗ | userspace rootfs (nvpmodel, nvfan, systemd units, etc.) |
| `bootloader/` | ✓ / ✗ | firmware blobs, BCT, MB1/MB2 dts |
| `kernel/`     | ✓ / ✗ | prebuilt kernel + modules |
| `source/`     | ✓ / ✗ | BSP source tree (kernel, OOT drivers, DT) |
| `tools/`      | ✓ / ✗ | flashing helpers, jetson-io, kernel_flash |
| `nv_tegra/`   | ✓ / ✗ | nvidia firmware tarballs, kernel-supplements |

Active flash conf `<flash_config>`: present at
`<bsp_image.root_path>/<flash_config>` _or_ `(missing — verify before flashing)`.

### nvpmodel files matching the active SKU

Filtered from `rootfs/etc/nvpmodel/` by `nvpmodel_<module.id>_<module.sku>*.conf`:

- `<each match, one per line>`

The active variant at boot is selected by `nvpower.sh` from
`/proc/device-tree/compatible` plus super / safety state — see
`jetson-customize-nvpmodel` for the resolution rules.

## Source tree layout

(omit this whole section if `source.root_path` is `NA`/missing)

Top-level subtrees under `<source.root_path>`:

| Subtree | Present | Purpose |
|---|---|---|
| `kernel-jammy-src/`   | ✓ / ✗ | mainline 5.x kernel sources |
| `hardware/nvidia/`    | ✓ / ✗ | NVIDIA platform DTs (per chip family) |
| `nvidia-oot/`         | ✓ / ✗ | NVIDIA out-of-tree kernel modules |
| `nvgpu/`              | ✓ / ✗ | GPU driver |
| `nvethernetrm/`       | ✓ / ✗ | ethernet driver |
| `nvdisplay/`          | ✓ / ✗ | display driver |
| `hwpm/`               | ✓ / ✗ | hardware performance monitor |
| `kernel-devicetree/`  | ✓ / ✗ | devicetree sources |

### Devicetree files for chip family `<chip>`

(omit if `kernel-devicetree/generic-dts/dts/` is absent)

Files matching `tegra<chip>*` under `kernel-devicetree/generic-dts/dts/`:

- `<each match, one per line — cap at 30, then a "first 30 of N" note>`

## Documents

| Field | Reference |
|---|---|
| Documents root folder                    | `<doc_root>`                    _or_ _not recorded_ |
| BSP / Jetson Linux developer guide       | `<bsp_developer_guide>`         _or_ _not recorded_ |
| Tegra SoC Technical Reference Manual     | `<soc_tech_ref_manual>`         _or_ _not recorded_ |
| Jetson module data sheet                 | `<module_data_sheet>`           _or_ _not recorded_ |
| Jetson module design guide (PDG)         | `<module_design_guide>`         _or_ _not recorded_ |
| Jetson module thermal design guide (TDG) | `<module_thermal_design_guide>` _or_ _not recorded_ |
| Jetson module schematic                  | `<module_schematic>`            _or_ _not recorded_ |
| Reference carrier board specification    | `<carrier_board_spec>`          _or_ _not recorded_ |
| Reference carrier schematic              | `<carrier_schematic>`           _or_ _not recorded_ |
| Custom carrier schematic                 | `<custom_carrier_schematic>`    _or_ _not recorded / N/A (no custom carrier)_ |
| Reference-devkit pinmux spreadsheet      | `<ref_devkit_pinmux_xls>`       _or_ _not recorded_ |
| Custom-carrier pinmux spreadsheet        | `<custom_carrier_pinmux_xls>`   _or_ _not recorded / N/A (no custom carrier)_ |

(Local paths are tagged ` (missing)` if absent on disk. URLs are
recorded verbatim and not fetched. If `doc_root` is set, also tag
` (missing)` on it if the directory itself is gone — that signals
auto-mapping in `jetson-link-docs` won't work on a re-run.)

## How to refresh this file

Re-run `jetson-generate-kb` whenever any of the following changes:

- the BSP at `<bsp_image.root_path>` is re-extracted, patched, or upgraded,
- the source tree at `<source.root_path>` changes,
- the active profile's `bsp_image.*` or `documents.*` fields are edited.

This file is overwritten on every run. Do not hand-edit it — edit the
source data (profile YAML or the BSP tree) and re-run instead.
```

### Confirm

Print a short summary:

- Output path: `target-platform/<profile-stem>.md`.
- BSP top-level directory count and which canonical subtrees were
  present / absent.
- nvpmodel match count for the active SKU.
- Source-tree section: rendered or skipped (and why).
- Documents: count of recorded fields, count of local paths flagged
  `(missing)`.

If a downstream skill triggered this run, tell the user to re-issue
their original request.

## Gotchas

- **The KB is a snapshot, not a live view.** The dated header is
  authoritative — if it doesn't match today, the BSP/source/docs may
  have changed underneath. Re-run on demand.
- **Always overwrites.** No prompt before clobbering the previous KB
  at `target-platform/<profile-stem>.md`. This is intentional —
  re-runnability is the whole point. Tell the user not to hand-edit
  the file; edit profile YAML or the BSP and regenerate.
- **Refuses on `bsp_image.root_path = NA`.** A profile with no BSP path
  produces a content-free KB. Do not write one — instead, point the
  user at the profile YAML to fill in.
- **No URL fetching.** Document URLs are recorded verbatim. Promoting
  to deep indexing (HTTP HEAD, PDF parsing) is out of scope for v0.1.
- **No recursive scans.** Discovery is one level deep per directory,
  with at most one targeted glob (nvpmodel + devicetree). Never walk
  the entire BSP — it's huge and slow.
- **Cap devicetree listings at 30 entries** to keep the KB readable.
  Show "first 30 of N" when truncating.
- **Don't auto-invoke from setup skills.** Setup may suggest running
  this skill in its summary, but the user opts in. Auto-running hides
  the I/O step and surprises users whose BSP/doc paths are incomplete.
- **Filename collision risk.** The KB sits at
  `target-platform/<stem>.md` next to `<stem>.yaml`. Don't accidentally
  read `.md` files in the profile-listing logic of
  `jetson-set-target` (it already filters to `*.yaml`, but check
  before adding new file types).
- **Chip-family map is short.** If a future module SKU is added that
  isn't in the map, the devicetree filter step is skipped — the KB
  will note `chip: unknown` rather than fabricate a `<chip>` prefix.
  Update this skill's chip-family table when a new chip lands.

## Prerequisites

- Active target profile resolved per
  `../../context/target-platform-contract.md`.
- `bsp_image:` recorded by `/jetson-init-image`; this is the only
  required on-disk tree. If `source.root_path` is missing, render the KB
  without the source-tree section.
- Optional: `/jetson-init-source` already resolved `source:` when the
  user wants source-tree discovery included.
- Optional but recommended: `/jetson-link-docs` already wrote the
  `documents:` block.

## Limitations

- Read-only against the BSP and source trees; never edits the profile
  YAML or rewrites source files.
- Devicetree-file enumeration depends on the chip-family table inside
  this skill; an unknown module SKU lands in the KB as `chip: unknown`
  rather than a fabricated prefix.
- Filename layout is fixed at `target-platform/<stem>.md` to stay next
  to the profile YAML; renaming the YAML invalidates the link.

## Troubleshooting

- **`bsp_image.root_path` not found** — re-run `/jetson-init-image` so
  the BSP is extracted and the path is recorded before regenerating
  the KB.
- **Source tree walk picks up wrong subtrees** — `source.root_path`
  override is stale; rerun `/jetson-init-source` or correct the
  profile field.
- **`documents:` block missing from the KB** — `/jetson-link-docs` was
  never run; the KB falls back to "no documents bound" rather than
  guessing paths.
- **Devicetree section short / empty** — chip-family table doesn't
  cover the active SoC; update the table and rerun.

## References

- [`../../context/target-platform-contract.md`](../../context/target-platform-contract.md) — read-order contract this skill follows.
- [`../../context/bsp-customization-workflow.md`](../../context/bsp-customization-workflow.md) — origin of the canonical BSP/source subtree list.
- [`../../references/platform_template.yaml`](../../references/platform_template.yaml) — source of the documents-field one-line descriptions.
- [`../jetson-init-target/SKILL.md`](../jetson-init-target/SKILL.md) — sibling skill that authors the active target identity.
- [`../jetson-init-image/SKILL.md`](../jetson-init-image/SKILL.md) — sibling skill that authors the BSP image metadata this skill scans.
- [`../jetson-set-target/SKILL.md`](../jetson-set-target/SKILL.md) — sibling skill that flips the active pointer this skill resolves.