chore: improve compatibility and release readiness

CHANGELOG.md

@@ -6,13 +6,17 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.1.0] - 2026-08-30
+
 ### Added
 
 - Windows CI for installer, agent validators, unit tests, PowerShell parsing, and TOML parsing.
 - Installer and private-overlay regression tests.
 - Standalone documentation and static contract tests for `_factbot` and `_mantou`.
 - Repository-wide validation for local Markdown links, structured data, and common privacy leaks.
 - Contribution, security, issue, pull-request, and dependency-update configuration.
+- Runtime and model compatibility guidance plus a maintainer release checklist.
+- Installer `-WhatIf` support for previewing forced updates without changing files.
 
 ### Changed
 

COMPATIBILITY.md

@@ -0,0 +1,28 @@
+# Compatibility
+
+This package contains Codex custom-agent configuration and supporting files. Local validation confirms repository structure and syntax; model availability and product features still depend on the user's Codex workspace.
+
+## Runtime requirements
+
+- Codex must support custom agents with `model`, `model_reasoning_effort`, and `sandbox_mode` configuration fields.
+- `_factbot` and `_manuel` request `gpt-5.6-terra`; `_invest` and `_mantou` request `gpt-5.6-sol`. Installation does not grant access to either model.
+- PowerShell is required for installation and the repository validation entry points.
+- Python 3.11 or later is required for static validators and unit tests.
+- `_mantou` requires a Windows interactive session with `Set-Clipboard` and `Get-Clipboard` available.
+- `_invest` can optionally route approved writes to Obsidian. Its local vault path is supplied outside the public package.
+
+## Portability
+
+If a configured model is unavailable, choose an accessible model with equivalent tool and reasoning support, update the relevant TOML file, and run `./tests/validate_repository.ps1` before installation. Treat that change as a local compatibility override unless the repository's supported defaults are intentionally being changed.
+
+The default CI exercises Windows with Python 3.11 and 3.13. It does not call paid model services or perform live behavioral evaluation.
+
+## Upgrade check
+
+Before upgrading Codex or this package:
+
+1. run `./install.ps1 -Force -WhatIf` to preview managed targets;
+2. review the changelog and agent-specific behavior changes;
+3. run `./tests/validate_repository.ps1`;
+4. install with `-Force`, then restart Codex;
+5. exercise each agent with a non-sensitive smoke test before relying on it for substantive work.

README.md

@@ -34,6 +34,12 @@ The installer copies the agent configuration files and support libraries to `$en
 ./install.ps1 -Force
 ```
 
+Preview a forced update without changing the target directory:
+
+```powershell
+./install.ps1 -Force -WhatIf
+```
+
 `-Force` updates only files managed by this package at their existing relative
 paths. It does not remove unmanaged local files such as
 `agents/_invest/knowledge-map.local.md`.
@@ -50,6 +56,8 @@ Maintainers can run the complete local validation suite with
 
 Restart Codex after installation so the custom-agent list is reloaded.
 
+Before installation, review [`COMPATIBILITY.md`](COMPATIBILITY.md) for model access, platform, and runtime requirements. The package validates configuration syntax locally, but it cannot grant access to a model that is unavailable in the user's Codex workspace.
+
 ## Usage
 
 Ask Codex to call the relevant agent:
@@ -68,6 +76,8 @@ See [`agents/_manuel/README.md`](agents/_manuel/README.md) and [`agents/_invest/
 - [`CONTRIBUTING.md`](CONTRIBUTING.md): validation, change, and release policy.
 - [`SECURITY.md`](SECURITY.md): private security and privacy reporting.
 - [`CHANGELOG.md`](CHANGELOG.md): repository-wide change history.
+- [`COMPATIBILITY.md`](COMPATIBILITY.md): supported runtime assumptions and portability notes.
+- [`RELEASING.md`](RELEASING.md): maintainer release checklist.
 - [`AGENTS.md`](AGENTS.md): constraints for automated repository maintenance.
 
 ## Source and copyright note

RELEASING.md

@@ -0,0 +1,15 @@
+# Releasing
+
+Releases use Semantic Versioning and copy their user-visible notes from `CHANGELOG.md`.
+
+## Checklist
+
+1. Confirm the intended version and move relevant entries from `Unreleased` to a dated version section.
+2. Review model identifiers and the assumptions in `COMPATIBILITY.md` against current official Codex documentation.
+3. Run `./tests/validate_repository.ps1` from a clean checkout.
+4. Confirm the `Validate` workflow succeeds on the exact release commit.
+5. Create a signed or annotated `vMAJOR.MINOR.PATCH` tag.
+6. Create the GitHub Release from that tag, copy the changelog notes, and include any migration steps.
+7. Test a clean installation from the released archive without using private overlays or credentials.
+
+Do not publish a release while required validation is skipped, a model identifier is known to be unavailable to the intended audience, or private material appears in the diff or archive.

install.ps1

@@ -1,4 +1,4 @@
-[CmdletBinding()]
+[CmdletBinding(SupportsShouldProcess)]
 param(
     [switch]$Force
 )
@@ -33,6 +33,11 @@ foreach ($item in $items) {
     }
 }
 
+if (-not $PSCmdlet.ShouldProcess($targetRoot, "Install managed Codex agent files")) {
+    Write-Host "No files changed. Target would be $targetRoot"
+    return
+}
+
 New-Item -ItemType Directory -Path $targetRoot -Force | Out-Null
 
 # Copy managed files to their exact relative paths. Copying a directory onto an

tests/validate_install.ps1

@@ -48,6 +48,16 @@ try {
     Assert-True (-not (Test-Path -LiteralPath (Join-Path $cleanRoot 'agents/_invest/_invest'))) 'Force update created nested _invest/_invest.'
     Assert-True (-not (Test-Path -LiteralPath (Join-Path $cleanRoot 'agents/_manuel/_manuel'))) 'Force update created nested _manuel/_manuel.'
 
+    $managedTarget = Join-Path $cleanRoot 'agents/_mantou.toml'
+    Set-Content -LiteralPath $managedTarget -Value 'local-managed-change' -Encoding utf8
+    $beforeWhatIf = (Get-FileHash -LiteralPath $managedTarget -Algorithm SHA256).Hash
+    & $installer -Force -WhatIf
+    $afterWhatIf = (Get-FileHash -LiteralPath $managedTarget -Algorithm SHA256).Hash
+    Assert-True ($beforeWhatIf -eq $afterWhatIf) '-WhatIf changed a managed target file.'
+    & $installer -Force
+    Assert-ManagedFilesMatch $cleanRoot
+    Assert-True ((Get-Content -Raw -LiteralPath $overlay).Trim() -eq 'private-local-overlay') 'Update after -WhatIf changed the private overlay.'
+
     $partialRoot = Join-Path $testRoot 'partial'
     $partialInvest = Join-Path $partialRoot 'agents/_invest'
     New-Item -ItemType Directory -Path $partialInvest -Force | Out-Null
@@ -67,6 +77,7 @@ try {
     Write-Host 'INSTALL VALIDATION PASSED'
     Write-Host '- clean installation matches all packaged files'
     Write-Host '- forced update is idempotent and preserves private overlays'
+    Write-Host '- WhatIf previews a forced update without changing managed files'
     Write-Host '- collision preflight performs no partial installation'
 }
 finally {