jetson-link-docs

Overview

This skill writes the

documents:

block of the active Jetson / IGX target-platform profile YAML so downstream skills (

/jetson-generate-kb

/jetson-customize-pinmux

, camera / pcie / uphy, etc.) can resolve doc paths by name. It walks the user through every document slot in the profile schema, tries to auto-bind each slot to a file under

<documents.root_path>/

via case-insensitive glob matching, and writes the resulting paths back into the active profile.

Scope is registering pointers only — this skill does not fetch or download. The files must already exist on disk under

<documents.root_path>/

When to invoke

After
```
/jetson-init-target
```
finishes and the user has documents on disk to register.
The user wants to add, change, or remove document references on an existing profile.
A downstream skill (e.g.
```
jetson-generate-kb
```
) reports "no documents recorded" and the user wants to fix that.

Procedure

Resolve the active target

Resolve the active profile +

<workspace>

per the contract in

../../context/target-platform-contract.md

. Cache the loaded profile in memory — this skill mutates it in the "Write the

documents:

block back to the profile" step.

Load the document-slot schema

Load

../../references/platform_template.yaml

. Parse the

documents:

block. Each per-document field is marked

<OPTIONAL: description>

. Use the marker description as prompt text verbatim. Match markers with the regex

^<(REQUIRED|OPTIONAL|DERIVED):\s*(.*)>$

after YAML parsing strips surrounding quotes.

Skip

custom_carrier_schematic

and

custom_carrier_pinmux_xls

entirely when the active profile has no

custom_carrier:

block — both are meaningless without one. This filter applies through the "Scan and auto-match" and "Manual prompts for unmatched fields" steps.

Resolve

documents.root_path

Default:

<workspace>/Documents

. If the profile already records

documents.root_path

, use it. Otherwise, if

<workspace>/Documents/

exists, use it (the field is omitted from the written profile — downstream skills fall back to the workspace default). If neither is available, prompt the user for an absolute path, or accept Enter /

cancel

to skip the auto-scan. A user-provided path that doesn't exist is treated as skipped (warn, don't refuse — the field is OPTIONAL); manual prompts in the "Manual prompts for unmatched fields" step still run.

Resolve the product token

Read the Product Token column from

../../references/bsp-platforms-catalogue.md

for the row matching

reference_devkit.name

. The token is a case-insensitive glob fragment (e.g.

*orin*nano*

*agx*thor*

) consumed by the fallback patterns in the "Scan and auto-match" step.

reference_devkit.name

has no row in the catalogue, log a warning and proceed without a product-token fallback — the "Scan and auto-match" step still works with strictly SKU-keyed matching.

For custom carriers, derive

<custom-token>

from

custom_carrier.name

using this recipe: lowercase, replace each space with

, wrap in

on both ends. E.g. "Acme Vision X1" →

*acme*vision*x1*

Scan and auto-match

Skip this step entirely if

documents.root_path

did not resolve in the "Resolve

documents.root_path

" step (no scan target → no auto-suggest; fall through to manual prompts in the "Manual prompts for unmatched fields" step).

Scan the directory once (one level deep) and try to auto-match each remaining

<OPTIONAL:…>

field using the case-insensitive globs below. Use the lower-case

module.id

carrier.id

custom_carrier.id

strings from the profile in the SKU column.

