ci: aggregate package validation and align documentation identity

.github/workflows/real-codex-binary.yml

@@ -1,10 +1,14 @@
 name: Real Codex Binary
 
 on:
-  push:
-    branches: [master]
-  pull_request:
-    branches: [master]
+  workflow_call:
+    inputs:
+      codex_version:
+        type: string
+        default: '0.154.0'
+      mcp_codex_version:
+        type: string
+        default: '0.139.0'
   workflow_dispatch:
     inputs:
       codex_version:

.github/workflows/swift-package.yml

@@ -11,6 +11,37 @@ permissions:
   contents: read
 
 jobs:
+  policy:
+    if: github.event_name == 'pull_request' || github.event_name == 'push'
+    uses: swift-library/.github/.github/workflows/policy.yml@7badcc53166c6afcb265b39c789b8240d9a30233
+    with:
+      allow-terms: Codex
+
+  integration:
+    uses: ./.github/workflows/real-codex-binary.yml
+
+  result:
+    needs: [policy, windows, windows-runtime, quality, build-and-test, integration]
+    if: always()
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Require all package checks to succeed
+        env:
+          RESULTS: ${{ toJSON(needs) }}
+          EVENT: ${{ github.event_name }}
+        run: |
+          python3 - <<'PY'
+          import json, os
+          jobs = json.loads(os.environ['RESULTS'])
+          failed = []
+          for name, job in jobs.items():
+              expected = 'skipped' if name == 'policy' and os.environ['EVENT'] == 'workflow_dispatch' else 'success'
+              if job['result'] != expected:
+                  failed.append(name)
+          if failed:
+              raise SystemExit('Validation did not succeed: ' + ', '.join(failed))
+          PY
+
   windows:
     name: Windows products
     runs-on: windows-2022

AGENTS.md

@@ -49,3 +49,31 @@ Scripts/verify-documentation.sh
 
 Use the pinned Codex CLI version for opt-in App Server and MCP integration
 tests before a release.
+
+## Code Review Rules
+
+### Compatibility and versioning
+
+- Flag a change to public API or observable behavior, including a raised
+  minimum platform or Swift version, without a `CHANGELOG.md` entry or a release version
+  consistent with `RELEASING.md`. Safe path: record the change under the next
+  version and follow that compatibility policy.
+
+### Claims
+
+- Flag README, DocC, or release-note statements that the code and tests do
+  not support: capabilities that do not exist, existing behavior described as
+  new, or platforms CI does not build. Safe path: describe what the code
+  shows.
+
+### Public documentation
+
+- Flag a new public symbol without a documentation comment, and public prose
+  that compares the package with other projects or describes internal
+  process. Safe path: document the symbol, and describe only this package's
+  own behavior.
+
+### Tests
+
+- Flag a behavior change without a test that would fail before the change.
+  Safe path: add the test beside the existing suite for that behavior.

CHANGELOG.md

