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.

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

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

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