docs: tailored README + AGENTS.md signpost (layer-nvidia) (#286)

AGENTS.md

@@ -0,0 +1,60 @@
+# AGENTS.md — layer-nvidia
+
+Standalone candy repo for the `nvidia` layer — NVIDIA GPU runtime support. The
+candy lives in `charly.yml` at the repo root: multi-distro package arms, the
+`LD_LIBRARY_PATH` environment, the Vulkan ICD wiring and signature-verification
+`plan:` steps, and the embedded `skill:` entity projected into the marketplace
+corpus as `/charly-distros:nvidia`.
+
+Canonical files:
+
+- `charly.yml` — the `nvidia:` candy entity and the `nvidia-skill:` skill entity.
+- `CHANGELOG/` — per-CalVer release history; read it before changing baked checks.
+- `.github/workflows/deploy.yml` — the manifest gate.
+- `.github/workflows/tag-on-merge.yml` — CalVer tag + `CHANGELOG/` on merge.
+- `README.md` — user overview only; never agent guidance.
+
+## Load these skills first (R0)
+
+- `/charly-distros:nvidia` — the owning skill. GPU runtime, CDI device
+  generation, the distro package arms, and verification. Load before editing or
+  troubleshooting the layer.
+- `/charly-image:layer` — the candy authoring reference (`charly.yml` schema,
+  `plan:` step verbs incl. `check:`, per-distro `distro:` arms, package/repo
+  sections, and service declarations). Load before editing any entity field or
+  plan step.
+
+## Build / validate / test
+
+- `charly box validate` at the repo root — the same structural gate CI runs: the
+  manifest must parse and validate at the pinned charly. The CI pin lives in
+  `.github/workflows/deploy.yml`; keep the `version:` schema stamp within the
+  pinned charly's supported range (do not migrate the stamp past the pin).
+- `.github/workflows/deploy.yml` — builds the pinned charly from a CI-time
+  checkout and runs `charly box validate`. This is the merge gate.
+- The candy's `plan:` `check:` steps are the functional evidence; they must stay
+  valid on every distro arm they run on. Where a check only applies to one
+  distro family (e.g. a Fedora-only DNF path), scope it in the command itself —
+  the check runner does not honour runner-level `exclude-distro` fields.
+
+## Modify this repo
+
+- Edit the `nvidia:` candy entity AND the `nvidia-skill:` skill entity in
+  `charly.yml` together. The skill is the projected usage source, so a package,
+  distro-arm, or behaviour change that is not mirrored in the skill leaves the
+  corpus stale.
+- Package changes go in the top-level `package:` or a `distro:` arm; repository
+  and signing policy go in the matching `distro:` arm's `repo:` block.
+- New behaviour claims belong in the `plan:` as an observable `check:` step, and
+  in the skill body. Keep the Fedora signature-verification check intact.
+
+## Landing
+
+- PR-only. Every change lands through a pull request; the org-required
+  `charly/pr-validator` validates the diff and body and arms native auto-merge
+  on PASS. Direct pushes to `main` are blocked.
+- History lives in `CHANGELOG/` (written by `tag-on-merge` at merge time); the
+  PR body IS the changelog.
+- The authoritative rulebook is the umbrella `AGENTS.md` in
+  `opencharly/opencharly` and `charly/AGENTS.md` in the charly repo. Do not
+  restate its rules here.

README.md

@@ -1,19 +1,75 @@
-# layer-nvidia
+# nvidia
 
-The `layer-nvidia` candy of the [opencharly/charly](https://github.com/opencharly/charly)
-candy library, as a standalone repo (the candy de-submodule cutover).
+NVIDIA GPU runtime layer for OpenCharly images.
 
-The candy manifest lives at the repo root (`charly.yml`); the charly resolver
-fetches this repo at the pinned tag (`@github.com/opencharly/layer-nvidia:v<tag>`).
+The `nvidia` candy prepares an image to use an NVIDIA GPU. It installs
+`nvidia-container-toolkit` — the `nvidia-ctk` CLI that generates CDI device
+specs — together with the per-distro driver libraries, exports
+`LD_LIBRARY_PATH=/usr/lib64` so the driver libraries resolve, and prepares
+`/etc/vulkan/icd.d` to hold the NVIDIA Vulkan ICD symlinks. It is the GPU
+runtime base that GPU-accelerated boxes compose; the CUDA toolchain is a
+separate `cuda` layer.
 
-## Pins
+## What it provides
 
-- `charly` — the charly checkout this candy's manifest is validated against,
-  cloned into `.ci/charly` at CI time at the pinned tag (no committed
-  submodule).
+| Property | Value |
+|---|---|
+| Layer / candy | `nvidia` |
+| Package | `nvidia-container-toolkit` (all distros) |
+| Binary | `/usr/bin/nvidia-ctk` |
+| Environment | `LD_LIBRARY_PATH=/usr/lib64` |
+| Directory | `/etc/vulkan/icd.d` (NVIDIA Vulkan ICD / layer symlinks) |
+| Service / port | none |
 
-## Gate
+Per-distro driver packages:
 
-`.github/workflows/deploy.yml` builds charly from the pinned checkout and runs
-`charly box validate` on this repo's `charly.yml` — the manifest must parse and
-validate at the pinned charly (the project schema version tracks the pin).
+- `arch` / `omarchy` — `nvidia-utils`
+- `fedora` — `libva-nvidia-driver` (from the negativo17 `fedora-multimedia`
+  repo) plus NVIDIA's own `nvidia-container-toolkit` repo, with package
+  signature verification enforced (`gpgcheck=1`, overriding NVIDIA's shipped
+  `gpgcheck=0`).
+
+## How to use it
+
+Compose the layer by pinning this repo in a box's `candy:` list:
+
+```yaml
+my-box:
+  candy:
+    base: fedora                       # or cachyos / omarchy for the Arch driver layout
+    candy:
+      - '@github.com/opencharly/layer-nvidia:v2026.245.1541'
+```
+
+Once the image is built and the GPU is attached by the runtime:
+
+```bash
+nvidia-smi                 # GPU information
+nvidia-ctk --version       # CDI toolkit
+```
+
+The layer bakes every artifact (package, `nvidia-ctk` binary, exported path,
+Vulkan ICD directory) into the image, so it is verifiable without a physical
+GPU. A GPU-accelerated box pairs it with `cuda` (CUDA toolkit, cuDNN) — for
+example `python-ml`, `jupyter`, `ollama`, and `comfyui`.
+
+## Layout
+
+- `charly.yml` — the candy manifest: the multi-distro package arms, the
+  `LD_LIBRARY_PATH` environment, the Vulkan ICD wiring `plan:`, the `plan:`
+  checks, and the embedded `skill:` entity.
+- `CHANGELOG/` — per-CalVer release notes.
+- `.github/workflows/deploy.yml` — builds the pinned charly and runs
+  `charly box validate` on the manifest (the merge gate).
+- `.github/workflows/tag-on-merge.yml` — CalVer tag + `CHANGELOG/` on merge.
+- `README.md` — this user overview.
+
+## Related
+
+- Owning skill: `/charly-distros:nvidia`
+- CUDA toolkit: `/charly-distros:cuda`
+- Derived GPU boxes: `/charly-languages:python-ml`, `/charly-jupyter:jupyter`,
+  `/charly-ollama:ollama`, `/charly-comfyui:comfyui`
+- Arch/CachyOS GPU base sibling: `cachyos.nvidia` in `opencharly/distro-cachyos`
+- [`opencharly/charly`](https://github.com/opencharly/charly) — the charly CLI and image builder
+- [`opencharly/opencharly`](https://github.com/opencharly/opencharly) — the umbrella