Dan Streetman (ddstreet) · Oct 30, 2026 · Oct 30, 2026 · Nov 3, 2026 · Nov 3, 2026 · Nov 3, 2026
diff --git a/.github/instructions/agent-skills.instructions.md b/.github/instructions/agent-skills.instructions.md
@@ -68,10 +68,9 @@ Before shipping any skill/instruction:
 
 ## Mode-specific content
 
-azldev has two modes, and the emitted content follows the one it runs in. A `Catalog`
-(`NewCatalog(withoutLockfile)`) resolves the skills, instruction wrappers, and templates;
-the package-level `Skills`, `Instructions`, `FindSkill`, `SkillDocument`, and `Files`
-helpers are the default (lock-file) mode.
+The CLI always emits the default catalog, covering both workflows selected by
+`lockless-components.txt`. `NewCatalog(true)` retains an internal all-lockless
+variant; the package-level helpers use the default mixed-workflow catalog.
 
 - **Shared by default.** Registry entries and templates under `content/` describe the
   default mode and are used by both, so most edits need nothing extra.
@@ -82,11 +81,11 @@ helpers are the default (lock-file) mode.
   same-named default template for that mode; add one only when the document's content
   actually differs.
 
-When you add or edit a skill, check whether its content names a command that exists in
-only one mode (for example `comp update` versus `comp refresh-upstream-commit`) and, if
-so, provide the mode-specific variant. Verify both with
-`./out/bin/azldev docs agent show --skill <name>` and
-`./out/bin/azldev --without-lockfile docs agent show --skill <name>`.
+When editing a skill, describe which components each command processes:
+`comp update` handles locked components; `comp refresh-upstream-commit` handles
+listed lockless components. Verify CLI output with
+`./out/bin/azldev docs agent show --skill <name>` and cover catalog variants in
+unit tests. There is no global CLI mode selector.
 
 ## Config-resolved bindings
 

diff --git a/docs/developer/reference/build.md b/docs/developer/reference/build.md
@@ -16,7 +16,7 @@ This repo contains configs for the `golangci-lint` linter. It is installed as pa
 | Command | Description | When to Use |
 |---------|-------------|-------------|
 | `mage -l` | List all available targets | To see all options |
-| `mage all` | Build, test, default checks, and scenario pipeline | Before submitting PR |
+| `mage all` | Build, then run unit tests, default checks, and scenario tests in parallel; generate docs after they pass | Before submitting PR |
 | `mage build` | Build Go binaries | After code changes |
 | `mage install` | Build Go binaries and install | Outer-loop testing |
 | `mage unit` | Run unit tests | After writing tests |
@@ -33,6 +33,13 @@ This repo contains configs for the `golangci-lint` linter. It is installed as pa
 **Note**: Dependencies run automatically in correct order
 (i.e. `mage build` and `mage unit` automatically run code generation as needed).
 
+`mage all` shares one code-generation and build pass across its parallel
+validation targets. Each validation target must pass before documentation is
+regenerated. It still runs the default Go checks, not the optional Python checks;
+use `mage check all` to include those. Parallel validation can increase peak
+resource use; set `GOMAXPROCS` and `GOFLAGS=-p=<count>` to limit Go concurrency
+on memory-constrained hosts.
+
 ## Code Generation
 
 The project uses automatic code generation including:

diff --git a/docs/user/README.md b/docs/user/README.md
@@ -5,9 +5,10 @@
 - [Create a Project](./how-to/create-project.md) — set up a new Azure Linux project
 - [Add a Component](./how-to/add-component.md) — import or create a new package
 - [Build a Component](./how-to/build-component.md) — build RPMs from component definitions
+- [Extract a Dist-Git Repository](./how-to/extract-dist-git-repo.md) — export a component's committed files and history
 - [Build an Image](./how-to/build-image.md) — build and boot Azure Linux images
 - [Set Up AI Coding Agents](./how-to/set-up-ai-agents.md) — emit agent skill and instruction files
-- [Preview the Lock-File-Free Mode](./how-to/preview-without-lockfile.md) — opt in to `--without-lockfile`
+- [Preview the Lock-File-Free Mode](./how-to/preview-without-lockfile.md) — select lockless components
 
 ## Explanation
 

