Promote BSP Image

Purpose

Stage every Customize-* and Build output into

bsp_image

so it is ready for

/jetson-flash-image

. This is the promote leg of Deploy — it copies files, never flashes and never builds.

Prerequisites

Active target-platform profile with both
```
source:
```
and
```
bsp_image:
```
resolved (run
```
/jetson-init-source
```
and
```
/jetson-init-image
```
first).
```
<source.root_path>/Linux_for_Tegra/
```
initialized as a git repo (overlay tracker) with a clean working tree.

<bsp_image.root_path>/Linux_for_Tegra/

extracted from a BSP tarball +

apply_binaries.sh

already run.

```
git
```
,
```
yq
```
,
```
cmp
```
, and
```
sudo
```
(for
```
rootfs/*
```
destinations) on the host.

<source.root_path>/.build-manifest.yaml

.build-state.yaml

from

/jetson-build-source

(required when kernel-side repos have customize-* commits).

Overview

This is the promote leg of Deploy — see

../../context/bsp-customization-workflow.md

for the pipeline view. The two channels this skill walks are:

Channel	Source	Carrier	Owner
Overlay tracker	`<source.root_path>/Linux_for_Tegra/` (git repo at HEAD)	Customize-* outputs that don't require a build (e.g. `nvfancontrol.conf` , `nvpmodel.conf` , BPMP DTB hand-edits)	Customize `customize-*` skills commit here
Build manifest	`<source.root_path>/.build-manifest.yaml`	Rebuilt kernel `Image` , in-tree `.ko` , OOT `.ko` , NVIDIA DTBs	Build `jetson-build-source` writes here

The skill computes the union of files to copy and writes each into

<bsp_image.root_path>/Linux_for_Tegra/

with diff-aware skip-if-identical logic. When the copy pass touches the kernel

Image

or anything under

rootfs/lib/modules/

, it also rebuilds the initramfs via NVIDIA's

tools/l4t_update_initrd.sh

so the freshly promoted kernel + modules ship in the initrd the bootloader actually loads. After it returns,

bsp_image

carries every Customize and Build output. The skill does not flash and does not modify the workspace.

When to invoke

First leg of the typical Deploy chain

jetson-promote-image → jetson-flash-image → jetson-validate-image

Standalone, when the user wants
```
bsp_image
```
updated but isn't ready to flash yet (e.g. to inspect resolved files, run an out-of-band build that reads bsp_image, or hand bsp_image to a separate flashing host).

Procedure

Resolve active target + paths

Resolve the active profile per the contract in

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

Refuse and route in these cases:

Condition	Refuse with
No active profile, or `active: NA`	Route to `/jetson-set-target` or `/jetson-init-target` .
Profile lacks `bsp_image:`	Route to `/jetson-init-image` .
`<bsp_image.root_path>/Linux_for_Tegra/` missing	Route to `/jetson-init-image` .
`<source.root_path>/Linux_for_Tegra/` missing or not a git repo	Route to `/jetson-init-source` .

Resolve paths:

```
<workspace>
```
= parent of the active profile's
```
target-platform/
```
directory (discovered at load time).

<bsp_image.root_path>

from

bsp_image.root_path:

if present, else

<workspace>/Image

<source.root_path>

from

source.root_path:

if present, else

<workspace>/Source

Bind shell variables for the rest of the procedure:

bash

LFT_SRC="<source.root_path>/Linux_for_Tegra"   # overlay tracker
LFT_DST="<bsp_image.root_path>/Linux_for_Tegra"
MANIFEST="<source.root_path>/.build-manifest.yaml"   # build outputs

Validate the two channels

The skill needs at least one channel populated. Refuse if the overlay tracker has uncommitted changes (

status --porcelain

non-empty), if

$MANIFEST

exists but doesn't parse as YAML, or if both channels are empty. Records

OVERLAY_HAS_COMMITS

OVERLAY_HEAD

and

MANIFEST_PRESENT

for downstream steps.

