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:

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

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

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:

```
ls -1
```
of
```
bsp_image.root_path
```
(one level deep). Record which directories are present.
For each canonical subtree below, mark present/absent:
```
rootfs/
```
,
```
bootloader/
```
,
```
kernel/
```
,
```
source/
```
,
```
tools/
```
,
```
nv_tegra/
```
.

Verify the active

flash_config

file exists at

<bsp_image.root_path>/<flash_config>

. Record its path or

(missing)

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

NA

or missing. Otherwise, run only:

```
ls -1
```
of
```
source.root_path
```
(one level deep).

For each canonical subtree below, mark present/absent:

kernel-jammy-src/

hardware/nvidia/

nvidia-oot/

nvgpu/

nvethernetrm/

nvdisplay/

hwpm/

kernel-devicetree/

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`

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:

Classify the value as URL (starts with
```
http://
```
,
```
https://
```
, or
```
ftp://
```
) or local path (anything else).
For URLs: record verbatim. Do not fetch the URL — KB generation must remain offline. (A future skill can promote to deep indexing.)
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

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

jetson-generate-kb

NPX Install

Tags

SKILL.md Content

Generate Target Knowledge Base

Overview

When to invoke

Procedure

Resolve the active target

Validate inputs

BSP discovery (under
`bsp_image.root_path`
)

Source tree discovery (under
`source.root_path`
)

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

Documents pass

Render and write the KB

Rendered structure

Confirm

Gotchas

Prerequisites

Limitations

Troubleshooting

References

jetson-generate-kb

NPX Install

Tags

SKILL.md Content

Generate Target Knowledge Base

Overview

When to invoke

Procedure

Resolve the active target

Validate inputs

BSP discovery (under bsp_image.root_path)

Source tree discovery (under source.root_path)

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

Documents pass

Render and write the KB

Rendered structure

Confirm

Gotchas

Prerequisites

Limitations

Troubleshooting

References

BSP discovery (under
`bsp_image.root_path`
)

Source tree discovery (under
`source.root_path`
)