Field	SKU glob (primary)	Product-token glob (fallback)
`bsp_developer_guide`	`developerguide.pdf` , `BSPguide.pdf`	(no fallback — pattern is product-agnostic)
`soc_tech_ref_manual`	`TRM.pdf` , `techrefmanual.pdf`	(no fallback — same)
`module_data_sheet`	`<module.id>datasheet.pdf` , `<module.id>datasheet*.pdf`	`<token>datasheet.pdf` , `<token>datasheet*.pdf`
`module_design_guide`	`<module.id>designguide.pdf` , `<module.id>PDG*.pdf`	`<token>designguide.pdf` , `<token>PDG*.pdf`
`module_thermal_design_guide`	`<module.id>thermal*.pdf` (covers "Thermal Design Guide" / "TDG")	`<token>thermal*.pdf`
`module_schematic`	`<module.id>schem*.pdf`	`<token>schem*.pdf`
`carrier_board_spec`	`<carrier.id>boardspec.pdf` , `<carrier.id>spec*.pdf`	`<token>carrierspec.pdf`
`carrier_schematic`	`<carrier.id>schem*.pdf`	`<token>carrierschem.pdf`
`custom_carrier_schematic`	`<custom_carrier.id>schem*.pdf` (only if custom carrier)	`<custom-token>schem*.pdf` (only if custom carrier)
`ref_devkit_pinmux_xls`	`<carrier.id>pinmux.xls` (matches `.xls` , `.xlsx` , `.xlsm` )	`<token>pinmux.xls`
`custom_carrier_pinmux_xls`	`<custom_carrier.id>pinmux.xls` (only if custom carrier)	`<custom-token>pinmux.xls` (only if custom carrier)

<token>

is the catalogue-resolved product token;

<custom-token>

is derived from

custom_carrier.name

per the "Resolve the product token" step. Tokens already include leading/trailing

, so the table does not repeat them.

Match policy per field

For each field that has auto-match results:

Take the union of hits across the SKU glob and the product- token glob, then deduplicate by absolute path — a file matched by both globs counts once.
Exactly 1 unique hit → show the path and prompt
```
use this? (yes/no, default yes)
```
. On
```
yes
```
, record it and skip the manual prompt for that field. On
```
no
```
, fall through to the manual prompt in the "Manual prompts for unmatched fields" step.
0 hits → skip auto-suggest entirely for that field; fall through to the "Manual prompts for unmatched fields" step.
2+ unique hits → present them as a numbered list in the "Manual prompts for unmatched fields" step so the user can pick by number rather than typing a path; include a
```
skip / NA
```
option. Never silently bind a multi-hit candidate.
Never silently bind without user confirmation — wrong-schematic / wrong-pinmux bindings are real and costly.

documents.root_path

is folder-organised one level deeper than flat (NVIDIA archives often are:

Schematics/

Design-Guides/

Pinmux/

, etc.), the file globs may return zero hits even when the right documents exist. v0.2 only scans one level deep — when 0 hits is suspicious (

documents.root_path

exists but no fields auto-bound), surface the limitation to the user and offer to fall through to manual prompts.

Manual prompts for unmatched fields

For every field that wasn't auto-bound (and wasn't filtered out in the "Load the document-slot schema" step), prompt using the marker description from the "Load the document-slot schema" step as prompt text, in document order. Accept Enter and

NA

interchangeably as "skip this field". When the "Match policy per field" step produced 2+ candidate hits for a field, present them as a numbered list with a

skip / NA

option rather than asking for a free-text path.

Validate that user-provided paths exist on disk (warn if not, but do not refuse — the user may be recording a planned path). URLs (values starting with

http://

https://

, or

ftp://

) are accepted verbatim and not validated.

Write the

documents:

block back to the profile

Edit

target-platform/<active>.yaml

in place. Preserve all other top-level blocks (

reference_devkit:

custom_carrier:

bsp_image:

source:

) and their comments verbatim. Write only the fields the user provided — omit skipped /

NA

fields entirely (no

NA

placeholders, no empty keys).

Edge behavior: when every field was skipped (including

documents.root_path

), drop the

documents:

block entirely from the profile — never write

documents: {}

or a block of

NA

values. When only

documents.root_path

was provided (no per-document binding), record it alone — the path has value as a hint for future re-runs. On re-run with an existing

documents:

block, merge: existing bindings are preserved unless the user picks a new file or

NA

; newly bound fields are added.

Confirm

Print a summary:

Profile path written.
```
documents.root_path
```
— resolved value (or "default — omitted").
Auto-bound fields: count + per-field one-line list.
Manually entered fields: count + list.
Skipped fields: count.
A reminder that
```
jetson-generate-kb
```
re-reads
```
documents.*
```
and should be re-run if a KB exists.