diff --git a/docs/user/explanation/config-system.md b/docs/user/explanation/config-system.md
@@ -99,7 +99,7 @@ Component definitions are merged additively. If the same component name (e.g., `
 
 > **Note:** Slice fields (like `overlays`) are **appended**, not replaced, following the same merge behavior used by component configuration inheritance.
 
-> **Preview:** With the global `--without-lockfile` flag, component definitions merge with override semantics instead, and component validation runs only after every included file has been merged, so an individual file may hold a partial component definition. See [Preview the Lock-File-Free Mode](../how-to/preview-without-lockfile.md).
+> **Preview:** Components listed in `lockless-components.txt` beside the top-level `azldev.toml` merge with override semantics instead, and their validation runs only after every included file has been merged, so an individual file may hold a partial component definition. Unlisted components retain additive merging and per-file validation. See [Preview the Lock-File-Free Mode](../how-to/preview-without-lockfile.md).
 
 ### Component Groups and Images
 

diff --git a/docs/user/how-to/build-component.md b/docs/user/how-to/build-component.md
@@ -26,6 +26,15 @@ Built packages are placed in structured subdirectories under the project's outpu
 
 ## Common Options
 
+For components listed in `lockless-components.txt`, render and commit first.
+Build extracts the committed component dist-git history using `git-filter-repo`,
+fetches configured source files (including download and custom origins), downloads
+remaining manifest payloads from lookaside, and builds the SRPM with Mock's `rpmautospec` plugin.
+Install `git-filter-repo` and Mock 5.3 or newer. Uncommitted rendered edits are
+ignored. Lockless builds reject `--without-git` and `--rpmdev-bumpspec`;
+lock-file-based builds are unchanged. See the
+[lockless workflow](preview-without-lockfile.md#preparing-querying-and-building-committed-dist-git).
+
 | Flag | Description |
 |------|-------------|
 | `--no-check` | Skip the `%check` section (package test suite) |

diff --git a/docs/user/how-to/extract-dist-git-repo.md b/docs/user/how-to/extract-dist-git-repo.md
@@ -0,0 +1,65 @@
+# How To: Extract a Component's Dist-Git Repository
+
+Use `azldev comp dist-git-repo` to extract one component's committed rendered
+files and their Git history from the local project into a standalone repository.
+This works for both locked and lockless components.
+
+Install **git-filter-repo** first. If `git filter-repo --version` is unavailable,
+the command fails with an installation message before replacing any output.
+
+## Extract a component
+
+Specify exactly one component name and a required output directory:
+
+```bash
+azldev comp dist-git-repo curl -o ./dist-git/curl
+```
+
+`--output-dir` is the long form of `-o`. Relative output paths are relative to
+your current working directory. To select a project elsewhere, use the global
+`-C` option:
+
+```bash
+azldev -C /path/to/project comp dist-git-repo curl -o ./dist-git/curl
+```
+
+The command clones the local project repository's current branch using
+`git clone --single-branch --no-local`. It then runs
+`git filter-repo --subdirectory-filter` in the clone, selecting:
+
+```text
+<project.rendered-specs-dir>/<lowercase-first-letter>/<component-name>
+```
+
+The path passed to the filter is relative to the project repository's Git root.
+For example, `project.rendered-specs-dir = "specs"` selects `specs/c/curl`;
+`SLOF` selects `specs/s/SLOF`. A configured nested rendered-specs directory is
+respected.
+
+The selected files become the standalone repository's root:
+
+```bash
+git -C ./dist-git/curl log --oneline
+ls ./dist-git/curl
+```
+
+Only committed content is exported. This command does not render files, refresh pins,
+or fetch the component's upstream Fedora/dist-git repository. Render and commit
+changes first if you want them included.
+
+## Replace an existing output
+
+Even an empty existing directory is rejected unless you provide `--force`:
+
+```bash
+azldev comp dist-git-repo curl --output-dir ./dist-git/curl --force
+```
+
+**`--force` deletes the existing output directory and its contents.** Prerequisite,
+source-path, and output-safety checks run before deletion. The source
+repository and home directory (including their ancestors), Git metadata, and paths
+containing symbolic links are not allowed as destinations.
+
+If cloning or filtering fails, any partial output remains for inspection.
+Resolve the cause and retry with `--force`. A global `--dry-run` makes no
+filesystem changes and does not run Git commands.