/jetson-generate-kb

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

# 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