{"owner":"microsoft","repo":"azurelinux","hasSkills":true,"totalSkillsCount":5,"totalTokensCount":5078,"categories":["root-instruction","copilot-instructions","mcp-config","marketplace","plugin-manifest"],"hasMcp":true,"mcpConfig":{"mcpServers":{"azurelinux":{"command":"npx","args":["-y","@modelcontextprotocol/server-azurelinux"]}}},"found":["AGENTS.md",".github/copilot-instructions.md",".cursor/mcp.json",".claude-plugin/marketplace.json",".claude-plugin/plugin.json"],"skills":{"AGENTS.md":"# Azure Linux — Agent Guide\n\nFor project context and architecture, see [`.github/copilot-instructions.md`](.github/copilot-instructions.md).\n\n## Mandatory Testing\n\n> **USE YOUR BEST JUDGEMENT**, but when in doubt, test. If your change could affect the built RPMs, smoke-test before reporting success. See [`azldev-mock`](.agents/skills/azldev-mock/SKILL.md).\n\n### Examples of changes that should trigger a final test prior to sign-off (not an exhaustive list)\n\n- Version bumps or pinning a new upstream version\n- Adding, modifying, or removing overlays (trivial edits may only require `render` verification, but when in doubt, do a full build + smoke-test)\n- Changing build config (`build.defines`, `build.with`, `build.without`)\n- Modifying local spec files or source files (again, trivial edits may not require a full rebuild, but when in doubt, test)\n- Adding a new component (first build)\n\n### Examples of changes that may not require testing (no effect on RPM output)\n\n- Moving a component definition between files (inline `components.toml` → dedicated `<name>.comp.toml` or vice versa)\n- Editing only component metadata fields (e.g., overlay descriptions, build descriptions, comments) without changing actual build config or overlays\n- Adding or editing TOML comments\n- Pure documentation or formatting changes\n\n### Minimum required testing\n\n1. **Build** — `azldev comp build -p <name>` succeeds, RPMs appear in `base/out/`.\n2. **Inspect** — Use `mock --copyin` to copy the RPM into the chroot and inspect with `rpm -qlp` without installing. See [`azldev-mock`](.agents/skills/azldev-mock/SKILL.md).\n3. **Smoke-test** — Use a mock chroot (`azldev adv mock shell --add-package /path/to/rpm`) to install and validate basic functionality (e.g., `<binary> --version`, service starts, library loads). See [`azldev-mock`](.agents/skills/azldev-mock/SKILL.md).\n\nDo NOT skip testing for changes that affect RPM output. Do NOT tell the user \"the build succeeded\" without also running the smoke-test. If testing cannot be performed (e.g., the package has no runnable binary, or some other issue), explicitly document why and what was verified instead.\n\n## Conventions\n\n- Always run `azldev comp list -p <name> -q -O json` before modifying a component.\n- Prefer overlays over forking/local specs when customizing upstream packages.\n- 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.\n  - 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`.\n- **Always re-run `azldev comp update -p <name>` before opening a PR**, even for minor edits — lock fingerprints are computed from the full component config, and the `Update Locks` CI check runs against the committed state. See [`azldev-update-component`](.agents/skills/azldev-update-component/SKILL.md).\n- **Every commit that touches a component bumps `%changelog` / `Release:` on the next render** (rpmautospec walks `git log` for the spec). After committing, re-render and amend so the spec tracks your commit, otherwise `Check Rendered Specs` will fail. See [`azldev-update-component`](.agents/skills/azldev-update-component/SKILL.md) for the finalize-and-amend pattern, plus the pin-bump variant.\n- 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.\n- Follow the inner loop cycle: investigate → modify → render → build → test → inspect. See [`azldev-build-component`](.agents/skills/azldev-build-component/SKILL.md).\n  - 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.\n- `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.\n- 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.\n\n> **Do NOT use `/tmp` or bare `mktemp -d`** — always use `base/build/work/scratch/` (or a subdirectory) for temporary files. This avoids permission issues and keeps all working files inside the project tree.\n\nExample: `workDir=\"/home/user/azurelinux/base/build/work\"`, use \"./base/build/work/scratch/\" for all temp dirs, or a subdir like \"./base/build/work/scratch/thing\".\n\n## Skills\n\nDetailed workflows live in skills (loaded on-demand when relevant):\n\n| Task | Skill |\n| ---- | ----- |\n| Use azldev or edit distro configuration | [`azldev`](.agents/skills/azldev/SKILL.md) |\n| Build a component, debug build failures | [`azldev-build-component`](.agents/skills/azldev-build-component/SKILL.md) |\n| Bump a component's upstream pin (lock files) | [`azldev-update-component`](.agents/skills/azldev-update-component/SKILL.md) |\n| Add a new component to the distro | [`azldev-add-component`](.agents/skills/azldev-add-component/SKILL.md) |\n| Remove component(s) from the distro | [`azldev-remove-component`](.agents/skills/azldev-remove-component/SKILL.md) |\n| Diagnose and fix overlay issues | [`azldev-overlays`](.agents/skills/azldev-overlays/SKILL.md) |\n| Test and inspect packages in mock chroot | [`azldev-mock`](.agents/skills/azldev-mock/SKILL.md) |\n| Review component for hygiene and best practices | [`azldev-comp-toml` review checklist](.agents/skills/azldev-comp-toml/SKILL.md#review-checklist) |\n| Build, boot, test, or configure images | [`azldev-image`](.agents/skills/azldev-image/SKILL.md) |\n| Triage Koji build failures | [`skill-koji-triage`](.agents/skills/skill-koji-triage/SKILL.md) |\n| Batch-triage build failures from results file | [`skill-mass-triage`](.agents/skills/skill-mass-triage/SKILL.md) |\n| Fix Stage 1 Fedora mirror dependency gaps (injections) | [`skill-fedora-mirror-injections`](.agents/skills/skill-fedora-mirror-injections/SKILL.md) |\n| Inspect Koji AKS cluster health and node pools | [`skill-aks-health`](.agents/skills/skill-aks-health/SKILL.md) |\n| Resolve Koji AKS deployment context | [`skill-deployment-context`](.agents/skills/skill-deployment-context/SKILL.md) |\n| KQL queries for Koji logs, pods, and events | [`skill-kql-queries`](.agents/skills/skill-kql-queries/SKILL.md) |\n| Query Azure Monitor metrics for Koji AKS | [`skill-metrics`](.agents/skills/skill-metrics/SKILL.md) |\n\n> **Azure infra workflow ordering:** Before running any KQL log queries, metrics queries, or AKS health checks, **always resolve deployment context first** using [`skill-deployment-context`](.agents/skills/skill-deployment-context/SKILL.md). This provides the resource group, cluster name, subscription, and Log Analytics workspace needed by the other Azure skills.\n\n## Directory Guidance\n\n- **Components:** [`base/comps/AGENTS.md`](base/comps/AGENTS.md) — file organization rules\n- **Distro config:** [`distro/AGENTS.md`](distro/AGENTS.md) — build defaults, shared config\n",".github/copilot-instructions.md":"# Azure Linux — Copilot Instructions\n\nAzure Linux is a TOML-defined Linux distribution that imports RPM specs from upstream distros (primarily Fedora) and customizes them via an **overlay system** — no spec forking required. The `azldev` CLI tool drives all component and image workflows.\n\nOne of the core tenets of this project is **minimal necessary divergence** from upstream. Overlays should be surgical and only change what's needed to meet Azure Linux requirements. Upstream packages should be preferred over bespoke components, and local specs should be a last resort. This keeps maintenance overhead low and makes it easier to pull in new versions and security updates from upstream.\n\nWhile AZL derives from Fedora, it is also an enterprise focused distro which tries to align with RHEL where it makes sense. At times this can cause conflicts in spec files that normally expect the Fedora and RHEL macros to be mutually exclusive. Use your best judgement when navigating these conflicts, but in general the guiding principle should be to minimize divergence from Fedora while still producing a stable enterprise distro suitable for use in the Azure cloud. If a spec file has complex conditional logic to handle differences between Fedora and RHEL, consult with the user to understand the rationale and determine the best path forward for AZL.\n\n## Repository Layout\n\n```\nazldev.toml                          # Root config — includes distro/ and base/\n├── base/                            # The \"base\" project\n│   ├── project.toml                 # Project metadata, output dirs, default distro ref\n│   ├── out/                         # Built RPMs/SRPMs (configured by output-dir in project.toml)\n│   ├── build/                       # Build artifacts (configured by log-dir, work-dir)\n│   │   ├── logs/                    # Build logs\n│   │   └── work/<name>/             # Per-component working directories\n│   └── comps/                       # Component definitions\n│       ├── components.toml          # Main component list (includes **/*.comp.toml)\n│       ├── <name>/<name>.comp.toml  # Dedicated component files (when overlays/config needed)\n│       └── <name>/                  # May also contain local spec files and overlay sources\n├── distro/                          # Distro definitions (shared across projects)\n│   ├── azurelinux.distro.toml       # Azure Linux 4.0: default distro, mock configs, build defines\n│   ├── distro.toml                  # Includes all *.distro.toml\n│   ├── fedora.distro.toml           # Fedora: dist-git URIs, lookaside, version branches\n│   └── mock/                        # Mock build environment configs\n├── specs/                           # Rendered specs (generated by `azldev comp render`)\n│   └── <first-char>/<name>/         # Per-component: spec, patches, scripts (no source tarballs)\n└── external/schemas/\n    └── azldev.schema.json           # Authoritative schema for all TOML config files\n```\n\n## Rendered Specs (`specs/`)\n\nThe `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:\n\n```bash\nazldev comp render -p <name>   # Single component\nazldev comp render -a          # All components (slow)\n```\n\nTo 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.\n\n## Lock Files (`locks/`)\n\nThe `locks/` directory (as specified by `lock-dir` config) contains per-component lock files that pin upstream commits + an input fingerprint. They are managed by `azldev comp update`:\n\n```bash\nazldev comp update -p <name>   # Refresh a single lock\nazldev comp update -a          # Refresh all locks\n```\n\n**Always re-run `update` before opening a PR**, even after minor edits — the input fingerprint is computed from the full component config, and the `Update Locks` CI check runs against the committed state.\n\n**⚠️ Critical quirk** — `%changelog` and `Release:` are derived from `git log` for the component, not the working tree. In this mono-repo, commits that change a component's tracked inputs (for example `base/comps/<name>/` and/or `locks/<name>.lock`) drift the rendered output, so after committing you must re-render and amend (or commit the spec separately). See [`azldev-update-component`](../.agents/skills/azldev-update-component/SKILL.md) for the finalize-and-amend pattern that keeps `Check Rendered Specs` and `Update Locks` both green, including the pin-bump variant.\n\n### Prior to PR\n\nWhen making a PR, the lock and rendered specs must be updated and self-consistent.\n\n## Key Concepts\n\n**Components** = unit of packaging (→ one or more RPMs). Spec sources: upstream (default, from Fedora dist-git), local, or pinned upstream. See the [`azldev-comp-toml` skill](../.agents/skills/azldev-comp-toml/SKILL.md#spec-source) for syntax.\n\n**Overlays** modify upstream specs/sources without forking. See the [`azldev-overlays` skill](../.agents/skills/azldev-overlays/SKILL.md) for types, syntax, and pitfalls. Schema: [`azldev.schema.json`](../external/schemas/azldev.schema.json).\n\n**TOML include hierarchy**: `azldev.toml` → `distro/distro.toml` + `base/project.toml` → `base/comps/components.toml` → `**/*.comp.toml` (stitched into single namespace).\n\n## azldev CLI Reference\n\nRun all commands from the repo root (where `azldev.toml` lives). If the terminal's cwd has drifted, use `azldev -C /path/to/repo <command>`. Use `azldev --help` and `azldev <command> --help` for current syntax — the tool is under active development.\n\n**Agent-friendly flags:** Use `-q` (quiet) to reduce noise and `-O json` for machine-parseable output. These are global flags and work on all commands.\n\n| Task | Command |\n|------|---------|\n| List all components | `azldev comp list -a -q -O json` |\n| List a specific component | `azldev comp list -p <name> -q -O json` |\n| List with wildcard | `azldev comp list -p \"azurelinux*\" -q -O json` |\n| Query a component (parsed spec, slow) | `azldev comp query -p <name> -q -O json` |\n| Add a component | `azldev comp add` |\n| Build a component | `azldev comp build -p <name> -q` |\n| Build chain (auto-publish to local repo) | `azldev comp build --local-repo-with-publish ./base/out -p <a> -p <b> -q` |\n| Render all specs for check-in | `azldev comp render -a` |\n| Render a single component | `azldev comp render -p <name>` |\n| Update a single lock file | `azldev comp update -p <name>` |\n| Update all lock files | `azldev comp update -a` |\n| Prepare sources (apply overlays) | `azldev comp prep-sources -p <name> --force -o <dir> -q` |\n| Prepare sources (skip overlays) | `azldev comp prep-sources -p <name> --skip-overlays --force -o <dir> -q` |\n| Build, keep env on failure | `azldev comp build -p <name> --preserve-buildenv on-failure -q` |\n| List images | `azldev image list` |\n| Build an image | `azldev image build` |\n| Boot an image in QEMU | `azldev image boot` |\n| Dump resolved config | `azldev config dump -q -f json` |\n| Advanced commands (like mock shell) | `azldev adv --help` (hidden from normal help) |\n\n## Repository Hygiene Rules\n\n1. **Overlay descriptions**: Every overlay MUST include a `description` field explaining *why* the change is needed.\n2. **Naming**: Component names should match the upstream package name. Use `upstream-name` when the upstream name differs (e.g., `upstream-name = \"redhat-rpm-config\"` for `azurelinux-rpm-config`).\n3. **Schema validation**: The authoritative schema is `external/schemas/azldev.schema.json`. Do NOT add `$schema` keys to TOML files — `$` is invalid at the start of a bare TOML key.\n4. **Don't edit generated output**: Build artifacts in `base/out/` and `base/build/` are generated (configured by `output-dir`, `log-dir`, `work-dir` in `base/project.toml`) — never edit them directly. Note: `prep-sources -o <dir>` writes to a user-specified directory, separate from these project output dirs.\n5. **Mandatory testing**: Any change that affects a component's output (overlays, build config, spec edits, version bumps, new components) MUST be validated by building AND testing the resulting RPMs. A successful build alone is not sufficient — smoke-test in a mock chroot. Pure organizational changes (moving definitions between files, editing descriptions/comments) do not require rebuild. See `AGENTS.md` for the full testing protocol.\n6. **New specs use autorelease**: For any spec we author ourselves (local specs), use `%autorelease` and `%autochangelog` rather than a static `Release:` with a hand-written `%changelog`. The default `release.calculation = \"auto\"` detects ordinary, unconditional `%autorelease` usage, so do not set it explicitly. Use `release = { calculation = \"autorelease\" }` only when auto-detection cannot identify the spec's autorelease behavior, such as when `%autorelease` is conditional.\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/.claude-plugin/plugin.json)"},"files":{"AGENTS.md":"# Azure Linux — Agent Guide\n\nFor project context and architecture, see [`.github/copilot-instructions.md`](.github/copilot-instructions.md).\n\n## Mandatory Testing\n\n> **USE YOUR BEST JUDGEMENT**, but when in doubt, test. If your change could affect the built RPMs, smoke-test before reporting success. See [`azldev-mock`](.agents/skills/azldev-mock/SKILL.md).\n\n### Examples of changes that should trigger a final test prior to sign-off (not an exhaustive list)\n\n- Version bumps or pinning a new upstream version\n- Adding, modifying, or removing overlays (trivial edits may only require `render` verification, but when in doubt, do a full build + smoke-test)\n- Changing build config (`build.defines`, `build.with`, `build.without`)\n- Modifying local spec files or source files (again, trivial edits may not require a full rebuild, but when in doubt, test)\n- Adding a new component (first build)\n\n### Examples of changes that may not require testing (no effect on RPM output)\n\n- Moving a component definition between files (inline `components.toml` → dedicated `<name>.comp.toml` or vice versa)\n- Editing only component metadata fields (e.g., overlay descriptions, build descriptions, comments) without changing actual build config or overlays\n- Adding or editing TOML comments\n- Pure documentation or formatting changes\n\n### Minimum required testing\n\n1. **Build** — `azldev comp build -p <name>` succeeds, RPMs appear in `base/out/`.\n2. **Inspect** — Use `mock --copyin` to copy the RPM into the chroot and inspect with `rpm -qlp` without installing. See [`azldev-mock`](.agents/skills/azldev-mock/SKILL.md).\n3. **Smoke-test** — Use a mock chroot (`azldev adv mock shell --add-package /path/to/rpm`) to install and validate basic functionality (e.g., `<binary> --version`, service starts, library loads). See [`azldev-mock`](.agents/skills/azldev-mock/SKILL.md).\n\nDo NOT skip testing for changes that affect RPM output. Do NOT tell the user \"the build succeeded\" without also running the smoke-test. If testing cannot be performed (e.g., the package has no runnable binary, or some other issue), explicitly document why and what was verified instead.\n\n## Conventions\n\n- Always run `azldev comp list -p <name> -q -O json` before modifying a component.\n- Prefer overlays over forking/local specs when customizing upstream packages.\n- 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.\n  - 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`.\n- **Always re-run `azldev comp update -p <name>` before opening a PR**, even for minor edits — lock fingerprints are computed from the full component config, and the `Update Locks` CI check runs against the committed state. See [`azldev-update-component`](.agents/skills/azldev-update-component/SKILL.md).\n- **Every commit that touches a component bumps `%changelog` / `Release:` on the next render** (rpmautospec walks `git log` for the spec). After committing, re-render and amend so the spec tracks your commit, otherwise `Check Rendered Specs` will fail. See [`azldev-update-component`](.agents/skills/azldev-update-component/SKILL.md) for the finalize-and-amend pattern, plus the pin-bump variant.\n- 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.\n- Follow the inner loop cycle: investigate → modify → render → build → test → inspect. See [`azldev-build-component`](.agents/skills/azldev-build-component/SKILL.md).\n  - 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.\n- `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.\n- 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.\n\n> **Do NOT use `/tmp` or bare `mktemp -d`** — always use `base/build/work/scratch/` (or a subdirectory) for temporary files. This avoids permission issues and keeps all working files inside the project tree.\n\nExample: `workDir=\"/home/user/azurelinux/base/build/work\"`, use \"./base/build/work/scratch/\" for all temp dirs, or a subdir like \"./base/build/work/scratch/thing\".\n\n## Skills\n\nDetailed workflows live in skills (loaded on-demand when relevant):\n\n| Task | Skill |\n| ---- | ----- |\n| Use azldev or edit distro configuration | [`azldev`](.agents/skills/azldev/SKILL.md) |\n| Build a component, debug build failures | [`azldev-build-component`](.agents/skills/azldev-build-component/SKILL.md) |\n| Bump a component's upstream pin (lock files) | [`azldev-update-component`](.agents/skills/azldev-update-component/SKILL.md) |\n| Add a new component to the distro | [`azldev-add-component`](.agents/skills/azldev-add-component/SKILL.md) |\n| Remove component(s) from the distro | [`azldev-remove-component`](.agents/skills/azldev-remove-component/SKILL.md) |\n| Diagnose and fix overlay issues | [`azldev-overlays`](.agents/skills/azldev-overlays/SKILL.md) |\n| Test and inspect packages in mock chroot | [`azldev-mock`](.agents/skills/azldev-mock/SKILL.md) |\n| Review component for hygiene and best practices | [`azldev-comp-toml` review checklist](.agents/skills/azldev-comp-toml/SKILL.md#review-checklist) |\n| Build, boot, test, or configure images | [`azldev-image`](.agents/skills/azldev-image/SKILL.md) |\n| Triage Koji build failures | [`skill-koji-triage`](.agents/skills/skill-koji-triage/SKILL.md) |\n| Batch-triage build failures from results file | [`skill-mass-triage`](.agents/skills/skill-mass-triage/SKILL.md) |\n| Fix Stage 1 Fedora mirror dependency gaps (injections) | [`skill-fedora-mirror-injections`](.agents/skills/skill-fedora-mirror-injections/SKILL.md) |\n| Inspect Koji AKS cluster health and node pools | [`skill-aks-health`](.agents/skills/skill-aks-health/SKILL.md) |\n| Resolve Koji AKS deployment context | [`skill-deployment-context`](.agents/skills/skill-deployment-context/SKILL.md) |\n| KQL queries for Koji logs, pods, and events | [`skill-kql-queries`](.agents/skills/skill-kql-queries/SKILL.md) |\n| Query Azure Monitor metrics for Koji AKS | [`skill-metrics`](.agents/skills/skill-metrics/SKILL.md) |\n\n> **Azure infra workflow ordering:** Before running any KQL log queries, metrics queries, or AKS health checks, **always resolve deployment context first** using [`skill-deployment-context`](.agents/skills/skill-deployment-context/SKILL.md). This provides the resource group, cluster name, subscription, and Log Analytics workspace needed by the other Azure skills.\n\n## Directory Guidance\n\n- **Components:** [`base/comps/AGENTS.md`](base/comps/AGENTS.md) — file organization rules\n- **Distro config:** [`distro/AGENTS.md`](distro/AGENTS.md) — build defaults, shared config\n",".github/copilot-instructions.md":"# Azure Linux — Copilot Instructions\n\nAzure Linux is a TOML-defined Linux distribution that imports RPM specs from upstream distros (primarily Fedora) and customizes them via an **overlay system** — no spec forking required. The `azldev` CLI tool drives all component and image workflows.\n\nOne of the core tenets of this project is **minimal necessary divergence** from upstream. Overlays should be surgical and only change what's needed to meet Azure Linux requirements. Upstream packages should be preferred over bespoke components, and local specs should be a last resort. This keeps maintenance overhead low and makes it easier to pull in new versions and security updates from upstream.\n\nWhile AZL derives from Fedora, it is also an enterprise focused distro which tries to align with RHEL where it makes sense. At times this can cause conflicts in spec files that normally expect the Fedora and RHEL macros to be mutually exclusive. Use your best judgement when navigating these conflicts, but in general the guiding principle should be to minimize divergence from Fedora while still producing a stable enterprise distro suitable for use in the Azure cloud. If a spec file has complex conditional logic to handle differences between Fedora and RHEL, consult with the user to understand the rationale and determine the best path forward for AZL.\n\n## Repository Layout\n\n```\nazldev.toml                          # Root config — includes distro/ and base/\n├── base/                            # The \"base\" project\n│   ├── project.toml                 # Project metadata, output dirs, default distro ref\n│   ├── out/                         # Built RPMs/SRPMs (configured by output-dir in project.toml)\n│   ├── build/                       # Build artifacts (configured by log-dir, work-dir)\n│   │   ├── logs/                    # Build logs\n│   │   └── work/<name>/             # Per-component working directories\n│   └── comps/                       # Component definitions\n│       ├── components.toml          # Main component list (includes **/*.comp.toml)\n│       ├── <name>/<name>.comp.toml  # Dedicated component files (when overlays/config needed)\n│       └── <name>/                  # May also contain local spec files and overlay sources\n├── distro/                          # Distro definitions (shared across projects)\n│   ├── azurelinux.distro.toml       # Azure Linux 4.0: default distro, mock configs, build defines\n│   ├── distro.toml                  # Includes all *.distro.toml\n│   ├── fedora.distro.toml           # Fedora: dist-git URIs, lookaside, version branches\n│   └── mock/                        # Mock build environment configs\n├── specs/                           # Rendered specs (generated by `azldev comp render`)\n│   └── <first-char>/<name>/         # Per-component: spec, patches, scripts (no source tarballs)\n└── external/schemas/\n    └── azldev.schema.json           # Authoritative schema for all TOML config files\n```\n\n## Rendered Specs (`specs/`)\n\nThe `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:\n\n```bash\nazldev comp render -p <name>   # Single component\nazldev comp render -a          # All components (slow)\n```\n\nTo 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.\n\n## Lock Files (`locks/`)\n\nThe `locks/` directory (as specified by `lock-dir` config) contains per-component lock files that pin upstream commits + an input fingerprint. They are managed by `azldev comp update`:\n\n```bash\nazldev comp update -p <name>   # Refresh a single lock\nazldev comp update -a          # Refresh all locks\n```\n\n**Always re-run `update` before opening a PR**, even after minor edits — the input fingerprint is computed from the full component config, and the `Update Locks` CI check runs against the committed state.\n\n**⚠️ Critical quirk** — `%changelog` and `Release:` are derived from `git log` for the component, not the working tree. In this mono-repo, commits that change a component's tracked inputs (for example `base/comps/<name>/` and/or `locks/<name>.lock`) drift the rendered output, so after committing you must re-render and amend (or commit the spec separately). See [`azldev-update-component`](../.agents/skills/azldev-update-component/SKILL.md) for the finalize-and-amend pattern that keeps `Check Rendered Specs` and `Update Locks` both green, including the pin-bump variant.\n\n### Prior to PR\n\nWhen making a PR, the lock and rendered specs must be updated and self-consistent.\n\n## Key Concepts\n\n**Components** = unit of packaging (→ one or more RPMs). Spec sources: upstream (default, from Fedora dist-git), local, or pinned upstream. See the [`azldev-comp-toml` skill](../.agents/skills/azldev-comp-toml/SKILL.md#spec-source) for syntax.\n\n**Overlays** modify upstream specs/sources without forking. See the [`azldev-overlays` skill](../.agents/skills/azldev-overlays/SKILL.md) for types, syntax, and pitfalls. Schema: [`azldev.schema.json`](../external/schemas/azldev.schema.json).\n\n**TOML include hierarchy**: `azldev.toml` → `distro/distro.toml` + `base/project.toml` → `base/comps/components.toml` → `**/*.comp.toml` (stitched into single namespace).\n\n## azldev CLI Reference\n\nRun all commands from the repo root (where `azldev.toml` lives). If the terminal's cwd has drifted, use `azldev -C /path/to/repo <command>`. Use `azldev --help` and `azldev <command> --help` for current syntax — the tool is under active development.\n\n**Agent-friendly flags:** Use `-q` (quiet) to reduce noise and `-O json` for machine-parseable output. These are global flags and work on all commands.\n\n| Task | Command |\n|------|---------|\n| List all components | `azldev comp list -a -q -O json` |\n| List a specific component | `azldev comp list -p <name> -q -O json` |\n| List with wildcard | `azldev comp list -p \"azurelinux*\" -q -O json` |\n| Query a component (parsed spec, slow) | `azldev comp query -p <name> -q -O json` |\n| Add a component | `azldev comp add` |\n| Build a component | `azldev comp build -p <name> -q` |\n| Build chain (auto-publish to local repo) | `azldev comp build --local-repo-with-publish ./base/out -p <a> -p <b> -q` |\n| Render all specs for check-in | `azldev comp render -a` |\n| Render a single component | `azldev comp render -p <name>` |\n| Update a single lock file | `azldev comp update -p <name>` |\n| Update all lock files | `azldev comp update -a` |\n| Prepare sources (apply overlays) | `azldev comp prep-sources -p <name> --force -o <dir> -q` |\n| Prepare sources (skip overlays) | `azldev comp prep-sources -p <name> --skip-overlays --force -o <dir> -q` |\n| Build, keep env on failure | `azldev comp build -p <name> --preserve-buildenv on-failure -q` |\n| List images | `azldev image list` |\n| Build an image | `azldev image build` |\n| Boot an image in QEMU | `azldev image boot` |\n| Dump resolved config | `azldev config dump -q -f json` |\n| Advanced commands (like mock shell) | `azldev adv --help` (hidden from normal help) |\n\n## Repository Hygiene Rules\n\n1. **Overlay descriptions**: Every overlay MUST include a `description` field explaining *why* the change is needed.\n2. **Naming**: Component names should match the upstream package name. Use `upstream-name` when the upstream name differs (e.g., `upstream-name = \"redhat-rpm-config\"` for `azurelinux-rpm-config`).\n3. **Schema validation**: The authoritative schema is `external/schemas/azldev.schema.json`. Do NOT add `$schema` keys to TOML files — `$` is invalid at the start of a bare TOML key.\n4. **Don't edit generated output**: Build artifacts in `base/out/` and `base/build/` are generated (configured by `output-dir`, `log-dir`, `work-dir` in `base/project.toml`) — never edit them directly. Note: `prep-sources -o <dir>` writes to a user-specified directory, separate from these project output dirs.\n5. **Mandatory testing**: Any change that affects a component's output (overlays, build config, spec edits, version bumps, new components) MUST be validated by building AND testing the resulting RPMs. A successful build alone is not sufficient — smoke-test in a mock chroot. Pure organizational changes (moving definitions between files, editing descriptions/comments) do not require rebuild. See `AGENTS.md` for the full testing protocol.\n6. **New specs use autorelease**: For any spec we author ourselves (local specs), use `%autorelease` and `%autochangelog` rather than a static `Release:` with a hand-written `%changelog`. The default `release.calculation = \"auto\"` detects ordinary, unconditional `%autorelease` usage, so do not set it explicitly. Use `release = { calculation = \"autorelease\" }` only when auto-detection cannot identify the spec's autorelease behavior, such as when `%autorelease` is conditional.\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/.claude-plugin/plugin.json)"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Azure Linux — Agent Guide\n\nFor project context and architecture, see [`.github/copilot-instructions.md`](.github/copilot-instructions.md).\n\n## Mandatory Testing\n\n> **USE YOUR BEST JUDGEMENT**, but when in doubt, test. If your change could affect the built RPMs, smoke-test before reporting success. See [`azldev-mock`](.agents/skills/azldev-mock/SKILL.md).\n\n### Examples of changes that should trigger a final test prior to sign-off (not an exhaustive list)\n\n- Version bumps or pinning a new upstream version\n- Adding, modifying, or removing overlays (trivial edits may only require `render` verification, but when in doubt, do a full build + smoke-test)\n- Changing build config (`build.defines`, `build.with`, `build.without`)\n- Modifying local spec files or source files (again, trivial edits may not require a full rebuild, but when in doubt, test)\n- Adding a new component (first build)\n\n### Examples of changes that may not require testing (no effect on RPM output)\n\n- Moving a component definition between files (inline `components.toml` → dedicated `<name>.comp.toml` or vice versa)\n- Editing only component metadata fields (e.g., overlay descriptions, build descriptions, comments) without changing actual build config or overlays\n- Adding or editing TOML comments\n- Pure documentation or formatting changes\n\n### Minimum required testing\n\n1. **Build** — `azldev comp build -p <name>` succeeds, RPMs appear in `base/out/`.\n2. **Inspect** — Use `mock --copyin` to copy the RPM into the chroot and inspect with `rpm -qlp` without installing. See [`azldev-mock`](.agents/skills/azldev-mock/SKILL.md).\n3. **Smoke-test** — Use a mock chroot (`azldev adv mock shell --add-package /path/to/rpm`) to install and validate basic functionality (e.g., `<binary> --version`, service starts, library loads). See [`azldev-mock`](.agents/skills/azldev-mock/SKILL.md).\n\nDo NOT skip testing for changes that affect RPM output. Do NOT tell the user \"the build succeeded\" without also running the smoke-test. If testing cannot be performed (e.g., the package has no runnable binary, or some other issue), explicitly document why and what was verified instead.\n\n## Conventions\n\n- Always run `azldev comp list -p <name> -q -O json` before modifying a component.\n- Prefer overlays over forking/local specs when customizing upstream packages.\n- 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.\n  - 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`.\n- **Always re-run `azldev comp update -p <name>` before opening a PR**, even for minor edits — lock fingerprints are computed from the full component config, and the `Update Locks` CI check runs against the committed state. See [`azldev-update-component`](.agents/skills/azldev-update-component/SKILL.md).\n- **Every commit that touches a component bumps `%changelog` / `Release:` on the next render** (rpmautospec walks `git log` for the spec). After committing, re-render and amend so the spec tracks your commit, otherwise `Check Rendered Specs` will fail. See [`azldev-update-component`](.agents/skills/azldev-update-component/SKILL.md) for the finalize-and-amend pattern, plus the pin-bump variant.\n- 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.\n- Follow the inner loop cycle: investigate → modify → render → build → test → inspect. See [`azldev-build-component`](.agents/skills/azldev-build-component/SKILL.md).\n  - 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.\n- `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.\n- 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.\n\n> **Do NOT use `/tmp` or bare `mktemp -d`** — always use `base/build/work/scratch/` (or a subdirectory) for temporary files. This avoids permission issues and keeps all working files inside the project tree.\n\nExample: `workDir=\"/home/user/azurelinux/base/build/work\"`, use \"./base/build/work/scratch/\" for all temp dirs, or a subdir like \"./base/build/work/scratch/thing\".\n\n## Skills\n\nDetailed workflows live in skills (loaded on-demand when relevant):\n\n| Task | Skill |\n| ---- | ----- |\n| Use azldev or edit distro configuration | [`azldev`](.agents/skills/azldev/SKILL.md) |\n| Build a component, debug build failures | [`azldev-build-component`](.agents/skills/azldev-build-component/SKILL.md) |\n| Bump a component's upstream pin (lock files) | [`azldev-update-component`](.agents/skills/azldev-update-component/SKILL.md) |\n| Add a new component to the distro | [`azldev-add-component`](.agents/skills/azldev-add-component/SKILL.md) |\n| Remove component(s) from the distro | [`azldev-remove-component`](.agents/skills/azldev-remove-component/SKILL.md) |\n| Diagnose and fix overlay issues | [`azldev-overlays`](.agents/skills/azldev-overlays/SKILL.md) |\n| Test and inspect packages in mock chroot | [`azldev-mock`](.agents/skills/azldev-mock/SKILL.md) |\n| Review component for hygiene and best practices | [`azldev-comp-toml` review checklist](.agents/skills/azldev-comp-toml/SKILL.md#review-checklist) |\n| Build, boot, test, or configure images | [`azldev-image`](.agents/skills/azldev-image/SKILL.md) |\n| Triage Koji build failures | [`skill-koji-triage`](.agents/skills/skill-koji-triage/SKILL.md) |\n| Batch-triage build failures from results file | [`skill-mass-triage`](.agents/skills/skill-mass-triage/SKILL.md) |\n| Fix Stage 1 Fedora mirror dependency gaps (injections) | [`skill-fedora-mirror-injections`](.agents/skills/skill-fedora-mirror-injections/SKILL.md) |\n| Inspect Koji AKS cluster health and node pools | [`skill-aks-health`](.agents/skills/skill-aks-health/SKILL.md) |\n| Resolve Koji AKS deployment context | [`skill-deployment-context`](.agents/skills/skill-deployment-context/SKILL.md) |\n| KQL queries for Koji logs, pods, and events | [`skill-kql-queries`](.agents/skills/skill-kql-queries/SKILL.md) |\n| Query Azure Monitor metrics for Koji AKS | [`skill-metrics`](.agents/skills/skill-metrics/SKILL.md) |\n\n> **Azure infra workflow ordering:** Before running any KQL log queries, metrics queries, or AKS health checks, **always resolve deployment context first** using [`skill-deployment-context`](.agents/skills/skill-deployment-context/SKILL.md). This provides the resource group, cluster name, subscription, and Log Analytics workspace needed by the other Azure skills.\n\n## Directory Guidance\n\n- **Components:** [`base/comps/AGENTS.md`](base/comps/AGENTS.md) — file organization rules\n- **Distro config:** [`distro/AGENTS.md`](distro/AGENTS.md) — build defaults, shared config\n","isInternal":false,"tokens":1935,"sizeBytes":7639},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","rawUrl":"https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/.github/copilot-instructions.md","title":"GitHub Copilot Instructions","category":"copilot-instructions","format":"markdown","content":"# Azure Linux — Copilot Instructions\n\nAzure Linux is a TOML-defined Linux distribution that imports RPM specs from upstream distros (primarily Fedora) and customizes them via an **overlay system** — no spec forking required. The `azldev` CLI tool drives all component and image workflows.\n\nOne of the core tenets of this project is **minimal necessary divergence** from upstream. Overlays should be surgical and only change what's needed to meet Azure Linux requirements. Upstream packages should be preferred over bespoke components, and local specs should be a last resort. This keeps maintenance overhead low and makes it easier to pull in new versions and security updates from upstream.\n\nWhile AZL derives from Fedora, it is also an enterprise focused distro which tries to align with RHEL where it makes sense. At times this can cause conflicts in spec files that normally expect the Fedora and RHEL macros to be mutually exclusive. Use your best judgement when navigating these conflicts, but in general the guiding principle should be to minimize divergence from Fedora while still producing a stable enterprise distro suitable for use in the Azure cloud. If a spec file has complex conditional logic to handle differences between Fedora and RHEL, consult with the user to understand the rationale and determine the best path forward for AZL.\n\n## Repository Layout\n\n```\nazldev.toml                          # Root config — includes distro/ and base/\n├── base/                            # The \"base\" project\n│   ├── project.toml                 # Project metadata, output dirs, default distro ref\n│   ├── out/                         # Built RPMs/SRPMs (configured by output-dir in project.toml)\n│   ├── build/                       # Build artifacts (configured by log-dir, work-dir)\n│   │   ├── logs/                    # Build logs\n│   │   └── work/<name>/             # Per-component working directories\n│   └── comps/                       # Component definitions\n│       ├── components.toml          # Main component list (includes **/*.comp.toml)\n│       ├── <name>/<name>.comp.toml  # Dedicated component files (when overlays/config needed)\n│       └── <name>/                  # May also contain local spec files and overlay sources\n├── distro/                          # Distro definitions (shared across projects)\n│   ├── azurelinux.distro.toml       # Azure Linux 4.0: default distro, mock configs, build defines\n│   ├── distro.toml                  # Includes all *.distro.toml\n│   ├── fedora.distro.toml           # Fedora: dist-git URIs, lookaside, version branches\n│   └── mock/                        # Mock build environment configs\n├── specs/                           # Rendered specs (generated by `azldev comp render`)\n│   └── <first-char>/<name>/         # Per-component: spec, patches, scripts (no source tarballs)\n└── external/schemas/\n    └── azldev.schema.json           # Authoritative schema for all TOML config files\n```\n\n## Rendered Specs (`specs/`)\n\nThe `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:\n\n```bash\nazldev comp render -p <name>   # Single component\nazldev comp render -a          # All components (slow)\n```\n\nTo 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.\n\n## Lock Files (`locks/`)\n\nThe `locks/` directory (as specified by `lock-dir` config) contains per-component lock files that pin upstream commits + an input fingerprint. They are managed by `azldev comp update`:\n\n```bash\nazldev comp update -p <name>   # Refresh a single lock\nazldev comp update -a          # Refresh all locks\n```\n\n**Always re-run `update` before opening a PR**, even after minor edits — the input fingerprint is computed from the full component config, and the `Update Locks` CI check runs against the committed state.\n\n**⚠️ Critical quirk** — `%changelog` and `Release:` are derived from `git log` for the component, not the working tree. In this mono-repo, commits that change a component's tracked inputs (for example `base/comps/<name>/` and/or `locks/<name>.lock`) drift the rendered output, so after committing you must re-render and amend (or commit the spec separately). See [`azldev-update-component`](../.agents/skills/azldev-update-component/SKILL.md) for the finalize-and-amend pattern that keeps `Check Rendered Specs` and `Update Locks` both green, including the pin-bump variant.\n\n### Prior to PR\n\nWhen making a PR, the lock and rendered specs must be updated and self-consistent.\n\n## Key Concepts\n\n**Components** = unit of packaging (→ one or more RPMs). Spec sources: upstream (default, from Fedora dist-git), local, or pinned upstream. See the [`azldev-comp-toml` skill](../.agents/skills/azldev-comp-toml/SKILL.md#spec-source) for syntax.\n\n**Overlays** modify upstream specs/sources without forking. See the [`azldev-overlays` skill](../.agents/skills/azldev-overlays/SKILL.md) for types, syntax, and pitfalls. Schema: [`azldev.schema.json`](../external/schemas/azldev.schema.json).\n\n**TOML include hierarchy**: `azldev.toml` → `distro/distro.toml` + `base/project.toml` → `base/comps/components.toml` → `**/*.comp.toml` (stitched into single namespace).\n\n## azldev CLI Reference\n\nRun all commands from the repo root (where `azldev.toml` lives). If the terminal's cwd has drifted, use `azldev -C /path/to/repo <command>`. Use `azldev --help` and `azldev <command> --help` for current syntax — the tool is under active development.\n\n**Agent-friendly flags:** Use `-q` (quiet) to reduce noise and `-O json` for machine-parseable output. These are global flags and work on all commands.\n\n| Task | Command |\n|------|---------|\n| List all components | `azldev comp list -a -q -O json` |\n| List a specific component | `azldev comp list -p <name> -q -O json` |\n| List with wildcard | `azldev comp list -p \"azurelinux*\" -q -O json` |\n| Query a component (parsed spec, slow) | `azldev comp query -p <name> -q -O json` |\n| Add a component | `azldev comp add` |\n| Build a component | `azldev comp build -p <name> -q` |\n| Build chain (auto-publish to local repo) | `azldev comp build --local-repo-with-publish ./base/out -p <a> -p <b> -q` |\n| Render all specs for check-in | `azldev comp render -a` |\n| Render a single component | `azldev comp render -p <name>` |\n| Update a single lock file | `azldev comp update -p <name>` |\n| Update all lock files | `azldev comp update -a` |\n| Prepare sources (apply overlays) | `azldev comp prep-sources -p <name> --force -o <dir> -q` |\n| Prepare sources (skip overlays) | `azldev comp prep-sources -p <name> --skip-overlays --force -o <dir> -q` |\n| Build, keep env on failure | `azldev comp build -p <name> --preserve-buildenv on-failure -q` |\n| List images | `azldev image list` |\n| Build an image | `azldev image build` |\n| Boot an image in QEMU | `azldev image boot` |\n| Dump resolved config | `azldev config dump -q -f json` |\n| Advanced commands (like mock shell) | `azldev adv --help` (hidden from normal help) |\n\n## Repository Hygiene Rules\n\n1. **Overlay descriptions**: Every overlay MUST include a `description` field explaining *why* the change is needed.\n2. **Naming**: Component names should match the upstream package name. Use `upstream-name` when the upstream name differs (e.g., `upstream-name = \"redhat-rpm-config\"` for `azurelinux-rpm-config`).\n3. **Schema validation**: The authoritative schema is `external/schemas/azldev.schema.json`. Do NOT add `$schema` keys to TOML files — `$` is invalid at the start of a bare TOML key.\n4. **Don't edit generated output**: Build artifacts in `base/out/` and `base/build/` are generated (configured by `output-dir`, `log-dir`, `work-dir` in `base/project.toml`) — never edit them directly. Note: `prep-sources -o <dir>` writes to a user-specified directory, separate from these project output dirs.\n5. **Mandatory testing**: Any change that affects a component's output (overlays, build config, spec edits, version bumps, new components) MUST be validated by building AND testing the resulting RPMs. A successful build alone is not sufficient — smoke-test in a mock chroot. Pure organizational changes (moving definitions between files, editing descriptions/comments) do not require rebuild. See `AGENTS.md` for the full testing protocol.\n6. **New specs use autorelease**: For any spec we author ourselves (local specs), use `%autorelease` and `%autochangelog` rather than a static `Release:` with a hand-written `%changelog`. The default `release.calculation = \"auto\"` detects ordinary, unconditional `%autorelease` usage, so do not set it explicitly. Use `release = { calculation = \"autorelease\" }` only when auto-detection cannot identify the spec's autorelease behavior, such as when `%autorelease` is conditional.\n","isInternal":false,"tokens":2243,"sizeBytes":9289},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/.claude-plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/.claude-plugin/marketplace.json)","tokens":300,"sizeBytes":199},{"name":"plugin.json","path":".claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/.claude-plugin/plugin.json","title":"claude-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/.claude-plugin/plugin.json)","tokens":300,"sizeBytes":185},{"name":"mcp.json","path":".cursor/mcp.json","rawUrl":"https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/.cursor/mcp.json","title":"Model Context Protocol (MCP) Configuration","category":"mcp-config","format":"json","content":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/.cursor/mcp.json)","tokens":300,"sizeBytes":178}],"systemPromptSnippet":"<yakaai_skills repo=\"microsoft/azurelinux\">\n<!-- File: AGENTS.md (Tokens: ~1935 | Category: root-instruction) -->\n# Azure Linux — Agent Guide\n\nFor project context and architecture, see [`.github/copilot-instructions.md`](.github/copilot-instructions.md).\n\n## Mandatory Testing\n\n> **USE YOUR BEST JUDGEMENT**, but when in doubt, test. If your change could affect the built RPMs, smoke-test before reporting success. See [`azldev-mock`](.agents/skills/azldev-mock/SKILL.md).\n\n### Examples of changes that should trigger a final test prior to sign-off (not an exhaustive list)\n\n- Version bumps or pinning a new upstream version\n- Adding, modifying, or removing overlays (trivial edits may only require `render` verification, but when in doubt, do a full build + smoke-test)\n- Changing build config (`build.defines`, `build.with`, `build.without`)\n- Modifying local spec files or source files (again, trivial edits may not require a full rebuild, but when in doubt, test)\n- Adding a new component (first build)\n\n### Examples of changes that may not require testing (no effect on RPM output)\n\n- Moving a component definition between files (inline `components.toml` → dedicated `<name>.comp.toml` or vice versa)\n- Editing only component metadata fields (e.g., overlay descriptions, build descriptions, comments) without changing actual build config or overlays\n- Adding or editing TOML comments\n- Pure documentation or formatting changes\n\n### Minimum required testing\n\n1. **Build** — `azldev comp build -p <name>` succeeds, RPMs appear in `base/out/`.\n2. **Inspect** — Use `mock --copyin` to copy the RPM into the chroot and inspect with `rpm -qlp` without installing. See [`azldev-mock`](.agents/skills/azldev-mock/SKILL.md).\n3. **Smoke-test** — Use a mock chroot (`azldev adv mock shell --add-package /path/to/rpm`) to install and validate basic functionality (e.g., `<binary> --version`, service starts, library loads). See [`azldev-mock`](.agents/skills/azldev-mock/SKILL.md).\n\nDo NOT skip testing for changes that affect RPM output. Do NOT tell the user \"the build succeeded\" without also running the smoke-test. If testing cannot be performed (e.g., the package has no runnable binary, or some other issue), explicitly document why and what was verified instead.\n\n## Conventions\n\n- Always run `azldev comp list -p <name> -q -O json` before modifying a component.\n- Prefer overlays over forking/local specs when customizing upstream packages.\n- 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.\n  - 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`.\n- **Always re-run `azldev comp update -p <name>` before opening a PR**, even for minor edits — lock fingerprints are computed from the full component config, and the `Update Locks` CI check runs against the committed state. See [`azldev-update-component`](.agents/skills/azldev-update-component/SKILL.md).\n- **Every commit that touches a component bumps `%changelog` / `Release:` on the next render** (rpmautospec walks `git log` for the spec). After committing, re-render and amend so the spec tracks your commit, otherwise `Check Rendered Specs` will fail. See [`azldev-update-component`](.agents/skills/azldev-update-component/SKILL.md) for the finalize-and-amend pattern, plus the pin-bump variant.\n- 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.\n- Follow the inner loop cycle: investigate → modify → render → build → test → inspect. See [`azldev-build-component`](.agents/skills/azldev-build-component/SKILL.md).\n  - 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.\n- `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.\n- 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.\n\n> **Do NOT use `/tmp` or bare `mktemp -d`** — always use `base/build/work/scratch/` (or a subdirectory) for temporary files. This avoids permission issues and keeps all working files inside the project tree.\n\nExample: `workDir=\"/home/user/azurelinux/base/build/work\"`, use \"./base/build/work/scratch/\" for all temp dirs, or a subdir like \"./base/build/work/scratch/thing\".\n\n## Skills\n\nDetailed workflows live in skills (loaded on-demand when relevant):\n\n| Task | Skill |\n| ---- | ----- |\n| Use azldev or edit distro configuration | [`azldev`](.agents/skills/azldev/SKILL.md) |\n| Build a component, debug build failures | [`azldev-build-component`](.agents/skills/azldev-build-component/SKILL.md) |\n| Bump a component's upstream pin (lock files) | [`azldev-update-component`](.agents/skills/azldev-update-component/SKILL.md) |\n| Add a new component to the distro | [`azldev-add-component`](.agents/skills/azldev-add-component/SKILL.md) |\n| Remove component(s) from the distro | [`azldev-remove-component`](.agents/skills/azldev-remove-component/SKILL.md) |\n| Diagnose and fix overlay issues | [`azldev-overlays`](.agents/skills/azldev-overlays/SKILL.md) |\n| Test and inspect packages in mock chroot | [`azldev-mock`](.agents/skills/azldev-mock/SKILL.md) |\n| Review component for hygiene and best practices | [`azldev-comp-toml` review checklist](.agents/skills/azldev-comp-toml/SKILL.md#review-checklist) |\n| Build, boot, test, or configure images | [`azldev-image`](.agents/skills/azldev-image/SKILL.md) |\n| Triage Koji build failures | [`skill-koji-triage`](.agents/skills/skill-koji-triage/SKILL.md) |\n| Batch-triage build failures from results file | [`skill-mass-triage`](.agents/skills/skill-mass-triage/SKILL.md) |\n| Fix Stage 1 Fedora mirror dependency gaps (injections) | [`skill-fedora-mirror-injections`](.agents/skills/skill-fedora-mirror-injections/SKILL.md) |\n| Inspect Koji AKS cluster health and node pools | [`skill-aks-health`](.agents/skills/skill-aks-health/SKILL.md) |\n| Resolve Koji AKS deployment context | [`skill-deployment-context`](.agents/skills/skill-deployment-context/SKILL.md) |\n| KQL queries for Koji logs, pods, and events | [`skill-kql-queries`](.agents/skills/skill-kql-queries/SKILL.md) |\n| Query Azure Monitor metrics for Koji AKS | [`skill-metrics`](.agents/skills/skill-metrics/SKILL.md) |\n\n> **Azure infra workflow ordering:** Before running any KQL log queries, metrics queries, or AKS health checks, **always resolve deployment context first** using [`skill-deployment-context`](.agents/skills/skill-deployment-context/SKILL.md). This provides the resource group, cluster name, subscription, and Log Analytics workspace needed by the other Azure skills.\n\n## Directory Guidance\n\n- **Components:** [`base/comps/AGENTS.md`](base/comps/AGENTS.md) — file organization rules\n- **Distro config:** [`distro/AGENTS.md`](distro/AGENTS.md) — build defaults, shared config\n\n<!-- File: .github/copilot-instructions.md (Tokens: ~2243 | Category: copilot-instructions) -->\n# Azure Linux — Copilot Instructions\n\nAzure Linux is a TOML-defined Linux distribution that imports RPM specs from upstream distros (primarily Fedora) and customizes them via an **overlay system** — no spec forking required. The `azldev` CLI tool drives all component and image workflows.\n\nOne of the core tenets of this project is **minimal necessary divergence** from upstream. Overlays should be surgical and only change what's needed to meet Azure Linux requirements. Upstream packages should be preferred over bespoke components, and local specs should be a last resort. This keeps maintenance overhead low and makes it easier to pull in new versions and security updates from upstream.\n\nWhile AZL derives from Fedora, it is also an enterprise focused distro which tries to align with RHEL where it makes sense. At times this can cause conflicts in spec files that normally expect the Fedora and RHEL macros to be mutually exclusive. Use your best judgement when navigating these conflicts, but in general the guiding principle should be to minimize divergence from Fedora while still producing a stable enterprise distro suitable for use in the Azure cloud. If a spec file has complex conditional logic to handle differences between Fedora and RHEL, consult with the user to understand the rationale and determine the best path forward for AZL.\n\n## Repository Layout\n\n```\nazldev.toml                          # Root config — includes distro/ and base/\n├── base/                            # The \"base\" project\n│   ├── project.toml                 # Project metadata, output dirs, default distro ref\n│   ├── out/                         # Built RPMs/SRPMs (configured by output-dir in project.toml)\n│   ├── build/                       # Build artifacts (configured by log-dir, work-dir)\n│   │   ├── logs/                    # Build logs\n│   │   └── work/<name>/             # Per-component working directories\n│   └── comps/                       # Component definitions\n│       ├── components.toml          # Main component list (includes **/*.comp.toml)\n│       ├── <name>/<name>.comp.toml  # Dedicated component files (when overlays/config needed)\n│       └── <name>/                  # May also contain local spec files and overlay sources\n├── distro/                          # Distro definitions (shared across projects)\n│   ├── azurelinux.distro.toml       # Azure Linux 4.0: default distro, mock configs, build defines\n│   ├── distro.toml                  # Includes all *.distro.toml\n│   ├── fedora.distro.toml           # Fedora: dist-git URIs, lookaside, version branches\n│   └── mock/                        # Mock build environment configs\n├── specs/                           # Rendered specs (generated by `azldev comp render`)\n│   └── <first-char>/<name>/         # Per-component: spec, patches, scripts (no source tarballs)\n└── external/schemas/\n    └── azldev.schema.json           # Authoritative schema for all TOML config files\n```\n\n## Rendered Specs (`specs/`)\n\nThe `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:\n\n```bash\nazldev comp render -p <name>   # Single component\nazldev comp render -a          # All components (slow)\n```\n\nTo 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.\n\n## Lock Files (`locks/`)\n\nThe `locks/` directory (as specified by `lock-dir` config) contains per-component lock files that pin upstream commits + an input fingerprint. They are managed by `azldev comp update`:\n\n```bash\nazldev comp update -p <name>   # Refresh a single lock\nazldev comp update -a          # Refresh all locks\n```\n\n**Always re-run `update` before opening a PR**, even after minor edits — the input fingerprint is computed from the full component config, and the `Update Locks` CI check runs against the committed state.\n\n**⚠️ Critical quirk** — `%changelog` and `Release:` are derived from `git log` for the component, not the working tree. In this mono-repo, commits that change a component's tracked inputs (for example `base/comps/<name>/` and/or `locks/<name>.lock`) drift the rendered output, so after committing you must re-render and amend (or commit the spec separately). See [`azldev-update-component`](../.agents/skills/azldev-update-component/SKILL.md) for the finalize-and-amend pattern that keeps `Check Rendered Specs` and `Update Locks` both green, including the pin-bump variant.\n\n### Prior to PR\n\nWhen making a PR, the lock and rendered specs must be updated and self-consistent.\n\n## Key Concepts\n\n**Components** = unit of packaging (→ one or more RPMs). Spec sources: upstream (default, from Fedora dist-git), local, or pinned upstream. See the [`azldev-comp-toml` skill](../.agents/skills/azldev-comp-toml/SKILL.md#spec-source) for syntax.\n\n**Overlays** modify upstream specs/sources without forking. See the [`azldev-overlays` skill](../.agents/skills/azldev-overlays/SKILL.md) for types, syntax, and pitfalls. Schema: [`azldev.schema.json`](../external/schemas/azldev.schema.json).\n\n**TOML include hierarchy**: `azldev.toml` → `distro/distro.toml` + `base/project.toml` → `base/comps/components.toml` → `**/*.comp.toml` (stitched into single namespace).\n\n## azldev CLI Reference\n\nRun all commands from the repo root (where `azldev.toml` lives). If the terminal's cwd has drifted, use `azldev -C /path/to/repo <command>`. Use `azldev --help` and `azldev <command> --help` for current syntax — the tool is under active development.\n\n**Agent-friendly flags:** Use `-q` (quiet) to reduce noise and `-O json` for machine-parseable output. These are global flags and work on all commands.\n\n| Task | Command |\n|------|---------|\n| List all components | `azldev comp list -a -q -O json` |\n| List a specific component | `azldev comp list -p <name> -q -O json` |\n| List with wildcard | `azldev comp list -p \"azurelinux*\" -q -O json` |\n| Query a component (parsed spec, slow) | `azldev comp query -p <name> -q -O json` |\n| Add a component | `azldev comp add` |\n| Build a component | `azldev comp build -p <name> -q` |\n| Build chain (auto-publish to local repo) | `azldev comp build --local-repo-with-publish ./base/out -p <a> -p <b> -q` |\n| Render all specs for check-in | `azldev comp render -a` |\n| Render a single component | `azldev comp render -p <name>` |\n| Update a single lock file | `azldev comp update -p <name>` |\n| Update all lock files | `azldev comp update -a` |\n| Prepare sources (apply overlays) | `azldev comp prep-sources -p <name> --force -o <dir> -q` |\n| Prepare sources (skip overlays) | `azldev comp prep-sources -p <name> --skip-overlays --force -o <dir> -q` |\n| Build, keep env on failure | `azldev comp build -p <name> --preserve-buildenv on-failure -q` |\n| List images | `azldev image list` |\n| Build an image | `azldev image build` |\n| Boot an image in QEMU | `azldev image boot` |\n| Dump resolved config | `azldev config dump -q -f json` |\n| Advanced commands (like mock shell) | `azldev adv --help` (hidden from normal help) |\n\n## Repository Hygiene Rules\n\n1. **Overlay descriptions**: Every overlay MUST include a `description` field explaining *why* the change is needed.\n2. **Naming**: Component names should match the upstream package name. Use `upstream-name` when the upstream name differs (e.g., `upstream-name = \"redhat-rpm-config\"` for `azurelinux-rpm-config`).\n3. **Schema validation**: The authoritative schema is `external/schemas/azldev.schema.json`. Do NOT add `$schema` keys to TOML files — `$` is invalid at the start of a bare TOML key.\n4. **Don't edit generated output**: Build artifacts in `base/out/` and `base/build/` are generated (configured by `output-dir`, `log-dir`, `work-dir` in `base/project.toml`) — never edit them directly. Note: `prep-sources -o <dir>` writes to a user-specified directory, separate from these project output dirs.\n5. **Mandatory testing**: Any change that affects a component's output (overlays, build config, spec edits, version bumps, new components) MUST be validated by building AND testing the resulting RPMs. A successful build alone is not sufficient — smoke-test in a mock chroot. Pure organizational changes (moving definitions between files, editing descriptions/comments) do not require rebuild. See `AGENTS.md` for the full testing protocol.\n6. **New specs use autorelease**: For any spec we author ourselves (local specs), use `%autorelease` and `%autochangelog` rather than a static `Release:` with a hand-written `%changelog`. The default `release.calculation = \"auto\"` detects ordinary, unconditional `%autorelease` usage, so do not set it explicitly. Use `release = { calculation = \"autorelease\" }` only when auto-detection cannot identify the spec's autorelease behavior, such as when `%autorelease` is conditional.\n\n<!-- File: .claude-plugin/marketplace.json (Tokens: ~300 | Category: marketplace) -->\n# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/.claude-plugin/marketplace.json)\n\n<!-- File: .claude-plugin/plugin.json (Tokens: ~300 | Category: plugin-manifest) -->\n# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/.claude-plugin/plugin.json)\n\n<!-- File: .cursor/mcp.json (Tokens: ~300 | Category: mcp-config) -->\n# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/microsoft/azurelinux/HEAD/.cursor/mcp.json)\n</yakaai_skills>"}