docs(ai): Update docs with new azldev render feature

Author: dmcilvaney

.github/copilot-instructions.md

@@ -25,10 +25,23 @@ azldev.toml                          # Root config — includes distro/ and base
 │   ├── distro.toml                  # Includes all *.distro.toml
 │   ├── fedora.distro.toml           # Fedora: dist-git URIs, lookaside, version branches
 │   └── mock/                        # Mock build environment configs
+├── specs/                           # Rendered specs (generated by `azldev comp render`)
+│   └── <first-char>/<name>/         # Per-component: spec, patches, scripts (no source tarballs)
 └── external/schemas/
     └── azldev.schema.json           # Authoritative schema for all TOML config files
 ```
 
+## Rendered Specs (`specs/`)
+
+The `specs/` directory  (as specified by `rendered-specs-dir` config) contains rendered spec files generated by `azldev comp render`. These are the final specs with all overlays applied — ready for check-in. After adding or modifying components/overlays, re-render:
+
+```bash
+azldev comp render -p <name>   # Single component
+azldev comp render -a          # All components (slow)
+```
+
+To inspect what a component's spec looks like after overlays, read `specs/<first-char>/<name>/<name>.spec` directly — no need to run `prep-sources` just to view the result. Use `prep-sources` when you need the full source tree (tarballs) or want to diff pre/post overlay output for debugging.
+
 ## Key Concepts
 
 **Components** = unit of packaging (→ one or more RPMs). Spec sources: upstream (default, from Fedora dist-git), local, or pinned upstream. See [`comp-toml.instructions.md`](instructions/comp-toml.instructions.md#spec-source-types) for syntax.
@@ -52,13 +65,15 @@ Run all commands from the repo root (where `azldev.toml` lives). If the terminal
 | Add a component | `azldev comp add` |
 | Build a component | `azldev comp build -p <name> -q` |
 | Build chain (auto-publish to local repo) | `azldev comp build --local-repo-with-publish ./base/out -p <a> -p <b> -q` |
+| Render all specs for check-in | `azldev comp render -a` |
+| Render a single component | `azldev comp render -p <name>` |
 | Prepare sources (apply overlays) | `azldev comp prep-sources -p <name> --force -o <dir> -q` |
 | Prepare sources (skip overlays) | `azldev comp prep-sources -p <name> --skip-overlays --force -o <dir> -q` |
 | Build, keep env on failure | `azldev comp build -p <name> --preserve-buildenv on-failure -q` |
 | List images | `azldev image list` |
 | Build an image | `azldev image build` |
 | Boot an image in QEMU | `azldev image boot` |
-| Dump resolved config | `azldev config dump -q -O json` |
+| Dump resolved config | `azldev config dump -q -f json` |
 | Advanced commands (like mock shell) | `azldev adv --help` (hidden from normal help) |
 
 ## Repository Hygiene Rules

.github/instructions/rendered-specs.instructions.md

@@ -0,0 +1,32 @@
+---
+applyTo: "specs/**/*"
+description: ALWAYS refer to this when working with rendered spec files (`*.spec`) in the `specs/` directory.
+---
+
+# Rendered Spec Files (`specs/*.spec`)
+
+## What are rendered specs?
+
+Rendered specs are generated by the `azldev comp render` command based on the component definitions and overlays. They are output to the `specs/` directory  (as specified by `rendered-specs-dir` config) and should not be edited directly.
+
+They are meant to be consumed by downstream processes (e.g., build pipelines) and are the source of truth for all subsequent steps. Any changes to the spec should be made via the component definition and overlays, not by editing the rendered spec.
+
+## Changing a rendered spec
+
+To change a rendered spec, modify the component's `.comp.toml` and/or its overlays. Then re-run the render command to regenerate the spec:
+
+```bash
+# VERY SLOW - Re-render all specs, removes any stale specs that are no longer defined in the components
+azldev comp render -a --clean-stale -O json
+```
+
+```bash
+# Small set, will NOT remove stale specs, faster for iterative development
+azldev comp render -p <component-1> -p <component-2> -O json
+```
+
+```bash
+# Custom output directory, useful for debugging. When not using the automatically configured spec directory, --force is
+# required to delete and re-create the output folders if they already exist.
+azldev comp render -p <component> -O json -o ./base/build/work/scratch/rendered-specs --force
+```

.github/instructions/spec.instructions.md

@@ -1,5 +1,6 @@
 ---
-applyTo: "**/*.spec"
+applyTo: "base/**/*.spec"
+description: Read this when working with spec files (`*.spec`) that are hand-maintained in the Azure Linux repo (not rendered).
 ---
 
 # RPM Spec Files (`*.spec`)

