release: prepare v1.3.1

[gaelic-ghost]

Release

• prepares v1.3.1 from branch startup/ergonomic-startup-errors
• keeps protected main updates behind pull request review and CI
• release tag v1.3.1 was created locally before this PR so the reviewed release candidate is preserved exactly

Review Loop

Before merge, scripts/repo-maintenance/release.sh watches CI and stops on review comments unless the maintainer has already addressed or resolved them and reruns with --review-comments-addressed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ce1b0a7b-ef74-4fa0-b6f0-882b21e792d0

📥 Commits

Reviewing files that changed from the base of the PR and between 2b30c51 and 6a927d2.

📒 Files selected for processing (1)

• Sources/SwiftASB/SwiftASB.docc/GettingStartedWithSwiftASB.md

✅ Files skipped from review due to trivial changes (1)

• Sources/SwiftASB/SwiftASB.docc/GettingStartedWithSwiftASB.md

---

📝 Walkthrough

Walkthrough

This PR introduces an ergonomic one-call startup API for CodexAppServer, bundled with v1.3.1 release updates. The new start(_: StartupRequest) overload orchestrates subprocess launch, CLI compatibility validation, and initialization in a single call, returning a typed StartupSession result or CodexAppServerStartupError exception.

Changes

Ergonomic Startup API

Layer / File(s)	Summary
Bootstrap API Data Shapes Sources/SwiftASB/Public/CodexAppServer+Bootstrap.swift	Adds StartupCompatibilityPolicy enum (requires vs. allows outside reviewed window), StartupRequest struct with compatibilityPolicy and initializeRequest, and StartupSession struct carrying diagnostics and session result.
Startup Error Type Sources/SwiftASB/Public/CodexErrors.swift	Introduces CodexAppServerStartupError enum with five cases (CLI discovery, incompatibility, unknown version, launch failure, initialize failure), localized descriptions, and internal error mappers startFailure(from:) and initializeFailure(from:).
Startup Implementation Sources/SwiftASB/Public/CodexAppServer.swift	Refactors start() to delegate transport startup to private startTransport() helper; reworks start(_ request: StartupRequest) to orchestrate transport startup, CLI diagnostics fetch, compatibility validation, and initialize call; maps failures to typed CodexAppServerStartupError cases.
API Reference Documentation Sources/SwiftASB/SwiftASB.docc/CodexAppServer.md	Documents start(_:) as the normal end-to-end startup path with StartupRequest and StartupSession contracts; contrasts with lower-level start() + initialize(_:) ownership pattern; updates Startup topic index.
Getting Started Guide Sources/SwiftASB/SwiftASB.docc/GettingStartedWithSwiftASB.md	Updates example code to use start(_:) with defer-based shutdown; prints CLI version from returned session; expands "Startup Order" section explaining start(_:) behavior, early-failure error handling, and lower-level ownership guidance.
Test Support Enhancements Tests/SwiftASBTests/Public/CodexAppServerTestSupport.swift	Adds startError parameter to FakeCodexAppServerTransport initializer; start() throws configured error when present; adds isStarted computed property.
Startup Request Tests Tests/SwiftASBTests/Public/CodexAppServerTests.swift	Four new tests: successful StartupRequest flow with transport verification; typed error for incompatible Codex CLI version; policy override allowing outside-window CLI; typed error when executable discovery fails.
Release Documentation README.md, ROADMAP.md, docs/maintainers/v1-public-api-audit.md	Updates version references from v1.3.0 to v1.3.1 across status, dependency snippet, SPI recheck, priority baseline, readiness checklist, documentation tasks, packaging verification, migration guidance, post-V1 work, and audit cutoff boundary.

---

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

---

Suggested labels

enhancement

---

Poem

🐰 A startup made graceful, one call instead of two,
With policies, diagnostics, and errors framed true,
From bootstrap to session the flow hops along,
Docs and tests sing the same cheerful song,
Hooray for v1.3.1 — a rabbit's tiny song!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'release: prepare v1.3.1' directly and clearly describes the primary change—preparing the v1.3.1 release across documentation, public APIs, and tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch startup/ergonomic-startup-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@README.md`:
- Line 26: The README currently states "v1.3.1" as the current and latest
release; change that sentence (the line containing "SwiftASB is actively
maintained..." and the literal "v1.3.1") to avoid asserting the tag is
published—e.g., say the API is v1 and that "v1.3.1 is the intended/upcoming
release" or "latest release (v1.3.1) pending publication" and only merge the
definitive "latest" phrasing after the tag is actually published.

In `@Sources/SwiftASB/SwiftASB.docc/GettingStartedWithSwiftASB.md`:
- Around line 56-57: Update the wording to clarify ownership of compatibility
policy: state that compatibility policy is configured on the StartupRequest
passed to CodexAppServer/start(_:) (not via initialize(_:)), and that the
lower-level start() + initialize(_:) path is useful when the client
intentionally owns each startup step (custom compatibility policy provided via
StartupRequest, diagnostics-only startup screens, or tests that inspect the
selected binary before deciding whether to initialize). Refer to
CodexAppServer/start(_:) and CodexAppServer/initialize(_:) and the
StartupRequest type in the revised sentence.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fd68b831-8df1-42b8-9d96-04c7ce742803

📥 Commits

Reviewing files that changed from the base of the PR and between a7db7e6 and 2b30c51.

📒 Files selected for processing (10)

• README.md
• ROADMAP.md
• Sources/SwiftASB/Public/CodexAppServer+Bootstrap.swift
• Sources/SwiftASB/Public/CodexAppServer.swift
• Sources/SwiftASB/Public/CodexErrors.swift
• Sources/SwiftASB/SwiftASB.docc/CodexAppServer.md
• Sources/SwiftASB/SwiftASB.docc/GettingStartedWithSwiftASB.md
• Tests/SwiftASBTests/Public/CodexAppServerTestSupport.swift
• Tests/SwiftASBTests/Public/CodexAppServerTests.swift
• docs/maintainers/v1-public-api-audit.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Avoid presenting v1.3.1 as already released before the tag is published.

These lines can briefly break user onboarding if the tag isn’t live yet (install command fails and “latest release” is inaccurate). Consider wording this as pending until publication, or merge this text only once the tag/release is public.

Suggested wording tweak

-SwiftASB is actively maintained and supported by Gale. Our current API is v1, and `v1.3.1` is the current and latest release.
+SwiftASB is actively maintained and supported by Gale. Our current API is v1.
+The next release is `v1.3.1` (update this line to “latest release” once published).

-.package(url: "https://github.com/gaelic-ghost/SwiftASB", from: "1.3.1"),
+.package(url: "https://github.com/gaelic-ghost/SwiftASB", from: "1.3.1"), // after v1.3.1 is published

As per coding guidelines, README.md: "Keep the README product-facing and approachable for package users and their agents".

Also applies to: 41-41

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` at line 26, The README currently states "v1.3.1" as the current
and latest release; change that sentence (the line containing "SwiftASB is
actively maintained..." and the literal "v1.3.1") to avoid asserting the tag is
published—e.g., say the API is v1 and that "v1.3.1 is the intended/upcoming
release" or "latest release (v1.3.1) pending publication" and only merge the
definitive "latest" phrasing after the tag is actually published.