docs: note optional configuration traits

Author: gaelic-ghost

shared/agents-snippets/apple-swift-package-core.md

@@ -47,7 +47,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - For asynchronous event-driven tests in Swift Testing, prefer `confirmation(...)` with an explicit expected count or count range instead of ad hoc sleeps or polling loops.
 - Keep XCTest for integration points that still require it, for legacy package surfaces that have not migrated yet, or when a dependency or platform toolchain still expects XCTest.
 - Prefer first-party and top-tier Swift ecosystem packages from Apple, `swiftlang`, the Swift Server Work Group, and similarly trusted core Swift projects when they simplify the code and make it easier to reason about.
-- Commonly approved examples include `swift-configuration` and `swift-async-algorithms` when they reduce bespoke code and improve readability. New Swift packages should include `swift-configuration` by default with the `Configuration` product and package traits `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments` unless the package has a concrete reason to remove that dependency.
+- Commonly approved examples include `swift-configuration` and `swift-async-algorithms` when they reduce bespoke code and improve readability. New Swift packages should include `swift-configuration` by default with the `Configuration` product and package traits `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments` unless the package has a concrete reason to remove that dependency. The `PropertyList` trait is also available when property-list configuration parsing is needed, and the `Logging` trait is available when configuration access should integrate with `SwiftLog.Logger`.
 - For packages, server-side, or cross-platform Swift, prefer Swift Logging as the primary logging API.
 - Prefer Swift OpenTelemetry for telemetry and instrumentation when telemetry is needed, and prefer existing ecosystem integrations over bespoke wrappers.
 - Prefer a checked-in repo-root `.swiftformat` file as the default Swift formatting source of truth, and prefer a pre-commit hook that formats staged Swift sources and then verifies them with `swiftformat --lint` before commit.
@@ -60,7 +60,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Prefer `swift package` subcommands for dependency, target, and manifest-adjacent changes before hand-editing `Package.swift`.
 - Edit `Package.swift` intentionally and keep it readable; agents may modify it when package structure, targets, products, or dependencies need to change, and should try to keep package graph updates consolidated in one change when possible.
 - Keep `Package.swift` explicit about its package-wide Swift language mode. On current Swift 6-era manifests, prefer `swiftLanguageModes: [.v6]` as the default declaration, treat `swiftLanguageVersions` as a legacy alias used only when an older manifest surface requires it, and remember that lowering the manifest's `// swift-tools-version:` from the bootstrap default is often appropriate when the package should support an older Swift 6 toolchain, but never below `6.1` while trait-enabled dependencies remain in the manifest.
-- Keep dependency manifests aligned with the default `swift-configuration` baseline unless the package has a concrete reason to remove it: depend on `https://github.com/apple/swift-configuration` from `1.2.0`, enable the `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments` package traits, and add the `Configuration` product to the primary target.
+- Keep dependency manifests aligned with the default `swift-configuration` baseline unless the package has a concrete reason to remove it: depend on `https://github.com/apple/swift-configuration` from `1.2.0`, enable the `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments` package traits, and add the `Configuration` product to the primary target. Add the `PropertyList` trait when the package should parse property-list configuration, and add the `Logging` trait when configuration access should integrate with `SwiftLog.Logger`.
 - Keep dependency provenance concise but explicit enough for another contributor to fetch the same package: use package-manager, package-registry, GitHub URL, or other real remote repository requirements, and do not commit machine-local dependency paths such as `/Users/...`, `~/...`, `../...`, local worktrees, or private checkout paths. Avoid branch- or revision-based requirements unless the user explicitly asks for that level of control.
 - Treat `Package.resolved` and similar package-manager outputs as generated files; do not hand-edit them.
 - Keep package resources under the owning target directory, typically below `Sources/<TargetName>/Resources` or `Tests/<TargetName>Tests/Resources`, so target membership stays obvious.

skills/bootstrap-swift-package/assets/AGENTS.md

@@ -23,7 +23,7 @@
 - For package configuration not covered by CLI commands, update `Package.swift` intentionally and keep edits minimal.
 - Edit `Package.swift` intentionally and keep it readable; agents may modify it when package structure, targets, products, or dependencies need to change, and should try to keep package graph updates consolidated in one change when possible.
 - Keep `Package.swift` explicit about its package-wide Swift language mode. On current Swift 6-era manifests, prefer `swiftLanguageModes: [.v6]` as the default declaration, treat `swiftLanguageVersions` as a legacy alias used only when an older manifest surface requires it, and remember that lowering the manifest's `// swift-tools-version:` from the bootstrap default is often appropriate when the package should support an older Swift 6 toolchain, but never below `6.1` while trait-enabled dependencies remain in the manifest.
