Multiple manifest implementation

README.md

@@ -266,6 +266,8 @@ in focused files:
 - [`doc/cli.md`](doc/cli.md) describes the supported command-line interface.
 - [`doc/manifest-format.md`](doc/manifest-format.md) describes the manifest
   grammar and parser behavior.
+- [`doc/examples/`](doc/examples/) contains small, release-specific starter
+  manifests.
 - [`doc/adr/`](doc/adr/) contains the project's Architecture Decision Records.
 - [`testing.md`](doc/testing.md) describes how to test the tool during development
   work.

doc/examples/README.md

@@ -0,0 +1,36 @@
+# Example Manifests
+
+This directory contains small, release-specific starter manifests for
+Bootstrap.  The examples are intended to reduce the effort required to begin a
+new workstation manifest without implying that every listed package is needed
+on every system.
+
+Examples are organized by operating system, distribution, release, and
+purpose:
+
+```text
+doc/examples/<operating-system>/<distribution>/<release>/<purpose>.manifest
+```
+
+The initial example is:
+
+- [`linux/ubuntu/26.04/core.manifest`](linux/ubuntu/26.04/core.manifest), a
+  compact collection of generally useful command-line tools for Ubuntu 26.04.
+
+Treat each example as a starting point:
+
+- review the manifest before running it;
+- add or remove packages to match the system's purpose;
+- remember that package availability depends on configured repositories; and
+- prefer unconstrained package names unless a genuine compatibility requirement
+  justifies a version constraint.
+
+Inspect an example without changing the system:
+
+```bash
+./bootstrap.bash --dry-run --explain \
+  doc/examples/linux/ubuntu/26.04/core.manifest
+```
+
+Additional purpose-specific manifests may be added alongside `core.manifest`
+when a small, well-documented example would help users get started.

doc/examples/linux/ubuntu/26.04/core.manifest

@@ -0,0 +1,22 @@
+#------------------------------------------------------------------------------
+# Ubuntu 26.04 core workstation example
+#
+# This manifest is a starting point for a small, generally useful collection
+# of command-line tools. Review it before use and add or remove packages to
+# match the system's purpose.
+#------------------------------------------------------------------------------
+
+# Version control and build tools
+git
+make
+
+# Download and transfer tools
+curl
+wget
+
+# Archive and compression tools
+zip
+unzip
+
+# HTTPS certificate roots
+ca-certificates

tests/examples.bats

@@ -0,0 +1,22 @@
+#!/usr/bin/env bats
+
+load 'helpers'
+
+setup() {
+    REPO_ROOT="${BATS_TEST_DIRNAME}/.."
+    SCRIPT="${REPO_ROOT}/dist/bootstrap.bash"
+}
+
+@test "example manifests are accepted by the manifest parser" {
+    example_count=0
+
+    while IFS= read -r manifest; do
+        example_count=$((example_count + 1))
+        run bash -c "source '$SCRIPT'; bootstrap_manifest_parse_file '$manifest'"
+
+        [ "$status" -eq 0 ]
+        [ -n "$output" ]
+    done < <(find "${REPO_ROOT}/doc/examples" -type f -name '*.manifest' -print | sort)
+
+    [ "$example_count" -gt 0 ]
+}