Jetson Link Docs

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.