-- Keep `swift-configuration` as the default configuration dependency for new packages unless the package has a concrete reason to remove it. The generated manifest should depend on `https://github.com/apple/swift-configuration` from `1.2.0`, enable the `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments` package traits, and add the `Configuration` product to the primary target.
+- Keep `swift-configuration` as the default configuration dependency for new packages unless the package has a concrete reason to remove it. The generated manifest should depend on `https://github.com/apple/swift-configuration` from `1.2.0`, enable the `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments` package traits, and add the `Configuration` product to the primary target. Add the `PropertyList` trait when the package should parse property-list configuration, and add the `Logging` trait when configuration access should integrate with `SwiftLog.Logger`.
 - Keep dependency provenance concise but explicit enough for another contributor to fetch the same package: use package-manager, package-registry, GitHub URL, or other real remote repository requirements, and do not commit machine-local dependency paths such as `/Users/...`, `~/...`, `../...`, local worktrees, or private checkout paths. Avoid branch- or revision-based requirements unless the user explicitly asks for that level of control.
 - Treat `Package.resolved` and similar package-manager outputs as generated files; do not hand-edit them.
 - Validate package changes with:

skills/bootstrap-swift-package/references/automation-prompts.md

@@ -91,6 +91,7 @@ Verification:
 - Confirm `Package.swift` keeps the explicit Swift 6 language-mode declaration `swiftLanguageModes: [.v6]`.
 - Confirm `Package.swift` keeps `// swift-tools-version:` at `6.1` or newer while the trait-enabled `swift-configuration` dependency remains in the manifest, even if it is lowered from the scaffold default.
 - Confirm `Package.swift` includes `swift-configuration` from `1.2.0`, enables `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments`, and adds the `Configuration` product to the primary target.
+- Confirm the generated guidance notes that `PropertyList` is available for property-list configuration parsing and `Logging` is available for `SwiftLog.Logger` integration.
 - If validation is enabled, verify `swift build` and `swift test` success.
 - If branch protection is configured, require the GitHub Actions check context `validate`, not `Validate Repo Maintenance / validate`.
 

skills/bootstrap-swift-package/references/package-types.md

@@ -38,6 +38,8 @@ The generated manifest should include `swift-configuration` by default:
 - dependency traits: `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments`
 - primary target product: `.product(name: "Configuration", package: "swift-configuration")`
 
+The `PropertyList` trait is also available when a package should parse property-list configuration, and the `Logging` trait is available when configuration access should integrate with `SwiftLog.Logger`.
+
 ## Testing Modes
 
 - Supported and validated Swift toolchain floor: `6.1+`.

skills/bootstrap-swift-package/references/snippets/apple-swift-package-core.md

@@ -47,7 +47,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - For asynchronous event-driven tests in Swift Testing, prefer `confirmation(...)` with an explicit expected count or count range instead of ad hoc sleeps or polling loops.
 - Keep XCTest for integration points that still require it, for legacy package surfaces that have not migrated yet, or when a dependency or platform toolchain still expects XCTest.
 - Prefer first-party and top-tier Swift ecosystem packages from Apple, `swiftlang`, the Swift Server Work Group, and similarly trusted core Swift projects when they simplify the code and make it easier to reason about.
-- Commonly approved examples include `swift-configuration` and `swift-async-algorithms` when they reduce bespoke code and improve readability. New Swift packages should include `swift-configuration` by default with the `Configuration` product and package traits `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments` unless the package has a concrete reason to remove that dependency.
+- Commonly approved examples include `swift-configuration` and `swift-async-algorithms` when they reduce bespoke code and improve readability. New Swift packages should include `swift-configuration` by default with the `Configuration` product and package traits `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments` unless the package has a concrete reason to remove that dependency. The `PropertyList` trait is also available when property-list configuration parsing is needed, and the `Logging` trait is available when configuration access should integrate with `SwiftLog.Logger`.
 - For packages, server-side, or cross-platform Swift, prefer Swift Logging as the primary logging API.
 - Prefer Swift OpenTelemetry for telemetry and instrumentation when telemetry is needed, and prefer existing ecosystem integrations over bespoke wrappers.
 - Prefer a checked-in repo-root `.swiftformat` file as the default Swift formatting source of truth, and prefer a pre-commit hook that formats staged Swift sources and then verifies them with `swiftformat --lint` before commit.
@@ -60,7 +60,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Prefer `swift package` subcommands for dependency, target, and manifest-adjacent changes before hand-editing `Package.swift`.
 - Edit `Package.swift` intentionally and keep it readable; agents may modify it when package structure, targets, products, or dependencies need to change, and should try to keep package graph updates consolidated in one change when possible.
 - Keep `Package.swift` explicit about its package-wide Swift language mode. On current Swift 6-era manifests, prefer `swiftLanguageModes: [.v6]` as the default declaration, treat `swiftLanguageVersions` as a legacy alias used only when an older manifest surface requires it, and remember that lowering the manifest's `// swift-tools-version:` from the bootstrap default is often appropriate when the package should support an older Swift 6 toolchain, but never below `6.1` while trait-enabled dependencies remain in the manifest.