@@ -157,7 +157,8 @@ follows [Semantic Versioning](https://semver.org/) beginning with `0.1.0`.
 - Deterministic Swift Testing coverage, API inventory, schema verification, and
   opt-in real Codex binary validation.
 
-[Unreleased]: https://github.com/swift-library/swift-codex/compare/v0.4.1...HEAD
+[Unreleased]: https://github.com/swift-library/swift-codex/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/swift-library/swift-codex/compare/v0.4.1...v0.5.0
 [0.4.1]: https://github.com/swift-library/swift-codex/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/swift-library/swift-codex/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/swift-library/swift-codex/compare/v0.2.2...v0.3.0

RELEASING.md

@@ -67,14 +67,20 @@ Before tagging:
    machine-local paths are not tracked.
 6. Resolve and build a fresh consumer without this repository's `.build` or a
    sibling checkout.
-7. Confirm the worktree is clean and all required checks are green.
+7. Open a pull request for the release preparation branch. Address or answer
+   review findings and confirm all required checks pass before squash-merging
+   the reviewed head. Follow the organization's
+   [PR workflow](https://github.com/swift-library/.github/blob/master/MAINTENANCE.md).
+8. Fetch the merged default branch and verify the clean merged candidate and
+   its required checks before tagging. Use that accepted commit for the tag.
 
-Create and push the release only after review:
+Set `release_tag` to the intended immutable `vMAJOR.MINOR.PATCH` tag and
+`accepted_commit` to the validated merged commit. Create a signed annotated
+tag only after the above acceptance:
 
 ```sh
-git push origin master
-git tag -s -a v0.1.0 -m "swift-codex 0.1.0"
-git push origin v0.1.0
+git tag -s -a "$release_tag" "$accepted_commit" -m "swift-codex $release_tag"
+git push origin "$release_tag"
 ```
 
 After publishing, check out the remote tag in an empty directory and repeat

Scripts/verify-public-repository.sh

@@ -133,8 +133,15 @@ if repository_content_files_null ':(exclude)Vendor/**' | xargs -0 rg -n --no-mes
 fi
 
 while IFS= read -r use_line; do
-  [[ "$use_line" =~ uses:[[:space:]]+[^[:space:]@]+@[0-9a-fA-F]{40}([[:space:]]|$) ]] \
-    || fail "GitHub Actions must be pinned to a full commit SHA: $use_line"
+  # Local reusable workflows execute from the caller's commit.
+  if [[ "$use_line" =~ uses:[[:space:]]+\./(\.github/workflows/[A-Za-z0-9_.-]+\.ya?ml)[[:space:]]*$ ]]; then
+    local_workflow="${BASH_REMATCH[1]}"
+    [[ -f "$local_workflow" ]] && git ls-files --error-unmatch "$local_workflow" >/dev/null \
+      || fail "Local reusable workflow must be tracked: $use_line"
+  else
+    [[ "$use_line" =~ uses:[[:space:]]+[^[:space:]@]+@[0-9a-fA-F]{40}([[:space:]]|$) ]] \
+      || fail "External GitHub Actions must be pinned to a full commit SHA: $use_line"
+  fi
 done < <(rg --no-filename '^\s*-?\s*uses:' .github/workflows || true)
 
 if [[ "$(find Sources -type d -name '*.docc' | wc -l | tr -d ' ')" != "11" ]]; then

Sources/Codex/Documentation.docc/Codex.md

@@ -1,5 +1,10 @@
 # ``Codex``
 
+@Metadata {
+  @PageImage(purpose: icon, source: "codex-icon", alt: "swift-codex logo")
+  @PageColor(purple)
+}
+
 Use Codex through SDK-style Swift threads and streamed or buffered turns.
 
 ## Overview

Sources/CodexAppServerClient/Documentation.docc/CodexAppServerClient.md

@@ -1,5 +1,10 @@
 # ``CodexAppServerClient``
 
+@Metadata {
+  @PageImage(purpose: icon, source: "codexappserverclient-icon", alt: "swift-codex logo")
+  @PageColor(purple)
+}
+
 Call an upstream Codex AppServer through typed bindings or complete JSON messages.
 
 ## Overview

Sources/CodexAppServerHummingbird/Documentation.docc/CodexAppServerHummingbird.md

@@ -1,5 +1,10 @@
 # ``CodexAppServerHummingbird``
 
+@Metadata {
+  @PageImage(purpose: icon, source: "codexappserverhummingbird-icon", alt: "swift-codex logo")
+  @PageColor(purple)
+}
+
 Expose a downstream AppServer-compatible WebSocket route through Hummingbird.
 
 ## Overview

Sources/CodexAppServerNIO/Documentation.docc/CodexAppServerNIO.md

@@ -1,5 +1,10 @@
 # ``CodexAppServerNIO``
 
+@Metadata {
+  @PageImage(purpose: icon, source: "codexappservernio-icon", alt: "swift-codex logo")
+  @PageColor(purple)
+}
+
 Connect to a Codex AppServer WebSocket endpoint with SwiftNIO.
 
 ## Overview

Sources/CodexAppServerProtocol/Documentation.docc/CodexAppServerProtocol.md

@@ -1,5 +1,10 @@
 # ``CodexAppServerProtocol``
 
+@Metadata {
+  @PageImage(purpose: icon, source: "codexappserverprotocol-icon", alt: "swift-codex logo")
+  @PageColor(purple)
+}
+
 Use generated stable and experimental Codex AppServer protocol models.
 
 ## Overview

Sources/CodexAppServerRuntime/Documentation.docc/CodexAppServerRuntime.md

@@ -1,5 +1,10 @@
 # ``CodexAppServerRuntime``
 
+@Metadata {
+  @PageImage(purpose: icon, source: "codexappserverruntime-icon", alt: "swift-codex logo")
+  @PageColor(purple)
+}
+
 Build schema-independent Codex AppServer sessions and transports.
 
 ## Overview

Sources/CodexAppServerStdio/Documentation.docc/CodexAppServerStdio.md

@@ -1,5 +1,10 @@
 # ``CodexAppServerStdio``
 
+@Metadata {
+  @PageImage(purpose: icon, source: "codexappserverstdio-icon", alt: "swift-codex logo")
+  @PageColor(purple)
+}
+
 Launch and connect to a local `codex app-server` process over stdio.
 
 ## Overview

Sources/CodexAppServerURLSession/Documentation.docc/CodexAppServerURLSession.md

@@ -1,5 +1,10 @@
 # ``CodexAppServerURLSession``
 
+@Metadata {
+  @PageImage(purpose: icon, source: "codexappserverurlsession-icon", alt: "swift-codex logo")
+  @PageColor(purple)
+}
+
 Connect to a Codex AppServer WebSocket endpoint with Foundation URLSession.
 
 ## Overview

Sources/CodexAppServerVapor/Documentation.docc/CodexAppServerVapor.md

@@ -1,5 +1,10 @@
 # ``CodexAppServerVapor``
 
+@Metadata {
+  @PageImage(purpose: icon, source: "codexappservervapor-icon", alt: "swift-codex logo")
+  @PageColor(purple)
+}
+
 Expose a downstream AppServer-compatible WebSocket route through Vapor.
 
 ## Overview

Sources/CodexExec/Documentation.docc/CodexExec.md

@@ -1,5 +1,10 @@
 # ``CodexExec``
 
+@Metadata {
+  @PageImage(purpose: icon, source: "codexexec-icon", alt: "swift-codex logo")
+  @PageColor(purple)
+}
+
 Run `codex exec` and `codex exec resume` through a typed Swift process boundary.
 
 ## Overview

Sources/CodexMCP/Documentation.docc/CodexMCP.md

@@ -1,5 +1,10 @@
 # ``CodexMCP``
 
+@Metadata {
+  @PageImage(purpose: icon, source: "codexmcp-icon", alt: "swift-codex logo")
+  @PageColor(purple)
+}
+
 Integrate with the upstream `codex mcp-server` process.
 
 ## Overview