microsoft · reubeno · Apr 1, 2026 · Mar 24, 2026 · Mar 24, 2026 · Mar 31, 2026
diff --git a/docs/user/how-to/inspect-package-config.md b/docs/user/how-to/inspect-package-config.md
@@ -0,0 +1,99 @@
+# How To: Inspect Resolved Package Configuration
+
+This guide shows how to use `azldev package list` to audit the effective
+binary-package configuration for your project without running a build.
+
+## Background
+
+Binary package configuration in azldev is assembled from up to four layers
+(see [Package Groups](../reference/config/package-groups.md) for details):
+
+1. Project `default-package-config`
+2. Package group `default-package-config`
+3. Component `default-package-config`
+4. Component `packages.<name>` override (highest priority)
+
+`azldev package list` resolves all of these layers and prints the effective
+configuration for each package you ask about.
+
+## List All Explicitly-Configured Packages
+
+Use `-a` to enumerate every package that appears in any package-group or
+component `packages` map:
+
+```bash
+azldev package list -a
+```
+
+Example output:
+
+```
+╭──────────────────┬────────────────┬───────────┬──────────────╮
+│ PACKAGE          │ GROUP          │ COMPONENT │ CHANNEL      │
+├──────────────────┼────────────────┼───────────┼──────────────┤
+│ curl-debugsource │ debug-packages │           │ rpm-debug    │
+│ libcurl          │ base-packages  │           │ rpm-base     │
+│ libcurl-devel    │ devel-packages │ curl      │ rpm-base     │
+│ wget2-wget       │                │ wget2     │ rpm-base     │
+╰──────────────────┴────────────────┴───────────┴──────────────╯
+```
+
+### Column meanings
+
+| Column | Meaning |
+|--------|---------|
+| **Package** | Binary package name (RPM `Name` tag) |
+| **Group** | Package-group whose `packages` list contains this package, if any |
+| **Component** | Component that has an explicit `packages.<name>` override for this package, if any |
+| **Channel** | Effective publish channel after all config layers are applied |
+
+> **Note:** A non-empty **Component** column means the component has an explicit
+> per-package entry in its `packages` map — it does **not** mean "the component
+> whose spec produces this package". Packages that get their configuration only
+> from the project default or a package-group will show an empty Component.
+
+## Look Up Specific Packages
+
+Use `-p` to look up one or more packages by exact name. Packages that are not
+in any explicit configuration are still shown — they resolve using only the
+project default:
+
+```bash
+azldev package list -p libcurl -p libcurl-devel -p curl-debugsource
+```
+
+Positional arguments are equivalent to `-p`:
+
+```bash
+azldev package list libcurl libcurl-devel curl-debugsource
+```
+
+You can combine `-a` and `-p` — the results are the union of both selections.
+
+## Machine-Readable Output
+
+Pass `-q -O json` to get JSON output suitable for scripting:
+
+```bash
+azldev package list -a -q -O json
+```
+
+```json
+[
+  {
+    "packageName": "libcurl",
+    "group": "base-packages",
+    "component": "",
+    "channel": "rpm-base"
+  },
+  ...
+]
+```
+
+## Alias
+
+`pkg` is an alias for the `package` subcommand:
+
+```bash
+azldev pkg list -a
+```
diff --git a/docs/user/reference/cli/azldev.md b/docs/user/reference/cli/azldev.md
diff --git a/docs/user/reference/cli/azldev_package.md b/docs/user/reference/cli/azldev_package.md
diff --git a/docs/user/reference/cli/azldev_package_list.md b/docs/user/reference/cli/azldev_package_list.md
diff --git a/docs/user/reference/config/project.md b/docs/user/reference/config/project.md
@@ -2,7 +2,9 @@
 
 The `[project]` section defines metadata and directory layout for an azldev project. It is typically defined in a project-level config file (e.g., `base/project.toml`) rather than the root `azldev.toml`.
 
-## Field Reference
+## `[project]` Field Reference
+
+The following fields are nested under the `[project]` TOML section:
 
 | Field | TOML Key | Type | Required | Description |
 |-------|----------|------|----------|-------------|
@@ -11,8 +13,8 @@ The `[project]` section defines metadata and directory layout for an azldev proj
 | Work directory | `work-dir` | string | No | Path to the temporary working directory for build artifacts (relative to this config file) |
 | Output directory | `output-dir` | string | No | Path to the directory where final build outputs (RPMs, SRPMs) are placed (relative to this config file) |
 | Default distro | `default-distro` | [DistroReference](distros.md#distro-references) | No | The default distro and version to use when building components |
-| Default package config | `default-package-config` | [PackageConfig](package-groups.md#package-config) | No | Project-wide default applied to every binary package before group and component overrides |
-| Package groups | `package-groups` | map of string → [PackageGroupConfig](package-groups.md) | No | Named groups of binary packages with shared configuration |
+
+> **Note:** `[default-package-config]` and `[package-groups]` are **top-level** TOML sections — they are not nested under `[project]`. They are documented in the sections below.
 
 ## Directory Paths
 
@@ -37,7 +39,7 @@ Components inherit their spec source and build environment from the default dist
 
 ## Default Package Config
 
-The `[default-package-config]` section defines the lowest-priority configuration layer applied to every binary package produced by any component in the project. It is overridden by [package groups](package-groups.md), [component-level defaults](components.md#package-configuration), and explicit per-package overrides.
+The `[default-package-config]` section is a **top-level** TOML section (not nested under `[project]`). It defines the lowest-priority configuration layer applied to every binary package produced by any component in the project. It is overridden by [package groups](package-groups.md), [component-level defaults](components.md#package-configuration), and explicit per-package overrides.
 
 The most common use is to set a project-wide default publish channel:
 
@@ -50,7 +52,7 @@ See [Package Groups](package-groups.md#resolution-order) for the full resolution
 
 ## Package Groups
 
-The `[package-groups.<name>]` section defines named groups of binary packages. Each group lists its members explicitly in the `packages` field and provides a `default-package-config` that is applied to all listed packages.
+The `[package-groups.<name>]` section is a **top-level** TOML section (not nested under `[project]`). It defines named groups of binary packages. Each group lists its members explicitly in the `packages` field and provides a `default-package-config` that is applied to all listed packages.
 
 This is currently used to route different types of packages (e.g., `-devel`, `-debuginfo`) to different publish channels, though groups can also carry other future configuration.
 

diff --git a/internal/app/azldev/cmds/component/build.go b/internal/app/azldev/cmds/component/build.go
@@ -323,7 +323,7 @@ func buildComponentUsingBuilder(
 	// Enrich each RPM with its binary package name and resolved publish channel.
 	results.RPMs, err = resolveRPMResults(env.FS(), results.RPMPaths, env.Config(), component.GetConfig())
 	if err != nil {
-		return results, fmt.Errorf("failed to resolve publish channels for %q:\n%w", component.GetName(), err)
+		return results, fmt.Errorf("failed to resolve publish channels for %#q:\n%w", component.GetName(), err)
 	}
 
 	// Populate the parallel Channels slice for table display.