If a downstream skill triggered this run, tell the user to re-issue their original request; do not silently re-trigger it.

Gotchas

Active profile must exist. This skill writes back to whichever profile is active. If no profile is active, refuse and route to
```
jetson-set-target
```
/
```
jetson-init-target
```
.
Product-token globs are intentionally broad. A token like
```
*orin*nano*
```
matches both Orin-Nano-specific docs and combined Orin-NX/Nano docs (e.g.
```
Jetson-Orin-NX-Nano-Design-Guide_…
```
). That is usually correct for module-side docs (NVIDIA ships combined manuals), but verify on schematic / pinmux / spec fields where wrong-product binding is costly.
Update
bsp-platforms-catalogue.md
when adding new product rows. The Product Token column is consumed by the "Resolve the product token" step; a missing token degrades the auto-scan to SKU-only matching (the skill warns and continues, but doc-rich
```
documents.root_path
```
scans will degrade silently from "5 auto-binds" to "fewer auto- binds").
Use a round-tripping YAML loader. the "Write the
```
documents:
```
block back to the profile" step mutates an existing YAML file. Plain
```
yaml.safe_load
```
+
```
yaml.safe_dump
```
loses comments, block ordering, and quoting style — use
```
ruamel.yaml
```
or equivalent so hand-edited fields and comments survive.
Re-runnable. Re-running merges new bindings; existing bindings are preserved unless the user explicitly changes them. Safe to invoke as part of a profile refresh.

Prerequisites

Active target profile resolved per

../../context/target-platform-contract.md

Documents available either under the recorded
```
documents.root_path
```
, under default
```
<workspace>/Documents/
```
, or as user-provided paths / URLs during manual prompts. A missing root only disables auto-scan; it is not a hard prerequisite.
```
ruamel.yaml
```
or another round-tripping YAML writer for the profile edit step.

Limitations

Registers pointers only; never downloads, copies, or renames files.
Per-document field set is fixed to the schema in
```
../../references/platform_template.yaml
```
— no ad-hoc keys.
Glob matching is filename-only; bad filenames in
```
documents.root_path
```
will under-bind and require manual selection.

Troubleshooting

documents.root_path
missing — auto-scan is skipped. Provide an absolute root path, enter individual document paths / URLs manually, or skip the fields you do not want to bind.
Multiple files match a single slot — the skill stops and prompts; pick or rename the file. Example: two
```
Jetson-Linux-Developer-Guide*.pdf
```
files → keep the active version, rename the stale one.
Profile comments lost after write — a non-round-tripping YAML writer was used; switch to
```
ruamel.yaml
```
and rerun against a fresh pristine copy.
Validation fails because a binding points outside
documents.root_path
—
```
documents.*
```
are relative paths only; move the file under the root and retry.

References

```
../../context/target-platform-contract.md
```
— target-platform contract; this skill consumes and mutates the active profile.
```
../../references/bsp-platforms-catalogue.md
```
— source of the Product Token column for the "Resolve the product token" step.
```
../../references/platform_template.yaml
```
— schema for the
```
documents:
```
block (source of truth for prompts and field list).

../jetson-init-target/SKILL.md

— sibling skill that authors target identity (

reference_devkit:

, optional

custom_carrier:

```
../jetson-init-image/SKILL.md
```
— sibling skill that authors
```
bsp_image:
```
.
```
../jetson-init-source/SKILL.md
```
— sibling skill: clones shared repos and handles
```
source.root_path
```
overrides.
```
../jetson-generate-kb/SKILL.md
```
— sibling skill: consumes the
```
documents:
```
block this skill writes.

jetson-link-docs

NPX Install

Tags

SKILL.md Content

jetson-link-docs

Overview

When to invoke

Procedure

Resolve the active target

Load the document-slot schema

Resolve
`documents.root_path`

Resolve the product token

Scan and auto-match

Match policy per field

Manual prompts for unmatched fields

Write the
`documents:`
block back to the profile

Confirm

Gotchas

Prerequisites

Limitations

Troubleshooting

References