See

references/copy-pass-snippets.md

for the shell snippet and refuse messages.

Verify build-source freshness

Refuse if

.build-state.yaml

shows any kernel-side repo in

Source/bsp_sources/

dirty since the last

/jetson-build-source

— otherwise the copy pass would silently ship stale artifacts. Detection rules + shell snippet in

references/build-source-freshness-gate.md

. Records

BUILD_FRESH=1

Pre-promote collision check (overlay only)

When the overlay tracks a remote, refuse if upstream has commits not yet pulled. Skip gracefully when no remote is configured (the default

git init

empty tracker from

jetson-init-source

). Manifest channel has no git remote concept — this check is overlay-only. Records

COLLISION_CHECK

for the Summary.

See

references/copy-pass-snippets.md

for the shell snippet.

Enumerate sources (both channels)

Channel A — overlay:

git ls-files

against

$LFT_SRC

is the source of truth (transparent to symlink mounts when

source.repos.Linux_for_Tegra

was overridden, excludes untracked /

.gitignore

d files). Each entry maps

src = $LFT_SRC/<rel>

→

dst = $LFT_DST/<rel>

Channel B — manifest: parse

artifacts[].{src,dst}

from

$MANIFEST

. Refuse if any

src

is missing on disk (build was interrupted, or manifest stale — re-run

/jetson-build-source

). The manifest schema is written by

jetson-build-source

v0.2.0.

See

references/copy-pass-snippets.md

for both shell snippets and the manifest YAML schema.

Diff-aware copy into bsp_image

Iterate the union of overlay files and manifest entries. For each

dst

: if byte-identical, skip; otherwise

cp -p

