Quickstart

Before you begin#

Each KERNARY project starts with a defined engineering baseline: a Git repository, approved vendor BSP sources, an exact hardware description and measurable acceptance criteria. Together, these inputs establish the permitted source material, target configuration and validation requirements.

• A Linux-capable reference or custom board and its exact revision
• Vendor BSP source, licence permission and toolchain inputs
• Schematic or structured hardware description with access controls
• A recovery interface such as JTAG/SWD or external programmer
• Testable product requirements and a human release owner

Step 1: Create a project#

Initialise a project beside the source repository. The target value identifies a target profile; it does not by itself claim that a board is supported.

# Illustrative command — no public CLI is available yet
kernary project init orbit-controller \
  --target imx93-orbit-revb \
  --bsp ./vendor/nxp-bsp \
  --repo .

cd orbit-controller

apiVersion: kernary.dev/v1alpha1
kind: EmbeddedProject
metadata:
  name: orbit-controller
spec:
  target:
    family: nxp-imx93
    boardRevision: rev-b
  system:
    buildSystem: yocto
    bootloader: u-boot
    kernel: linux-6.6
  requirements:
    - can1 at 500-kbit
    - ethernet dhcp
    - boot under 5s
    - signed a-b updates
  releasePolicy:
    humanApprovalRequired: true

Step 2: Plan the system#

Kernary Engineer resolves the target context, decomposes the work and attaches acceptance evidence to each stage. Planning may use AI reasoning; completion must be proved by deterministic tools.

kernary engineer plan \
  --project kernary.yaml \
  --acceptance "can1-up,boot<5s,hil-pass"

# Inspect the proposed stages before execution
kernary plan show plan://orbit-controller/12

1. 01
   Resolve

   Pin the SoC, board revision, BSP, kernel, layers and provenance.

2. 02
   Decompose

   Create boot, kernel, device-tree, build and test work units.

3. 03
   Gate

   Mark source edits, hardware actions, signing and release approval boundaries.

Step 3: Build and simulate#

Kernary Build restores a target-aware cell with pinned sources, toolchains and caches. The build system remains authoritative for the binary output.

BUILD_ID=$(kernary build run \
  --plan plan://orbit-controller/12 \
  --profile imx93-orbit \
  --output id)

kernary test run \
  --build "$BUILD_ID" \
  --target qemu \
  --suite smoke

Step 4: Validate on hardware#

Reserve a compatible lab target only after simulation and policy checks pass. The Board gateway, not the model, owns power, flashing, debug and instrument control.

RESERVATION=$(kernary board reserve \
  --target imx93-orbit-revb \
  --duration 45m \
  --output uri)

kernary board flash "$RESERVATION" \
  --build "$BUILD_ID" \
  --strategy recovery

kernary test run \
  --target "$RESERVATION" \
  --suite can-and-boot \
  --capture serial,power,can

Step 5: Review and release#

Review the exact source revision, build manifest, SBOM, board revision, measurements and repair history. A release agent can assemble the proposal but cannot bypass signing policy or the human gate.

kernary evidence show \
  --project orbit-controller \
  --latest \
  --include diff,build,hil,sbom

kernary release propose \
  --build "$BUILD_ID" \
  --policy production-canary

# A human release owner completes approval outside the agent cell.