.github/prompts/azl-add-component.prompt.md

@@ -19,6 +19,6 @@ Follow the workflow in the [skill-add-component skill](../skills/skill-add-compo
    - Needs overlays or customizations → create `${input:component_name}/${input:component_name}.comp.toml`
    - Needs extensive changes overlays can't handle → forked local spec (**last resort**, requires explicit user sign-off)
 6. Add overlays with meaningful `description` fields explaining *why* each change is needed
-7. Validate: `azldev comp prep-sources -p ${input:component_name} --force -o base/build/work/scratch/${input:component_name}-post -q` (with overlays) and diff against the skip-overlays output
+7. Render and verify: `azldev comp render -p ${input:component_name}` and inspect `specs/` (as specified by `rendered-specs-dir` config) output. For deeper debugging, diff pre/post overlay output with `prep-sources`.
 8. Build: `azldev comp build -p ${input:component_name} -q`
 9. Smoke-test the built RPMs in a mock chroot

.github/prompts/azl-debug-component.prompt.md

@@ -27,15 +27,21 @@ First, determine the error category:
    - Follow the `skill-mock` workflow: install RPMs in a mock chroot, verify contents, check dependencies
    - Common causes: missing Requires, wrong file paths, permission issues
 
-**When in doubt**, start with a `prep-sources` pre/post diff to determine if the issue is overlay-related:
+**When in doubt**, start with a render to determine if the issue is overlay-related:
+
+```bash
+azldev comp render -p ${input:component_name}
+```
+
+If `render` fails, the issue is overlay-related (category 1). For deeper debugging, diff pre/post overlay output:
 
 ```bash
 azldev comp prep-sources -p ${input:component_name} --skip-overlays -o base/build/work/scratch/${input:component_name}-pre --force
 azldev comp prep-sources -p ${input:component_name} -o base/build/work/scratch/${input:component_name}-post --force
 diff -r base/build/work/scratch/${input:component_name}-pre base/build/work/scratch/${input:component_name}-post
 ```
 
-If `prep-sources` itself fails, the issue is overlay-related (category 1). If it succeeds but `comp build` fails, it's a build issue (category 2).
+If both render and `prep-sources` succeed but `comp build` fails, it's a build issue (category 2).
 
 ## Fix
 

.github/prompts/azl-update-component.prompt.md

@@ -18,6 +18,10 @@ Use structural patterns from [comp-toml.instructions.md](../instructions/comp-to
    - `config` — build config changes (`build.defines`, `build.without`)
 3. **Apply changes** to the `.comp.toml` file
 4. **Verify overlays still apply:**
+   ```bash
+   azldev comp render -p ${input:component_name}
+   ```
+   Inspect `specs/`  (as specified by `rendered-specs-dir` config) output. For deeper debugging, diff pre/post overlay output:
    ```bash
    azldev comp prep-sources -p ${input:component_name} --skip-overlays -o base/build/work/scratch/${input:component_name}-pre --force
    azldev comp prep-sources -p ${input:component_name} -o base/build/work/scratch/${input:component_name}-post --force

.github/skills/skill-add-component/SKILL.md

@@ -69,6 +69,16 @@ Overlays are vastly preferable to maintaining a forked spec, they get automatic
 
 ## Validate
 
+After adding overlays or customizations, render the spec to verify:
+
+```bash
+azldev comp render -p <name>
+# Inspect the result
+cat specs/<first-char>/<name>/<name>.spec
+```
+
+For deeper debugging (diffing pre/post overlay output with full sources):
+
 > Use a temp dir for `prep-sources` output. Use `--force` to overwrite an existing output dir.
 
 `prep-sources -o <dir>` writes to a user-specified directory (NOT `base/out/` — that's for `comp build` output).
@@ -77,9 +87,11 @@ Overlays are vastly preferable to maintaining a forked spec, they get automatic
 azldev comp prep-sources -p <name> --skip-overlays --force -o base/build/work/scratch/<name>-pre -q
 azldev comp prep-sources -p <name> --force -o base/build/work/scratch/<name>-post -q
 diff -r base/build/work/scratch/<name>-pre base/build/work/scratch/<name>-post
+```
 
+```bash
 # Test build (RPMs land in base/out/ per project.toml output-dir)
 azldev comp build -p <name> -q
 ```
 
-For testing the built RPMs, see the [`skill-mock`](../skill-mock/SKILL.md) skill. New components always need a smoke-test. For the full inner loop cycle (investigate → modify → verify → build → test → inspect), see [`skill-build-component`](../skill-build-component/SKILL.md).
+For testing the built RPMs, see the [`skill-mock`](../skill-mock/SKILL.md) skill. New components always need a smoke-test. For the full inner loop cycle (investigate → modify → render → build → test → inspect), see [`skill-build-component`](../skill-build-component/SKILL.md).

.github/skills/skill-build-component/SKILL.md

@@ -49,26 +49,40 @@ Build foundational packages first (e.g., `azurelinux-rpm-config`), then dependen
 The standard cycle for investigating, modifying, and verifying components:
 
 ```
-investigate → modify → verify → build → test → inspect
+investigate → modify → render → build → test → inspect
 ```
 
 | Step | Command | What to check |
 |------|---------|---------------|
-| **Investigate** | `prep-sources --skip-overlays --force -o base/build/work/scratch/<name>-pre` | Upstream spec/sources as-is |
-| **Compare** | `prep-sources --force -o base/build/work/scratch/<name>-post` + `diff -r ...-pre ...-post` | Current overlay effect |
+| **Investigate** | Read `specs/<first-char>/<name>/<name>.spec` or `prep-sources --skip-overlays --force -o base/build/work/scratch/<name>-pre` | Upstream spec/sources as-is |
+| **Compare** | `prep-sources --force -o base/build/work/scratch/<name>-post` + `diff -r ...-pre ...-post` | Current overlay effect (deep debug) |
 | **Modify** | Edit `*.comp.toml` (overlays, defines, without) | — |
-| **Verify** | `prep-sources --force -o base/build/work/scratch/<name>-post` | Overlay applies cleanly |
+| **Verify** | `comp render -p <name>` + inspect `specs/<first-char>/<name>/` | Overlay applies cleanly (fast path) |
 | **Build** | `comp build -p <name>` | RPMs appear in `base/out/` |
 | **Test** | `adv mock shell --add-package base/out/<name>*.rpm` | Package installs, binary runs, basic functionality works |
 | **Inspect** | `comp build --preserve-buildenv always` + `adv mock shell` | BUILDROOT contents, file lists |
 
+> **Prefer `comp render` for quick verification.** It's faster than `prep-sources` since it skips downloading source tarballs. Use `prep-sources` when you need the full source tree or want to diff pre/post overlay output for debugging.
+
 > Use a temp dir for `prep-sources` output. Use `--force` to overwrite an existing output dir.
 
 > Package builds are often very long, so adjust command timeouts accordingly when using shell tools to run builds, or use background mode if available.
 
 ## Debugging Build Failures
 
-### 1. Diff sources pre/post overlay
+### 1. Render and inspect the spec
+
+The fastest way to verify overlays applied correctly:
+
+```bash
+azldev comp render -p <name>
+# Inspect the result
+cat specs/<first-char>/<name>/<name>.spec
+```
+
+### 2. Diff sources pre/post overlay (deep debug)
+
+When you need to understand exactly what upstream provides vs. what overlays change:
 
 ```bash
 azldev comp prep-sources -p <name> --skip-overlays --force -o base/build/work/scratch/<name>-pre -q
@@ -78,14 +92,14 @@ diff -r base/build/work/scratch/<name>-pre base/build/work/scratch/<name>-post
 
 This reveals whether overlays apply as intended or whether upstream changed.
 
-### 2. Preserve build environment on failure
+### 3. Preserve build environment on failure
 
 ```bash
 azldev comp build -p <name> --preserve-buildenv on-failure -q
 # Use `always` to inspect even successful builds
 ```
 
-### 3. Enter mock shell (deep debug)
+### 4. Enter mock shell (deep debug)
 
 For testing built RPMs or inspecting the chroot, see the [`skill-mock`](../skill-mock/SKILL.md) skill. Quick reference:
 

.github/skills/skill-fix-overlay/SKILL.md

@@ -7,7 +7,21 @@ description: "[Skill] Diagnose and fix overlay issues in Azure Linux components.
 
 ## Diagnosis Workflow
 
-### 1. Reproduce and inspect
+### 1. Render and inspect
+
+The fastest way to check if overlays apply cleanly:
+
+```bash
+azldev comp render -p <name>
+# Inspect the result
+cat specs/<first-char>/<name>/<name>.spec
+```
+
+If `render` fails, the error message will identify which overlay failed and why.
+
+### 2. Diff pre/post overlay (deep debug)
+
+When you need to understand exactly what upstream provides vs. what overlays change:
 
 > Use a temp dir for `prep-sources` output. Use `--force` to overwrite an existing output dir.
 
@@ -19,9 +33,7 @@ azldev comp prep-sources -p <name> --force -o base/build/work/scratch/<name>-pos
 diff -r base/build/work/scratch/<name>-pre base/build/work/scratch/<name>-post
 ```
 
-If `prep-sources` fails, the error message will identify which overlay failed and why.
-
-### 2. Inspect the upstream spec/sources
+### 3. Inspect the upstream spec/sources
 
 Look at the pre-overlay output dir — this is what the overlay is trying to modify. Common root cause: upstream changed and the overlay's assumptions no longer hold.
 
@@ -61,5 +73,5 @@ For overlay type reference (all 12 types with key fields), see [`comp-toml.instr
 - **Test incrementally.** Apply one overlay at a time and verify with `prep-sources`. Debugging 10 overlays at once is painful.
 - **Minimize overlays.** Each is a potential failure point. Prefer the smallest delta from upstream.
 - **Verify in chroot.** If overlays apply but the build still fails, use [`skill-mock`](../skill-mock/SKILL.md) to inspect the build environment.
-- **Follow the inner loop.** The full cycle is: investigate → modify → verify → build → test → inspect. See [`skill-build-component`](../skill-build-component/SKILL.md) for details.
+- **Follow the inner loop.** The full cycle is: investigate → modify → render → build → test → inspect. See [`skill-build-component`](../skill-build-component/SKILL.md) for details.
 - **Smoke-test after fixing overlays.** A clean apply and successful build don't guarantee working RPMs. See [`skill-mock`](../skill-mock/SKILL.md).

AGENTS.md

@@ -9,7 +9,7 @@ For project context and architecture, see [`.github/copilot-instructions.md`](.g
 ### Examples of changes that should trigger a final test prior to sign-off (not an exhaustive list)
 
 - Version bumps or pinning a new upstream version
-- Adding, modifying, or removing overlays (trivial edits may only require `prep-sources` verification, but when in doubt, do a full build + smoke-test)
+- Adding, modifying, or removing overlays (trivial edits may only require `render` verification, but when in doubt, do a full build + smoke-test)
 - Changing build config (`build.defines`, `build.with`, `build.without`)
 - Modifying local spec files or source files (again, trivial edits may not require a full rebuild, but when in doubt, test)
 - Adding a new component (first build)
@@ -33,9 +33,11 @@ Do NOT skip testing for changes that affect RPM output. Do NOT tell the user "th
 
 - Always run `azldev comp list -p <name> -q -O json` before modifying a component.
 - Prefer overlays over forking/local specs when customizing upstream packages.
-- Use `azldev comp prep-sources -p <name> --force -o <dir> -q` to verify overlays apply cleanly before building. Always use `--force` to overwrite an existing output dir, `rm -rf` requires user confirmation which is disruptive.
-- Follow the inner loop cycle: investigate → modify → verify → build → test → inspect. See [`skill-build-component`](.github/skills/skill-build-component/SKILL.md).
-  - Note: Use your best judgement, some packages are VERY slow to build (e.g., `kernel`), in those cases you may want to do multiple iterations of investigate → modify → verify with `prep-sources` before doing a full build + test.
+- After modifying overlays or component config, re-render with `azldev comp render -p <name>` and inspect `specs/<first-char>/<name>/` to verify the result. This is the fastest verification path.
+  - Note: Changing a global snapshot time may affect all components that depend on it, potentially causing widespread rebuilds. Full re-render is time-consuming, but may be done by `azldev comp render -a --clean-stale`.
+- Use `prep-sources` for deeper debugging: `azldev comp prep-sources -p <name> --skip-overlays --force -o <pre-dir> -q` and `azldev comp prep-sources -p <name> --force -o <post-dir> -q` to diff pre/post overlay output when you need to understand what upstream provides vs. what overlays change. Always use `--force` to overwrite an existing output dir, `rm -rf` requires user confirmation which is disruptive.
+- Follow the inner loop cycle: investigate → modify → render → build → test → inspect. See [`skill-build-component`](.github/skills/skill-build-component/SKILL.md).
+  - Note: Use your best judgement, some packages are VERY slow to build (e.g., `kernel`), in those cases you may want to do multiple iterations of investigate → modify → verify with `render` before doing a full build + test.
 - `prep-sources -o <dir>` output is ad-hoc (user-chosen dir). `comp build` output goes to project-configured dirs (`base/out/`, `base/build/`). Don't conflate them.
 - For temporary files, ensure they are all placed inside the project's defined work directory (`azldev config dump -q -f json 2>&1 | grep 'workDir'`). Example commands use `base/build/work/scratch/`, and all temp directories should be inside it unless there's a specific reason not to be.