(with

sudo

for

rootfs/*

destinations, where the sample rootfs was extracted as root). Tag

INITRD_DIRTY=1

on any

rootfs/lib/modules/*

kernel/Image

write — the "Refresh initramfs" step gates on this flag. Counts /

FIRST

LAST

are recorded for the Summary.

Fail-fast: if any

cp

fails, surface the failed path and stop.

bsp_image

may be left partially updated — re-running after fixing the cause resumes via the diff-aware skip. Channel order is overlay first, then manifest: on a

dst

collision the manifest wins (freshly built artifact beats the older overlay copy).

See

references/copy-pass-snippets.md

for the

copy_one()

function and the two driving loops.

Mirror kernel Image into rootfs (when kernel changed)

The kernel

Image

lives in two paths inside

bsp_image

<LFT_DST>/kernel/Image

(read by the flash tool) and

<LFT_DST>/rootfs/boot/Image

(the rootfs-side copy, visible as

/boot/Image

from inside the rootfs chroot the refresh tool will run in). The build manifest only carries the

kernel/Image

dst, so this step mirrors

kernel/Image

→

rootfs/boot/Image

(diff-aware, no-op when already in sync) so the chrooted refresh tool resolves the kernel against the freshly promoted binary, not the stale rootfs copy. The mirror also sets

INITRD_DIRTY=1

so a kernel-only promote (no

rootfs/lib/modules/*

writes) still triggers the refresh.

See

references/kernel-image-and-initramfs.md

for the shell snippet, the failure mode this prevents, and the

INITRD_DIRTY

corner case.

Refresh initramfs (when kernel or modules changed)

Run

tools/l4t_update_initrd.sh

from

<LFT_DST>/

whenever

INITRD_DIRTY=1

(set by the diff-aware copy or the mirror step above). The tool chroots into

rootfs/

, runs NVIDIA's

nv-update-initrd

, and writes both

<LFT_DST>/bootloader/l4t_initrd.img

(used by the flash tool) and

<LFT_DST>/rootfs/boot/initrd

(

/boot/initrd

on the DUT). Idempotent; ~30 s. Skip when

INITRD_DIRTY=0

(overlay-only edits). DUT-side workarounds (

update-initramfs -u

+ manual

cp

) are out of scope — fix the gap here so flash ships a coherent image.

See

references/kernel-image-and-initramfs.md

for the shell snippet, refuse paths, the "module shadowing" and "vermagic skew" failure modes the rebuild closes, and why

bootloader/initrd

(a different file) is left alone.

Summary

Report:

Overlay scope:
```
overlay HEAD ($OVERLAY_HEAD)
```
or "(empty)".

Manifest scope:

mode=<...>, bsp_version=<...>, rebuilt_at=<...>, N artifacts

or "(absent)".

Collision check:
```
$COLLISION_CHECK
```
.

Counts:

overlay:

$COPIED_OVERLAY copied, $IDENTICAL_OVERLAY identical

manifest:

$COPIED_MANIFEST copied, $IDENTICAL_MANIFEST identical

Kernel Image mirror:

$KIMG_MIRRORED

and initramfs:

$INITRD_STATUS

(

copied …

rebuilt

when triggered by

kernel/Image

rootfs/lib/modules/*

writes;

skipped …

otherwise).

First / last paths copied (omit if both
```
COPIED
```
totals are 0).
Resolved
```
<source.root_path>
```
,
```
<bsp_image.root_path>
```
.
Next step:
```
/jetson-flash-image
```
(or
```
/jetson-validate-image
```
if the user only wanted bsp_image refreshed for inspection / static validation).

Limitations

Two channels, one destination.
```
bsp_image/Linux_for_Tegra/
```
is written by both passes. Overlay carries customize-* outputs (overlay-only edits like nvfancontrol.conf); manifest carries rebuilt binaries (kernel/OOT/DT). The two are intentionally disjoint by construction: build outputs don't go into the overlay, and customize-* edits to non-build files don't enter the manifest.
Build manifest is the trace-to-dirty contract. Anything in the manifest came from a dirty source repo (per
```
jetson-build-source
```
's "Write the build manifest" step trace policy). Promoting the manifest is therefore safe: every entry is a customization-bearing artifact, not toolchain-divergence noise. The skill does not re-derive the trace — it trusts the manifest.
Manifest entries can outlive their build outputs. If the user wipes
```
Source/.build/
```
or
```
bsp_sources/
```
's build artifacts between
```
jetson-build-source
```
and
```
jetson-promote-image
```
, the manifest will reference missing files. The "Enumerate sources (both channels)" step refuses in that case and points the user at
```
/jetson-build-source
```
to rebuild.
Manifest absence is fine when only overlay edits happened. A purely overlay-side customization (e.g.
```
customize-fan
```
) produces no build outputs and writes no manifest — the "Enumerate sources (both channels)" step is a no-op, the "Diff-aware copy into bsp_image" step promotes only overlay files. The skill prints "manifest: (absent)" in the summary and continues.
Diff-aware, idempotent. Re-running with no overlay commits or manifest changes since the last promote is a no-op (all files identical). Use this to confirm bsp_image is in sync without side effects.
Symlink-mount transparency. When
```
source.repos.Linux_for_Tegra
```
was overridden in
```
jetson-init-source
```
, the canonical mount is a symlink into
```
<source.root_path>/.repos/Linux_for_Tegra/<subdir>
```
.
```
git -C
```
,
```
cp -p
```
, and
```
cmp -s
```
all follow it transparently — no special handling needed at this layer. Manifest
```
src
```
paths are absolute, so symlinks under
```
bsp_sources/
```
don't matter for the manifest channel.
sudo
is scoped to
rootfs/
destinations. Files under
```
rootfs/
```
were extracted with
```
sudo tar xpjf
```
by
```
jetson-init-image
```
, so they carry root ownership and special mode bits the flashing toolchain reads back.
```
sudo cp -p
```
preserves them. Everything else (
```
bootloader/
```
,
```
kernel/
```
,
```
kernel/dtb/
```
,
```
tools/
```
, etc.) is user-owned and does not need
```
sudo
```
. This applies to both channels.
Channel-overlap precedence. If the same
```
dst
```
appears in both overlay and manifest, manifest wins (later in the "Diff-aware copy into bsp_image" step's loop). This is the desired semantic — manifest entries are freshly built, overlay entries may be older state. Hand-editing binary files into the overlay is discouraged (Build's job is to rebuild them); the precedence rule makes such mistakes recoverable.
bsp_image
is read-only outside Deploy. This skill is the only writer in the normal flow (matches the workflow invariant). Hand-edits to
```
<bsp_image.root_path>/Linux_for_Tegra/
```
outside Deploy will be silently overwritten on the next promote run if the same path exists in either channel; conversely they will not be reverted if no entry shadows them. Both behaviors are wrong for the diff trail — never hand-edit upstream.
Scope is overlay HEAD only (channel A). Named tags / manifests / commit ranges are deferred (see below). To promote a historical state,
```
git -C $LFT_SRC checkout <ref>
```
first, then re-run. The manifest channel has no ranged scope — it reflects whatever
```
jetson-build-source
```
's last run produced.
No automatic rollback on partial failure. If
```
cp
```
fails partway through,
```
bsp_image
```
is left in an intermediate state. Fix the underlying cause (usually permissions / disk full) and re-run — the "Diff-aware copy into bsp_image" step will resume by skipping already-promoted files.
Kernel
Image
mirror + initramfs refresh. Gated on copy-pass writes to
```
kernel/Image
```
or
```
rootfs/lib/modules/*
```
; the mirror feeds the refresh's chroot. Both are diff-aware and skipped on pure-overlay edits.
```
tools/l4t_update_initrd.sh
```
must exist in
```
bsp_image
```
(ships with
```
apply_binaries.sh
```
); a missing tool refuses and routes to
```
/jetson-init-image
```
. See
```
references/kernel-image-and-initramfs.md
```
for the full contract and failure modes.

Troubleshooting

Error	Cause	Solution
`Overlay has uncommitted changes at <LFT_SRC>`	Customize-* edits not committed before promote	Run `git -C $LFT_SRC commit` (or stash), then re-run.
`origin has N unpulled commits on <upstream>`	Remote overlay diverged from local	`git -C $LFT_SRC pull` , resolve conflicts, then re-run.
`Both overlay and manifest are empty — nothing to promote`	No Customize-* commits and no Build manifest	Run a customize-* skill or `/jetson-build-source` first.
`Kernel-side source(s) changed since last /jetson-build-source`	Freshness gate detected unprocessed customize-* edits under `Source/bsp_sources/`	Commit pending edits, run `/jetson-build-source` , re-run promote.
`Manifest entry references missing build output: <src>`	`bsp_sources/` build outputs wiped or stale manifest	Re-run `/jetson-build-source` to regenerate.
`Build manifest at <MANIFEST> is not valid YAML`	Manifest hand-edited or partially written	Re-run `/jetson-build-source` to rewrite the manifest.
`cp: permission denied` under `rootfs/`	Missing `sudo` privilege on the host	Run on an account that can `sudo cp` ; re-run resumes via diff-aware copy.
Profile lacks `bsp_image:` / `source:`	Workspace not bootstrapped	Run `/jetson-init-image` and/or `/jetson-init-source` .
`tool not found at <LFT_DST>/tools/l4t_update_initrd.sh`	`tools/` was pruned, or bsp_image extracted from a non-NVIDIA tarball	Re-run `/jetson-init-image` to repopulate.
`l4t_update_initrd.sh exited non-zero`	Insufficient sudo, broken rootfs (missing `lib/modules/<ver>/modules.dep` ), or out-of-space `/tmp`	Run `depmod -a -b <LFT_DST>/rootfs <ver>` against the rootfs first; verify `/tmp` headroom; rerun promote.
DUT boots with stale kernel / modules after promote, modules fail to load with `disagrees about version of symbol …` , or initramfs ships pre-customize modules even after the refresh ran	The mirror / refresh gate didn't fire (manual hand-edit under `<LFT_DST>` outside the skill), or `rootfs/boot/Image` drifted from `kernel/Image` so the chrooted refresh built against the stale kernel	Force the gate by `sudo touch <LFT_DST>/kernel/Image` + re-run promote, or run the two steps manually: `sudo cp -p <LFT_DST>/kernel/Image <LFT_DST>/rootfs/boot/Image && cd <LFT_DST> && sudo ./tools/l4t_update_initrd.sh` . Then re-flash. See `references/kernel-image-and-initramfs.md` .

Spec status

Locked in for v0.2.0:

Two-channel scope — overlay HEAD + build manifest, both diff-aware, both copying into
```
<bsp_image.root_path>/Linux_for_Tegra/
```
.
Channel-overlap precedence — manifest wins on
```
dst
```
collision.
Source-repo collision check — overlay only; manifest has no remote concept and source repos under
```
bsp_sources/
```
are not fetched (their state was sealed when
```
jetson-build-source
```
wrote the manifest).
Atomicity — fail-fast, no rollback. Diff-aware copy makes resume natural.
Audit trail — stdout-only at promote time. The overlay tracker's git log is the canonical record for channel A; the manifest itself is the canonical record for channel B.
Kernel Image mirror + initramfs refresh. Locked in as a paired step. The mirror copies
```
kernel/Image
```
→
```
rootfs/boot/Image
```
whenever the copy pass touched
```
kernel/Image
```
; the refresh runs
```
tools/l4t_update_initrd.sh
```
whenever
```
kernel/Image
```
or any
```
rootfs/lib/modules/*
```
was promoted, rebuilding both
```
bootloader/l4t_initrd.img
```
and
```
rootfs/boot/initrd
```
. Inseparable because the refresh chroots into
```
rootfs/
```
and resolves the kernel through
```
/boot/Image
```
— the mirror has to run first. Closes both module-shadowing and vermagic-skew failure modes; both diff-aware, both skipped on overlay-only edits. Full contract in
```
references/kernel-image-and-initramfs.md
```
.

Still deferred:

Named-tag / commit-range scope for the overlay channel. Revisit when a "promote release X" use case appears.
Manifest history. Currently only the last build's manifest exists; if a user wants to roll bsp_image back to a previous build state, they'd need to re-run
```
/jetson-build-source
```
at the prior commit. A manifest archive (saved per-build-mode or per-commit) would enable rollback without rebuild.
Sidecar manifest in
bsp_image
. Revisit when promotion happens on a host that does not have access to the overlay tracker repo (or the workspace's manifest file).

References

```
references/kernel-image-and-initramfs.md
```
— full contract for the kernel
```
Image
```
mirror +
```
l4t_update_initrd.sh
```
refresh: shell snippets, failure modes, tool semantics, output filenames.

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

— target-platform contract.

```
../../context/bsp-customization-workflow.md
```
— workspace edit protocol (this skill is the promote leg of Deploy).
```
../jetson-init-source/SKILL.md
```
— Setup; materializes the overlay tracker this skill reads (channel A) and authors
```
source.toolchain
```
.
```
../jetson-build-source/SKILL.md
```
— Build builder; writes the
```
.build-manifest.yaml
```
this skill reads (channel B).
```
../jetson-flash-image/SKILL.md
```
— next leg; flashes the just-promoted bsp_image to the DUT.
```
../jetson-validate-image/SKILL.md
```
— final leg; static + on-target validation.

jetson-promote-image

NPX Install

Tags

SKILL.md Content

Promote BSP Image

Purpose

Prerequisites

Overview

When to invoke

Procedure

Resolve active target + paths

Validate the two channels

Verify build-source freshness

Pre-promote collision check (overlay only)

Enumerate sources (both channels)

Diff-aware copy into bsp_image

Mirror kernel Image into rootfs (when kernel changed)

Refresh initramfs (when kernel or modules changed)

Summary

Limitations

Troubleshooting

Spec status

References