docs(readme): document rule skills, managed manifest, and installer params

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

README.md

@@ -16,10 +16,17 @@ into platform-specific packages that can be inspected before they are installed.
 - One shared source of truth for Codex and Claude Code.
 - Separate generated packages for Windows and Linux.
 - Native PowerShell 5.1 and Bash scripts.
-- Interactive installation for Codex, Claude Code, or both.
+- Interactive or non-interactive (`-Client`/`-Platform`) installation for Codex, Claude Code, or both.
-- Dry-run support and timestamped backups of replaced managed files.
+- Claude Code loads technology- and situation-specific rules as skills, so only their name and description sit
+  permanently in context; the full rule text loads only when the skill is invoked. Codex keeps loading rules as plain
+  files, unchanged.
+- A managed-file manifest (path and SHA-256 per destination) makes installation idempotent, detects files this setup
+  previously installed but no longer ships, and protects files a user changed locally instead of silently overwriting
+  or deleting them.
+- Dry-run support (no writes, no backups, no plugin changes) and timestamped, per-run backup directories.
 - Shared safety, notification, validation, and status-line hooks.
-- User-level plugin installation and updates for Ponytail, i-have-adhd, Superpowers, and Context7.
+- User-level plugin installation for Ponytail, i-have-adhd, Superpowers, and Context7; updates only with
+  `-UpdatePlugins`/`--update-plugins`.
 
 ## Architecture
 
@@ -74,10 +81,11 @@ Every repository change must pass the build before completion. Building only wri
 
 ## Installation
 
-The installer runs a fresh build and then asks for the target platform and client. Selecting Linux or Windows chooses
+The installer runs a fresh build and then asks for the target platform and client, unless they are passed as
-the generated package format; installation always targets the current user's home directory.
+parameters. Selecting Linux or Windows chooses the generated package format; installation always targets the current
+user's home directory.
 
-Preview an installation without changing user files or plugins:
+Preview an installation without changing user files, backups, or plugins:
 
 Powershell: (Windows)
 ```powershell
@@ -89,7 +97,7 @@ Bash: (Linux)
 ./scripts/install.sh --dry-run
 ```
 
-Install the selected configuration:
+Install the selected configuration interactively:
 
 Powershell: (Windows)
 ```powershell
@@ -101,9 +109,29 @@ Bash: (Linux)
 ./scripts/install.sh
 ```
 
-Existing managed files receive timestamped backups before replacement. Unrelated files are left untouched. Selecting
+Install non-interactively, for scripting or CI:
-Codex also installs shared skills to `.agents/skills`. A normal installation ensures configured plugins are present and
+
-updates plugins that are already installed.
+Powershell: (Windows)
+```powershell
+.\scripts\install.ps1 -Client Both -Platform Windows
+```
+
+Bash: (Linux)
+```bash
+./scripts/install.sh --client both --platform linux
+```
+
+`-Platform`/`--platform` defaults to the current platform when omitted together with `-Client`/`--client`.
+
+Every installed file is tracked in a per-destination manifest (`.ai-config-manifest.tsv`). A second run of the same
+installation is a no-op for unchanged files (no write, no backup). A file this setup installed before but no longer
+ships is backed up and removed, unless it was changed locally since the last install, in which case it is backed up
+and left in place with a warning instead. A file the installer never tracked is never touched, even if a file of the
+same name is now part of the package. Backups land in a single timestamped directory per run under
+`backups/<timestamp>/` inside each destination.
+
+Selecting Codex also installs shared skills to `.agents/skills`. A normal installation only installs plugins that are
+missing; add `-UpdatePlugins`/`--update-plugins` to also update and enable plugins that are already installed.
 
 Run the same installation command whenever the repository configuration should be updated. There is no separate update
 script.
@@ -127,10 +155,14 @@ The doctor reports concise `PASS`, `WARN`, and `FAIL` results without reading or
 ## Configuration
 
 Codex receives global instructions, rules, skills, agent TOML files, hooks, and `config.toml`. Its defaults keep writes
-workspace-scoped and use automatic review for eligible escalation requests.
+workspace-scoped and use automatic review for eligible escalation requests. Every rule ships as a plain file under
+`rules/`, and `AGENTS.md` tells Codex to load the matching one by path.
 
-Claude Code receives the equivalent global instructions, rules, skills, agents, hooks, and `settings.json`. Its generated
+Claude Code receives the equivalent global instructions, agents, hooks, and `settings.json`. Only `general.md` ships as
-settings use the supported automatic permission mode where available.
+an always-applied rule file (its content is also embedded directly in `CLAUDE.md`); every technology- or
+situation-specific rule (`adapters/claude/rule-skills.tsv`) is generated as a skill under `skills/rules/` instead, so
+only its name and description are permanently visible and the full rule text loads only when Claude invokes it. Its
+generated settings use the supported automatic permission mode where available.
 
 Both clients receive the same logical agent roles:
 
@@ -147,8 +179,10 @@ when research, design, independent review, or focused verification adds value.
 
 ### Add a rule
 
-Create a focused Markdown file in `shared/rules/`. Add its loading condition to `shared/global-instructions.md` when the
+Create a focused Markdown file in `shared/rules/`. For a rule that applies only to a language, framework, tool, or
-rule applies only to a language, framework, tool, or change area.
+change area, add a row to `adapters/claude/rule-skills.tsv` (Claude generates it as a skill) and add its loading
+condition to the Codex rule-loading text in `scripts/build.ps1`/`scripts/build.sh` (Codex loads it as a plain file, by
+path — unchanged from before). A rule that should always apply, like `general.md`, needs neither.
 
 ### Add a skill