-- Keep dependency manifests aligned with the default `swift-configuration` baseline unless the package has a concrete reason to remove it: depend on `https://github.com/apple/swift-configuration` from `1.2.0`, enable the `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments` package traits, and add the `Configuration` product to the primary target.
+- Keep dependency manifests aligned with the default `swift-configuration` baseline unless the package has a concrete reason to remove it: depend on `https://github.com/apple/swift-configuration` from `1.2.0`, enable the `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments` package traits, and add the `Configuration` product to the primary target. Add the `PropertyList` trait when the package should parse property-list configuration, and add the `Logging` trait when configuration access should integrate with `SwiftLog.Logger`.
 - Keep dependency provenance concise but explicit enough for another contributor to fetch the same package: use package-manager, package-registry, GitHub URL, or other real remote repository requirements, and do not commit machine-local dependency paths such as `/Users/...`, `~/...`, `../...`, local worktrees, or private checkout paths. Avoid branch- or revision-based requirements unless the user explicitly asks for that level of control.
 - Treat `Package.resolved` and similar package-manager outputs as generated files; do not hand-edit them.
 - Keep package resources under the owning target directory, typically below `Sources/<TargetName>/Resources` or `Tests/<TargetName>Tests/Resources`, so target membership stays obvious.

skills/swift-package-build-run-workflow/references/snippets/apple-swift-package-core.md

@@ -47,7 +47,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - For asynchronous event-driven tests in Swift Testing, prefer `confirmation(...)` with an explicit expected count or count range instead of ad hoc sleeps or polling loops.
 - Keep XCTest for integration points that still require it, for legacy package surfaces that have not migrated yet, or when a dependency or platform toolchain still expects XCTest.
 - Prefer first-party and top-tier Swift ecosystem packages from Apple, `swiftlang`, the Swift Server Work Group, and similarly trusted core Swift projects when they simplify the code and make it easier to reason about.
-- Commonly approved examples include `swift-configuration` and `swift-async-algorithms` when they reduce bespoke code and improve readability. New Swift packages should include `swift-configuration` by default with the `Configuration` product and package traits `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments` unless the package has a concrete reason to remove that dependency.
+- Commonly approved examples include `swift-configuration` and `swift-async-algorithms` when they reduce bespoke code and improve readability. New Swift packages should include `swift-configuration` by default with the `Configuration` product and package traits `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments` unless the package has a concrete reason to remove that dependency. The `PropertyList` trait is also available when property-list configuration parsing is needed, and the `Logging` trait is available when configuration access should integrate with `SwiftLog.Logger`.
 - For packages, server-side, or cross-platform Swift, prefer Swift Logging as the primary logging API.
 - Prefer Swift OpenTelemetry for telemetry and instrumentation when telemetry is needed, and prefer existing ecosystem integrations over bespoke wrappers.
 - Prefer a checked-in repo-root `.swiftformat` file as the default Swift formatting source of truth, and prefer a pre-commit hook that formats staged Swift sources and then verifies them with `swiftformat --lint` before commit.
@@ -60,7 +60,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Prefer `swift package` subcommands for dependency, target, and manifest-adjacent changes before hand-editing `Package.swift`.
 - Edit `Package.swift` intentionally and keep it readable; agents may modify it when package structure, targets, products, or dependencies need to change, and should try to keep package graph updates consolidated in one change when possible.
 - Keep `Package.swift` explicit about its package-wide Swift language mode. On current Swift 6-era manifests, prefer `swiftLanguageModes: [.v6]` as the default declaration, treat `swiftLanguageVersions` as a legacy alias used only when an older manifest surface requires it, and remember that lowering the manifest's `// swift-tools-version:` from the bootstrap default is often appropriate when the package should support an older Swift 6 toolchain, but never below `6.1` while trait-enabled dependencies remain in the manifest.
-- Keep dependency manifests aligned with the default `swift-configuration` baseline unless the package has a concrete reason to remove it: depend on `https://github.com/apple/swift-configuration` from `1.2.0`, enable the `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments` package traits, and add the `Configuration` product to the primary target.
+- Keep dependency manifests aligned with the default `swift-configuration` baseline unless the package has a concrete reason to remove it: depend on `https://github.com/apple/swift-configuration` from `1.2.0`, enable the `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments` package traits, and add the `Configuration` product to the primary target. Add the `PropertyList` trait when the package should parse property-list configuration, and add the `Logging` trait when configuration access should integrate with `SwiftLog.Logger`.
 - Keep dependency provenance concise but explicit enough for another contributor to fetch the same package: use package-manager, package-registry, GitHub URL, or other real remote repository requirements, and do not commit machine-local dependency paths such as `/Users/...`, `~/...`, `../...`, local worktrees, or private checkout paths. Avoid branch- or revision-based requirements unless the user explicitly asks for that level of control.
 - Treat `Package.resolved` and similar package-manager outputs as generated files; do not hand-edit them.
 - Keep package resources under the owning target directory, typically below `Sources/<TargetName>/Resources` or `Tests/<TargetName>Tests/Resources`, so target membership stays obvious.