diff --git a/.codex-plugin/README.md b/.codex-plugin/README.md
index 7f723920d..ed4ece00e 100644
--- a/.codex-plugin/README.md
+++ b/.codex-plugin/README.md
@@ -79,13 +79,19 @@ not create a second scope or duplicate hook registration.
 
 ## Native plugin versus legacy managed sync
 
-The commands above are the native Codex plugin path. The legacy managed sync
+The commands above are the native Codex plugin path. The deprecated legacy managed sync
 (`bash scripts/sync-ecc-to-codex.sh`) is a separate compatibility
 path that merges files into `~/.codex`. It is not a native plugin install and
 does not create a marketplace registration. Prefer the native path on current
 Codex; use the legacy managed sync only when you intentionally need its copied
 configuration layer.
 
+New sync runs record a versioned ownership manifest. Inspect or remove that
+layer explicitly with `ecc uninstall --legacy-codex-sync --dry-run`, followed
+by `ecc uninstall --legacy-codex-sync`. Cleanup never targets conversation
+history or native plugin caches. Older pre-manifest installs are cleaned
+conservatively and unverifiable files are retained with warnings.
+
 After install, `codex plugin list` is only a registration check. From an ECC
 checkout, run the cache check to verify that the installed manifest can resolve
 its referenced skills, MCP config, and assets:
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 526414555..af0926402 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -108,6 +108,74 @@ jobs:
             tests/
             !tests/node_modules/
 
+  pack-installer:
+    name: Pack Installer Artifact
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      package_file: ${{ steps.pack.outputs.package_file }}
+      package_sha256: ${{ steps.pack.outputs.package_sha256 }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '20.x'
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Pack exact installer artifact
+        id: pack
+        run: |
+          npm pack --json > npm-pack.json
+          node -e "const crypto = require('crypto'); const fs = require('fs'); const data = JSON.parse(fs.readFileSync('npm-pack.json', 'utf8')); const file = data[0]?.filename; if (!/^ecc-universal-[0-9A-Za-z.+-]+\.tgz$/.test(file || '')) throw new Error('Unexpected packed filename'); const archives = fs.readdirSync('.').filter(name => name.endsWith('.tgz')); if (archives.length !== 1 || archives[0] !== file) throw new Error('Expected exactly one packed archive'); const digest = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex'); fs.appendFileSync(process.env.GITHUB_OUTPUT, 'package_file=' + file + '\npackage_sha256=' + digest + '\n')"
+
+      - name: Upload exact installer artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: ecc-ci-installer-artifact
+          path: ${{ steps.pack.outputs.package_file }}
+          if-no-files-found: error
+
+  packed-install-lifecycle:
+    name: Packed Install (${{ matrix.os }})
+    needs: pack-installer
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+      - name: Checkout lifecycle test
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '20.x'
+
+      - name: Download exact installer artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: ecc-ci-installer-artifact
+          path: release-artifacts
+
+      - name: Verify packed install lifecycle
+        env:
+          ECC_RELEASE_PACKAGE: release-artifacts/${{ needs.pack-installer.outputs.package_file }}
+          ECC_RELEASE_SHA256: ${{ needs.pack-installer.outputs.package_sha256 }}
+        run: node tests/ci/packed-artifact-lifecycle.js
+
   validate:
     name: Validate Components
     runs-on: ubuntu-latest
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index a0856f94d..ee8946509 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -15,6 +15,8 @@ jobs:
       already_published: ${{ steps.npm_publish_state.outputs.already_published }}
       dist_tag: ${{ steps.npm_publish_state.outputs.dist_tag }}
       package_file: ${{ steps.pack.outputs.package_file }}
+      package_sha256: ${{ steps.pack.outputs.package_sha256 }}
+      release_commit: ${{ steps.source.outputs.release_commit }}
 
     steps:
       - name: Checkout
@@ -23,6 +25,12 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
 
+      - name: Pin release source
+        id: source
+        run: |
+          RELEASE_COMMIT=$(git rev-parse HEAD)
+          echo "release_commit=${RELEASE_COMMIT}" >> "$GITHUB_OUTPUT"
+
       - name: Setup Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
@@ -104,8 +112,7 @@ jobs:
         id: pack
         run: |
           npm pack --json > npm-pack.json
-          PACKAGE_FILE=$(node -e "const fs = require('fs'); const data = JSON.parse(fs.readFileSync('npm-pack.json', 'utf8')); console.log(data[0].filename)")
-          echo "package_file=${PACKAGE_FILE}" >> "$GITHUB_OUTPUT"
+          node -e "const crypto = require('crypto'); const fs = require('fs'); const data = JSON.parse(fs.readFileSync('npm-pack.json', 'utf8')); const file = data[0]?.filename; if (!/^ecc-universal-[0-9A-Za-z.+-]+\.tgz$/.test(file || '')) throw new Error('Unexpected packed filename'); const archives = fs.readdirSync('.').filter(name => name.endsWith('.tgz')); if (archives.length !== 1 || archives[0] !== file) throw new Error('Expected exactly one packed archive'); const digest = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex'); fs.appendFileSync(process.env.GITHUB_OUTPUT, 'package_file=' + file + '\npackage_sha256=' + digest + '\n')"
 
       - name: Upload release artifacts
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
@@ -116,10 +123,55 @@ jobs:
             ${{ steps.pack.outputs.package_file }}
           if-no-files-found: error
 
+      - name: Verify existing npm artifact matches candidate
+        if: steps.npm_publish_state.outputs.already_published == 'true'
+        env:
+          ECC_RELEASE_PACKAGE: ${{ steps.pack.outputs.package_file }}
+        run: |
+          PACKAGE_NAME=$(node -p "require('./package.json').name")
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          REGISTRY_INTEGRITY=$(npm view "${PACKAGE_NAME}@${PACKAGE_VERSION}" dist.integrity)
+          ECC_REGISTRY_INTEGRITY="$REGISTRY_INTEGRITY" node -e "const crypto = require('crypto'); const fs = require('fs'); const expected = process.env.ECC_REGISTRY_INTEGRITY; if (!/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(expected || '')) throw new Error('Invalid registry integrity'); const actual = 'sha512-' + crypto.createHash('sha512').update(fs.readFileSync(process.env.ECC_RELEASE_PACKAGE)).digest('base64'); if (actual !== expected) throw new Error('Existing npm artifact does not match tested candidate')"
+
+  lifecycle:
+    name: Packed Lifecycle (${{ matrix.os }})
+    needs: verify
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout lifecycle test
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ needs.verify.outputs.release_commit }}
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '20.x'
+
+      - name: Download exact packed artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: ecc-release-artifacts
+          path: release-artifacts
+
+      - name: Verify packed install lifecycle
+        env:
+          ECC_RELEASE_PACKAGE: release-artifacts/${{ needs.verify.outputs.package_file }}
+          ECC_RELEASE_SHA256: ${{ needs.verify.outputs.package_sha256 }}
+        run: node tests/ci/packed-artifact-lifecycle.js
+
   publish:
     name: Publish Release
     runs-on: ubuntu-latest
-    needs: verify
+    needs: [verify, lifecycle]
     permissions:
       contents: write
       id-token: write
@@ -136,6 +188,12 @@ jobs:
           node-version: '20.x'
           registry-url: 'https://registry.npmjs.org'
 
+      - name: Verify artifact before publish
+        env:
+          ECC_RELEASE_PACKAGE: ${{ needs.verify.outputs.package_file }}
+          ECC_RELEASE_SHA256: ${{ needs.verify.outputs.package_sha256 }}
+        run: node -e "const crypto = require('crypto'); const fs = require('fs'); const file = process.env.ECC_RELEASE_PACKAGE; const expected = process.env.ECC_RELEASE_SHA256; if (!/^ecc-universal-[0-9A-Za-z.+-]+\.tgz$/.test(file || '')) throw new Error('Unexpected packed filename'); if (!/^[a-f0-9]{64}$/.test(expected || '')) throw new Error('Invalid packed SHA-256'); const archives = fs.readdirSync('.').filter(name => name.endsWith('.tgz')); if (archives.length !== 1 || archives[0] !== file) throw new Error('Expected exactly one downloaded archive'); const actual = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex'); if (actual !== expected) throw new Error('Downloaded publish artifact SHA-256 mismatch')"
+
       - name: Create GitHub Release
         uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
         with:
@@ -148,4 +206,6 @@ jobs:
         if: needs.verify.outputs.already_published != 'true'
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: npm publish "${{ needs.verify.outputs.package_file }}" --access public --provenance --tag "${{ needs.verify.outputs.dist_tag }}"
+          ECC_RELEASE_PACKAGE: ${{ needs.verify.outputs.package_file }}
+          NPM_DIST_TAG: ${{ needs.verify.outputs.dist_tag }}
+        run: npm publish "./${ECC_RELEASE_PACKAGE}" --access public --provenance --tag "${NPM_DIST_TAG}"
diff --git a/.github/workflows/reusable-release.yml b/.github/workflows/reusable-release.yml
index 5f666613a..81dade65a 100644
--- a/.github/workflows/reusable-release.yml
+++ b/.github/workflows/reusable-release.yml
@@ -38,15 +38,23 @@ jobs:
       already_published: ${{ steps.npm_publish_state.outputs.already_published }}
       dist_tag: ${{ steps.npm_publish_state.outputs.dist_tag }}
       package_file: ${{ steps.pack.outputs.package_file }}
+      package_sha256: ${{ steps.pack.outputs.package_sha256 }}
+      release_commit: ${{ steps.source.outputs.release_commit }}
 
     steps:
       - name: Checkout
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
-          ref: ${{ inputs.tag }}
+          ref: refs/tags/${{ inputs.tag }}
           persist-credentials: false
 
+      - name: Pin release source
+        id: source
+        run: |
+          RELEASE_COMMIT=$(git rev-parse HEAD)
+          echo "release_commit=${RELEASE_COMMIT}" >> "$GITHUB_OUTPUT"
+
       - name: Setup Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
@@ -62,9 +70,6 @@ jobs:
       - name: Verify OpenCode package payload
         run: node tests/scripts/build-opencode.test.js
 
-      - name: Verify OMP adapter payload
-        run: node tests/omp/omp-plugin.test.js
-
       - name: Validate version tag
         env:
           INPUT_TAG: ${{ inputs.tag }}
@@ -124,8 +129,7 @@ jobs:
         id: pack
         run: |
           npm pack --json > npm-pack.json
-          PACKAGE_FILE=$(node -e "const fs = require('fs'); const data = JSON.parse(fs.readFileSync('npm-pack.json', 'utf8')); console.log(data[0].filename)")
-          echo "package_file=${PACKAGE_FILE}" >> "$GITHUB_OUTPUT"
+          node -e "const crypto = require('crypto'); const fs = require('fs'); const data = JSON.parse(fs.readFileSync('npm-pack.json', 'utf8')); const file = data[0]?.filename; if (!/^ecc-universal-[0-9A-Za-z.+-]+\.tgz$/.test(file || '')) throw new Error('Unexpected packed filename'); const archives = fs.readdirSync('.').filter(name => name.endsWith('.tgz')); if (archives.length !== 1 || archives[0] !== file) throw new Error('Expected exactly one packed archive'); const digest = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex'); fs.appendFileSync(process.env.GITHUB_OUTPUT, 'package_file=' + file + '\npackage_sha256=' + digest + '\n')"
 
       - name: Upload release artifacts
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
@@ -136,10 +140,55 @@ jobs:
             ${{ steps.pack.outputs.package_file }}
           if-no-files-found: error
 
+      - name: Verify existing npm artifact matches candidate
+        if: steps.npm_publish_state.outputs.already_published == 'true'
+        env:
+          ECC_RELEASE_PACKAGE: ${{ steps.pack.outputs.package_file }}
+        run: |
+          PACKAGE_NAME=$(node -p "require('./package.json').name")
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          REGISTRY_INTEGRITY=$(npm view "${PACKAGE_NAME}@${PACKAGE_VERSION}" dist.integrity)
+          ECC_REGISTRY_INTEGRITY="$REGISTRY_INTEGRITY" node -e "const crypto = require('crypto'); const fs = require('fs'); const expected = process.env.ECC_REGISTRY_INTEGRITY; if (!/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(expected || '')) throw new Error('Invalid registry integrity'); const actual = 'sha512-' + crypto.createHash('sha512').update(fs.readFileSync(process.env.ECC_RELEASE_PACKAGE)).digest('base64'); if (actual !== expected) throw new Error('Existing npm artifact does not match tested candidate')"
+
+  lifecycle:
+    name: Packed Lifecycle (${{ matrix.os }})
+    needs: verify
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout lifecycle test
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ needs.verify.outputs.release_commit }}
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '20.x'
+
+      - name: Download exact packed artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: ecc-release-artifacts
+          path: release-artifacts
+
+      - name: Verify packed install lifecycle
+        env:
+          ECC_RELEASE_PACKAGE: release-artifacts/${{ needs.verify.outputs.package_file }}
+          ECC_RELEASE_SHA256: ${{ needs.verify.outputs.package_sha256 }}
+        run: node tests/ci/packed-artifact-lifecycle.js
+
   publish:
     name: Publish Release
     runs-on: ubuntu-latest
-    needs: verify
+    needs: [verify, lifecycle]
     permissions:
       contents: write
       id-token: write
@@ -156,6 +205,12 @@ jobs:
           node-version: '20.x'
           registry-url: 'https://registry.npmjs.org'
 
+      - name: Verify artifact before publish
+        env:
+          ECC_RELEASE_PACKAGE: ${{ needs.verify.outputs.package_file }}
+          ECC_RELEASE_SHA256: ${{ needs.verify.outputs.package_sha256 }}
+        run: node -e "const crypto = require('crypto'); const fs = require('fs'); const file = process.env.ECC_RELEASE_PACKAGE; const expected = process.env.ECC_RELEASE_SHA256; if (!/^ecc-universal-[0-9A-Za-z.+-]+\.tgz$/.test(file || '')) throw new Error('Unexpected packed filename'); if (!/^[a-f0-9]{64}$/.test(expected || '')) throw new Error('Invalid packed SHA-256'); const archives = fs.readdirSync('.').filter(name => name.endsWith('.tgz')); if (archives.length !== 1 || archives[0] !== file) throw new Error('Expected exactly one downloaded archive'); const actual = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex'); if (actual !== expected) throw new Error('Downloaded publish artifact SHA-256 mismatch')"
+
       - name: Create GitHub Release
         uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
         with:
@@ -169,4 +224,6 @@ jobs:
         if: needs.verify.outputs.already_published != 'true'
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: npm publish "${{ needs.verify.outputs.package_file }}" --access public --provenance --tag "${{ needs.verify.outputs.dist_tag }}"
+          ECC_RELEASE_PACKAGE: ${{ needs.verify.outputs.package_file }}
+          NPM_DIST_TAG: ${{ needs.verify.outputs.dist_tag }}
+        run: npm publish "./${ECC_RELEASE_PACKAGE}" --access public --provenance --tag "${NPM_DIST_TAG}"
diff --git a/README.md b/README.md
index c02e7756b..17cd1b201 100644
--- a/README.md
+++ b/README.md
@@ -236,7 +236,7 @@ node scripts/codex/check-plugin-cache.js
 
 Both add commands are idempotent. To refresh later, run `codex plugin marketplace upgrade ecc` followed by `codex plugin add ecc@ecc`. Codex stores one enabled plugin state in the active `CODEX_HOME`; it does not offer Claude's `user`, `project`, and `local` scopes. Its native hooks require an explicit trust decision and do not use Claude's four ECC hook profiles. Inside Codex, invoke `$configure-ecc` for the guided provider-aware flow.
 
-The older `scripts/sync-ecc-to-codex.sh` path remains a separate compatibility option for users who intentionally want copied and merged configuration in `~/.codex`; it is not required for the native plugin. Run Codex once first so `~/.codex/config.toml` exists, then:
+The older `scripts/sync-ecc-to-codex.sh` path is a deprecated compatibility option for users who intentionally need copied and merged configuration in `~/.codex`; it is not required for the native plugin. New sync runs write an ownership manifest so cleanup can preserve modified user files. Run Codex once first so `~/.codex/config.toml` exists, then:
 
 ```bash
 git clone https://github.com/affaan-m/ECC.git
@@ -245,6 +245,15 @@ npm install
 bash scripts/sync-ecc-to-codex.sh
 ```
 
+To inspect or remove that legacy layer without touching Codex conversations or native plugin caches:
+
+```bash
+node scripts/ecc.js uninstall --legacy-codex-sync --dry-run
+node scripts/ecc.js uninstall --legacy-codex-sync
+```
+
+Pre-manifest installations are handled conservatively: ECC removes its marked `AGENTS.md` block but preserves copied files it cannot prove it owns and reports them for review.
+
 You can also open the ECC repository directly in Codex for a project-local setup. Codex reads the root `AGENTS.md` and the trusted project configuration in `.codex/` without a global sync. Do not add the native marketplace plugin on top of the sync flow.
 
 For repo navigation, surface ownership, and PR diff packet guidance, read the [Codex ECC Navigation Map](docs/CODEX-NAVIGATION-GUIDE.md). See the [.codex plugin notes](.codex-plugin/README.md) for native lifecycle details.
@@ -2014,7 +2023,7 @@ Yes. ECC is cross-platform:
 - **OpenCode**: Beta plugin integration in `.opencode/`; provider model selection and catalog parity remain limited.
 - **Codex**: Supported repo/sync path for macOS app and CLI; ECC's marketplace package remains experimental.
 - **GitHub Copilot (VS Code)**: Instruction and prompt layer via `.github/copilot-instructions.md`, `.vscode/settings.json`, and `.github/prompts/`.
-- **Antigravity**: Tightly integrated setup for workflows, skills, and flattened rules in `.agent/`. See [Antigravity Guide](docs/ANTIGRAVITY-GUIDE.md).
+- **Antigravity**: Native Antigravity 2.0 setup for workflows, skills, custom agents, and flattened rules in `.agents/`. See [Antigravity Guide](docs/ANTIGRAVITY-GUIDE.md).
 - **JoyCode / CodeBuddy**: Project-local selective install adapters for commands, agents, skills, and flattened rules. See [JoyCode Adapter Guide](docs/JOYCODE-GUIDE.md).
 - **Qwen CLI**: Home-directory selective install adapter for commands, agents, skills, rules, and Qwen config. See [Qwen CLI Adapter Guide](docs/QWEN-GUIDE.md).
 - **Zed**: Project-local selective install adapter for `.zed/settings.json`, flattened rules, commands, agents, and skills.
diff --git a/docs/ANTIGRAVITY-GUIDE.md b/docs/ANTIGRAVITY-GUIDE.md
index d792aec9f..f20c50a5f 100644
--- a/docs/ANTIGRAVITY-GUIDE.md
+++ b/docs/ANTIGRAVITY-GUIDE.md
@@ -1,156 +1,114 @@
 # Antigravity Setup and Usage Guide
 
-Google's [Antigravity](https://antigravity.dev) is an AI coding IDE that uses a `.agent/` directory convention for configuration. ECC provides first-class support for Antigravity through its selective install system.
+Google Antigravity 2.0 discovers workspace customizations from the project-local
+`.agents/` directory. ECC's Antigravity target installs native rules, workflows,
+skills, and custom agents into that directory.
 
-## Quick Start
+## Quick start
 
 ```bash
-# Install ECC with Antigravity target
-./install.sh --target antigravity typescript
+# Install the minimal profile
+./install.sh --profile minimal --target antigravity
 
-# Or with multiple language modules
+# Compatibility syntax: common rules plus only these language packs
 ./install.sh --target antigravity typescript python go
 ```
 
-This installs ECC components into your project's `.agent/` directory, ready for Antigravity to pick up.
+Start a new Antigravity conversation after installing so the agent receives the
+updated skill inventory.
 
-## How the Install Mapping Works
+## Native install mapping
 
-ECC remaps its component structure to match Antigravity's expected layout:
+| ECC source | Antigravity destination | Purpose |
+|---|---|---|
+| `rules/` | `.agents/rules/` | Workspace rules, flattened with collision-safe names |
+| `commands/` | `.agents/workflows/` | User-invoked slash workflows |
+| `skills/<name>/` | `.agents/skills/<name>/` | Agent Skills with a required `SKILL.md` |
+| `agents/<name>.md` | `.agents/agents/<name>.md` | Custom main agents and subagents |
 
-| ECC Source | Antigravity Destination | What It Contains |
-|------------|------------------------|------------------|
-| `rules/` | `.agent/rules/` | Language rules and coding standards (flattened) |
-| `commands/` | `.agent/workflows/` | Slash commands become Antigravity workflows |
-| `agents/` | `.agent/skills/` | Agent definitions become Antigravity skills |
+ECC does not copy the repository's `.agents/` directory wholesale. That source
+tree is Codex packaging and contains Codex-specific marketplace metadata. An
+Antigravity plugin instead requires `.agents/plugins/<plugin-name>/plugin.json`.
 
-> **Note on `.agents/` vs `.agent/` vs `agents/`**: The installer only handles three source paths explicitly: `rules` → `.agent/rules/`, `commands` → `.agent/workflows/`, and `agents` (no dot prefix) → `.agent/skills/`. The dot-prefixed `.agents/` directory in the ECC repo is a **static layout** for Codex/Antigravity skill definitions and `openai.yaml` configs — it is not directly mapped by the installer. Any `.agents/` path falls through to the default scaffold operation. If you want `.agents/skills/` content available in the Antigravity runtime, you must manually copy it to `.agent/skills/`.
+Installed custom agent definitions are adapted to Antigravity's frontmatter:
+Claude model tiers become `flash` or `pro`, and Claude tool names become their
+Antigravity equivalents. Unsupported tool identifiers are never emitted because
+Antigravity warns that invalid tool names can hang custom-agent execution.
 
-### Key Differences from Claude Code
+## Expected project tree
 
-- **Rules are flattened**: Claude Code nests rules under subdirectories (`rules/common/`, `rules/typescript/`). Antigravity expects a flat `rules/` directory — the installer handles this automatically.
-- **Commands become workflows**: ECC's `/command` files land in `.agent/workflows/`, which is Antigravity's equivalent of slash commands.
-- **Agents become skills**: ECC agent definitions map to `.agent/skills/`, where Antigravity looks for skill configurations.
-
-## Directory Structure After Install
-
-```
+```text
 your-project/
-├── .agent/
-│   ├── rules/
-│   │   ├── coding-standards.md
-│   │   ├── testing.md
-│   │   ├── security.md
-│   │   └── typescript.md          # language-specific rules
-│   ├── workflows/
-│   │   ├── plan.md
-│   │   ├── code-review.md
-│   │   ├── tdd.md
-│   │   └── ...
-│   ├── skills/
-│   │   ├── planner.md
-│   │   ├── code-reviewer.md
-│   │   ├── tdd-guide.md
-│   │   └── ...
-│   └── ecc-install-state.json     # tracks what ECC installed
+└── .agents/
+    ├── rules/
+    │   ├── common-coding-style.md
+    │   └── typescript-testing.md
+    ├── workflows/
+    │   └── plan.md
+    ├── skills/
+    │   └── coding-standards/
+    │       └── SKILL.md
+    ├── agents/
+    │   └── code-reviewer.md
+    └── ecc-install-state.json
 ```
 
-## The `openai.yaml` Agent Config
-
-Each skill directory under `.agents/skills/` contains an `agents/openai.yaml` file at the path `.agents/skills/<skill-name>/agents/openai.yaml` that configures the skill for Antigravity:
-
-```yaml
-interface:
-  display_name: "API Design"
-  short_description: "REST API design patterns and best practices"
-  brand_color: "#F97316"
-  default_prompt: "Design REST API: resources, status codes, pagination"
-policy:
-  allow_implicit_invocation: true
-```
-
-| Field | Purpose |
-|-------|---------|
-| `display_name` | Human-readable name shown in Antigravity's UI |
-| `short_description` | Brief description of what the skill does |
-| `brand_color` | Hex color for the skill's visual badge |
-| `default_prompt` | Suggested prompt when the skill is invoked manually |
-| `allow_implicit_invocation` | When `true`, Antigravity can activate the skill automatically based on context |
-
-## Managing Your Installation
-
-### Check What's Installed
+## Verify the installation
 
 ```bash
 node scripts/list-installed.js --target antigravity
-```
-
-### Repair a Broken Install
-
-```bash
-# First, diagnose what's wrong
 node scripts/doctor.js --target antigravity
-
-# Then, restore missing or drifted files
-node scripts/repair.js --target antigravity
+rg --files .agents/skills -g 'SKILL.md'
+rg --files .agents/agents -g '*.md'
 ```
 
-### Uninstall
+In Antigravity, open **Settings > Customizations**, confirm that workspace
+skills appear, start a new conversation, and request one by its exact name.
+
+## Existing `.agent/` installations
+
+Antigravity still reads legacy `.agent/rules` and `.agent/skills`, but ECC now
+uses the canonical `.agents/` layout. Do not rename `.agent` manually because
+ECC install-state contains absolute managed paths.
+
+Rerun the same ECC install command after updating. ECC writes and verifies the
+new `.agents/ecc-install-state.json` first, then removes only unchanged files
+owned by the valid legacy state. Modified and unmanaged files remain in
+`.agent/` and remain discoverable by doctor and uninstall until handled.
+
+Preview lifecycle operations before applying them when desired:
 
 ```bash
-node scripts/uninstall.js --target antigravity
+node scripts/doctor.js --target antigravity
+node scripts/repair.js --target antigravity --dry-run
+node scripts/uninstall.js --target antigravity --dry-run
 ```
 
-### Install State
-
-The installer writes `.agent/ecc-install-state.json` to track which files ECC owns. This enables safe uninstall and repair — ECC will never touch files it didn't create.
-
-## Adding Custom Skills for Antigravity
-
-If you're contributing a new skill and want it available on Antigravity:
-
-1. Create the skill under `skills/your-skill-name/SKILL.md` as usual
-2. Add an agent definition at `agents/your-skill-name.md` — this is the path the installer maps to `.agent/skills/` at runtime, making your skill available in the Antigravity harness
-3. Add the Antigravity agent config at `.agents/skills/your-skill-name/agents/openai.yaml` — this is a static repo layout consumed by Codex for implicit invocation metadata
-4. Mirror the `SKILL.md` content to `.agents/skills/your-skill-name/SKILL.md` — this static copy is used by Codex and serves as a reference for Antigravity
-5. Mention in your PR that you added Antigravity support
-
-> **Key distinction**: The installer deploys `agents/` (no dot) → `.agent/skills/` — this is what makes skills available at runtime. The `.agents/` (dot-prefixed) directory is a separate static layout for Codex `openai.yaml` configs and is not auto-deployed by the installer.
-
-See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full contribution guide.
-
-## Comparison with Other Targets
-
-| Feature | Claude Code | Cursor | Codex | Antigravity |
-|---------|-------------|--------|-------|-------------|
-| Install target | `claude-home` | `cursor-project` | `codex-home` | `antigravity` |
-| Config root | `~/.claude/` | `.cursor/` | `~/.codex/` | `.agent/` |
-| Scope | User-level | Project-level | User-level | Project-level |
-| Rules format | Nested dirs | Flat | Flat | Flat |
-| Commands | `commands/` | N/A | N/A | `workflows/` |
-| Agents/Skills | `agents/` | N/A | N/A | `skills/` |
-| Install state | `ecc-install-state.json` | `ecc-install-state.json` | `ecc-install-state.json` | `ecc-install-state.json` |
-
 ## Troubleshooting
 
-### Skills not loading in Antigravity
+### Skills do not appear
 
-- Verify the `.agent/` directory exists in your project root (not home directory)
-- Check that `ecc-install-state.json` was created — if missing, re-run the installer
-- Ensure files have `.md` extension and valid frontmatter
+- A valid skill must be `.agents/skills/<name>/SKILL.md`.
+- `.agent/.agents/skills` is an obsolete nested layout from older ECC builds.
+- Start a new conversation after changing skill files.
 
-### Rules not applying
+### Rules do not apply
 
-- Rules must be in `.agent/rules/`, not nested in subdirectories
-- Run `node scripts/doctor.js --target antigravity` to verify the install
+- Confirm the files are directly under `.agents/rules/`.
+- Run doctor and inspect any missing or drifted managed-file warning.
 
-### Workflows not available
+### Workflows do not appear
 
-- Antigravity looks for workflows in `.agent/workflows/`, not `commands/`
-- If you manually copied ECC commands, rename the directory
+- Confirm the files are under `.agents/workflows/`.
+- Invoke a workflow with `/<workflow-name>` after restarting Antigravity.
 
-## Related Resources
+## Official Antigravity references
 
-- [Selective Install Architecture](./SELECTIVE-INSTALL-ARCHITECTURE.md) — how the install system works under the hood
-- [Selective Install Design](./SELECTIVE-INSTALL-DESIGN.md) — design decisions and target adapter contracts
-- [CONTRIBUTING.md](../CONTRIBUTING.md) — how to contribute skills, agents, and commands
+- [Skills](https://antigravity.google/docs/skills)
+- [Rules and workflows](https://antigravity.google/docs/rules-workflows)
+- [Custom agents and subagents](https://antigravity.google/docs/subagents)
+- [Plugins](https://antigravity.google/docs/plugins)
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for ECC contribution guidance and
+[SELECTIVE-INSTALL-ARCHITECTURE.md](SELECTIVE-INSTALL-ARCHITECTURE.md) for the
+installer lifecycle contract.
diff --git a/docs/SELECTIVE-INSTALL-ARCHITECTURE.md b/docs/SELECTIVE-INSTALL-ARCHITECTURE.md
index deab37779..0b5123920 100644
--- a/docs/SELECTIVE-INSTALL-ARCHITECTURE.md
+++ b/docs/SELECTIVE-INSTALL-ARCHITECTURE.md
@@ -593,7 +593,7 @@ Suggested first adapters:
 2. `cursor-project`
    writes into `./.cursor/...`
 3. `antigravity-project`
-   writes into `./.agent/...`
+   writes into `./.agents/...`
 4. `codex-home`
    later
 5. `opencode-home`
@@ -668,7 +668,7 @@ Suggested path conventions:
 - Cursor target:
   `./.cursor/ecc-install-state.json`
 - Antigravity target:
-  `./.agent/ecc-install-state.json`
+  `./.agents/ecc-install-state.json`
 - future Codex target:
   `~/.codex/ecc-install-state.json`
 
diff --git a/docs/de-DE/README.md b/docs/de-DE/README.md
index c7463d5ff..248c825b0 100644
--- a/docs/de-DE/README.md
+++ b/docs/de-DE/README.md
@@ -1151,7 +1151,7 @@ Ja. ECC ist Cross-Platform:
 - **OpenCode**: Vollständige Plugin-Unterstützung in `.opencode/`. Siehe [OpenCode-Unterstützung](#opencode-unterstützung).
 - **Codex**: Erstklassige Unterstützung sowohl für die macOS-App als auch die CLI, mit Adapter-Drift-Guards und SessionStart-Fallback. Siehe PR [#257](https://github.com/affaan-m/ECC/pull/257).
 - **GitHub Copilot (VS Code)**: Instruction- und Prompt-Schicht über `.github/copilot-instructions.md`, `.vscode/settings.json` und `.github/prompts/`. Siehe [GitHub-Copilot-Unterstützung](#github-copilot-unterstützung).
-- **Antigravity**: Eng integriertes Setup für Workflows, Skills und abgeflachte Rules in `.agent/`. Siehe [Antigravity-Leitfaden](../../docs/ANTIGRAVITY-GUIDE.md).
+- **Antigravity**: Eng integriertes Setup für Workflows, Skills und abgeflachte Rules in `.agents/`. Siehe [Antigravity-Leitfaden](../../docs/ANTIGRAVITY-GUIDE.md).
 - **JoyCode / CodeBuddy**: Projektlokale Adapter für selektive Installation von Commands, Agents, Skills und abgeflachten Rules. Siehe [JoyCode-Adapter-Leitfaden](../../docs/JOYCODE-GUIDE.md).
 - **Qwen CLI**: Adapter für selektive Installation im Home-Verzeichnis für Commands, Agents, Skills, Rules und Qwen-Konfiguration. Siehe [Qwen-CLI-Adapter-Leitfaden](../../docs/QWEN-GUIDE.md).
 - **Zed**: Projektlokaler Adapter für selektive Installation von `.zed/settings.json`, abgeflachten Rules, Commands, Agents und Skills.
diff --git a/docs/es/README.md b/docs/es/README.md
index 0a727e18e..6ecd1c2ac 100644
--- a/docs/es/README.md
+++ b/docs/es/README.md
@@ -1009,7 +1009,7 @@ Sí. ECC es multiplataforma:
 - **OpenCode**: Soporte completo del plugin en `.opencode/`. Consulta [Soporte para OpenCode](#soporte-para-opencode).
 - **Codex**: Soporte de primera clase para la app macOS y CLI, con guardias de deriva del adaptador y fallback de SessionStart. Consulta PR [#257](https://github.com/affaan-m/ECC/pull/257).
 - **GitHub Copilot (VS Code)**: Capa de instrucciones y prompts mediante `.github/copilot-instructions.md`, `.vscode/settings.json` y `.github/prompts/`. Consulta [Soporte para GitHub Copilot](#soporte-para-github-copilot).
-- **Antigravity**: Configuración estrechamente integrada para flujos de trabajo, skills y reglas aplanadas en `.agent/`. Consulta la [Guía de Antigravity](../ANTIGRAVITY-GUIDE.md).
+- **Antigravity**: Configuración estrechamente integrada para flujos de trabajo, skills y reglas aplanadas en `.agents/`. Consulta la [Guía de Antigravity](../ANTIGRAVITY-GUIDE.md).
 - **JoyCode / CodeBuddy**: Adaptadores de instalación selectiva locales al proyecto para comandos, agentes, skills y reglas aplanadas. Consulta la [Guía del Adaptador JoyCode](../JOYCODE-GUIDE.md).
 - **Qwen CLI**: Adaptador de instalación selectiva en el directorio home para comandos, agentes, skills, reglas y configuración de Qwen. Consulta la [Guía del Adaptador Qwen CLI](../QWEN-GUIDE.md).
 - **Zed**: Adaptador de instalación selectiva local al proyecto para `.zed/settings.json`, reglas aplanadas, comandos, agentes y skills.
diff --git a/docs/ja-JP/skills/repo-scan/SKILL.md b/docs/ja-JP/skills/repo-scan/SKILL.md
index 35aad3ee9..733ecb146 100644
--- a/docs/ja-JP/skills/repo-scan/SKILL.md
+++ b/docs/ja-JP/skills/repo-scan/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: repo-scan
-description: クロススタックのソースコード資産監査——各ファイルを分類し、埋め込まれたサードパーティライブラリを検出し、各モジュールに対してインタラクティブなHTMLレポートとともに実用的な4段階の判定を提供する。
+description: 固定されレビュー可能なコミットから外部の repo-scan スキルをインストールするブートストラップ用ポインター。クロススタックのソースコード資産監査を実行する前に repo-scan のインストールが必要な場合に使用する。この ECC ポインター自体は監査を実行しない。
 origin: community
 ---
 
@@ -18,18 +18,109 @@ origin: community
 ## インストール
 
 ```bash
-# Fetch only the pinned commit for reproducibility
-mkdir -p ~/.claude/skills/repo-scan
-git init repo-scan
-cd repo-scan
-git remote add origin https://github.com/haibindev/repo-scan.git
-git fetch --depth 1 origin 2742664
-git checkout --detach FETCH_HEAD
-cp -r . ~/.claude/skills/repo-scan
+# Clone first so the pinned commit can be reviewed before installation
+set -euo pipefail
+
+REPO_SCAN_COMMIT=2742664ebcad1450c208eda0ae45d3c17fad5dd8
+REPO_SCAN_INSTALL_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/repo-scan"
+REPO_SCAN_INSTALL_PARENT="$(dirname "$REPO_SCAN_INSTALL_DIR")"
+mkdir -p "$REPO_SCAN_INSTALL_PARENT"
+REPO_SCAN_TMP="$(mktemp -d "$REPO_SCAN_INSTALL_PARENT/.repo-scan-install.XXXXXX")"
+REPO_SCAN_TOKEN="${REPO_SCAN_TMP##*.}"
+REPO_SCAN_STAGE="$REPO_SCAN_TMP/stage-$REPO_SCAN_TOKEN"
+REPO_SCAN_BACKUP="$REPO_SCAN_TMP/backup-$REPO_SCAN_TOKEN"
+REPO_SCAN_LOCK="$REPO_SCAN_INSTALL_PARENT/.repo-scan-install.lock"
+REPO_SCAN_KEEP_TMP=0
+REPO_SCAN_LOCK_HELD=0
+REPO_SCAN_MV_HAS_NO_TARGET=0
+cleanup_repo_scan_install() {
+  if [ "$REPO_SCAN_KEEP_TMP" -eq 0 ]; then
+    rm -rf -- "$REPO_SCAN_TMP"
+  fi
+  if [ "$REPO_SCAN_LOCK_HELD" -eq 1 ] && ! rmdir -- "$REPO_SCAN_LOCK"; then
+    printf 'Could not release installation lock at %s\n' "$REPO_SCAN_LOCK" >&2
+  fi
+}
+trap cleanup_repo_scan_install EXIT
+mkdir "$REPO_SCAN_TMP/mv-probe-source"
+if mv -T -- "$REPO_SCAN_TMP/mv-probe-source" \
+  "$REPO_SCAN_TMP/mv-probe-destination" 2>/dev/null; then
+  REPO_SCAN_MV_HAS_NO_TARGET=1
+  rmdir "$REPO_SCAN_TMP/mv-probe-destination"
+else
+  rmdir "$REPO_SCAN_TMP/mv-probe-source"
+fi
+move_repo_scan_dir() {
+  REPO_SCAN_MOVE_SOURCE=$1
+  REPO_SCAN_MOVE_DESTINATION=$2
+  REPO_SCAN_MOVE_NAME=${REPO_SCAN_MOVE_SOURCE##*/}
+  if [ -e "$REPO_SCAN_MOVE_DESTINATION" ] || [ -L "$REPO_SCAN_MOVE_DESTINATION" ]; then
+    return 1
+  fi
+  if [ "$REPO_SCAN_MV_HAS_NO_TARGET" -eq 1 ]; then
+    mv -T -- "$REPO_SCAN_MOVE_SOURCE" "$REPO_SCAN_MOVE_DESTINATION"
+    return
+  fi
+  if ! mv -- "$REPO_SCAN_MOVE_SOURCE" "$REPO_SCAN_MOVE_DESTINATION"; then
+    return 1
+  fi
+  if [ -e "$REPO_SCAN_MOVE_DESTINATION/$REPO_SCAN_MOVE_NAME" ] || \
+    [ -L "$REPO_SCAN_MOVE_DESTINATION/$REPO_SCAN_MOVE_NAME" ]; then
+    if ! mv -- "$REPO_SCAN_MOVE_DESTINATION/$REPO_SCAN_MOVE_NAME" \
+      "$REPO_SCAN_MOVE_SOURCE"; then
+      REPO_SCAN_KEEP_TMP=1
+      printf 'Move conflict recovery failed; staged data remains at %s\n' \
+        "$REPO_SCAN_MOVE_DESTINATION/$REPO_SCAN_MOVE_NAME" >&2
+    fi
+    return 1
+  fi
+}
+
+git clone --filter=blob:none --no-checkout \
+  https://github.com/haibindev/repo-scan.git "$REPO_SCAN_TMP/source"
+git -C "$REPO_SCAN_TMP/source" checkout --detach "$REPO_SCAN_COMMIT"
+mkdir -p "$REPO_SCAN_STAGE"
+git -C "$REPO_SCAN_TMP/source" archive "$REPO_SCAN_COMMIT" | \
+  tar -xf - -C "$REPO_SCAN_STAGE"
+
+# Review "$REPO_SCAN_TMP/source" before approving installation.
+printf 'Type install to replace %s after reviewing the pinned source: ' \
+  "$REPO_SCAN_INSTALL_DIR" >&2
+read -r REPO_SCAN_CONFIRM
+if [ "$REPO_SCAN_CONFIRM" != install ]; then
+  printf 'Installation cancelled.\n' >&2
+  exit 1
+fi
+if ! mkdir -- "$REPO_SCAN_LOCK" 2>/dev/null; then
+  printf 'Another repo-scan installation holds the lock at %s\n' \
+    "$REPO_SCAN_LOCK" >&2
+  exit 1
+fi
+REPO_SCAN_LOCK_HELD=1
+
+if [ -e "$REPO_SCAN_INSTALL_DIR" ] || [ -L "$REPO_SCAN_INSTALL_DIR" ]; then
+  move_repo_scan_dir "$REPO_SCAN_INSTALL_DIR" "$REPO_SCAN_BACKUP"
+fi
+if ! move_repo_scan_dir "$REPO_SCAN_STAGE" "$REPO_SCAN_INSTALL_DIR"; then
+  if [ -e "$REPO_SCAN_BACKUP" ] || [ -L "$REPO_SCAN_BACKUP" ]; then
+    if [ -e "$REPO_SCAN_INSTALL_DIR" ] || [ -L "$REPO_SCAN_INSTALL_DIR" ]; then
+      REPO_SCAN_KEEP_TMP=1
+      printf 'Replacement failed and target was recreated; previous installation preserved at %s\n' \
+        "$REPO_SCAN_BACKUP" >&2
+    elif ! move_repo_scan_dir "$REPO_SCAN_BACKUP" "$REPO_SCAN_INSTALL_DIR"; then
+      REPO_SCAN_KEEP_TMP=1
+      printf 'Replacement and rollback failed; previous installation preserved at %s\n' \
+        "$REPO_SCAN_BACKUP" >&2
+    fi
+  fi
+  exit 1
+fi
 ```
 
 > エージェントスキルをインストールする前に、ソースコードをレビューしてください。
 
+インストール後、エージェントハーネスを再読み込みしてから、`repo-scan` を再度呼び出してください。この ECC ポインターは外部スキルをインストールするだけで、スキャン自体は実行しません。
+
 ## コア機能
 
 | 機能 | 説明 |
diff --git a/docs/ko-KR/README.md b/docs/ko-KR/README.md
index 66726f98f..82b99a85f 100644
--- a/docs/ko-KR/README.md
+++ b/docs/ko-KR/README.md
@@ -586,7 +586,7 @@ cp -r everything-claude-code/rules/common ~/.claude/rules/common
 - **Cursor**: `.cursor/`에 변환된 설정 제공
 - **OpenCode**: `.opencode/`에 전체 플러그인 지원
 - **Codex**: macOS 앱과 CLI 모두 퍼스트클래스 지원
-- **Antigravity**: `.agent/`에 워크플로우, 스킬, 평탄화된 룰 통합
+- **Antigravity**: `.agents/`에 워크플로우, 스킬, 에이전트, 평탄화된 룰 통합
 - **Claude Code**: 네이티브 — 이것이 주 타겟입니다
 </details>
 
diff --git a/docs/pt-BR/README.md b/docs/pt-BR/README.md
index 80259bad8..548d8e9e6 100644
--- a/docs/pt-BR/README.md
+++ b/docs/pt-BR/README.md
@@ -477,7 +477,7 @@ Sim. O ECC é multiplataforma:
 - **Cursor**: Configs pré-traduzidas em `.cursor/`
 - **OpenCode**: Suporte completo a plugins em `.opencode/`
 - **Codex**: Suporte de primeira classe para app macOS e CLI
-- **Antigravity**: Configuração integrada em `.agent/`
+- **Antigravity**: Configuração integrada em `.agents/`
 - **Claude Code**: Nativo — este é o alvo principal
 </details>
 
diff --git a/docs/ru/README.md b/docs/ru/README.md
index f42a19c97..fa4f94b5b 100644
--- a/docs/ru/README.md
+++ b/docs/ru/README.md
@@ -1082,7 +1082,7 @@ cp -r everything-claude-code/rules/common ~/.claude/rules/ecc/
 - **Gemini CLI**: экспериментальная project-local поддержка через `.gemini/GEMINI.md` и общий plumbing установщика.
 - **OpenCode**: полная поддержка плагина в `.opencode/`. См. [Поддержка OpenCode](#поддержка-opencode).
 - **Codex**: первоклассная поддержка macOS app и CLI, с guards против adapter drift и SessionStart fallback. См. PR [#257](https://github.com/affaan-m/everything-claude-code/pull/257).
-- **Antigravity**: плотная настройка для workflows, skills и flattened rules в `.agent/`. См. [Antigravity Guide](../ANTIGRAVITY-GUIDE.md).
+- **Antigravity**: плотная настройка для workflows, skills, agents и flattened rules в `.agents/`. См. [Antigravity Guide](../ANTIGRAVITY-GUIDE.md).
 - **Ненативные среды**: ручной fallback path для Grok и похожих интерфейсов. См. [Manual Adaptation Guide](../MANUAL-ADAPTATION-GUIDE.md).
 - **Claude Code**: нативно — это основная цель.
 </details>
diff --git a/docs/tr/README.md b/docs/tr/README.md
index ac43c7b8c..3327be34d 100644
--- a/docs/tr/README.md
+++ b/docs/tr/README.md
@@ -411,7 +411,7 @@ Evet. ECC çapraz platformdur:
 - **Cursor**: `.cursor/` içinde önceden çevrilmiş config'ler. [Cursor IDE Desteği](../../README.md#cursor-ide-support) bölümüne bakın.
 - **OpenCode**: `.opencode/` içinde tam plugin desteği. [OpenCode Desteği](../../README.md#opencode-support) bölümüne bakın.
 - **Codex**: macOS app ve CLI için birinci sınıf destek. PR [#257](https://github.com/affaan-m/everything-claude-code/pull/257)'ye bakın.
-- **Antigravity**: İş akışları, skill'ler ve `.agent/` içinde düzleştirilmiş rule'lar için sıkı entegre kurulum.
+- **Antigravity**: İş akışları, skill'ler ve `.agents/` içinde düzleştirilmiş rule'lar için sıkı entegre kurulum.
 - **Claude Code**: Native — bu birincil hedeftir.
 </details>
 
diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md
index 458122125..f13d8aeae 100644
--- a/docs/zh-CN/README.md
+++ b/docs/zh-CN/README.md
@@ -936,7 +936,7 @@ cp -r everything-claude-code/rules/common ~/.claude/rules/common
 * **Cursor**: 预翻译的配置位于 `.cursor/`。参见 [Cursor IDE 支持](#cursor-ide-支持)。
 * **OpenCode**: `.opencode/` 中的完整插件支持。参见 [OpenCode 支持](#opencode-支持)。
 * **Codex**: 对 macOS 应用和 CLI 的一流支持，带有适配器漂移防护和 SessionStart 回退。参见 PR [#257](https://github.com/affaan-m/everything-claude-code/pull/257)。
-* **Antigravity**: 为工作流、技能和扁平化规则紧密集成的设置，位于 `.agent/`。参见 [Antigravity 指南](../ANTIGRAVITY-GUIDE.md)。
+* **Antigravity**: 为工作流、技能和扁平化规则紧密集成的设置，位于 `.agents/`。参见 [Antigravity 指南](../ANTIGRAVITY-GUIDE.md)。
 * **Claude Code**: 原生支持 — 这是主要目标。
 
 </details>
diff --git a/docs/zh-CN/skills/repo-scan/SKILL.md b/docs/zh-CN/skills/repo-scan/SKILL.md
index 2797a2903..9b785f0b9 100644
--- a/docs/zh-CN/skills/repo-scan/SKILL.md
+++ b/docs/zh-CN/skills/repo-scan/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: repo-scan
-description: 跨栈源代码资产审计——对每个文件进行分类，检测嵌入的第三方库，并为每个模块提供可操作的四级判定结果，附带交互式HTML报告。
+description: 用于从固定且可审查的提交安装外部 repo-scan 技能的引导指针。在运行跨栈源代码资产审计前需要安装 repo-scan 时使用；此 ECC 指针本身不执行审计。
 origin: community
 ---
 
@@ -18,18 +18,109 @@ origin: community
 ## 安装
 
 ```bash
-# Fetch only the pinned commit for reproducibility
-mkdir -p ~/.claude/skills/repo-scan
-git init repo-scan
-cd repo-scan
-git remote add origin https://github.com/haibindev/repo-scan.git
-git fetch --depth 1 origin 2742664
-git checkout --detach FETCH_HEAD
-cp -r . ~/.claude/skills/repo-scan
+# Clone first so the pinned commit can be reviewed before installation
+set -euo pipefail
+
+REPO_SCAN_COMMIT=2742664ebcad1450c208eda0ae45d3c17fad5dd8
+REPO_SCAN_INSTALL_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/repo-scan"
+REPO_SCAN_INSTALL_PARENT="$(dirname "$REPO_SCAN_INSTALL_DIR")"
+mkdir -p "$REPO_SCAN_INSTALL_PARENT"
+REPO_SCAN_TMP="$(mktemp -d "$REPO_SCAN_INSTALL_PARENT/.repo-scan-install.XXXXXX")"
+REPO_SCAN_TOKEN="${REPO_SCAN_TMP##*.}"
+REPO_SCAN_STAGE="$REPO_SCAN_TMP/stage-$REPO_SCAN_TOKEN"
+REPO_SCAN_BACKUP="$REPO_SCAN_TMP/backup-$REPO_SCAN_TOKEN"
+REPO_SCAN_LOCK="$REPO_SCAN_INSTALL_PARENT/.repo-scan-install.lock"
+REPO_SCAN_KEEP_TMP=0
+REPO_SCAN_LOCK_HELD=0
+REPO_SCAN_MV_HAS_NO_TARGET=0
+cleanup_repo_scan_install() {
+  if [ "$REPO_SCAN_KEEP_TMP" -eq 0 ]; then
+    rm -rf -- "$REPO_SCAN_TMP"
+  fi
+  if [ "$REPO_SCAN_LOCK_HELD" -eq 1 ] && ! rmdir -- "$REPO_SCAN_LOCK"; then
+    printf 'Could not release installation lock at %s\n' "$REPO_SCAN_LOCK" >&2
+  fi
+}
+trap cleanup_repo_scan_install EXIT
+mkdir "$REPO_SCAN_TMP/mv-probe-source"
+if mv -T -- "$REPO_SCAN_TMP/mv-probe-source" \
+  "$REPO_SCAN_TMP/mv-probe-destination" 2>/dev/null; then
+  REPO_SCAN_MV_HAS_NO_TARGET=1
+  rmdir "$REPO_SCAN_TMP/mv-probe-destination"
+else
+  rmdir "$REPO_SCAN_TMP/mv-probe-source"
+fi
+move_repo_scan_dir() {
+  REPO_SCAN_MOVE_SOURCE=$1
+  REPO_SCAN_MOVE_DESTINATION=$2
+  REPO_SCAN_MOVE_NAME=${REPO_SCAN_MOVE_SOURCE##*/}
+  if [ -e "$REPO_SCAN_MOVE_DESTINATION" ] || [ -L "$REPO_SCAN_MOVE_DESTINATION" ]; then
+    return 1
+  fi
+  if [ "$REPO_SCAN_MV_HAS_NO_TARGET" -eq 1 ]; then
+    mv -T -- "$REPO_SCAN_MOVE_SOURCE" "$REPO_SCAN_MOVE_DESTINATION"
+    return
+  fi
+  if ! mv -- "$REPO_SCAN_MOVE_SOURCE" "$REPO_SCAN_MOVE_DESTINATION"; then
+    return 1
+  fi
+  if [ -e "$REPO_SCAN_MOVE_DESTINATION/$REPO_SCAN_MOVE_NAME" ] || \
+    [ -L "$REPO_SCAN_MOVE_DESTINATION/$REPO_SCAN_MOVE_NAME" ]; then
+    if ! mv -- "$REPO_SCAN_MOVE_DESTINATION/$REPO_SCAN_MOVE_NAME" \
+      "$REPO_SCAN_MOVE_SOURCE"; then
+      REPO_SCAN_KEEP_TMP=1
+      printf 'Move conflict recovery failed; staged data remains at %s\n' \
+        "$REPO_SCAN_MOVE_DESTINATION/$REPO_SCAN_MOVE_NAME" >&2
+    fi
+    return 1
+  fi
+}
+
+git clone --filter=blob:none --no-checkout \
+  https://github.com/haibindev/repo-scan.git "$REPO_SCAN_TMP/source"
+git -C "$REPO_SCAN_TMP/source" checkout --detach "$REPO_SCAN_COMMIT"
+mkdir -p "$REPO_SCAN_STAGE"
+git -C "$REPO_SCAN_TMP/source" archive "$REPO_SCAN_COMMIT" | \
+  tar -xf - -C "$REPO_SCAN_STAGE"
+
+# Review "$REPO_SCAN_TMP/source" before approving installation.
+printf 'Type install to replace %s after reviewing the pinned source: ' \
+  "$REPO_SCAN_INSTALL_DIR" >&2
+read -r REPO_SCAN_CONFIRM
+if [ "$REPO_SCAN_CONFIRM" != install ]; then
+  printf 'Installation cancelled.\n' >&2
+  exit 1
+fi
+if ! mkdir -- "$REPO_SCAN_LOCK" 2>/dev/null; then
+  printf 'Another repo-scan installation holds the lock at %s\n' \
+    "$REPO_SCAN_LOCK" >&2
+  exit 1
+fi
+REPO_SCAN_LOCK_HELD=1
+
+if [ -e "$REPO_SCAN_INSTALL_DIR" ] || [ -L "$REPO_SCAN_INSTALL_DIR" ]; then
+  move_repo_scan_dir "$REPO_SCAN_INSTALL_DIR" "$REPO_SCAN_BACKUP"
+fi
+if ! move_repo_scan_dir "$REPO_SCAN_STAGE" "$REPO_SCAN_INSTALL_DIR"; then
+  if [ -e "$REPO_SCAN_BACKUP" ] || [ -L "$REPO_SCAN_BACKUP" ]; then
+    if [ -e "$REPO_SCAN_INSTALL_DIR" ] || [ -L "$REPO_SCAN_INSTALL_DIR" ]; then
+      REPO_SCAN_KEEP_TMP=1
+      printf 'Replacement failed and target was recreated; previous installation preserved at %s\n' \
+        "$REPO_SCAN_BACKUP" >&2
+    elif ! move_repo_scan_dir "$REPO_SCAN_BACKUP" "$REPO_SCAN_INSTALL_DIR"; then
+      REPO_SCAN_KEEP_TMP=1
+      printf 'Replacement and rollback failed; previous installation preserved at %s\n' \
+        "$REPO_SCAN_BACKUP" >&2
+    fi
+  fi
+  exit 1
+fi
 ```
 
 > 安装任何代理技能前，请先审查源码。
 
+安装后，请重新加载智能体运行环境，然后再次调用 `repo-scan`。此 ECC 指针仅安装外部技能，本身不会执行扫描。
+
 ## 核心能力
 
 | 能力 | 描述 |
diff --git a/package-lock.json b/package-lock.json
index 01550d793..b08a202f1 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -11,6 +11,7 @@
       "dependencies": {
         "@iarna/toml": "2.2.5",
         "ajv": "8.20.0",
+        "js-yaml": "4.3.1",
         "sql.js": "1.14.1"
       },
       "bin": {
@@ -531,7 +532,6 @@
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
       "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
-      "dev": true,
       "license": "Python-2.0"
     },
     "node_modules/balanced-match": {
@@ -1474,10 +1474,9 @@
       }
     },
     "node_modules/js-yaml": {
-      "version": "4.3.0",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.0.tgz",
-      "integrity": "sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==",
-      "dev": true,
+      "version": "4.3.1",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.1.tgz",
+      "integrity": "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==",
       "funding": [
         {
           "type": "github",
diff --git a/package.json b/package.json
index 55030f5f4..56ac663db 100644
--- a/package.json
+++ b/package.json
@@ -134,6 +134,10 @@
     "scripts/skill-create-output.js",
     "scripts/status.js",
     "scripts/sync-ecc-to-codex.sh",
+    "scripts/codex/legacy-sync-state.js",
+    "scripts/codex/install-global-git-hooks.sh",
+    "scripts/codex/check-codex-global-state.sh",
+    "scripts/codex-git-hooks/",
     "scripts/work-items.js",
     "scripts/uninstall.js",
     "skills/agent-architecture-audit/",
@@ -469,6 +473,7 @@
   "dependencies": {
     "@iarna/toml": "2.2.5",
     "ajv": "8.20.0",
+    "js-yaml": "4.3.1",
     "sql.js": "1.14.1"
   },
   "pi": {
@@ -498,12 +503,12 @@
   "overrides": {
     "fast-uri": "3.1.5",
     "markdown-it": "14.3.0",
-    "js-yaml": "4.3.0"
+    "js-yaml": "4.3.1"
   },
   "resolutions": {
     "fast-uri": "3.1.5",
     "markdown-it": "14.3.0",
-    "js-yaml": "4.3.0"
+    "js-yaml": "4.3.1"
   },
   "packageManager": "yarn@4.9.2+sha512.1fc009bc09d13cfd0e19efa44cbfc2b9cf6ca61482725eb35bbc5e257e093ebf4130db6dfe15d604ff4b79efd8e1e8e99b25fa7d0a6197c9f9826358d4d65c3c"
 }
diff --git a/scripts/auto-update.js b/scripts/auto-update.js
index 284e532c2..67793d945 100644
--- a/scripts/auto-update.js
+++ b/scripts/auto-update.js
@@ -179,11 +179,18 @@ function runAutoUpdate(options = {}, dependencies = {}) {
   const homeDir = options.homeDir || process.env.HOME || os.homedir();
   const projectRoot = options.projectRoot || process.cwd();
   const requestedRepoRoot = options.repoRoot ? validateRepoRoot(options.repoRoot) : null;
-  const records = discover({
+  const discoveredRecords = discover({
     homeDir,
     projectRoot,
     targets: options.targets
-  }).filter(record => record.exists);
+  });
+  const records = discoveredRecords.filter(record => record.exists && !record.legacy);
+  const legacyRecords = discoveredRecords.filter(record => record.exists && record.legacy);
+  const warnings = records.length === 0 && legacyRecords.length > 0
+    ? [
+        'Found only a legacy Antigravity .agent install-state. Run the Antigravity installer once to migrate it to .agents before auto-updating.',
+      ]
+    : [];
 
   const results = [];
   if (records.length === 0) {
@@ -191,6 +198,7 @@ function runAutoUpdate(options = {}, dependencies = {}) {
       dryRun: Boolean(options.dryRun),
       repoRoot: requestedRepoRoot,
       results,
+      warnings,
       summary: {
         checkedCount: 0,
         updatedCount: 0,
@@ -233,6 +241,7 @@ function runAutoUpdate(options = {}, dependencies = {}) {
       dryRun: Boolean(options.dryRun),
       repoRoot,
       results,
+      warnings,
       summary: {
         checkedCount: results.length,
         updatedCount: 0,
@@ -296,6 +305,7 @@ function runAutoUpdate(options = {}, dependencies = {}) {
     dryRun: Boolean(options.dryRun),
     repoRoot,
     results,
+    warnings,
     summary: {
       checkedCount: results.length,
       updatedCount: results.filter(result => result.status === 'updated' || result.status === 'planned').length,
@@ -306,7 +316,13 @@ function runAutoUpdate(options = {}, dependencies = {}) {
 
 function printHuman(result) {
   if (result.results.length === 0) {
-    console.log('No ECC install-state files found for the current home/project context.');
+    const hasWarnings = Array.isArray(result.warnings) && result.warnings.length > 0;
+    console.log(hasWarnings
+      ? 'No active ECC install-state files found for the current home/project context.'
+      : 'No ECC install-state files found for the current home/project context.');
+    for (const warning of Array.isArray(result.warnings) ? result.warnings : []) {
+      console.log(`Warning: ${warning}`);
+    }
     return;
   }
 
diff --git a/scripts/codex/legacy-sync-state.js b/scripts/codex/legacy-sync-state.js
new file mode 100644
index 000000000..b6ce0c57b
--- /dev/null
+++ b/scripts/codex/legacy-sync-state.js
@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+'use strict';
+
+const {
+  beginLegacySyncState,
+  finalizeLegacySyncState,
+  recordLegacySyncPath,
+  rollbackLegacyCodexSync,
+} = require('../lib/codex-legacy-sync');
+
+function readFlag(args, name) {
+  const index = args.indexOf(name);
+  return index === -1 ? null : args[index + 1] || null;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const command = argv[0];
+  if (command === 'begin') {
+    const codexHome = readFlag(argv, '--codex-home');
+    const backupDir = readFlag(argv, '--backup-dir');
+    if (!codexHome || !backupDir) throw new Error('begin requires --codex-home and --backup-dir');
+    process.stdout.write(`${beginLegacySyncState({
+      codexHome,
+      backupDir,
+      previousHooksPath: readFlag(argv, '--previous-hooks-path') || '',
+      installedHooksPath: readFlag(argv, '--installed-hooks-path'),
+    })}\n`);
+    return;
+  }
+  if (command === 'record') {
+    const statePath = readFlag(argv, '--state');
+    const filePath = readFlag(argv, '--path');
+    if (!statePath || !filePath) throw new Error('record requires --state and --path');
+    recordLegacySyncPath({ statePath, filePath });
+    return;
+  }
+  if (command === 'finalize') {
+    const statePath = readFlag(argv, '--state');
+    if (!statePath) throw new Error('finalize requires --state');
+    finalizeLegacySyncState({ statePath });
+    return;
+  }
+  if (command === 'rollback') {
+    const statePath = readFlag(argv, '--state');
+    if (!statePath) throw new Error('rollback requires --state');
+    const result = rollbackLegacyCodexSync({ statePath });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (result.status !== 'rolled-back') process.exitCode = 1;
+    return;
+  }
+  throw new Error('Usage: legacy-sync-state.js <begin|record|finalize|rollback> [options]');
+}
+
+try {
+  main();
+} catch (error) {
+  process.stderr.write(`[ecc-sync] ERROR: ${error.message}\n`);
+  process.exit(1);
+}
+
+module.exports = { main, readFlag };
diff --git a/scripts/install-apply.js b/scripts/install-apply.js
index b961537a8..776d5f35d 100755
--- a/scripts/install-apply.js
+++ b/scripts/install-apply.js
@@ -36,7 +36,7 @@ Targets:
   claude       (default) - Install ECC into ~/.claude/ with managed rules under rules/ecc and flat skills under skills/
   claude-project - Install ECC into ./.claude/ (per-project) with managed rules under rules/ecc and flat skills under skills/
   cursor       - Install rules, hooks, and bundled Cursor configs to ./.cursor/
-  antigravity  - Install rules, workflows, skills, and agents to ./.agent/
+  antigravity  - Install rules, workflows, skills, and agents to ./.agents/
   codex        - Install shared agents/config into ~/.codex/
   gemini       - Install project-local Gemini config into ./.gemini/
   opencode     - Install shared commands/hooks/config into ~/.opencode/
@@ -134,7 +134,7 @@ function printHumanPlan(plan, dryRun) {
   console.log('\nCompute: ' + getComputeSponsorCopy());
 }
 
-function main() {
+async function main() {
   try {
     const options = parseInstallArgs(process.argv);
 
@@ -177,7 +177,18 @@ function main() {
       return;
     }
 
-    const result = applyInstallPlan(rawPlan);
+    let result = applyInstallPlan(rawPlan);
+    const { projectCanonicalInstallState } = require('./lib/install-state-store-sync');
+    const installStateProjection = await projectCanonicalInstallState(result.statePreview, {
+      homeDir: process.env.HOME || os.homedir(),
+    });
+    result = {
+      ...result,
+      installStateProjection,
+      warnings: installStateProjection.warning
+        ? [...result.warnings, `Install health projection warning: ${installStateProjection.warning.message}`]
+        : result.warnings,
+    };
     if (options.json) {
       console.log(JSON.stringify({ dryRun: false, result }, null, 2));
     } else {
diff --git a/scripts/lib/codex-legacy-sync.js b/scripts/lib/codex-legacy-sync.js
new file mode 100644
index 000000000..cbf5b2750
--- /dev/null
+++ b/scripts/lib/codex-legacy-sync.js
@@ -0,0 +1,479 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const SCHEMA = 'ecc.codex-legacy-sync.v1';
+const BEGIN_MARKER = '<!-- BEGIN ECC -->';
+const END_MARKER = '<!-- END ECC -->';
+
+function getStatePath(codexHome) {
+  return path.join(codexHome, 'ecc', 'legacy-sync-state.json');
+}
+
+function digestFile(filePath) {
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
+function atomicWriteJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tempPath, filePath);
+}
+
+function readState(statePath) {
+  const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+  if (state.schema !== SCHEMA || !Array.isArray(state.paths)) {
+    throw new Error(`Invalid legacy Codex sync state at ${statePath}`);
+  }
+  return state;
+}
+
+function hasUnsafeManagedAncestor(filePath, codexHome) {
+  const relativePath = path.relative(codexHome, filePath);
+  if (relativePath === '' || relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+    return relativePath !== '';
+  }
+  const segments = relativePath.split(path.sep).slice(0, -1);
+  let currentPath = codexHome;
+  for (const segment of [null, ...segments]) {
+    if (segment !== null) currentPath = path.join(currentPath, segment);
+    try {
+      const stat = fs.lstatSync(currentPath);
+      if (stat.isSymbolicLink() || !stat.isDirectory()) return true;
+    } catch (error) {
+      if (error.code === 'ENOENT') break;
+      throw error;
+    }
+  }
+  return false;
+}
+
+function isWithinRoot(filePath, rootPath) {
+  const relativePath = path.relative(rootPath, filePath);
+  return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+}
+
+function getTrustedRoot(state, filePath) {
+  const roots = Array.isArray(state.trustedRoots) && state.trustedRoots.length > 0
+    ? state.trustedRoots
+    : [state.codexHome];
+  return roots
+    .map(rootPath => path.resolve(rootPath))
+    .find(rootPath => isWithinRoot(filePath, rootPath)) || null;
+}
+
+function snapshotLegacyPath(filePath) {
+  let previousContentBase64 = null;
+  let previousMode = null;
+  let previousType = 'missing';
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (stat.isFile()) {
+      previousType = 'file';
+      previousContentBase64 = fs.readFileSync(filePath).toString('base64');
+      previousMode = stat.mode & 0o777;
+    } else {
+      previousType = stat.isSymbolicLink() ? 'symlink' : 'other';
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  if (previousType === 'symlink' || previousType === 'other') {
+    throw new Error(`Refusing to manage non-regular legacy sync path: ${filePath}`);
+  }
+  return {
+    path: filePath,
+    installedSha256: null,
+    previousType,
+    previousContentBase64,
+    previousMode,
+  };
+}
+
+function assertInstalledStateUnmodified(state) {
+  for (const entry of state.paths) {
+    const filePath = path.resolve(entry.path);
+    const trustedRoot = getTrustedRoot(state, filePath);
+    if (!trustedRoot || hasUnsafeManagedAncestor(filePath, trustedRoot)) {
+      throw new Error(`Refusing to reuse unsafe legacy Codex ownership path: ${filePath}`);
+    }
+    let stat = null;
+    try {
+      stat = fs.lstatSync(filePath);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    if (!entry.installedSha256) {
+      if (stat) throw new Error(`Refusing to replace modified legacy Codex artifact: ${filePath}`);
+      continue;
+    }
+    if (!stat || !stat.isFile() || digestFile(filePath) !== entry.installedSha256) {
+      throw new Error(`Refusing to replace modified legacy Codex artifact: ${filePath}`);
+    }
+  }
+}
+
+function beginLegacySyncState(options) {
+  const codexHome = path.resolve(options.codexHome);
+  const statePath = getStatePath(codexHome);
+  const configPath = path.join(codexHome, 'config.toml');
+  const agentsPath = path.join(codexHome, 'AGENTS.md');
+  const installedHooksPath = options.installedHooksPath ? path.resolve(options.installedHooksPath) : null;
+  const priorState = fs.existsSync(statePath) ? readState(statePath) : null;
+  if (priorState && priorState.status !== 'installed') {
+    throw new Error(`Legacy Codex sync state requires recovery before reinstall: ${statePath}`);
+  }
+  if (priorState) assertInstalledStateUnmodified(priorState);
+  const trustedRoots = [...new Set([
+    codexHome,
+    ...(Array.isArray(priorState?.trustedRoots) ? priorState.trustedRoots : []),
+    ...(priorState?.installedHooksPath ? [priorState.installedHooksPath] : []),
+    ...(installedHooksPath ? [installedHooksPath] : []),
+  ].map(rootPath => path.resolve(rootPath)))];
+  const state = priorState ? {
+    ...priorState,
+    status: 'applying',
+    updatedAt: new Date().toISOString(),
+    backupDir: options.backupDir ? path.resolve(options.backupDir) : priorState.backupDir,
+    installedHooksPath,
+    trustedRoots,
+    rollbackPreviousHooksPath: options.previousHooksPath || null,
+    rollbackPaths: priorState.paths.map(entry => snapshotLegacyPath(path.resolve(entry.path))),
+    previousInstalledState: priorState,
+  } : {
+    schema: SCHEMA,
+    status: 'applying',
+    createdAt: new Date().toISOString(),
+    codexHome,
+    backupDir: options.backupDir ? path.resolve(options.backupDir) : null,
+    previousHooksPath: options.previousHooksPath || null,
+    installedHooksPath,
+    trustedRoots,
+    before: {},
+    paths: [],
+    rollbackPaths: [],
+  };
+
+  for (const [key, filePath] of [['config', configPath], ['agents', agentsPath]]) {
+    if (priorState) break;
+    if (fs.existsSync(filePath)) {
+      const stat = fs.lstatSync(filePath);
+      if (!stat.isFile()) {
+        throw new Error(`Refusing to snapshot non-regular legacy sync path: ${filePath}`);
+      }
+      state.before[key] = fs.readFileSync(filePath, 'utf8');
+    } else {
+      state.before[key] = null;
+    }
+  }
+  atomicWriteJson(statePath, state);
+  return statePath;
+}
+
+function recordLegacySyncPath(options) {
+  const state = readState(options.statePath);
+  const filePath = path.resolve(options.filePath);
+  const trustedRoot = getTrustedRoot(state, filePath);
+  if (!trustedRoot) {
+    throw new Error(`Refusing to record a legacy sync path outside trusted roots: ${filePath}`);
+  }
+  if (hasUnsafeManagedAncestor(filePath, trustedRoot)) {
+    throw new Error(`Refusing to manage legacy sync path through symlinked ancestor: ${filePath}`);
+  }
+  if (!state.paths.some(entry => entry.path === filePath)) {
+    const snapshot = snapshotLegacyPath(filePath);
+    state.paths.push(snapshot);
+    state.rollbackPaths = [...(state.rollbackPaths || []), { ...snapshot }];
+    atomicWriteJson(options.statePath, state);
+  }
+}
+
+function rollbackLegacyCodexSync(options) {
+  const state = readState(options.statePath);
+  const restoredPaths = [];
+  const retainedPaths = [];
+
+  const rollbackPaths = Array.isArray(state.rollbackPaths) ? state.rollbackPaths : state.paths;
+  for (const entry of [...rollbackPaths].reverse()) {
+    const filePath = path.resolve(entry.path);
+    const trustedRoot = getTrustedRoot(state, filePath);
+    if (!trustedRoot) {
+      retainedPaths.push(filePath);
+      continue;
+    }
+    if (hasUnsafeManagedAncestor(filePath, trustedRoot)) {
+      retainedPaths.push(filePath);
+      continue;
+    }
+    let currentStat = null;
+    try {
+      currentStat = fs.lstatSync(filePath);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    if (currentStat && !currentStat.isFile() && !currentStat.isSymbolicLink()) {
+      retainedPaths.push(filePath);
+      continue;
+    }
+    if (entry.previousType === 'file' && typeof entry.previousContentBase64 === 'string') {
+      if (currentStat && currentStat.isSymbolicLink()) {
+        retainedPaths.push(filePath);
+        continue;
+      }
+      fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+      fs.writeFileSync(filePath, Buffer.from(entry.previousContentBase64, 'base64'), {
+        mode: entry.previousMode || 0o600,
+      });
+      if (entry.previousMode) fs.chmodSync(filePath, entry.previousMode);
+      restoredPaths.push(filePath);
+    } else if (entry.previousType === 'missing' || entry.previousType === undefined) {
+      if (currentStat) fs.rmSync(filePath, { force: true });
+      restoredPaths.push(filePath);
+    } else {
+      retainedPaths.push(filePath);
+    }
+  }
+
+  if (state.installedHooksPath) {
+    const getHooks = options.getGlobalHooksPath || defaultGetHooksPath;
+    const setHooks = options.setGlobalHooksPath || defaultSetHooksPath;
+    const currentHooks = getHooks();
+    if (currentHooks && path.resolve(currentHooks) === path.resolve(state.installedHooksPath)) {
+      setHooks(state.rollbackPreviousHooksPath ?? state.previousHooksPath ?? '');
+    } else if (currentHooks && currentHooks !== (state.rollbackPreviousHooksPath ?? state.previousHooksPath)) {
+      retainedPaths.push(`git:core.hooksPath=${currentHooks}`);
+    }
+  }
+
+  if (retainedPaths.length === 0) {
+    if (state.previousInstalledState) {
+      atomicWriteJson(options.statePath, state.previousInstalledState);
+    } else {
+      fs.rmSync(options.statePath, { force: true });
+    }
+  }
+  return {
+    status: retainedPaths.length === 0 ? 'rolled-back' : 'partial',
+    statePath: options.statePath,
+    restoredPaths,
+    retainedPaths: [...new Set(retainedPaths)].sort(),
+  };
+}
+
+function finalizeLegacySyncState(options) {
+  const state = readState(options.statePath);
+  state.status = 'installed';
+  state.installedAt = new Date().toISOString();
+  delete state.rollbackPaths;
+  delete state.rollbackPreviousHooksPath;
+  delete state.previousInstalledState;
+  state.paths = state.paths.map(entry => ({
+    ...entry,
+    installedSha256: getTrustedRoot(state, path.resolve(entry.path))
+      && !hasUnsafeManagedAncestor(entry.path, getTrustedRoot(state, path.resolve(entry.path)))
+      && fs.existsSync(entry.path)
+      && fs.lstatSync(entry.path).isFile()
+      ? digestFile(entry.path)
+      : null,
+  }));
+  atomicWriteJson(options.statePath, state);
+  return state;
+}
+
+function stripMarkerBlock(content) {
+  const markers = [];
+  let fence = null;
+  let offset = 0;
+  for (const lineWithEnding of content.match(/.*(?:\r?\n|$)/g) || []) {
+    if (lineWithEnding === '') continue;
+    const line = lineWithEnding.replace(/\r?\n$/, '');
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})(.*)$/);
+    if (fenceMatch) {
+      const run = fenceMatch[1];
+      const marker = run[0];
+      if (!fence) {
+        fence = { marker, length: run.length };
+      } else if (
+        marker === fence.marker
+        && run.length >= fence.length
+        && fenceMatch[2].trim() === ''
+      ) {
+        fence = null;
+      }
+    } else if (!fence && (line === BEGIN_MARKER || line === END_MARKER)) {
+      markers.push({ marker: line, index: offset });
+    }
+    offset += lineWithEnding.length;
+  }
+  const begins = markers.filter(match => match.marker === BEGIN_MARKER);
+  const ends = markers.filter(match => match.marker === END_MARKER);
+  if (begins.length !== 1 || ends.length !== 1 || ends[0].index < begins[0].index) {
+    return content;
+  }
+  const suffixStart = ends[0].index + END_MARKER.length;
+  const suffixWithLineEnding = content.slice(suffixStart).replace(/^\r?\n/, '');
+  return `${content.slice(0, begins[0].index)}${suffixWithLineEnding}`;
+}
+
+function defaultGetHooksPath() {
+  try {
+    return execFileSync('git', ['config', '--global', '--get', 'core.hooksPath'], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000,
+    }).trim();
+  } catch (_error) {
+    return '';
+  }
+}
+
+function defaultSetHooksPath(value) {
+  const args = value
+    ? ['config', '--global', 'core.hooksPath', value]
+    : ['config', '--global', '--unset-all', 'core.hooksPath'];
+  try {
+    execFileSync('git', args, { stdio: 'ignore', timeout: 5000 });
+  } catch (error) {
+    if (value || error.status !== 5) throw error;
+  }
+}
+
+function listLegacyCandidates(codexHome) {
+  const candidates = [];
+  const promptsDir = path.join(codexHome, 'prompts');
+  if (fs.existsSync(promptsDir)) {
+    for (const entry of fs.readdirSync(promptsDir)) {
+      if (entry.startsWith('ecc-') || entry.startsWith('ecc_') || entry.includes('ecc-rules-pack')) {
+        candidates.push(path.join(promptsDir, entry));
+      }
+    }
+  }
+  for (const relativePath of [
+    'docs/CODEX-NAVIGATION-GUIDE.md',
+    'docs/COMMAND-AGENT-MAP.md',
+    'COMMANDS-QUICK-REF.md',
+    'CONTRIBUTING.md',
+    '.github/PULL_REQUEST_TEMPLATE.md',
+    'ecc-prompts-manifest.txt',
+    'ecc-extension-prompts-manifest.txt',
+  ]) {
+    const candidate = path.join(codexHome, relativePath);
+    if (fs.existsSync(candidate)) candidates.push(candidate);
+  }
+  return candidates;
+}
+
+function uninstallLegacyCodexSync(options = {}) {
+  const codexHome = path.resolve(options.codexHome || process.env.CODEX_HOME || path.join(process.env.HOME || os.homedir(), '.codex'));
+  const statePath = getStatePath(codexHome);
+  const dryRun = options.dryRun === true;
+  const retainedPaths = [];
+  const plannedRemovals = [];
+  const removedPaths = [];
+  const agentsPath = path.join(codexHome, 'AGENTS.md');
+  const state = fs.existsSync(statePath) ? readState(statePath) : null;
+
+  if (!state) {
+    if (fs.existsSync(agentsPath)) {
+      const agentsStat = fs.lstatSync(agentsPath);
+      if (!agentsStat.isFile()) {
+        retainedPaths.push(agentsPath);
+      } else {
+        const content = fs.readFileSync(agentsPath, 'utf8');
+        const stripped = stripMarkerBlock(content);
+        if (stripped !== content) {
+          plannedRemovals.push(`${agentsPath}#ecc-marker-block`);
+          if (!dryRun) fs.writeFileSync(agentsPath, stripped, 'utf8');
+        }
+      }
+    }
+    retainedPaths.push(...listLegacyCandidates(codexHome));
+    return {
+      status: dryRun ? 'planned' : retainedPaths.length > 0 ? 'partial' : plannedRemovals.length > 0 ? 'uninstalled' : 'not-found',
+      statePath: null,
+      plannedRemovals,
+      removedPaths,
+      retainedPaths: [...new Set(retainedPaths)].sort(),
+      warnings: retainedPaths.length > 0
+        ? ['Legacy Codex artifacts without an ownership manifest were preserved for manual review.']
+        : [],
+    };
+  }
+
+  for (const entry of state.paths) {
+    const filePath = path.resolve(entry.path);
+    const trustedRoot = getTrustedRoot(state, filePath);
+    if (!trustedRoot) {
+      retainedPaths.push(filePath);
+      continue;
+    }
+    if (hasUnsafeManagedAncestor(filePath, trustedRoot)) {
+      retainedPaths.push(filePath);
+      continue;
+    }
+    if (!fs.existsSync(filePath)) continue;
+    const currentStat = fs.lstatSync(filePath);
+    const matches = entry.installedSha256 && currentStat.isFile()
+      ? digestFile(filePath) === entry.installedSha256
+      : false;
+    if (!matches) {
+      retainedPaths.push(filePath);
+      continue;
+    }
+    plannedRemovals.push(filePath);
+    if (!dryRun) {
+      if (entry.previousType === 'file' && typeof entry.previousContentBase64 === 'string') {
+        fs.writeFileSync(filePath, Buffer.from(entry.previousContentBase64, 'base64'), {
+          mode: entry.previousMode || 0o600,
+        });
+      } else if (entry.previousType === 'missing' || entry.previousType === undefined) {
+        fs.rmSync(filePath, { force: true });
+      } else {
+        retainedPaths.push(filePath);
+        continue;
+      }
+      removedPaths.push(filePath);
+    }
+  }
+
+  if (state.installedHooksPath) {
+    const getHooks = options.getGlobalHooksPath || defaultGetHooksPath;
+    const setHooks = options.setGlobalHooksPath || defaultSetHooksPath;
+    const currentHooks = getHooks();
+    if (path.resolve(currentHooks || '.') === path.resolve(state.installedHooksPath)) {
+      if (!dryRun) setHooks(state.previousHooksPath || '');
+    } else if (currentHooks) {
+      retainedPaths.push(`git:core.hooksPath=${currentHooks}`);
+    }
+  }
+
+  if (!dryRun && retainedPaths.length === 0) {
+    fs.rmSync(statePath, { force: true });
+  }
+  return {
+    status: dryRun ? 'planned' : retainedPaths.length > 0 ? 'partial' : 'uninstalled',
+    statePath,
+    plannedRemovals: [...new Set(plannedRemovals)],
+    removedPaths,
+    retainedPaths: [...new Set(retainedPaths)].sort(),
+    warnings: retainedPaths.length > 0
+      ? ['Modified or unverifiable legacy Codex artifacts were preserved.']
+      : [],
+  };
+}
+
+module.exports = {
+  BEGIN_MARKER,
+  END_MARKER,
+  SCHEMA,
+  beginLegacySyncState,
+  finalizeLegacySyncState,
+  getStatePath,
+  recordLegacySyncPath,
+  rollbackLegacyCodexSync,
+  stripMarkerBlock,
+  uninstallLegacyCodexSync,
+};
diff --git a/scripts/lib/harness-capabilities.js b/scripts/lib/harness-capabilities.js
index 10e9c07a7..f04f233e5 100644
--- a/scripts/lib/harness-capabilities.js
+++ b/scripts/lib/harness-capabilities.js
@@ -109,8 +109,8 @@ const HARNESS_CAPABILITIES = deepFreeze([
     installMode: 'managed-project',
     guidedReady: false,
     availability: 'advanced',
-    destination: './.agent',
-    scopes: [scope('project', 'antigravity', './.agent')],
+    destination: './.agents',
+    scopes: [scope('project', 'antigravity', './.agents')],
     hooks: hooks('not-configured', false, 'ECC hooks are not configured by this adapter.'),
     aliases: ['google-antigravity'],
   },
diff --git a/scripts/lib/install-executor.js b/scripts/lib/install-executor.js
index 5c0b478cd..23f9d1f6b 100644
--- a/scripts/lib/install-executor.js
+++ b/scripts/lib/install-executor.js
@@ -80,7 +80,8 @@ function validateLegacyTarget(target) {
   throw new Error(`Unknown install target: ${target}. Expected one of ${SUPPORTED_INSTALL_TARGETS.join(', ')}`);
 }
 
-const IGNORED_DIRECTORY_NAMES = new Set(['node_modules', '.git']);
+const IGNORED_DIRECTORY_NAMES = new Set(['node_modules', '.git', '__pycache__']);
+const IGNORED_FILE_EXTENSIONS = new Set(['.pyc', '.pyo', '.pyd']);
 
 function listFilesRecursive(dirPath) {
   if (!fs.existsSync(dirPath)) {
@@ -101,6 +102,9 @@ function listFilesRecursive(dirPath) {
         files.push(path.join(entry.name, childFile));
       }
     } else if (entry.isFile()) {
+      if (IGNORED_FILE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+        continue;
+      }
       files.push(entry.name);
     }
   }
@@ -128,7 +132,14 @@ function previewInstallPlan(plan) {
   return previewPlan(plan);
 }
 
-function buildCopyFileOperation({ moduleId, sourcePath, sourceRelativePath, destinationPath, strategy }) {
+function buildCopyFileOperation({
+  moduleId,
+  sourcePath,
+  sourceRelativePath,
+  destinationPath,
+  strategy,
+  contentTransform,
+}) {
   return {
     kind: 'copy-file',
     moduleId,
@@ -137,7 +148,8 @@ function buildCopyFileOperation({ moduleId, sourcePath, sourceRelativePath, dest
     destinationPath,
     strategy,
     ownership: 'managed',
-    scaffoldOnly: false
+    scaffoldOnly: false,
+    ...(contentTransform ? { contentTransform } : {}),
   };
 }
 
@@ -163,7 +175,8 @@ function addRecursiveCopyOperations(operations, options) {
         sourcePath,
         sourceRelativePath,
         destinationPath,
-        strategy: options.strategy || 'preserve-relative-path'
+        strategy: options.strategy || 'preserve-relative-path',
+        contentTransform: options.contentTransform,
       })
     );
   }
@@ -343,6 +356,7 @@ function planClaudeStyleLegacyInstall(context, { adapterId, adapterRootInput, ru
 
   return {
     mode: 'legacy',
+    sourceRoot: context.sourceRoot,
     adapter,
     target: adapterId,
     targetRoot,
@@ -514,7 +528,8 @@ function planAntigravityLegacyInstall(context) {
     moduleId: 'legacy-antigravity-install',
     sourceRoot: context.sourceRoot,
     sourceRelativeDir: 'agents',
-    destinationDir: path.join(targetRoot, 'skills')
+    destinationDir: path.join(targetRoot, 'agents'),
+    contentTransform: 'antigravity-agent-frontmatter'
   });
   addRecursiveCopyOperations(operations, {
     moduleId: 'legacy-antigravity-install',
@@ -589,6 +604,7 @@ function createLegacyInstallPlan(options = {}) {
 
   return {
     mode: 'legacy',
+    sourceRoot,
     target: plan.target,
     adapter: {
       id: plan.adapter.id,
@@ -630,6 +646,7 @@ function createLegacyCompatInstallPlan(options = {}) {
     includeComponentIds,
     excludeComponentIds,
     legacyLanguages: selection.legacyLanguages,
+    ruleLanguages: selection.ruleLanguages,
     legacyMode: true,
     requestProfileId: null,
     requestModuleIds: [],
@@ -672,7 +689,8 @@ function materializeScaffoldOperation(sourceRoot, operation) {
         sourcePath,
         sourceRelativePath: operation.sourceRelativePath,
         destinationPath: operation.destinationPath,
-        strategy: operation.strategy
+        strategy: operation.strategy,
+        contentTransform: operation.contentTransform,
       })
     ];
   }
@@ -688,11 +706,22 @@ function materializeScaffoldOperation(sourceRoot, operation) {
       sourcePath: path.join(sourcePath, relativeFile),
       sourceRelativePath,
       destinationPath: path.join(operation.destinationPath, relativeFile),
-      strategy: operation.strategy
+      strategy: operation.strategy,
+      contentTransform: operation.contentTransform,
     });
   });
 }
 
+function isSelectedAntigravityLegacyRule(operation, ruleLanguages) {
+  const normalizedSourcePath = String(operation.sourceRelativePath || '').replace(/\\/g, '/');
+  if (!normalizedSourcePath.startsWith('rules/')) {
+    return true;
+  }
+
+  const namespace = normalizedSourcePath.split('/')[1];
+  return namespace === 'common' || ruleLanguages.includes(namespace);
+}
+
 function dedupeCopyFileOperations(operations) {
   // A `copy-file` operation fully overwrites its destination, so when several
   // of them target the same path (e.g. a generic `commands/<name>.md` shadowed
@@ -748,8 +777,16 @@ function createManifestInstallPlan(options = {}) {
     exemptValidationCodes: options.exemptValidationCodes || [],
   });
   const adapter = getInstallTargetAdapter(target);
+  const materializedOperations = plan.operations.flatMap(operation => (
+    materializeScaffoldOperation(sourceRoot, operation)
+  ));
+  const ruleLanguages = Array.isArray(options.ruleLanguages) ? [...options.ruleLanguages] : [];
   const operations = dedupeCopyFileOperations(
-    plan.operations.flatMap(operation => materializeScaffoldOperation(sourceRoot, operation))
+    options.legacyMode && target === 'antigravity'
+      ? materializedOperations.filter(operation => (
+        isSelectedAntigravityLegacyRule(operation, ruleLanguages)
+      ))
+      : materializedOperations
   );
   const source = {
     repoVersion: getPackageVersion(sourceRoot),
@@ -778,6 +815,7 @@ function createManifestInstallPlan(options = {}) {
 
   return {
     mode: options.mode || 'manifest',
+    sourceRoot,
     target,
     adapter: {
       id: adapter.id,
diff --git a/scripts/lib/install-lifecycle.js b/scripts/lib/install-lifecycle.js
index 69a623eda..7607f17bf 100644
--- a/scripts/lib/install-lifecycle.js
+++ b/scripts/lib/install-lifecycle.js
@@ -1,3 +1,4 @@
+const crypto = require('crypto');
 const fs = require('fs');
 const { execFileSync } = require('child_process');
 const os = require('os');
@@ -10,6 +11,12 @@ const { createManifestInstallPlan } = require('./install-executor');
 const {
   prepareClaudeSkillMigration,
 } = require('./install/claude-skill-migration');
+const {
+  getLegacyAntigravityLocation,
+  inspectLegacyAntigravityState,
+} = require('./install/antigravity-legacy-migration');
+const { adaptAntigravityAgent } = require('./install/antigravity-agent');
+const { buildInstallIndex, rewriteRelativeLinks } = require('./install/link-rewrite');
 const { getInstallTargetAdapter, listInstallTargetAdapters } = require('./install-targets/registry');
 const OPENCODE_BUILD_ARTIFACT = path.join('.opencode', 'dist');
 const OPENCODE_BUILD_SCRIPT = path.join('scripts', 'build-opencode.js');
@@ -138,6 +145,59 @@ function areFilesEqual(leftPath, rightPath) {
   }
 }
 
+function hasRecordedContentDigest(operation) {
+  return /^[a-f0-9]{64}$/i.test(String(operation && operation.contentSha256 || ''));
+}
+
+function fileMatchesRecordedContent(filePath, operation) {
+  if (!hasRecordedContentDigest(operation)) {
+    return false;
+  }
+
+  try {
+    return crypto.createHash('sha256')
+      .update(readFileNoFollow(filePath))
+      .digest('hex') === operation.contentSha256.toLowerCase();
+  } catch (_error) {
+    return false;
+  }
+}
+
+function isMarkdownPath(filePath) {
+  return /\.(md|mdx|markdown)$/i.test(String(filePath || ''));
+}
+
+function buildLinkIndexForOperations(operations, trustedRoot) {
+  const mappings = (operations || [])
+    .filter(operation => operation.kind === 'copy-file' && operation.sourceRelativePath)
+    .map(operation => ({
+      sourceRel: operation.sourceRelativePath,
+      destRel: path.relative(trustedRoot, operation.destinationPath),
+    }));
+  return buildInstallIndex(mappings);
+}
+
+function transformCopyFileContent(operation, content) {
+  if (!operation.contentTransform) {
+    return content;
+  }
+  if (operation.contentTransform === 'antigravity-agent-frontmatter') {
+    return adaptAntigravityAgent(content, operation.sourceRelativePath);
+  }
+  throw new Error(`Unknown install content transform: ${operation.contentTransform}`);
+}
+
+function getExpectedCopyFileContent(operation, content, linkIndex) {
+  const transformed = transformCopyFileContent(operation, content);
+  if (!linkIndex || !operation.sourceRelativePath || !isMarkdownPath(operation.destinationPath)) {
+    return transformed;
+  }
+  return rewriteRelativeLinks(transformed, {
+    sourceRel: operation.sourceRelativePath,
+    index: linkIndex,
+  });
+}
+
 function isPlainObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
@@ -591,7 +651,7 @@ function shouldRepairFromRecordedOperations(state) {
   return getManagedOperations(state).some(operation => operation.kind !== 'copy-file');
 }
 
-function executeRepairOperation(repoRoot, operation, trustedRoot) {
+function executeRepairOperation(repoRoot, operation, trustedRoot, linkIndex = null) {
   // Install-state is attacker-controllable; never write/delete outside the
   // adapter-derived trusted root, regardless of what the state file claims
   // (GHSA-hfpv-w6mp-5g95).
@@ -601,7 +661,18 @@ function executeRepairOperation(repoRoot, operation, trustedRoot) {
       throw new Error(`Missing source file for repair: ${sourcePath || operation.sourceRelativePath}`);
     }
 
-    copyContainedFile(sourcePath, operation.destinationPath, trustedRoot, 'repair');
+    if (operation.contentTransform || isMarkdownPath(operation.destinationPath)) {
+      const source = readFileWithMetadataNoFollow(sourcePath, 'utf8');
+      writeContainedFile(
+        operation.destinationPath,
+        getExpectedCopyFileContent(operation, source.content, linkIndex),
+        trustedRoot,
+        'repair',
+        source.mode & 0o777
+      );
+    } else {
+      copyContainedFile(sourcePath, operation.destinationPath, trustedRoot, 'repair');
+    }
     return operation.destinationPath;
   }
 
@@ -646,9 +717,35 @@ function executeRepairOperation(repoRoot, operation, trustedRoot) {
   throw new Error(`Unsupported repair operation kind: ${operation.kind}`);
 }
 
-function executeUninstallOperation(operation, trustedRoot) {
+function executeUninstallOperation(operation, trustedRoot, options = {}) {
   // Confine deletes to the trusted install root (GHSA-hfpv-w6mp-5g95).
   if (operation.kind === 'copy-file') {
+    if (options.preserveDriftedCopies) {
+      const existingDestination = getContainedExistingPath(
+        operation.destinationPath,
+        trustedRoot,
+        'uninstall'
+      );
+      if (!existingDestination) {
+        return {
+          removedPaths: [],
+          cleanupTargets: []
+        };
+      }
+      const recordedDigest = operation.contentSha256;
+      const currentDigest = /^[a-f0-9]{64}$/i.test(recordedDigest || '')
+        ? crypto.createHash('sha256')
+          .update(readFileNoFollow(existingDestination))
+          .digest('hex')
+        : null;
+      if (!currentDigest || currentDigest !== recordedDigest.toLowerCase()) {
+        return {
+          removedPaths: [],
+          cleanupTargets: []
+        };
+      }
+    }
+
     const removedPath = removeContainedPath(
       operation.destinationPath,
       trustedRoot,
@@ -794,7 +891,7 @@ function executeUninstallOperation(operation, trustedRoot) {
   throw new Error(`Unsupported uninstall operation kind: ${operation.kind}`);
 }
 
-function inspectManagedOperation(repoRoot, trustedRoot, operation) {
+function inspectManagedOperation(repoRoot, trustedRoot, operation, linkIndex = null) {
   const destinationPath = operation.destinationPath;
   if (!destinationPath) {
     return {
@@ -871,7 +968,27 @@ function inspectManagedOperation(repoRoot, trustedRoot, operation) {
       };
     }
 
-    if (!areFilesEqual(copySourcePath, inspectedPath)) {
+    let contentMatches;
+    try {
+      contentMatches = hasRecordedContentDigest(operation)
+        ? fileMatchesRecordedContent(inspectedPath, operation)
+        : operation.contentTransform || isMarkdownPath(operation.destinationPath)
+          ? readFileNoFollow(inspectedPath, 'utf8') === getExpectedCopyFileContent(
+            operation,
+            readFileNoFollow(copySourcePath, 'utf8'),
+            linkIndex
+          )
+          : areFilesEqual(copySourcePath, inspectedPath);
+    } catch (_error) {
+      return {
+        status: 'unverified',
+        operation,
+        destinationPath,
+        sourcePath: copySourcePath
+      };
+    }
+
+    if (!contentMatches) {
       return {
         status: 'drifted',
         operation,
@@ -963,9 +1080,10 @@ function inspectManagedOperation(repoRoot, trustedRoot, operation) {
 }
 
 function summarizeManagedOperationHealth(repoRoot, trustedRoot, operations) {
+  const linkIndex = buildLinkIndexForOperations(operations, trustedRoot);
   return operations.reduce(
     (summary, operation) => {
-      const inspection = inspectManagedOperation(repoRoot, trustedRoot, operation);
+      const inspection = inspectManagedOperation(repoRoot, trustedRoot, operation, linkIndex);
       if (inspection.status === 'missing') {
         summary.missing.push(inspection);
       } else if (inspection.status === 'drifted') {
@@ -1023,14 +1141,18 @@ function getUnsafeOperationResult(record, operationHealth) {
   };
 }
 
-function buildDiscoveryRecord(adapter, context) {
+function buildDiscoveryRecord(adapter, context, location = null, knownState = null) {
   const installTargetInput = {
     homeDir: context.homeDir,
     projectRoot: context.projectRoot,
     repoRoot: context.projectRoot
   };
-  const targetRoot = adapter.resolveRoot(installTargetInput);
-  const installStatePath = adapter.getInstallStatePath(installTargetInput);
+  const targetRoot = location
+    ? location.targetRoot
+    : adapter.resolveRoot(installTargetInput);
+  const installStatePath = location
+    ? location.installStatePath
+    : adapter.getInstallStatePath(installTargetInput);
   const exists = fs.existsSync(installStatePath);
 
   if (!exists) {
@@ -1044,7 +1166,24 @@ function buildDiscoveryRecord(adapter, context) {
       installStatePath,
       exists: false,
       state: null,
-      error: null
+      error: null,
+      legacy: Boolean(location)
+    };
+  }
+
+  if (knownState) {
+    return {
+      adapter: {
+        id: adapter.id,
+        target: adapter.target,
+        kind: adapter.kind
+      },
+      targetRoot,
+      installStatePath,
+      exists: true,
+      state: knownState,
+      error: null,
+      legacy: Boolean(location)
     };
   }
 
@@ -1060,7 +1199,8 @@ function buildDiscoveryRecord(adapter, context) {
       installStatePath,
       exists: true,
       state,
-      error: null
+      error: null,
+      legacy: Boolean(location)
     };
   } catch (error) {
     return {
@@ -1073,7 +1213,8 @@ function buildDiscoveryRecord(adapter, context) {
       installStatePath,
       exists: true,
       state: null,
-      error: error.message
+      error: error.message,
+      legacy: Boolean(location)
     };
   }
 }
@@ -1085,9 +1226,43 @@ function discoverInstalledStates(options = {}) {
   };
   const targets = normalizeTargets(options.targets);
 
-  return targets.map(target => {
+  return targets.flatMap(target => {
     const adapter = getInstallTargetAdapter(target);
-    return buildDiscoveryRecord(adapter, context);
+    const canonicalRecord = buildDiscoveryRecord(adapter, context);
+    if (adapter.target !== 'antigravity') {
+      return [canonicalRecord];
+    }
+
+    const legacyLocation = getLegacyAntigravityLocation(context.projectRoot);
+    const legacyInspection = inspectLegacyAntigravityState(legacyLocation);
+    if (
+      path.resolve(legacyLocation.installStatePath) === path.resolve(canonicalRecord.installStatePath)
+      || legacyInspection.status === 'absent'
+      || legacyInspection.status === 'invalid'
+    ) {
+      return [canonicalRecord];
+    }
+
+    if (legacyInspection.status === 'unreadable') {
+      return [canonicalRecord, {
+        adapter: {
+          id: adapter.id,
+          target: adapter.target,
+          kind: adapter.kind,
+        },
+        targetRoot: legacyLocation.targetRoot,
+        installStatePath: legacyLocation.installStatePath,
+        exists: true,
+        state: null,
+        error: legacyInspection.error,
+        legacy: true,
+      }];
+    }
+
+    return [
+      canonicalRecord,
+      buildDiscoveryRecord(adapter, context, legacyLocation, legacyInspection.state),
+    ];
   });
 }
 
@@ -1115,6 +1290,14 @@ function determineStatus(issues) {
 function analyzeRecord(record, context) {
   const issues = [];
 
+  if (record.legacy) {
+    issues.push(buildIssue(
+      'warning',
+      'legacy-antigravity-layout',
+      'Legacy Antigravity install-state remains under .agent. Review and move any preserved modified or unmanaged files out of .agent, then rerun the Antigravity install to finish migration.'
+    ));
+  }
+
   if (record.error) {
     issues.push(buildIssue('error', 'invalid-install-state', record.error));
     return {
@@ -1377,10 +1560,27 @@ function assertValidInstallStateForWrite(state, label) {
 
 function writeRefreshedInstallState(record, statePreview) {
   const trustedStatePreview = buildAdapterDerivedStatePreview(statePreview, record);
-  assertValidInstallStateForWrite(trustedStatePreview, record.installStatePath);
+  const stateWithCurrentDigests = {
+    ...trustedStatePreview,
+    operations: (trustedStatePreview.operations || []).map(operation => {
+      if (!operation.destinationPath) {
+        return { ...operation };
+      }
+      try {
+        const contentSha256 = crypto.createHash('sha256')
+          .update(readFileNoFollow(operation.destinationPath))
+          .digest('hex');
+        return { ...operation, contentSha256 };
+      } catch (_error) {
+        const { contentSha256: _staleDigest, ...operationWithoutDigest } = operation;
+        return operationWithoutDigest;
+      }
+    }),
+  };
+  assertValidInstallStateForWrite(stateWithCurrentDigests, record.installStatePath);
   return writeContainedFile(
     record.installStatePath,
-    formatJson(trustedStatePreview),
+    formatJson(stateWithCurrentDigests),
     record.targetRoot,
     'repair'
   );
@@ -1427,7 +1627,7 @@ function repairInstalledStates(options = {}) {
     homeDir: context.homeDir,
     projectRoot: context.projectRoot,
     targets: options.targets
-  }).filter(record => record.exists);
+  }).filter(record => record.exists && !record.legacy);
 
   const results = records.map(record => {
     if (record.error) {
@@ -1525,6 +1725,7 @@ function repairInstalledStates(options = {}) {
       }
 
       const repairOperations = [...operationHealth.missing.map(entry => ({ ...entry.operation })), ...operationHealth.drifted.map(entry => ({ ...entry.operation }))];
+      const repairLinkIndex = buildLinkIndexForOperations(desiredPlan.operations, record.targetRoot);
       const legacyMigrationPaths = migration.legacyOperationsToRemove.map(
         operation => operation.destinationPath
       );
@@ -1557,7 +1758,8 @@ function repairInstalledStates(options = {}) {
         const repairedPath = executeRepairOperation(
           context.repoRoot,
           operation,
-          record.targetRoot
+          record.targetRoot,
+          repairLinkIndex
         );
         if (repairedPath) {
           repairedPaths.push(repairedPath);
@@ -1576,7 +1778,17 @@ function repairInstalledStates(options = {}) {
           }
         }
       }
-      writeRefreshedInstallState(record, desiredPlan.statePreview);
+      const changedInstalledBytes = repairOperations.length > 0
+        || needsOpencodeBuild
+        || hasLegacyMigration;
+      const statePreviewToWrite = changedInstalledBytes
+        ? desiredPlan.statePreview
+        : {
+            ...desiredPlan.statePreview,
+            installedAt: record.state.installedAt,
+            source: { ...record.state.source },
+          };
+      writeRefreshedInstallState(record, statePreviewToWrite);
 
       return {
         adapter: record.adapter,
@@ -1682,8 +1894,21 @@ function uninstallInstalledStates(options = {}) {
     }
 
     const state = record.state;
+    const managedOperations = getManagedOperations(state);
+    if (record.legacy && managedOperations.length > 0) {
+      return {
+        adapter: record.adapter,
+        status: 'partial',
+        installStatePath: record.installStatePath,
+        removedPaths: [],
+        plannedRemovals: [],
+        retainedPaths: managedOperations.map(operation => operation.destinationPath),
+        warning: 'Legacy Antigravity files were preserved because their provenance cannot be revalidated during uninstall. Rerun the Antigravity installer to migrate verified files, then review .agent manually.',
+        error: null
+      };
+    }
     const plannedRemovals = Array.from(new Set([
-      ...getManagedOperations(state).map(operation => operation.destinationPath),
+      ...managedOperations.map(operation => operation.destinationPath),
       record.installStatePath
     ]));
 
@@ -1704,7 +1929,9 @@ function uninstallInstalledStates(options = {}) {
       const operations = getManagedOperations(state);
 
       for (const operation of operations) {
-        const outcome = executeUninstallOperation(operation, record.targetRoot);
+        const outcome = executeUninstallOperation(operation, record.targetRoot, {
+          preserveDriftedCopies: record.legacy,
+        });
         removedPaths.push(...outcome.removedPaths);
         cleanupTargets.push(...outcome.cleanupTargets);
       }
@@ -1749,12 +1976,14 @@ function uninstallInstalledStates(options = {}) {
       checkedCount: accumulator.checkedCount + 1,
       uninstalledCount: accumulator.uninstalledCount + (result.status === 'uninstalled' ? 1 : 0),
       plannedRemovalCount: accumulator.plannedRemovalCount + (result.status === 'planned' ? 1 : 0),
+      partialCount: accumulator.partialCount + (result.status === 'partial' ? 1 : 0),
       errorCount: accumulator.errorCount + (result.status === 'error' ? 1 : 0)
     }),
     {
       checkedCount: 0,
       uninstalledCount: 0,
       plannedRemovalCount: 0,
+      partialCount: 0,
       errorCount: 0
     }
   );
diff --git a/scripts/lib/install-manifests.js b/scripts/lib/install-manifests.js
index 3c98eaf8e..5a90c24d3 100644
--- a/scripts/lib/install-manifests.js
+++ b/scripts/lib/install-manifests.js
@@ -65,6 +65,8 @@ const LEGACY_COMPAT_BASE_MODULE_IDS_BY_TARGET = Object.freeze({
     'rules-core',
     'agents-core',
     'commands-core',
+    'skill-unified-memory',
+    'workflow-quality',
   ],
   zed: [
     'rules-core',
@@ -132,6 +134,14 @@ const LEGACY_LANGUAGE_EXTRA_MODULE_IDS = Object.freeze({
   swift: [],
   typescript: ['framework-language'],
 });
+const LEGACY_LANGUAGE_RULE_NAMESPACES = Object.freeze({
+  c: 'cpp',
+  harmonyos: 'arkts',
+  javascript: 'typescript',
+  go: 'golang',
+  golang: 'golang',
+  rails: 'ruby',
+});
 const TARGET_DEFAULT_PROFILE_IDS = Object.freeze({
   opencode: 'opencode',
 });
@@ -500,6 +510,9 @@ function resolveLegacyCompatibilitySelection(options = {}) {
 
   const canonicalLegacyLanguages = normalizedLegacyLanguages
     .map(language => LEGACY_LANGUAGE_ALIAS_TO_CANONICAL[language]);
+  const ruleLanguages = normalizedLegacyLanguages.map(language => (
+    LEGACY_LANGUAGE_RULE_NAMESPACES[language] || language
+  ));
   const baseModuleIds = LEGACY_COMPAT_BASE_MODULE_IDS_BY_TARGET[target || 'claude']
     || LEGACY_COMPAT_BASE_MODULE_IDS_BY_TARGET.claude;
   const moduleIds = dedupeStrings([
@@ -514,6 +527,7 @@ function resolveLegacyCompatibilitySelection(options = {}) {
   return {
     legacyLanguages: normalizedLegacyLanguages,
     canonicalLegacyLanguages,
+    ruleLanguages,
     moduleIds,
   };
 }
diff --git a/scripts/lib/install-state-store-sync.js b/scripts/lib/install-state-store-sync.js
new file mode 100644
index 000000000..3f3333486
--- /dev/null
+++ b/scripts/lib/install-state-store-sync.js
@@ -0,0 +1,63 @@
+'use strict';
+
+const {
+  createStateStore,
+  projectInstallState,
+  reconcileCurrentInstallState,
+} = require('./state-store');
+
+function openFailure(error) {
+  return {
+    status: 'warning',
+    warningCount: 1,
+    warnings: [{
+      code: 'projection-open-failed',
+      message: error.message,
+    }],
+    warning: {
+      code: 'projection-open-failed',
+      message: error.message,
+    },
+  };
+}
+
+async function withStateStore(options, operation) {
+  const openStore = options.createStore || createStateStore;
+  let store;
+  try {
+    store = await openStore({
+      dbPath: options.dbPath,
+      homeDir: options.homeDir,
+    });
+    return operation(store);
+  } catch (error) {
+    return openFailure(error);
+  } finally {
+    if (store) {
+      try {
+        store.close();
+      } catch (_error) {
+        // Projection is a derived cache. A close failure must not invalidate
+        // the canonical JSON install-state or a completed file operation.
+      }
+    }
+  }
+}
+
+async function projectCanonicalInstallState(state, options = {}) {
+  return withStateStore(options, store => projectInstallState(store, state));
+}
+
+async function reconcileCanonicalInstallStates(options = {}) {
+  return withStateStore(options, store => reconcileCurrentInstallState(store, {
+    homeDir: options.homeDir,
+    projectRoot: options.projectRoot,
+    targets: options.targets,
+    discoverInstalledStates: options.discoverInstalledStates,
+  }));
+}
+
+module.exports = {
+  projectCanonicalInstallState,
+  reconcileCanonicalInstallStates,
+};
diff --git a/scripts/lib/install-targets/antigravity-project.js b/scripts/lib/install-targets/antigravity-project.js
index 738f32e87..34a500eab 100644
--- a/scripts/lib/install-targets/antigravity-project.js
+++ b/scripts/lib/install-targets/antigravity-project.js
@@ -3,11 +3,12 @@ const path = require('path');
 const {
   createFlatRuleOperations,
   createInstallTargetAdapter,
+  createManagedOperation,
   createManagedScaffoldOperation,
   normalizeRelativePath,
 } = require('./helpers');
 
-const SUPPORTED_SOURCE_PREFIXES = ['rules', 'commands', 'agents', '.agents', 'AGENTS.md'];
+const SUPPORTED_SOURCE_PREFIXES = ['rules', 'commands', 'agents', 'skills'];
 
 function supportsAntigravitySourcePath(sourceRelativePath) {
   const normalizedPath = normalizeRelativePath(sourceRelativePath);
@@ -20,7 +21,7 @@ module.exports = createInstallTargetAdapter({
   id: 'antigravity-project',
   target: 'antigravity',
   kind: 'project',
-  rootSegments: ['.agent'],
+  rootSegments: ['.agents'],
   installStatePathSegments: ['ecc-install-state.json'],
   supportsModule(module) {
     const paths = Array.isArray(module && module.paths) ? module.paths : [];
@@ -47,38 +48,70 @@ module.exports = createInstallTargetAdapter({
       return paths
         .filter(supportsAntigravitySourcePath)
         .flatMap(sourceRelativePath => {
-        if (sourceRelativePath === 'rules') {
-          return createFlatRuleOperations({
-            moduleId: module.id,
-            repoRoot,
-            sourceRelativePath,
-            destinationDir: path.join(targetRoot, 'rules'),
-          });
-        }
+          const normalizedSourcePath = normalizeRelativePath(sourceRelativePath);
 
-        if (sourceRelativePath === 'commands') {
-          return [
-            createManagedScaffoldOperation(
-              module.id,
-              sourceRelativePath,
-              path.join(targetRoot, 'workflows'),
-              'preserve-relative-path'
-            ),
-          ];
-        }
+          if (normalizedSourcePath === 'rules') {
+            return createFlatRuleOperations({
+              moduleId: module.id,
+              repoRoot,
+              sourceRelativePath: normalizedSourcePath,
+              destinationDir: path.join(targetRoot, 'rules'),
+            });
+          }
 
-        if (sourceRelativePath === 'agents') {
-          return [
-            createManagedScaffoldOperation(
-              module.id,
-              sourceRelativePath,
-              path.join(targetRoot, 'skills'),
-              'preserve-relative-path'
-            ),
-          ];
-        }
+          if (
+            normalizedSourcePath === 'commands'
+            || normalizedSourcePath.startsWith('commands/')
+          ) {
+            const commandRelativePath = normalizedSourcePath === 'commands'
+              ? ''
+              : normalizedSourcePath.slice('commands/'.length);
+            return [
+              createManagedScaffoldOperation(
+                module.id,
+                normalizedSourcePath,
+                path.join(targetRoot, 'workflows', commandRelativePath),
+                'preserve-relative-path'
+              ),
+            ];
+          }
 
-          return [adapter.createScaffoldOperation(module.id, sourceRelativePath, planningInput)];
+          if (
+            normalizedSourcePath === 'agents'
+            || normalizedSourcePath.startsWith('agents/')
+          ) {
+            const agentRelativePath = normalizedSourcePath === 'agents'
+              ? ''
+              : normalizedSourcePath.slice('agents/'.length);
+            return [
+              createManagedOperation({
+                moduleId: module.id,
+                sourceRelativePath: normalizedSourcePath,
+                destinationPath: path.join(targetRoot, 'agents', agentRelativePath),
+                strategy: 'preserve-relative-path',
+                contentTransform: 'antigravity-agent-frontmatter',
+              }),
+            ];
+          }
+
+          if (
+            normalizedSourcePath === 'skills'
+            || normalizedSourcePath.startsWith('skills/')
+          ) {
+            const skillRelativePath = normalizedSourcePath === 'skills'
+              ? ''
+              : normalizedSourcePath.slice('skills/'.length);
+            return [
+              createManagedScaffoldOperation(
+                module.id,
+                normalizedSourcePath,
+                path.join(targetRoot, 'skills', skillRelativePath),
+                'preserve-relative-path'
+              ),
+            ];
+          }
+
+          return [];
         });
     });
   },
diff --git a/scripts/lib/install/antigravity-agent.js b/scripts/lib/install/antigravity-agent.js
new file mode 100644
index 000000000..ce9138a7a
--- /dev/null
+++ b/scripts/lib/install/antigravity-agent.js
@@ -0,0 +1,61 @@
+'use strict';
+
+const TOOL_NAMES = Object.freeze({
+  Read: 'view_file',
+  Write: 'write_to_file',
+  Edit: 'replace_file_content',
+  Grep: 'grep_search',
+  Glob: 'find_by_name',
+  Bash: 'run_command',
+  WebSearch: 'search_web',
+  WebFetch: 'read_url_content',
+});
+
+const MODEL_NAMES = Object.freeze({
+  haiku: 'flash',
+  sonnet: 'pro',
+  opus: 'pro',
+});
+
+function splitFrontmatter(source, label) {
+  const match = String(source || '').match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (!match) {
+    throw new Error(`Cannot adapt Antigravity agent ${label}: missing YAML frontmatter`);
+  }
+
+  const frontmatter = require('js-yaml').load(match[1]);
+  if (!frontmatter || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+    throw new Error(`Cannot adapt Antigravity agent ${label}: frontmatter must be an object`);
+  }
+
+  return {
+    frontmatter,
+    body: source.slice(match[0].length),
+  };
+}
+
+function normalizeToolNames(value) {
+  const names = Array.isArray(value) ? value : String(value || '').split(',');
+  return [...new Set(names
+    .map(name => String(name).trim())
+    .filter(name => Object.hasOwn(TOOL_NAMES, name))
+    .map(name => TOOL_NAMES[name]))];
+}
+
+function adaptAntigravityAgent(source, label = '<unknown>') {
+  const { frontmatter, body } = splitFrontmatter(source, label);
+  const { color: _claudeColor, ...supportedFrontmatter } = frontmatter;
+  const adapted = {
+    ...supportedFrontmatter,
+    tools: normalizeToolNames(frontmatter.tools),
+    model: MODEL_NAMES[frontmatter.model] || frontmatter.model,
+  };
+  const serialized = require('js-yaml')
+    .dump(adapted, { lineWidth: -1, noRefs: true })
+    .trimEnd();
+  return `---\n${serialized}\n---\n${body}`;
+}
+
+module.exports = {
+  adaptAntigravityAgent,
+};
diff --git a/scripts/lib/install/antigravity-legacy-migration.js b/scripts/lib/install/antigravity-legacy-migration.js
new file mode 100644
index 000000000..4f5e1a055
--- /dev/null
+++ b/scripts/lib/install/antigravity-legacy-migration.js
@@ -0,0 +1,413 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const { readInstallState } = require('../install-state');
+const { assertWithinTrustedRoot } = require('../path-safety');
+
+const ANTIGRAVITY_TARGET = 'antigravity';
+const CANONICAL_ROOT_NAME = '.agents';
+const LEGACY_ROOT_NAME = '.agent';
+const INSTALL_STATE_NAME = 'ecc-install-state.json';
+
+function samePath(leftPath, rightPath) {
+  const left = path.resolve(leftPath);
+  const right = path.resolve(rightPath);
+  if (process.platform === 'win32') {
+    return left.toLowerCase() === right.toLowerCase();
+  }
+  return left === right;
+}
+
+function pathExists(filePath) {
+  try {
+    fs.lstatSync(filePath);
+    return true;
+  } catch (error) {
+    if (error && (error.code === 'ENOENT' || error.code === 'ENOTDIR')) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function getLegacyAntigravityLocation(projectRoot) {
+  const targetRoot = path.join(path.resolve(projectRoot), LEGACY_ROOT_NAME);
+  return {
+    targetRoot,
+    installStatePath: path.join(targetRoot, INSTALL_STATE_NAME),
+  };
+}
+
+function getLegacyLocationForPlan(plan) {
+  if (
+    !plan
+    || !plan.adapter
+    || plan.adapter.target !== ANTIGRAVITY_TARGET
+    || typeof plan.targetRoot !== 'string'
+    || path.basename(path.resolve(plan.targetRoot)) !== CANONICAL_ROOT_NAME
+  ) {
+    return null;
+  }
+
+  return getLegacyAntigravityLocation(path.dirname(path.resolve(plan.targetRoot)));
+}
+
+function inspectLegacyAntigravityState(location) {
+  if (!location) {
+    return { status: 'absent', state: null, error: null };
+  }
+  try {
+    if (!pathExists(location.installStatePath)) {
+      return { status: 'absent', state: null, error: null };
+    }
+    const rootStat = fs.lstatSync(location.targetRoot);
+    const stateStat = fs.lstatSync(location.installStatePath);
+    if (
+      !rootStat.isDirectory()
+      || rootStat.isSymbolicLink()
+      || !stateStat.isFile()
+      || stateStat.isSymbolicLink()
+    ) {
+      return { status: 'invalid', state: null, error: null };
+    }
+    const state = readInstallState(location.installStatePath);
+    const isAntigravity = state.target.target === ANTIGRAVITY_TARGET
+      || state.target.id === 'antigravity-project';
+    if (
+      !isAntigravity
+      || !samePath(state.target.root, location.targetRoot)
+      || !samePath(state.target.installStatePath, location.installStatePath)
+      || state.operations.some(operation => (
+        operation.kind !== 'copy-file'
+        || operation.ownership !== 'managed'
+      ))
+    ) {
+      return { status: 'invalid', state: null, error: null };
+    }
+    return { status: 'valid', state, error: null };
+  } catch (error) {
+    return {
+      status: 'unreadable',
+      state: null,
+      error: `Unable to inspect legacy Antigravity install-state at ${location.installStatePath}: ${error.message}`,
+    };
+  }
+}
+
+function readValidLegacyAntigravityState(location) {
+  const inspection = inspectLegacyAntigravityState(location);
+  return inspection.status === 'valid' ? inspection.state : null;
+}
+
+function sha256FileNoFollow(filePath) {
+  const flags = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0);
+  const descriptor = fs.openSync(filePath, flags);
+  try {
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile()) {
+      return null;
+    }
+    return {
+      digest: crypto.createHash('sha256').update(fs.readFileSync(descriptor)).digest('hex'),
+      stat,
+    };
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+function getExpectedLegacyDestination(operation, legacyRoot) {
+  const sourceRelativePath = String(operation.sourceRelativePath || '')
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '');
+  const parts = sourceRelativePath.split('/');
+  if (
+    path.posix.isAbsolute(sourceRelativePath)
+    || path.win32.isAbsolute(sourceRelativePath)
+    || parts.some(part => part === '' || part === '.' || part === '..')
+  ) {
+    return null;
+  }
+
+  if (parts[0] === 'rules' && parts.length >= 2) {
+    const fileName = parts.length === 2
+      ? parts[1]
+      : `${parts[1]}-${parts.slice(2).join('-')}`;
+    return path.join(legacyRoot, 'rules', fileName);
+  }
+  if (parts[0] === 'commands' && parts.length >= 2) {
+    return path.join(legacyRoot, 'workflows', ...parts.slice(1));
+  }
+  if (parts[0] === 'agents' && parts.length >= 2) {
+    return path.join(legacyRoot, 'skills', ...parts.slice(1));
+  }
+  if (parts[0] === '.agents' && parts.length >= 2) {
+    return path.join(legacyRoot, '.agents', ...parts.slice(1));
+  }
+  if (sourceRelativePath === 'AGENTS.md') {
+    return path.join(legacyRoot, 'AGENTS.md');
+  }
+  return null;
+}
+
+function getVerifiedManagedFile(operation, legacyRoot, sourceRoot) {
+  if (
+    !operation
+    || operation.ownership !== 'managed'
+    || operation.kind !== 'copy-file'
+    || typeof operation.destinationPath !== 'string'
+    || typeof sourceRoot !== 'string'
+    || !/^[a-f0-9]{64}$/i.test(operation.contentSha256 || '')
+  ) {
+    return null;
+  }
+
+  let destinationPath;
+  let sourcePath;
+  try {
+    const expectedDestination = getExpectedLegacyDestination(operation, legacyRoot);
+    if (!expectedDestination || !samePath(operation.destinationPath, expectedDestination)) {
+      return null;
+    }
+    destinationPath = assertWithinTrustedRoot(
+      operation.destinationPath,
+      legacyRoot,
+      'migrate legacy Antigravity install'
+    );
+    sourcePath = assertWithinTrustedRoot(
+      path.join(sourceRoot, operation.sourceRelativePath),
+      sourceRoot,
+      'verify legacy Antigravity source'
+    );
+  } catch (_error) {
+    return null;
+  }
+
+  if (!pathExists(destinationPath)) {
+    return { destinationPath, missing: true };
+  }
+
+  const stat = fs.lstatSync(destinationPath);
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    return null;
+  }
+
+  const destination = sha256FileNoFollow(destinationPath);
+  if (
+    !destination
+    || destination.digest !== operation.contentSha256.toLowerCase()
+  ) {
+    return null;
+  }
+
+  if (!pathExists(sourcePath)) {
+    return {
+      destinationPath,
+      fileStat: destination.stat,
+      missing: false,
+      retainedReason: 'The current ECC source file is unavailable, so its provenance cannot be revalidated.',
+    };
+  }
+
+  const source = sha256FileNoFollow(sourcePath);
+  if (!source || destination.digest !== source.digest) {
+    return {
+      destinationPath,
+      fileStat: destination.stat,
+      missing: false,
+      retainedReason: 'The current ECC source differs from the recorded installed content, so the legacy file was preserved.',
+    };
+  }
+
+  return { destinationPath, fileStat: destination.stat, missing: false };
+}
+
+function cleanupResult(overrides = {}) {
+  return {
+    detected: false,
+    complete: false,
+    removedPaths: [],
+    retainedPaths: [],
+    warnings: [],
+    ...overrides,
+  };
+}
+
+function removeEmptyParents(startPath, legacyRoot) {
+  let currentPath = path.dirname(startPath);
+  while (!samePath(currentPath, legacyRoot)) {
+    let safePath;
+    try {
+      safePath = assertWithinTrustedRoot(
+        currentPath,
+        legacyRoot,
+        'clean legacy Antigravity install'
+      );
+    } catch (_error) {
+      return;
+    }
+    if (!pathExists(safePath)) {
+      currentPath = path.dirname(safePath);
+      continue;
+    }
+    const stat = fs.lstatSync(safePath);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || fs.readdirSync(safePath).length > 0) {
+      return;
+    }
+    fs.rmdirSync(safePath);
+    currentPath = path.dirname(safePath);
+  }
+}
+
+function listLegacyContent(legacyRoot, installStatePath) {
+  if (!pathExists(legacyRoot)) {
+    return [];
+  }
+
+  const content = [];
+  const pending = [legacyRoot];
+  while (pending.length > 0) {
+    const currentPath = pending.pop();
+    for (const entry of fs.readdirSync(currentPath, { withFileTypes: true })) {
+      const entryPath = path.join(currentPath, entry.name);
+      if (samePath(entryPath, installStatePath)) {
+        continue;
+      }
+      if (entry.isDirectory() && !entry.isSymbolicLink()) {
+        pending.push(entryPath);
+      } else {
+        content.push(entryPath);
+      }
+    }
+  }
+  return content;
+}
+
+function removeLegacyStateWhenEmpty(location) {
+  if (listLegacyContent(location.targetRoot, location.installStatePath).length > 0) {
+    return false;
+  }
+
+  try {
+    fs.rmSync(location.installStatePath, { force: true });
+  } catch (_error) {
+    return false;
+  }
+  try {
+    if (pathExists(location.targetRoot) && fs.readdirSync(location.targetRoot).length === 0) {
+      fs.rmdirSync(location.targetRoot);
+    }
+  } catch (_error) {
+    // Root cleanup is best effort after the legacy state is gone.
+  }
+  return true;
+}
+
+function cleanupLegacyAntigravityInstall(plan) {
+  const location = getLegacyLocationForPlan(plan);
+  if (!location || typeof plan.sourceRoot !== 'string' || !pathExists(plan.installStatePath)) {
+    return cleanupResult();
+  }
+
+  try {
+    const canonicalState = readInstallState(plan.installStatePath);
+    const isCanonicalState = (
+      canonicalState.target.target === ANTIGRAVITY_TARGET
+      || canonicalState.target.id === 'antigravity-project'
+    )
+      && samePath(canonicalState.target.root, plan.targetRoot)
+      && samePath(canonicalState.target.installStatePath, plan.installStatePath);
+    if (!isCanonicalState) {
+      return cleanupResult();
+    }
+  } catch (_error) {
+    return cleanupResult();
+  }
+
+  const legacyInspection = inspectLegacyAntigravityState(location);
+  if (legacyInspection.status === 'unreadable') {
+    return cleanupResult({
+      detected: true,
+      retainedPaths: [location.targetRoot],
+      warnings: [legacyInspection.error],
+    });
+  }
+  if (legacyInspection.status !== 'valid') {
+    return cleanupResult();
+  }
+  const legacyState = legacyInspection.state;
+
+  const removedPaths = [];
+  const filesToRemove = [];
+  const warnings = [];
+  for (const operation of legacyState.operations || []) {
+    const verified = getVerifiedManagedFile(operation, location.targetRoot, plan.sourceRoot);
+    if (!verified) {
+      continue;
+    }
+    if (verified.missing) {
+      continue;
+    }
+    if (verified.retainedReason) {
+      warnings.push(`${verified.destinationPath}: ${verified.retainedReason}`);
+      continue;
+    }
+    filesToRemove.push({
+      destinationPath: verified.destinationPath,
+      fileStat: verified.fileStat,
+    });
+  }
+
+  for (const { destinationPath, fileStat } of filesToRemove) {
+    try {
+      const safeDestination = assertWithinTrustedRoot(
+        destinationPath,
+        location.targetRoot,
+        'remove verified legacy Antigravity file'
+      );
+      const currentStat = fs.lstatSync(safeDestination);
+      if (
+        currentStat.isSymbolicLink()
+        || !currentStat.isFile()
+        || currentStat.dev !== fileStat.dev
+        || currentStat.ino !== fileStat.ino
+      ) {
+        continue;
+      }
+      fs.rmSync(safeDestination);
+      removedPaths.push(safeDestination);
+      removeEmptyParents(safeDestination, location.targetRoot);
+    } catch (_error) {
+      // Keep failed deletions tracked in legacy state so a later install can retry.
+    }
+  }
+
+  let complete = false;
+  try {
+    complete = removeLegacyStateWhenEmpty(location);
+  } catch (_error) {
+    complete = false;
+  }
+  if (complete) {
+    removedPaths.push(location.installStatePath);
+  }
+  let retainedPaths = [];
+  if (!complete) {
+    try {
+      retainedPaths = listLegacyContent(location.targetRoot, location.installStatePath);
+    } catch (_error) {
+      retainedPaths = [location.targetRoot];
+    }
+  }
+  return cleanupResult({ detected: true, complete, removedPaths, retainedPaths, warnings });
+}
+
+module.exports = {
+  cleanupLegacyAntigravityInstall,
+  getLegacyAntigravityLocation,
+  inspectLegacyAntigravityState,
+  readValidLegacyAntigravityState,
+};
diff --git a/scripts/lib/install/apply.js b/scripts/lib/install/apply.js
index 91c70e7fe..8f4e660e0 100644
--- a/scripts/lib/install/apply.js
+++ b/scripts/lib/install/apply.js
@@ -16,12 +16,24 @@ const {
   prepareClaudeSkillMigration,
   removeLegacyClaudeSkillFiles,
 } = require('./claude-skill-migration');
+const { cleanupLegacyAntigravityInstall } = require('./antigravity-legacy-migration');
 const { buildInstallIndex, rewriteRelativeLinks } = require('./link-rewrite');
+const { adaptAntigravityAgent } = require('./antigravity-agent');
 
 function isMarkdownPath(filePath) {
   return /\.(md|mdx|markdown)$/i.test(String(filePath || ''));
 }
 
+function transformInstallContent(operation, content) {
+  if (!operation.contentTransform) {
+    return content;
+  }
+  if (operation.contentTransform === 'antigravity-agent-frontmatter') {
+    return adaptAntigravityAgent(content, operation.sourceRelativePath);
+  }
+  throw new Error(`Unknown install content transform: ${operation.contentTransform}`);
+}
+
 // Map every copy-file operation to { sourceRel, destRel } so relative links in
 // namespaced markdown can be rewritten to the file's actual installed location
 // (issue #2340). Returns null when the plan lacks the data needed to do so.
@@ -348,7 +360,7 @@ function applyInstallPlan(plan, dependencies = {}) {
       && isMarkdownPath(operation.destinationPath)
     ) {
       const rewritten = rewriteRelativeLinks(
-        fs.readFileSync(operation.sourcePath, 'utf8'),
+        transformInstallContent(operation, fs.readFileSync(operation.sourcePath, 'utf8')),
         { sourceRel: operation.sourceRelativePath, index: linkIndex }
       );
       fs.writeFileSync(operation.destinationPath, rewritten, 'utf8');
@@ -385,6 +397,13 @@ function applyInstallPlan(plan, dependencies = {}) {
     beforeInstallStateWrite({ plan: appliedPlan, state: finalState });
   }
   persistInstallState(plan.installStatePath, finalState);
+  const antigravityMigration = cleanupLegacyAntigravityInstall(appliedPlan);
+  const antigravityMigrationWarnings = antigravityMigration.detected && !antigravityMigration.complete
+    ? [
+        'Legacy Antigravity migration is incomplete. ECC preserved modified, unverifiable, or unmanaged content under .agent; review and move anything you want to keep, then rerun the Antigravity install.',
+        ...(Array.isArray(antigravityMigration.warnings) ? antigravityMigration.warnings : []),
+      ]
+    : [];
 
   return {
     ...plan,
@@ -395,6 +414,7 @@ function applyInstallPlan(plan, dependencies = {}) {
     warnings: [
       ...(Array.isArray(plan.warnings) ? plan.warnings : []),
       ...migration.warnings,
+      ...antigravityMigrationWarnings,
     ],
     applied: true,
   };
diff --git a/scripts/lib/multi-harness-setup.js b/scripts/lib/multi-harness-setup.js
index 50a324b75..fdf2354a2 100644
--- a/scripts/lib/multi-harness-setup.js
+++ b/scripts/lib/multi-harness-setup.js
@@ -315,7 +315,7 @@ function preflightManagedPlan(plan, dependencies = {}) {
   };
 }
 
-function applyPreflightedManagedPlan(entry) {
+async function applyPreflightedManagedPlan(entry) {
   const preview = entry.preview && entry.preview.ownershipSnapshot
     ? entry.preview
     : preflightManagedPlan(entry.preview.plan);
@@ -326,7 +326,7 @@ function applyPreflightedManagedPlan(entry) {
     assertInstallStateUnchanged(preview.plan, expectedStateFingerprint)
   );
 
-  return require('./install-executor').applyInstallPlan(preview.plan, {
+  const result = require('./install-executor').applyInstallPlan(preview.plan, {
     beforeOperationWrite({ operation }) {
       assertStateUnchanged();
       const expected = preview.operations[operationIndex];
@@ -347,6 +347,15 @@ function applyPreflightedManagedPlan(entry) {
     },
     beforeInstallStateWrite: assertStateUnchanged,
   });
+  const { projectCanonicalInstallState } = require('./install-state-store-sync');
+  const installStateProjection = await projectCanonicalInstallState(result.statePreview);
+  return {
+    ...result,
+    installStateProjection,
+    warnings: installStateProjection.warning
+      ? [...result.warnings, `Install health projection warning: ${installStateProjection.warning.message}`]
+      : result.warnings,
+  };
 }
 
 function defaultDependencies(options = {}) {
diff --git a/scripts/lib/state-store/index.js b/scripts/lib/state-store/index.js
index bf60992e3..49b6204d6 100644
--- a/scripts/lib/state-store/index.js
+++ b/scripts/lib/state-store/index.js
@@ -1,6 +1,7 @@
 'use strict';
 
 const fs = require('fs');
+const crypto = require('crypto');
 const os = require('os');
 const path = require('path');
 const initSqlJs = require('sql.js');
@@ -8,8 +9,177 @@ const initSqlJs = require('sql.js');
 const { applyMigrations, getAppliedMigrations } = require('./migrations');
 const { createQueryApi } = require('./queries');
 const { assertValidEntity, validateEntity } = require('./schema');
+const {
+  buildInstallStateStoreRecord,
+  projectInstallState,
+  reconcileCurrentInstallState,
+  reconcileInstallStateProjections,
+  removeInstallStateProjection,
+  summarizeProjectedInstallHealth,
+} = require('./install-state-projection');
 
 const DEFAULT_STATE_STORE_RELATIVE_PATH = path.join('.claude', 'ecc', 'state.db');
+const PRIVATE_DIRECTORY_MODE = 0o700;
+const PRIVATE_FILE_MODE = 0o600;
+
+function stateStorePathError(targetPath, detail) {
+  return new Error(`Unsafe state-store path '${targetPath}': ${detail}`);
+}
+
+function lstatIfPresent(targetPath) {
+  try {
+    return fs.lstatSync(targetPath);
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  }
+}
+
+function isAllowedPlatformSymlink(targetPath, stats) {
+  if (process.platform !== 'darwin' || !stats || stats.uid !== 0) {
+    return false;
+  }
+
+  const allowedTargets = new Map([
+    ['/var', '/private/var'],
+    ['/tmp', '/private/tmp'],
+    ['/etc', '/private/etc'],
+  ]);
+  const expectedTarget = allowedTargets.get(targetPath);
+  if (!expectedTarget) {
+    return false;
+  }
+
+  try {
+    return fs.realpathSync(targetPath) === expectedTarget;
+  } catch (_error) {
+    return false;
+  }
+}
+
+function assertNotSymlink(targetPath, stats) {
+  if (stats && stats.isSymbolicLink()) {
+    if (isAllowedPlatformSymlink(targetPath, stats)) {
+      return;
+    }
+    throw stateStorePathError(targetPath, 'a symlink is not allowed');
+  }
+}
+
+function ensurePrivateDirectory(directoryPath) {
+  const absolutePath = path.resolve(directoryPath);
+  const parsed = path.parse(absolutePath);
+  const segments = absolutePath.slice(parsed.root.length).split(path.sep).filter(Boolean);
+  let currentPath = parsed.root;
+
+  for (const segment of segments) {
+    currentPath = path.join(currentPath, segment);
+    let stats = lstatIfPresent(currentPath);
+    assertNotSymlink(currentPath, stats);
+
+    if (!stats) {
+      try {
+        fs.mkdirSync(currentPath, { mode: PRIVATE_DIRECTORY_MODE });
+      } catch (error) {
+        if (!error || error.code !== 'EEXIST') {
+          throw error;
+        }
+      }
+      stats = fs.lstatSync(currentPath);
+      assertNotSymlink(currentPath, stats);
+    }
+
+    if (!stats.isDirectory() && !isAllowedPlatformSymlink(currentPath, stats)) {
+      throw stateStorePathError(currentPath, 'an intermediate component is not a directory');
+    }
+  }
+
+  return absolutePath;
+}
+
+function assertSafeDatabaseFile(dbPath) {
+  const stats = lstatIfPresent(dbPath);
+  assertNotSymlink(dbPath, stats);
+  if (stats && !stats.isFile()) {
+    throw stateStorePathError(dbPath, 'database path is not a regular file');
+  }
+  return stats;
+}
+
+function readDatabaseFile(dbPath) {
+  assertSafeDatabaseFile(dbPath);
+  const noFollow = fs.constants.O_NOFOLLOW || 0;
+  const fileDescriptor = fs.openSync(dbPath, fs.constants.O_RDONLY | noFollow);
+  try {
+    const stats = fs.fstatSync(fileDescriptor);
+    if (!stats.isFile()) {
+      throw stateStorePathError(dbPath, 'database path is not a regular file');
+    }
+    return fs.readFileSync(fileDescriptor);
+  } finally {
+    fs.closeSync(fileDescriptor);
+  }
+}
+
+function syncDirectory(directoryPath) {
+  if (process.platform === 'win32') {
+    return;
+  }
+
+  let fileDescriptor;
+  try {
+    fileDescriptor = fs.openSync(directoryPath, fs.constants.O_RDONLY);
+    fs.fsyncSync(fileDescriptor);
+  } catch (_error) {
+    // Some filesystems do not permit directory fsync. The file was still
+    // atomically replaced and fsynced before this durability best effort.
+  } finally {
+    if (fileDescriptor !== undefined) {
+      fs.closeSync(fileDescriptor);
+    }
+  }
+}
+
+function writeDatabaseFileAtomic(dbPath, data) {
+  const directoryPath = ensurePrivateDirectory(path.dirname(dbPath));
+  assertSafeDatabaseFile(dbPath);
+  const temporaryPath = path.join(
+    directoryPath,
+    `.${path.basename(dbPath)}.${process.pid}.${crypto.randomBytes(8).toString('hex')}.tmp`
+  );
+  const noFollow = fs.constants.O_NOFOLLOW || 0;
+  const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow;
+  let fileDescriptor;
+
+  try {
+    fileDescriptor = fs.openSync(temporaryPath, flags, PRIVATE_FILE_MODE);
+    fs.writeFileSync(fileDescriptor, data);
+    fs.fchmodSync(fileDescriptor, PRIVATE_FILE_MODE);
+    fs.fsyncSync(fileDescriptor);
+    fs.closeSync(fileDescriptor);
+    fileDescriptor = undefined;
+
+    // A final-path symlink is never followed. If one appeared after this
+    // check, rename replaces the link itself rather than its target.
+    assertSafeDatabaseFile(dbPath);
+    fs.renameSync(temporaryPath, dbPath);
+    syncDirectory(directoryPath);
+  } finally {
+    if (fileDescriptor !== undefined) {
+      fs.closeSync(fileDescriptor);
+    }
+    try {
+      fs.unlinkSync(temporaryPath);
+    } catch (error) {
+      if (!error || error.code !== 'ENOENT') {
+        // Preserve the original persistence result. The temporary file is
+        // private, exclusively created, and never used as canonical state.
+      }
+    }
+  }
+}
 
 function resolveStateStorePath(options = {}) {
   if (options.dbPath) {
@@ -40,7 +210,7 @@ function wrapSqlJsDatabase(rawDb, dbPath) {
     }
     const data = rawDb.export();
     const buffer = Buffer.from(data);
-    fs.writeFileSync(dbPath, buffer);
+    writeDatabaseFileAtomic(dbPath, buffer);
   }
 
   const db = {
@@ -140,12 +310,12 @@ function wrapSqlJsDatabase(rawDb, dbPath) {
 
 async function openDatabase(SQL, dbPath) {
   if (dbPath !== ':memory:') {
-    fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+    ensurePrivateDirectory(path.dirname(dbPath));
   }
 
   let rawDb;
-  if (dbPath !== ':memory:' && fs.existsSync(dbPath)) {
-    const fileBuffer = fs.readFileSync(dbPath);
+  if (dbPath !== ':memory:' && assertSafeDatabaseFile(dbPath)) {
+    const fileBuffer = readDatabaseFile(dbPath);
     rawDb = new SQL.Database(fileBuffer);
   } else {
     rawDb = new SQL.Database();
@@ -186,6 +356,12 @@ async function createStateStore(options = {}) {
 
 module.exports = {
   DEFAULT_STATE_STORE_RELATIVE_PATH,
+  buildInstallStateStoreRecord,
   createStateStore,
+  projectInstallState,
+  reconcileCurrentInstallState,
+  reconcileInstallStateProjections,
+  removeInstallStateProjection,
   resolveStateStorePath,
+  summarizeProjectedInstallHealth,
 };
diff --git a/scripts/lib/state-store/install-state-projection.js b/scripts/lib/state-store/install-state-projection.js
new file mode 100644
index 000000000..14a007c33
--- /dev/null
+++ b/scripts/lib/state-store/install-state-projection.js
@@ -0,0 +1,361 @@
+'use strict';
+
+const path = require('path');
+
+const MANAGED_FILE_HEALTH_CODES = new Set([
+  'missing-target-root',
+  'unsafe-managed-destination',
+  'unsafe-repair-source',
+  'missing-managed-files',
+  'drifted-managed-files',
+  'missing-source-files',
+  'unverified-managed-operations',
+]);
+
+function cloneJsonValue(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function buildInstallStateStoreRecord(state) {
+  if (!state || !state.target || !state.request || !state.resolution || !state.source) {
+    throw new Error('Invalid canonical install-state: required projection fields are missing');
+  }
+
+  return {
+    targetId: state.target.id,
+    targetRoot: state.target.root,
+    profile: state.request.profile ?? null,
+    modules: Array.isArray(state.resolution.selectedModules)
+      ? [...state.resolution.selectedModules]
+      : [],
+    operations: Array.isArray(state.operations)
+      ? state.operations.map(operation => cloneJsonValue(operation))
+      : [],
+    installedAt: state.installedAt,
+    sourceVersion: state.source.repoVersion ?? null,
+  };
+}
+
+function warningFor(record, code, message) {
+  return {
+    code,
+    message,
+    targetId: record && record.adapter ? record.adapter.id : null,
+    targetRoot: record && record.targetRoot ? record.targetRoot : null,
+    installStatePath: record && record.installStatePath ? record.installStatePath : null,
+  };
+}
+
+function getRecordIdentity(record) {
+  if (
+    !record
+    || !record.adapter
+    || typeof record.adapter.id !== 'string'
+    || record.adapter.id.length === 0
+    || typeof record.targetRoot !== 'string'
+    || record.targetRoot.length === 0
+  ) {
+    return null;
+  }
+
+  return {
+    targetId: record.adapter.id,
+    targetRoot: record.targetRoot,
+  };
+}
+
+function pathsMatch(left, right) {
+  return typeof left === 'string'
+    && left.length > 0
+    && typeof right === 'string'
+    && right.length > 0
+    && path.resolve(left) === path.resolve(right);
+}
+
+function stateMatchesDiscoveryRecord(state, record) {
+  return Boolean(
+    state
+    && state.target
+    && state.target.id === record.adapter.id
+    && pathsMatch(state.target.root, record.targetRoot)
+    && pathsMatch(state.target.installStatePath, record.installStatePath)
+  );
+}
+
+function projectInstallState(store, state) {
+  try {
+    const record = buildInstallStateStoreRecord(state);
+    store.upsertInstallState(record);
+    return {
+      status: 'projected',
+      record,
+      warning: null,
+    };
+  } catch (error) {
+    return {
+      status: 'warning',
+      record: null,
+      warning: {
+        code: 'projection-write-failed',
+        message: error.message,
+        targetId: state && state.target ? state.target.id : null,
+        targetRoot: state && state.target ? state.target.root : null,
+        installStatePath: state && state.target ? state.target.installStatePath : null,
+      },
+    };
+  }
+}
+
+function removeInstallStateProjection(store, identity) {
+  try {
+    return {
+      status: 'removed',
+      removed: store.deleteInstallState(identity),
+      warning: null,
+    };
+  } catch (error) {
+    return {
+      status: 'warning',
+      removed: false,
+      warning: {
+        code: 'projection-delete-failed',
+        message: error.message,
+        targetId: identity && identity.targetId ? identity.targetId : null,
+        targetRoot: identity && identity.targetRoot ? identity.targetRoot : null,
+        installStatePath: null,
+      },
+    };
+  }
+}
+
+function createReconciliationResult(discoveredCount) {
+  return {
+    status: 'ok',
+    discoveredCount,
+    projectedCount: 0,
+    removedCount: 0,
+    warningCount: 0,
+    warnings: [],
+    scopedTargets: [],
+    managedFileHealth: [],
+  };
+}
+
+function addWarning(result, warning) {
+  return {
+    ...result,
+    status: 'warning',
+    warningCount: result.warningCount + 1,
+    warnings: [...result.warnings, warning],
+  };
+}
+
+function removeDiscoverableProjection(store, identity, result) {
+  const removal = removeInstallStateProjection(store, identity);
+  if (removal.warning) {
+    return addWarning(result, removal.warning);
+  }
+  return {
+    ...result,
+    removedCount: result.removedCount + (removal.removed ? 1 : 0),
+  };
+}
+
+/**
+ * Reconcile only the identities enumerated by install target discovery.
+ * Canonical JSON files remain authoritative, and rows from other home or
+ * project scopes are deliberately left unchanged.
+ */
+function reconcileInstallStateProjections(store, discoveryRecords) {
+  const records = Array.isArray(discoveryRecords) ? discoveryRecords : [];
+  let result = {
+    ...createReconciliationResult(records.length),
+    scopedTargets: records.map(getRecordIdentity).filter(Boolean),
+  };
+
+  for (const record of records) {
+    const identity = getRecordIdentity(record);
+    if (!identity) {
+      result = addWarning(result, warningFor(
+        record,
+        'invalid-discovery-record',
+        'Install target discovery returned an invalid target identity'
+      ));
+      continue;
+    }
+
+    if (!record.exists) {
+      result = removeDiscoverableProjection(store, identity, result);
+      continue;
+    }
+
+    if (record.error || !record.state) {
+      result = removeDiscoverableProjection(store, identity, result);
+      result = addWarning(result, warningFor(
+        record,
+        'invalid-install-state',
+        record.error || 'Canonical install-state could not be read'
+      ));
+      continue;
+    }
+
+    if (!stateMatchesDiscoveryRecord(record.state, record)) {
+      result = removeDiscoverableProjection(store, identity, result);
+      result = addWarning(result, warningFor(
+        record,
+        'install-state-identity-mismatch',
+        'Canonical install-state identity does not match its discovered target'
+      ));
+      continue;
+    }
+
+    const projection = projectInstallState(store, record.state);
+    if (projection.warning) {
+      result = addWarning(result, projection.warning);
+      continue;
+    }
+    result = {
+      ...result,
+      projectedCount: result.projectedCount + 1,
+    };
+  }
+
+  return result;
+}
+
+function inspectManagedFileHealth(options) {
+  const buildReport = options.buildDoctorReport
+    || require('../install-lifecycle').buildDoctorReport;
+  const report = buildReport({
+    repoRoot: options.repoRoot,
+    homeDir: options.homeDir,
+    projectRoot: options.projectRoot,
+    targets: options.targets,
+  });
+
+  return report.results.map(result => {
+    const issues = Array.isArray(result.issues)
+      ? result.issues.filter(issue => MANAGED_FILE_HEALTH_CODES.has(issue.code))
+      : [];
+    const status = issues.some(issue => issue.severity === 'error')
+      ? 'error'
+      : issues.some(issue => issue.severity === 'warning') ? 'warning' : 'ok';
+    return {
+      targetId: result.adapter.id,
+      targetRoot: result.targetRoot,
+      status,
+      issues: issues.map(issue => cloneJsonValue(issue)),
+    };
+  });
+}
+
+function identityKey(identity) {
+  return `${identity.targetId}\u0000${path.resolve(identity.targetRoot)}`;
+}
+
+function summarizeProjectedInstallHealth(installHealth, reconciliation) {
+  const healthEntries = Array.isArray(reconciliation && reconciliation.managedFileHealth)
+    ? reconciliation.managedFileHealth
+    : [];
+  const healthByIdentity = new Map(healthEntries.map(entry => [identityKey(entry), entry]));
+  const healthCheckFailed = Boolean(
+    reconciliation
+    && Array.isArray(reconciliation.warnings)
+    && reconciliation.warnings.some(warning => warning.code === 'install-health-check-failed')
+  );
+  const scopedIdentities = new Set(
+    Array.isArray(reconciliation && reconciliation.scopedTargets)
+      ? reconciliation.scopedTargets.map(identityKey)
+      : []
+  );
+  const installations = installHealth.installations.map(installation => {
+    const key = identityKey(installation);
+    const canonicalHealth = healthByIdentity.get(key);
+    if (canonicalHealth) {
+      return {
+        ...installation,
+        status: canonicalHealth.status === 'ok' ? installation.status : 'warning',
+        canonicalStatus: canonicalHealth.status,
+        issues: canonicalHealth.issues.map(issue => cloneJsonValue(issue)),
+      };
+    }
+
+    if (healthCheckFailed && scopedIdentities.has(key)) {
+      return {
+        ...installation,
+        status: 'warning',
+        canonicalStatus: 'unverified',
+        issues: [{
+          severity: 'warning',
+          code: 'install-health-check-failed',
+          message: 'Canonical managed-file health could not be verified',
+        }],
+      };
+    }
+
+    return installation;
+  });
+  const healthyCount = installations.filter(installation => installation.status === 'healthy').length;
+  const warningCount = installations.length - healthyCount;
+
+  return {
+    ...installHealth,
+    status: installations.length === 0
+      ? 'missing'
+      : warningCount > 0 ? 'warning' : 'healthy',
+    healthyCount,
+    warningCount,
+    installations,
+  };
+}
+
+function reconcileCurrentInstallState(store, options = {}) {
+  try {
+    const discover = options.discoverInstalledStates
+      || require('../install-lifecycle').discoverInstalledStates;
+    const records = discover({
+      homeDir: options.homeDir,
+      projectRoot: options.projectRoot,
+      targets: options.targets,
+    });
+    let result = reconcileInstallStateProjections(store, records);
+    try {
+      result = {
+        ...result,
+        managedFileHealth: inspectManagedFileHealth(options),
+      };
+    } catch (error) {
+      result = addWarning(result, {
+        code: 'install-health-check-failed',
+        message: error.message,
+        targetId: null,
+        targetRoot: null,
+        installStatePath: null,
+      });
+    }
+    return result;
+  } catch (error) {
+    return {
+      ...createReconciliationResult(0),
+      status: 'warning',
+      warningCount: 1,
+      warnings: [{
+        code: 'install-state-discovery-failed',
+        message: error.message,
+        targetId: null,
+        targetRoot: null,
+        installStatePath: null,
+      }],
+    };
+  }
+}
+
+module.exports = {
+  buildInstallStateStoreRecord,
+  projectInstallState,
+  reconcileCurrentInstallState,
+  reconcileInstallStateProjections,
+  removeInstallStateProjection,
+  stateMatchesDiscoveryRecord,
+  summarizeProjectedInstallHealth,
+};
diff --git a/scripts/lib/state-store/queries.js b/scripts/lib/state-store/queries.js
index b265fc12c..0225f4761 100644
--- a/scripts/lib/state-store/queries.js
+++ b/scripts/lib/state-store/queries.js
@@ -348,6 +348,23 @@ function normalizeInstallStateInput(installState) {
   };
 }
 
+function normalizeInstallStateIdentity(identity) {
+  if (!identity || typeof identity !== 'object') {
+    throw new Error('Invalid installState identity: expected targetId and targetRoot');
+  }
+
+  const targetId = identity.targetId;
+  const targetRoot = identity.targetRoot;
+  if (typeof targetId !== 'string' || targetId.length === 0) {
+    throw new Error('Invalid installState identity: targetId must be a non-empty string');
+  }
+  if (typeof targetRoot !== 'string' || targetRoot.length === 0) {
+    throw new Error('Invalid installState identity: targetRoot must be a non-empty string');
+  }
+
+  return { targetId, targetRoot };
+}
+
 function normalizeGovernanceEventInput(governanceEvent) {
   return {
     id: governanceEvent.id,
@@ -432,6 +449,11 @@ function createQueryApi(db) {
     FROM install_state
     ORDER BY installed_at DESC, target_id ASC
   `);
+  const getInstallStateStatement = db.prepare(`
+    SELECT target_id
+    FROM install_state
+    WHERE target_id = ? AND target_root = ?
+  `);
   const countPendingGovernanceStatement = db.prepare(`
     SELECT COUNT(*) AS total_count
     FROM governance_events
@@ -617,6 +639,10 @@ function createQueryApi(db) {
       installed_at = excluded.installed_at,
       source_version = excluded.source_version
   `);
+  const deleteInstallStateStatement = db.prepare(`
+    DELETE FROM install_state
+    WHERE target_id = @target_id AND target_root = @target_root
+  `);
 
   const insertGovernanceEventStatement = db.prepare(`
     INSERT INTO governance_events (
@@ -778,6 +804,18 @@ function createQueryApi(db) {
   }
 
   return {
+    deleteInstallState(identity) {
+      const normalized = normalizeInstallStateIdentity(identity);
+      const existing = getInstallStateStatement.get(normalized.targetId, normalized.targetRoot);
+      if (!existing) {
+        return false;
+      }
+      deleteInstallStateStatement.run({
+        target_id: normalized.targetId,
+        target_root: normalized.targetRoot,
+      });
+      return true;
+    },
     getSessionById,
     getSessionDetail,
     getWorkItemById,
diff --git a/scripts/repair.js b/scripts/repair.js
index 8386208ef..34f614229 100644
--- a/scripts/repair.js
+++ b/scripts/repair.js
@@ -71,7 +71,7 @@ function printHuman(result) {
   }
 }
 
-function main() {
+async function main() {
   try {
     const options = parseArgs(process.argv);
     if (options.help) {
@@ -85,6 +85,14 @@ function main() {
       targets: options.targets,
       dryRun: options.dryRun,
     });
+    if (!options.dryRun) {
+      const { reconcileCanonicalInstallStates } = require('./lib/install-state-store-sync');
+      result.installStateProjection = await reconcileCanonicalInstallStates({
+        homeDir: process.env.HOME || os.homedir(),
+        projectRoot: process.cwd(),
+        targets: options.targets,
+      });
+    }
     const hasErrors = result.summary.errorCount > 0;
 
     if (options.json) {
diff --git a/scripts/status.js b/scripts/status.js
index 523738bba..0a1a3d84a 100644
--- a/scripts/status.js
+++ b/scripts/status.js
@@ -5,6 +5,10 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { createStateStore } = require('./lib/state-store');
+const {
+  reconcileCurrentInstallState,
+  summarizeProjectedInstallHealth,
+} = require('./lib/state-store/install-state-projection');
 
 function showHelp(exitCode = 0) {
   console.log(`
@@ -112,11 +116,17 @@ function printSkillRuns(section) {
   }
 }
 
-function printInstallHealth(section) {
+function printInstallHealth(section, projection) {
   console.log(`Install health: ${section.status}`);
   console.log(`  Targets recorded: ${section.totalCount}`);
   console.log(`  Healthy: ${section.healthyCount}`);
   console.log(`  Warning: ${section.warningCount}`);
+  if (projection) {
+    console.log(`  Projection: ${projection.status}`);
+    for (const warning of projection.warnings) {
+      console.log(`  - [warning] ${warning.code}: ${warning.message}`);
+    }
+  }
 
   if (section.installations.length === 0) {
     console.log('  Installations: none');
@@ -130,6 +140,9 @@ function printInstallHealth(section) {
     console.log(`    Profile: ${installation.profile || '(custom)'}`);
     console.log(`    Modules: ${installation.moduleCount}`);
     console.log(`    Source version: ${installation.sourceVersion || '(unknown)'}`);
+    for (const issue of installation.issues || []) {
+      console.log(`    - [${issue.severity}] ${issue.code}: ${issue.message}`);
+    }
   }
 }
 
@@ -252,7 +265,7 @@ function printHuman(payload) {
   console.log();
   printSkillRuns(payload.skillRuns);
   console.log();
-  printInstallHealth(payload.installHealth);
+  printInstallHealth(payload.installHealth, payload.installStateProjection);
   console.log();
   printGovernance(payload.governance);
   console.log();
@@ -336,6 +349,13 @@ function renderMarkdown(payload) {
     `Warning: ${payload.installHealth.warningCount}`
   );
 
+  if (payload.installStateProjection) {
+    lines.push(`Projection: ${payload.installStateProjection.status}`);
+    for (const warning of payload.installStateProjection.warnings) {
+      lines.push(`- [warning] ${warning.code}: ${warning.message}`);
+    }
+  }
+
   if (payload.installHealth.installations.length === 0) {
     lines.push('', 'Installations: none');
   } else {
@@ -346,6 +366,9 @@ function renderMarkdown(payload) {
       lines.push(`  - Profile: ${installation.profile || '(custom)'}`);
       lines.push(`  - Modules: ${installation.moduleCount}`);
       lines.push(`  - Source version: ${installation.sourceVersion || '(unknown)'}`);
+      for (const issue of installation.issues || []) {
+        lines.push(`  - [${issue.severity}] ${issue.code}: ${issue.message}`);
+      }
     }
   }
 
@@ -442,14 +465,48 @@ async function main() {
       homeDir: process.env.HOME || os.homedir(),
     });
 
+    const installStateProjection = reconcileCurrentInstallState(store, {
+      homeDir: process.env.HOME || os.homedir(),
+      projectRoot: process.cwd(),
+    });
+    const storedStatus = store.getStatus({
+      activeLimit: options.limit,
+      recentSkillRunLimit: 20,
+      pendingLimit: options.limit,
+      workItemLimit: options.limit,
+    });
+    const installHealth = summarizeProjectedInstallHealth(
+      storedStatus.installHealth,
+      installStateProjection
+    );
+    const installWarningDelta = installHealth.warningCount
+      - storedStatus.installHealth.warningCount;
+    const status = {
+      ...storedStatus,
+      installHealth,
+      readiness: installWarningDelta === 0
+        ? storedStatus.readiness
+        : {
+          ...storedStatus.readiness,
+          status: 'attention',
+          attentionCount: storedStatus.readiness.attentionCount + installWarningDelta,
+          warningInstallations: installHealth.warningCount,
+        },
+    };
+    const projectionWarningCount = installStateProjection.warningCount;
+
     const payload = {
       dbPath: store.dbPath,
-      ...store.getStatus({
-        activeLimit: options.limit,
-        recentSkillRunLimit: 20,
-        pendingLimit: options.limit,
-        workItemLimit: options.limit,
-      }),
+      ...status,
+      readiness: projectionWarningCount === 0
+        ? status.readiness
+        : {
+          ...status.readiness,
+          status: 'attention',
+          attentionCount: status.readiness.attentionCount + projectionWarningCount,
+          installProjectionWarnings: projectionWarningCount,
+        },
+      installStateProjection,
     };
     payload.githubCoordination = summarizeGithubCoordination(payload.workItems);
 
diff --git a/scripts/sync-ecc-to-codex.sh b/scripts/sync-ecc-to-codex.sh
index 43ca4fa53..e85a689cf 100755
--- a/scripts/sync-ecc-to-codex.sh
+++ b/scripts/sync-ecc-to-codex.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-set -euo pipefail
+set -Eeuo pipefail
 
 # Sync Everything Claude Code (ECC) assets into a local Codex CLI setup.
 # - Backs up ~/.codex config and AGENTS.md
@@ -44,6 +44,7 @@ PROMPTS_DEST="$CODEX_HOME/prompts"
 BASELINE_MERGE_SCRIPT="$REPO_ROOT/scripts/codex/merge-codex-config.js"
 HOOKS_INSTALLER="$REPO_ROOT/scripts/codex/install-global-git-hooks.sh"
 SANITY_CHECKER="$REPO_ROOT/scripts/codex/check-codex-global-state.sh"
+LEGACY_STATE_HELPER="$REPO_ROOT/scripts/codex/legacy-sync-state.js"
 CURSOR_RULES_DIR="$REPO_ROOT/.cursor/rules"
 
 STAMP="$(date +%Y%m%d-%H%M%S)"
@@ -169,6 +170,7 @@ require_path "$PROMPTS_SRC" "ECC commands directory"
 require_path "$BASELINE_MERGE_SCRIPT" "ECC Codex baseline merge script"
 require_path "$HOOKS_INSTALLER" "ECC global git hooks installer"
 require_path "$SANITY_CHECKER" "ECC global sanity checker"
+require_path "$LEGACY_STATE_HELPER" "ECC legacy sync state helper"
 require_path "$CURSOR_RULES_DIR" "ECC Cursor rules directory"
 require_path "$CONFIG_FILE" "Codex config.toml"
 require_path "$MCP_MERGE_SCRIPT" "ECC MCP merge script"
@@ -189,6 +191,40 @@ if [[ -f "$AGENTS_FILE" ]]; then
   run_or_echo cp "$AGENTS_FILE" "$BACKUP_DIR/AGENTS.md"
 fi
 
+LEGACY_STATE_PATH=""
+record_managed_path() {
+  local managed_path="$1"
+  if [[ "$MODE" == "apply" ]]; then
+    node "$LEGACY_STATE_HELPER" record --state "$LEGACY_STATE_PATH" --path "$managed_path"
+  fi
+}
+
+if [[ "$MODE" == "apply" ]]; then
+  previous_hooks_path="$(git config --global core.hooksPath || true)"
+  LEGACY_STATE_PATH="$(
+    node "$LEGACY_STATE_HELPER" begin \
+      --codex-home "$CODEX_HOME" \
+      --backup-dir "$BACKUP_DIR" \
+      --previous-hooks-path "$previous_hooks_path" \
+      --installed-hooks-path "${ECC_GLOBAL_HOOKS_DIR:-$CODEX_HOME/git-hooks}"
+  )"
+  record_managed_path "$CONFIG_FILE"
+  record_managed_path "$AGENTS_FILE"
+
+  rollback_legacy_sync() {
+    local exit_status="${1:-1}"
+    trap - ERR INT TERM
+    log "Install interrupted; restoring the pre-sync Codex state"
+    if ! node "$LEGACY_STATE_HELPER" rollback --state "$LEGACY_STATE_PATH"; then
+      log "ERROR: Automatic rollback was partial. Review: $LEGACY_STATE_PATH"
+    fi
+    exit "$exit_status"
+  }
+  trap 'rollback_legacy_sync $?' ERR
+  trap 'rollback_legacy_sync 130' INT
+  trap 'rollback_legacy_sync 143' TERM
+fi
+
 ECC_BEGIN_MARKER="<!-- BEGIN ECC -->"
 ECC_END_MARKER="<!-- END ECC -->"
 
@@ -276,11 +312,16 @@ fi
 
 log "Syncing Codex navigation guide"
 run_or_echo mkdir -p "$(dirname "$CODEX_NAV_GUIDE_DEST")"
+record_managed_path "$CODEX_NAV_GUIDE_DEST"
 run_or_echo cp "$CODEX_NAV_GUIDE_SRC" "$CODEX_NAV_GUIDE_DEST"
+record_managed_path "$CODEX_COMMAND_AGENT_MAP_DEST"
 run_or_echo cp "$CODEX_COMMAND_AGENT_MAP_SRC" "$CODEX_COMMAND_AGENT_MAP_DEST"
+record_managed_path "$CODEX_COMMANDS_QUICK_REF_DEST"
 run_or_echo cp "$CODEX_COMMANDS_QUICK_REF_SRC" "$CODEX_COMMANDS_QUICK_REF_DEST"
+record_managed_path "$CODEX_CONTRIBUTING_DEST"
 run_or_echo cp "$CODEX_CONTRIBUTING_SRC" "$CODEX_CONTRIBUTING_DEST"
 run_or_echo mkdir -p "$(dirname "$CODEX_PR_TEMPLATE_DEST")"
+record_managed_path "$CODEX_PR_TEMPLATE_DEST"
 run_or_echo cp "$CODEX_PR_TEMPLATE_SRC" "$CODEX_PR_TEMPLATE_DEST"
 
 log "Syncing sample Codex agent role files"
@@ -292,6 +333,7 @@ for agent_file in "$CODEX_AGENTS_SRC"/*.toml; do
   if [[ -e "$dest" ]]; then
     log "Keeping existing Codex agent role file: $dest"
   else
+    record_managed_path "$dest"
     run_or_echo cp "$agent_file" "$dest"
   fi
 done
@@ -303,6 +345,7 @@ done
 log "Generating prompt files from ECC commands"
 run_or_echo mkdir -p "$PROMPTS_DEST"
 manifest="$PROMPTS_DEST/ecc-prompts-manifest.txt"
+record_managed_path "$manifest"
 if [[ "$MODE" == "dry-run" ]]; then
   printf '[dry-run] > %s\n' "$manifest"
 else
@@ -316,6 +359,7 @@ while IFS= read -r -d '' command_file; do
   if [[ "$MODE" == "dry-run" ]]; then
     printf '[dry-run] generate %s from %s\n' "$out" "$command_file"
   else
+    record_managed_path "$out"
     generate_prompt_file "$command_file" "$out" "$name"
     printf 'ecc-%s.md\n' "$name" >> "$manifest"
   fi
@@ -328,6 +372,7 @@ fi
 
 log "Generating Codex tool prompts + optional rule-pack prompts"
 extension_manifest="$PROMPTS_DEST/ecc-extension-prompts-manifest.txt"
+record_managed_path "$extension_manifest"
 if [[ "$MODE" == "dry-run" ]]; then
   printf '[dry-run] > %s\n' "$extension_manifest"
 else
@@ -342,6 +387,7 @@ write_extension_prompt() {
   if [[ "$MODE" == "dry-run" ]]; then
     printf '[dry-run] generate %s\n' "$file"
   else
+    record_managed_path "$file"
     cat > "$file"
     printf '%s\n' "$name" >> "$extension_manifest"
   fi
@@ -531,6 +577,8 @@ if [[ "$MODE" == "dry-run" ]]; then
   ECC_GLOBAL_HOOKS_DIR="${ECC_GLOBAL_HOOKS_DIR:-$CODEX_HOME/git-hooks}" \
     "$HOOKS_INSTALLER" --dry-run
 else
+  record_managed_path "${ECC_GLOBAL_HOOKS_DIR:-$CODEX_HOME/git-hooks}/pre-commit"
+  record_managed_path "${ECC_GLOBAL_HOOKS_DIR:-$CODEX_HOME/git-hooks}/pre-push"
   HOME="$HOME" \
   CODEX_HOME="$CODEX_HOME" \
   AGENTS_HOME="${AGENTS_HOME:-$HOME/.agents}" \
@@ -554,5 +602,7 @@ log "Backup saved at: $BACKUP_DIR"
 log "Prompts generated: $((prompt_count + extension_count)) (commands: $prompt_count, extensions: $extension_count)"
 
 if [[ "$MODE" == "apply" ]]; then
+  node "$LEGACY_STATE_HELPER" finalize --state "$LEGACY_STATE_PATH"
+  trap - ERR INT TERM
   log "Done. Restart Codex CLI to reload AGENTS, prompts, and MCP servers."
 fi
diff --git a/scripts/uninstall.js b/scripts/uninstall.js
index 427ebfc94..f9a651ebb 100644
--- a/scripts/uninstall.js
+++ b/scripts/uninstall.js
@@ -4,12 +4,14 @@ const os = require('os');
 const { uninstallInstalledStates } = require('./lib/install-lifecycle');
 const { SUPPORTED_INSTALL_TARGETS } = require('./lib/install-manifests');
 const { exitFeedbackLines } = require('./lib/feedback-links');
+const { uninstallLegacyCodexSync } = require('./lib/codex-legacy-sync');
 
 function showHelp(exitCode = 0) {
   console.log(`
-Usage: node scripts/uninstall.js [--target <${SUPPORTED_INSTALL_TARGETS.join('|')}>] [--dry-run] [--json]
+Usage: node scripts/uninstall.js [--target <${SUPPORTED_INSTALL_TARGETS.join('|')}>] [--legacy-codex-sync] [--dry-run] [--json]
 
 Remove ECC-managed files recorded in install-state for the current context.
+Use --legacy-codex-sync explicitly for the older sync-ecc-to-codex.sh installation.
 `);
   process.exit(exitCode);
 }
@@ -20,6 +22,7 @@ function parseArgs(argv) {
     targets: [],
     dryRun: false,
     json: false,
+    legacyCodexSync: false,
     help: false,
   };
 
@@ -33,6 +36,8 @@ function parseArgs(argv) {
       parsed.dryRun = true;
     } else if (arg === '--json') {
       parsed.json = true;
+    } else if (arg === '--legacy-codex-sync') {
+      parsed.legacyCodexSync = true;
     } else if (arg === '--help' || arg === '-h') {
       parsed.help = true;
     } else {
@@ -60,34 +65,73 @@ function printHuman(result) {
       continue;
     }
 
-    const paths = result.dryRun ? entry.plannedRemovals : entry.removedPaths;
+    if (entry.warning) {
+      console.log(`  Warning: ${entry.warning}`);
+    }
+    if (Array.isArray(entry.retainedPaths) && entry.retainedPaths.length > 0) {
+      console.log(`  Retained paths: ${entry.retainedPaths.length}`);
+      for (const retainedPath of entry.retainedPaths) {
+        console.log(`    - ${retainedPath}`);
+      }
+    }
+
+    const candidatePaths = result.dryRun ? entry.plannedRemovals : entry.removedPaths;
+    const paths = Array.isArray(candidatePaths) ? candidatePaths : [];
     console.log(`  ${result.dryRun ? 'Planned removals' : 'Removed paths'}: ${paths.length}`);
   }
 
-  console.log(`\nSummary: checked=${result.summary.checkedCount}, ${result.dryRun ? 'planned' : 'uninstalled'}=${result.dryRun ? result.summary.plannedRemovalCount : result.summary.uninstalledCount}, errors=${result.summary.errorCount}`);
+  console.log(`\nSummary: checked=${result.summary.checkedCount}, ${result.dryRun ? 'planned' : 'uninstalled'}=${result.dryRun ? result.summary.plannedRemovalCount : result.summary.uninstalledCount}, partial=${result.summary.partialCount}, errors=${result.summary.errorCount}`);
 
   if (!result.dryRun) {
     console.log(`\n${exitFeedbackLines().join('\n')}`);
   }
 }
 
-function main() {
+async function main() {
   try {
     const options = parseArgs(process.argv);
     if (options.help) {
       showHelp(0);
     }
 
-    const result = uninstallInstalledStates({
-      homeDir: process.env.HOME || os.homedir(),
-      projectRoot: process.cwd(),
-      targets: options.targets,
-      dryRun: options.dryRun,
-    });
-    const hasErrors = result.summary.errorCount > 0;
+    if (options.legacyCodexSync && options.targets.length > 0) {
+      throw new Error('--legacy-codex-sync cannot be combined with --target');
+    }
+    const result = options.legacyCodexSync
+      ? uninstallLegacyCodexSync({
+          codexHome: process.env.CODEX_HOME,
+          dryRun: options.dryRun,
+        })
+      : uninstallInstalledStates({
+          homeDir: process.env.HOME || os.homedir(),
+          projectRoot: process.cwd(),
+          targets: options.targets,
+          dryRun: options.dryRun,
+        });
+    if (!options.dryRun && !options.legacyCodexSync) {
+      const { reconcileCanonicalInstallStates } = require('./lib/install-state-store-sync');
+      result.installStateProjection = await reconcileCanonicalInstallStates({
+        homeDir: process.env.HOME || os.homedir(),
+        projectRoot: process.cwd(),
+        targets: options.targets,
+      });
+    }
+    const hasErrors = options.legacyCodexSync
+      ? result.status === 'partial'
+      : result.summary.errorCount > 0 || result.summary.partialCount > 0;
 
     if (options.json) {
       console.log(JSON.stringify(result, null, 2));
+    } else if (options.legacyCodexSync) {
+      console.log('Legacy Codex sync cleanup summary:\n');
+      console.log(`Status: ${result.status.toUpperCase()}`);
+      const paths = options.dryRun ? result.plannedRemovals : result.removedPaths;
+      console.log(`${options.dryRun ? 'Planned changes' : 'Removed paths'}: ${paths.length}`);
+      if (result.retainedPaths.length > 0) {
+        console.log(`Retained paths: ${result.retainedPaths.length}`);
+        for (const retainedPath of result.retainedPaths) console.log(`  - ${retainedPath}`);
+      }
+      for (const warning of result.warnings) console.log(`Warning: ${warning}`);
     } else {
       printHuman(result);
     }
diff --git a/skills/repo-scan/SKILL.md b/skills/repo-scan/SKILL.md
index daa60d9fe..c2f40eee7 100644
--- a/skills/repo-scan/SKILL.md
+++ b/skills/repo-scan/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: repo-scan
-description: Cross-stack source code asset audit — classifies every file, detects embedded third-party libraries, and delivers actionable four-level verdicts per module with interactive HTML reports. Use when an unfamiliar or inherited repository needs a file-level audit of what each module is and what third-party code it embeds.
+description: Bootstrap pointer that installs the external repo-scan skill from a pinned, reviewable commit. Use when repo-scan must be installed before running its cross-stack source-code asset audit; this ECC pointer does not perform the audit itself.
 metadata:
   origin: community
 ---
@@ -19,18 +19,109 @@ metadata:
 ## Installation
 
 ```bash
-# Fetch only the pinned commit for reproducibility
-mkdir -p ~/.claude/skills/repo-scan
-git init repo-scan
-cd repo-scan
-git remote add origin https://github.com/haibindev/repo-scan.git
-git fetch --depth 1 origin 2742664
-git checkout --detach FETCH_HEAD
-cp -r . ~/.claude/skills/repo-scan
+# Clone first so the pinned commit can be reviewed before installation
+set -euo pipefail
+
+REPO_SCAN_COMMIT=2742664ebcad1450c208eda0ae45d3c17fad5dd8
+REPO_SCAN_INSTALL_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/repo-scan"
+REPO_SCAN_INSTALL_PARENT="$(dirname "$REPO_SCAN_INSTALL_DIR")"
+mkdir -p "$REPO_SCAN_INSTALL_PARENT"
+REPO_SCAN_TMP="$(mktemp -d "$REPO_SCAN_INSTALL_PARENT/.repo-scan-install.XXXXXX")"
+REPO_SCAN_TOKEN="${REPO_SCAN_TMP##*.}"
+REPO_SCAN_STAGE="$REPO_SCAN_TMP/stage-$REPO_SCAN_TOKEN"
+REPO_SCAN_BACKUP="$REPO_SCAN_TMP/backup-$REPO_SCAN_TOKEN"
+REPO_SCAN_LOCK="$REPO_SCAN_INSTALL_PARENT/.repo-scan-install.lock"
+REPO_SCAN_KEEP_TMP=0
+REPO_SCAN_LOCK_HELD=0
+REPO_SCAN_MV_HAS_NO_TARGET=0
+cleanup_repo_scan_install() {
+  if [ "$REPO_SCAN_KEEP_TMP" -eq 0 ]; then
+    rm -rf -- "$REPO_SCAN_TMP"
+  fi
+  if [ "$REPO_SCAN_LOCK_HELD" -eq 1 ] && ! rmdir -- "$REPO_SCAN_LOCK"; then
+    printf 'Could not release installation lock at %s\n' "$REPO_SCAN_LOCK" >&2
+  fi
+}
+trap cleanup_repo_scan_install EXIT
+mkdir "$REPO_SCAN_TMP/mv-probe-source"
+if mv -T -- "$REPO_SCAN_TMP/mv-probe-source" \
+  "$REPO_SCAN_TMP/mv-probe-destination" 2>/dev/null; then
+  REPO_SCAN_MV_HAS_NO_TARGET=1
+  rmdir "$REPO_SCAN_TMP/mv-probe-destination"
+else
+  rmdir "$REPO_SCAN_TMP/mv-probe-source"
+fi
+move_repo_scan_dir() {
+  REPO_SCAN_MOVE_SOURCE=$1
+  REPO_SCAN_MOVE_DESTINATION=$2
+  REPO_SCAN_MOVE_NAME=${REPO_SCAN_MOVE_SOURCE##*/}
+  if [ -e "$REPO_SCAN_MOVE_DESTINATION" ] || [ -L "$REPO_SCAN_MOVE_DESTINATION" ]; then
+    return 1
+  fi
+  if [ "$REPO_SCAN_MV_HAS_NO_TARGET" -eq 1 ]; then
+    mv -T -- "$REPO_SCAN_MOVE_SOURCE" "$REPO_SCAN_MOVE_DESTINATION"
+    return
+  fi
+  if ! mv -- "$REPO_SCAN_MOVE_SOURCE" "$REPO_SCAN_MOVE_DESTINATION"; then
+    return 1
+  fi
+  if [ -e "$REPO_SCAN_MOVE_DESTINATION/$REPO_SCAN_MOVE_NAME" ] || \
+    [ -L "$REPO_SCAN_MOVE_DESTINATION/$REPO_SCAN_MOVE_NAME" ]; then
+    if ! mv -- "$REPO_SCAN_MOVE_DESTINATION/$REPO_SCAN_MOVE_NAME" \
+      "$REPO_SCAN_MOVE_SOURCE"; then
+      REPO_SCAN_KEEP_TMP=1
+      printf 'Move conflict recovery failed; staged data remains at %s\n' \
+        "$REPO_SCAN_MOVE_DESTINATION/$REPO_SCAN_MOVE_NAME" >&2
+    fi
+    return 1
+  fi
+}
+
+git clone --filter=blob:none --no-checkout \
+  https://github.com/haibindev/repo-scan.git "$REPO_SCAN_TMP/source"
+git -C "$REPO_SCAN_TMP/source" checkout --detach "$REPO_SCAN_COMMIT"
+mkdir -p "$REPO_SCAN_STAGE"
+git -C "$REPO_SCAN_TMP/source" archive "$REPO_SCAN_COMMIT" | \
+  tar -xf - -C "$REPO_SCAN_STAGE"
+
+# Review "$REPO_SCAN_TMP/source" before approving installation.
+printf 'Type install to replace %s after reviewing the pinned source: ' \
+  "$REPO_SCAN_INSTALL_DIR" >&2
+read -r REPO_SCAN_CONFIRM
+if [ "$REPO_SCAN_CONFIRM" != install ]; then
+  printf 'Installation cancelled.\n' >&2
+  exit 1
+fi
+if ! mkdir -- "$REPO_SCAN_LOCK" 2>/dev/null; then
+  printf 'Another repo-scan installation holds the lock at %s\n' \
+    "$REPO_SCAN_LOCK" >&2
+  exit 1
+fi
+REPO_SCAN_LOCK_HELD=1
+
+if [ -e "$REPO_SCAN_INSTALL_DIR" ] || [ -L "$REPO_SCAN_INSTALL_DIR" ]; then
+  move_repo_scan_dir "$REPO_SCAN_INSTALL_DIR" "$REPO_SCAN_BACKUP"
+fi
+if ! move_repo_scan_dir "$REPO_SCAN_STAGE" "$REPO_SCAN_INSTALL_DIR"; then
+  if [ -e "$REPO_SCAN_BACKUP" ] || [ -L "$REPO_SCAN_BACKUP" ]; then
+    if [ -e "$REPO_SCAN_INSTALL_DIR" ] || [ -L "$REPO_SCAN_INSTALL_DIR" ]; then
+      REPO_SCAN_KEEP_TMP=1
+      printf 'Replacement failed and target was recreated; previous installation preserved at %s\n' \
+        "$REPO_SCAN_BACKUP" >&2
+    elif ! move_repo_scan_dir "$REPO_SCAN_BACKUP" "$REPO_SCAN_INSTALL_DIR"; then
+      REPO_SCAN_KEEP_TMP=1
+      printf 'Replacement and rollback failed; previous installation preserved at %s\n' \
+        "$REPO_SCAN_BACKUP" >&2
+    fi
+  fi
+  exit 1
+fi
 ```
 
 > Review the source before installing any agent skill.
 
+Installation completes only the bootstrap. Reload your agent harness, then invoke `repo-scan` again. This ECC pointer installs the external skill but does not run a scan itself.
+
 ## Core Capabilities
 
 | Capability | Description |
diff --git a/tests/ci/packed-artifact-lifecycle.js b/tests/ci/packed-artifact-lifecycle.js
new file mode 100644
index 000000000..25d841d32
--- /dev/null
+++ b/tests/ci/packed-artifact-lifecycle.js
@@ -0,0 +1,448 @@
+#!/usr/bin/env node
+'use strict';
+
+const assert = require('assert');
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { pathToFileURL } = require('url');
+const { spawnSync } = require('child_process');
+
+const PACKAGE_NAME = 'ecc-universal';
+const HASH_PATTERN = /^[a-f0-9]{64}$/i;
+const PACKAGE_PATH_PATTERN = /^release-artifacts\/ecc-universal-[0-9A-Za-z.+-]+\.tgz$/;
+
+function parseEnvironment(environment = process.env, cwd = process.cwd()) {
+  const packageValue = environment.ECC_RELEASE_PACKAGE;
+  const hashValue = environment.ECC_RELEASE_SHA256;
+
+  if (!packageValue) {
+    throw new Error('ECC_RELEASE_PACKAGE must name the downloaded release .tgz');
+  }
+  if (!PACKAGE_PATH_PATTERN.test(String(packageValue))) {
+    throw new Error('ECC_RELEASE_PACKAGE must name one ECC .tgz under release-artifacts');
+  }
+  if (!HASH_PATTERN.test(hashValue || '')) {
+    throw new Error('ECC_RELEASE_SHA256 must be a 64-character SHA-256 digest');
+  }
+
+  return {
+    packagePath: path.resolve(cwd, packageValue),
+    expectedSha256: hashValue.toLowerCase(),
+  };
+}
+
+function assertDownloadedArtifact(packagePath, cwd) {
+  const artifactRoot = path.resolve(cwd, 'release-artifacts');
+  const packageStat = fs.lstatSync(packagePath);
+  if (!packageStat.isFile() || packageStat.isSymbolicLink()) {
+    throw new Error('Release package must be a regular, non-symlink file');
+  }
+
+  const realArtifactRoot = fs.realpathSync(artifactRoot);
+  const realPackagePath = fs.realpathSync(packagePath);
+  const relativePath = path.relative(realArtifactRoot, realPackagePath);
+  if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+    throw new Error('Release package escapes release-artifacts');
+  }
+
+  const archives = fs.readdirSync(realArtifactRoot).filter(name => name.endsWith('.tgz'));
+  if (archives.length !== 1 || archives[0] !== path.basename(realPackagePath)) {
+    throw new Error('Expected exactly one downloaded release archive');
+  }
+}
+
+function hashFile(filePath) {
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
+function assertHash(actualSha256, expectedSha256) {
+  if (actualSha256 !== expectedSha256) {
+    throw new Error(
+      `Downloaded artifact SHA-256 ${actualSha256} does not match packed artifact ${expectedSha256}`
+    );
+  }
+}
+
+function createLifecycleEnvironment(baseEnvironment, homeDir) {
+  const environment = {};
+  const inheritedNames = [
+    'CI',
+    'ComSpec',
+    'LANG',
+    'LC_ALL',
+    'NO_COLOR',
+    'PATH',
+    'Path',
+    'PATHEXT',
+    'SystemRoot',
+    'TEMP',
+    'TMP',
+    'TMPDIR',
+    'WINDIR',
+  ];
+
+  for (const name of inheritedNames) {
+    if (baseEnvironment[name] !== undefined) {
+      environment[name] = baseEnvironment[name];
+    }
+  }
+
+  return {
+    ...environment,
+    HOME: homeDir,
+    USERPROFILE: homeDir,
+    APPDATA: path.join(homeDir, 'AppData', 'Roaming'),
+    LOCALAPPDATA: path.join(homeDir, 'AppData', 'Local'),
+    XDG_CONFIG_HOME: path.join(homeDir, '.config'),
+    XDG_DATA_HOME: path.join(homeDir, '.local', 'share'),
+    NPM_CONFIG_CACHE: path.join(homeDir, '.npm'),
+    NPM_CONFIG_USERCONFIG: path.join(homeDir, '.npmrc'),
+  };
+}
+
+function runProcess(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd,
+    env: options.env,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  const expectedStatus = options.expectedStatus ?? 0;
+  if (result.status !== expectedStatus) {
+    throw new Error([
+      `${options.label || command} exited ${result.status}, expected ${expectedStatus}.`,
+      result.stdout ? `stdout:\n${result.stdout}` : '',
+      result.stderr ? `stderr:\n${result.stderr}` : '',
+    ].filter(Boolean).join('\n'));
+  }
+
+  return result;
+}
+
+function getNpmExecInvocation(publicArgs, environment, platform = process.platform) {
+  const npmArgs = ['exec', '--offline', '--yes=false', '--', ...publicArgs];
+  if (platform !== 'win32') {
+    return { command: 'npm', args: npmArgs };
+  }
+
+  const commandParts = ['npm', ...npmArgs];
+  for (const part of commandParts) {
+    if (!/^[A-Za-z0-9_.=+/-]+$/.test(part)) {
+      throw new Error(`Unsafe npm exec argument for Windows lifecycle: ${part}`);
+    }
+  }
+
+  return {
+    command: environment.ComSpec || 'cmd.exe',
+    args: ['/d', '/s', '/c', commandParts.join(' ')],
+  };
+}
+
+function installPackage(projectDir, packagePath, environment) {
+  const projectManifest = {
+    name: 'ecc-packed-artifact-lifecycle',
+    version: '1.0.0',
+    private: true,
+    dependencies: {
+      [PACKAGE_NAME]: pathToFileURL(packagePath).href,
+    },
+  };
+  fs.writeFileSync(
+    path.join(projectDir, 'package.json'),
+    `${JSON.stringify(projectManifest, null, 2)}\n`,
+    'utf8'
+  );
+
+  if (process.platform === 'win32') {
+    runProcess(
+      environment.ComSpec || 'cmd.exe',
+      ['/d', '/s', '/c', 'npm install --no-audit --no-fund'],
+      { cwd: projectDir, env: environment, label: 'npm install packed artifact' }
+    );
+    return;
+  }
+
+  runProcess('npm', ['install', '--no-audit', '--no-fund'], {
+    cwd: projectDir,
+    env: environment,
+    label: 'npm install packed artifact',
+  });
+}
+
+function parseJsonOutput(result, label) {
+  try {
+    return JSON.parse(result.stdout);
+  } catch (error) {
+    throw new Error(`${label} did not emit valid JSON: ${error.message}\n${result.stdout}`);
+  }
+}
+
+function resolveManagedExistingPath(destinationPath, cursorRoot) {
+  const normalizedRoot = fs.realpathSync(cursorRoot);
+  const lexicalPath = path.resolve(destinationPath);
+  const lexicalRelativePath = path.relative(normalizedRoot, lexicalPath);
+  if (
+    lexicalRelativePath === ''
+    || lexicalRelativePath.startsWith('..')
+    || path.isAbsolute(lexicalRelativePath)
+    || !fs.existsSync(lexicalPath)
+  ) {
+    return null;
+  }
+
+  const pathStat = fs.lstatSync(lexicalPath);
+  if (pathStat.isSymbolicLink()) {
+    throw new Error(`Managed lifecycle path must not be a symlink: ${lexicalPath}`);
+  }
+
+  const realPath = fs.realpathSync(lexicalPath);
+  const realRelativePath = path.relative(normalizedRoot, realPath);
+  if (realRelativePath.startsWith('..') || path.isAbsolute(realRelativePath)) {
+    throw new Error(`Managed lifecycle path escapes Cursor root: ${lexicalPath}`);
+  }
+
+  return { path: realPath, stat: pathStat };
+}
+
+function getManagedOperationSnapshot(state, cursorRoot) {
+  const snapshot = [];
+  for (const operation of state.operations) {
+    if (operation.ownership !== 'managed' || typeof operation.destinationPath !== 'string') {
+      continue;
+    }
+    const resolved = resolveManagedExistingPath(operation.destinationPath, cursorRoot);
+    if (resolved) {
+      snapshot.push({ path: resolved.path, isFile: resolved.stat.isFile() });
+    }
+  }
+  return [...new Map(snapshot.map(entry => [entry.path, entry])).values()]
+    .sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function getOperationLedger(state) {
+  return state.operations.map(operation => ({
+    kind: operation.kind,
+    moduleId: operation.moduleId,
+    sourceRelativePath: operation.sourceRelativePath || null,
+    destinationPath: operation.destinationPath,
+    strategy: operation.strategy,
+    ownership: operation.ownership,
+    contentSha256: operation.contentSha256 || null,
+  }));
+}
+
+function findDriftCandidate(state, cursorRoot) {
+  const operation = state.operations.find(candidate => {
+    if (candidate.kind !== 'copy-file' || typeof candidate.destinationPath !== 'string') {
+      return false;
+    }
+    const resolved = resolveManagedExistingPath(candidate.destinationPath, cursorRoot);
+    return resolved && resolved.stat.isFile();
+  });
+
+  assert.ok(operation, 'installed state must contain a managed Cursor file that can be drifted');
+  return resolveManagedExistingPath(operation.destinationPath, cursorRoot).path;
+}
+
+function runLifecycle(options) {
+  assert.ok(fs.existsSync(options.packagePath), `release package does not exist: ${options.packagePath}`);
+  assertDownloadedArtifact(options.packagePath, process.cwd());
+  assertHash(hashFile(options.packagePath), options.expectedSha256);
+
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-packed-lifecycle-'));
+  const homeDir = path.join(tempRoot, 'home');
+  const projectDir = path.join(tempRoot, 'project');
+  fs.mkdirSync(homeDir, { recursive: true });
+  fs.mkdirSync(projectDir, { recursive: true });
+
+  const environment = createLifecycleEnvironment(process.env, homeDir);
+
+  try {
+    installPackage(projectDir, options.packagePath, environment);
+
+    const cursorRoot = path.join(projectDir, '.cursor');
+    const statePath = path.join(cursorRoot, 'ecc-install-state.json');
+    const sentinelPath = path.join(cursorRoot, 'user-sentinel.txt');
+    fs.mkdirSync(cursorRoot, { recursive: true });
+    fs.writeFileSync(sentinelPath, 'keep this user file\n', 'utf8');
+
+    const runPublicCli = (publicArgs, commandOptions = {}) => {
+      const invocation = getNpmExecInvocation(publicArgs, environment);
+      return runProcess(invocation.command, invocation.args, {
+        cwd: projectDir,
+        env: environment,
+        label: `npm exec -- ${publicArgs.join(' ')}`,
+        ...commandOptions,
+      });
+    };
+    const runCli = (args, commandOptions = {}) => runPublicCli(
+      ['ecc', ...args],
+      commandOptions
+    );
+
+    const setupHelp = runPublicCli(['ecc-universal', 'setup', '--help']);
+    assert.match(setupHelp.stdout, /ECC guided setup/);
+    assert.match(setupHelp.stdout, /ecc setup --mode claude-plugin/);
+
+    parseJsonOutput(
+      runCli(['install', '--profile', 'core', '--target', 'cursor', '--json']),
+      'initial install'
+    );
+    assert.ok(fs.existsSync(statePath), 'initial install must write Cursor install-state');
+    const initialState = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    const initialLedger = getOperationLedger(initialState);
+    const managedSnapshot = getManagedOperationSnapshot(initialState, cursorRoot);
+    assert.ok(managedSnapshot.length > 0, 'initial install must create managed Cursor files');
+
+    parseJsonOutput(
+      runCli(['install', '--profile', 'core', '--target', 'cursor', '--json']),
+      'repeat install'
+    );
+    const repeatState = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    assert.deepStrictEqual(
+      getOperationLedger(repeatState),
+      initialLedger,
+      'repeat install must preserve the complete ownership ledger'
+    );
+    for (const entry of managedSnapshot) {
+      assert.ok(fs.existsSync(entry.path), `repeat install lost managed path: ${entry.path}`);
+    }
+    assert.strictEqual(
+      fs.readFileSync(sentinelPath, 'utf8'),
+      'keep this user file\n',
+      'repeat install must preserve user-owned files'
+    );
+
+    const statusAfterInstall = parseJsonOutput(
+      runCli(['status', '--json']),
+      'status after install'
+    );
+    assert.strictEqual(statusAfterInstall.installHealth.status, 'healthy');
+    assert.strictEqual(statusAfterInstall.installHealth.totalCount, 1);
+    assert.strictEqual(statusAfterInstall.installStateProjection.status, 'ok');
+    assert.strictEqual(statusAfterInstall.installStateProjection.warningCount, 0);
+    assert.strictEqual(statusAfterInstall.readiness.status, 'ok');
+
+    const healthyBeforeDrift = parseJsonOutput(
+      runCli(['doctor', '--target', 'cursor', '--json']),
+      'doctor before drift'
+    );
+    assert.strictEqual(healthyBeforeDrift.summary.errorCount, 0);
+    assert.strictEqual(healthyBeforeDrift.summary.warningCount, 0);
+
+    const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    const driftPath = findDriftCandidate(state, cursorRoot);
+    fs.appendFileSync(driftPath, '\nECC_PACKED_LIFECYCLE_DRIFT\n', 'utf8');
+
+    const driftedDoctor = parseJsonOutput(
+      runCli(['doctor', '--target', 'cursor', '--json'], { expectedStatus: 1 }),
+      'doctor after drift'
+    );
+    assert.ok(
+      driftedDoctor.summary.errorCount + driftedDoctor.summary.warningCount > 0,
+      'doctor must detect induced managed-file drift'
+    );
+
+    const repair = parseJsonOutput(
+      runCli(['repair', '--target', 'cursor', '--json']),
+      'repair'
+    );
+    assert.ok(repair.summary.repairedCount > 0, 'repair must restore the drifted managed file');
+
+    const healthyAfterRepair = parseJsonOutput(
+      runCli(['doctor', '--target', 'cursor', '--json']),
+      'doctor after repair'
+    );
+    assert.strictEqual(healthyAfterRepair.summary.errorCount, 0);
+    assert.strictEqual(healthyAfterRepair.summary.warningCount, 0);
+
+    const statusAfterRepair = parseJsonOutput(
+      runCli(['status', '--json']),
+      'status after repair'
+    );
+    assert.strictEqual(statusAfterRepair.installHealth.status, 'healthy');
+    assert.strictEqual(statusAfterRepair.installHealth.totalCount, 1);
+    assert.strictEqual(statusAfterRepair.installStateProjection.status, 'ok');
+    assert.strictEqual(statusAfterRepair.installStateProjection.warningCount, 0);
+    assert.strictEqual(statusAfterRepair.readiness.status, 'ok');
+
+    parseJsonOutput(
+      runCli(['uninstall', '--target', 'cursor', '--json']),
+      'uninstall'
+    );
+    assert.ok(!fs.existsSync(statePath), 'uninstall must remove Cursor install-state');
+    for (const entry of managedSnapshot) {
+      assert.ok(!fs.existsSync(entry.path), `uninstall left managed path behind: ${entry.path}`);
+    }
+    assert.strictEqual(
+      fs.readFileSync(sentinelPath, 'utf8'),
+      'keep this user file\n',
+      'uninstall must preserve user-owned files'
+    );
+
+    const statusAfterUninstall = parseJsonOutput(
+      runCli(['status', '--json']),
+      'status after uninstall'
+    );
+    assert.strictEqual(statusAfterUninstall.installHealth.status, 'missing');
+    assert.strictEqual(statusAfterUninstall.installHealth.totalCount, 0);
+    assert.strictEqual(statusAfterUninstall.installStateProjection.status, 'ok');
+    assert.strictEqual(statusAfterUninstall.installStateProjection.warningCount, 0);
+    assert.strictEqual(statusAfterUninstall.readiness.status, 'ok');
+
+    return {
+      packageSha256: options.expectedSha256,
+      platform: process.platform,
+      node: process.version,
+      lifecycle: [
+        'npm-install',
+        'public-ecc-universal-setup',
+        'cursor-install',
+        'cursor-repeat-install',
+        'doctor-clean',
+        'status-installed',
+        'doctor-drift',
+        'repair',
+        'doctor-repaired',
+        'status-repaired',
+        'uninstall',
+        'status-uninstalled',
+        'sentinel-preserved',
+      ],
+    };
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+function main() {
+  try {
+    const report = runLifecycle(parseEnvironment());
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } catch (error) {
+    process.stderr.write(`Packed-artifact lifecycle failed: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  assertDownloadedArtifact,
+  assertHash,
+  createLifecycleEnvironment,
+  getNpmExecInvocation,
+  hashFile,
+  parseEnvironment,
+  runLifecycle,
+};
+
+if (require.main === module) {
+  main();
+}
diff --git a/tests/ci/packed-artifact-lifecycle.test.js b/tests/ci/packed-artifact-lifecycle.test.js
new file mode 100644
index 000000000..994555be7
--- /dev/null
+++ b/tests/ci/packed-artifact-lifecycle.test.js
@@ -0,0 +1,130 @@
+'use strict';
+
+const assert = require('assert');
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const lifecycle = require('./packed-artifact-lifecycle');
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ✓ ${name}`);
+    passed += 1;
+  } catch (error) {
+    console.log(`  ✗ ${name}`);
+    console.log(`    Error: ${error.message}`);
+    failed += 1;
+  }
+}
+
+console.log('\n=== Testing packed-artifact lifecycle runner ===\n');
+
+test('resolves package and hash from explicit environment variables', () => {
+  const options = lifecycle.parseEnvironment({
+    ECC_RELEASE_PACKAGE: 'release-artifacts/ecc-universal-2.2.0.tgz',
+    ECC_RELEASE_SHA256: 'a'.repeat(64),
+  }, '/workspace');
+
+  assert.strictEqual(
+    options.packagePath,
+    path.resolve('/workspace', 'release-artifacts/ecc-universal-2.2.0.tgz')
+  );
+  assert.strictEqual(options.expectedSha256, 'a'.repeat(64));
+});
+
+test('rejects missing, malformed, and non-tgz release inputs', () => {
+  assert.throws(() => lifecycle.parseEnvironment({}, '/workspace'), /ECC_RELEASE_PACKAGE/);
+  assert.throws(() => lifecycle.parseEnvironment({
+    ECC_RELEASE_PACKAGE: 'package.zip',
+    ECC_RELEASE_SHA256: 'a'.repeat(64),
+  }, '/workspace'), /\.tgz/);
+  assert.throws(() => lifecycle.parseEnvironment({
+    ECC_RELEASE_PACKAGE: 'release-artifacts/ecc-universal-2.2.0.tgz',
+    ECC_RELEASE_SHA256: 'not-a-hash',
+  }, '/workspace'), /SHA-256/);
+  assert.throws(() => lifecycle.parseEnvironment({
+    ECC_RELEASE_PACKAGE: '../release-artifacts/ecc-universal-2.2.0.tgz',
+    ECC_RELEASE_SHA256: 'a'.repeat(64),
+  }, '/workspace'), /release-artifacts/);
+  assert.throws(() => lifecycle.parseEnvironment({
+    ECC_RELEASE_PACKAGE: '/tmp/ecc-universal-2.2.0.tgz',
+    ECC_RELEASE_SHA256: 'a'.repeat(64),
+  }, '/workspace'), /release-artifacts/);
+});
+
+test('hashFile computes a lowercase SHA-256 digest', () => {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-packed-hash-'));
+  const filePath = path.join(tempDir, 'package.tgz');
+
+  try {
+    fs.writeFileSync(filePath, 'exact packed bytes');
+    const expected = crypto.createHash('sha256').update('exact packed bytes').digest('hex');
+    assert.strictEqual(lifecycle.hashFile(filePath), expected);
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+});
+
+test('assertHash rejects an artifact whose bytes do not match', () => {
+  assert.throws(
+    () => lifecycle.assertHash('a'.repeat(64), 'b'.repeat(64)),
+    /does not match/
+  );
+});
+
+test('lifecycle child processes receive no inherited credentials', () => {
+  const environment = lifecycle.createLifecycleEnvironment({
+    PATH: '/tools',
+    GITHUB_TOKEN: 'github-secret',
+    NODE_AUTH_TOKEN: 'npm-secret',
+    ACTIONS_RUNTIME_TOKEN: 'actions-secret',
+    AWS_SECRET_ACCESS_KEY: 'cloud-secret',
+  }, '/isolated-home');
+
+  assert.strictEqual(environment.PATH, '/tools');
+  assert.strictEqual(environment.HOME, '/isolated-home');
+  assert.strictEqual(environment.USERPROFILE, '/isolated-home');
+  assert.strictEqual(environment.GITHUB_TOKEN, undefined);
+  assert.strictEqual(environment.NODE_AUTH_TOKEN, undefined);
+  assert.strictEqual(environment.ACTIONS_RUNTIME_TOKEN, undefined);
+  assert.strictEqual(environment.AWS_SECRET_ACCESS_KEY, undefined);
+});
+
+test('public CLI invocations use npm exec instead of internal package paths', () => {
+  const invocation = lifecycle.getNpmExecInvocation(
+    ['ecc-universal', 'setup', '--help'],
+    { ComSpec: 'C:\\Windows\\System32\\cmd.exe' },
+    'win32'
+  );
+
+  assert.strictEqual(invocation.command, 'C:\\Windows\\System32\\cmd.exe');
+  assert.deepStrictEqual(invocation.args, [
+    '/d',
+    '/s',
+    '/c',
+    'npm exec --offline --yes=false -- ecc-universal setup --help',
+  ]);
+
+  const unixInvocation = lifecycle.getNpmExecInvocation(
+    ['ecc', 'doctor', '--target', 'cursor', '--json'],
+    {},
+    'linux'
+  );
+  assert.strictEqual(unixInvocation.command, 'npm');
+  assert.deepStrictEqual(
+    unixInvocation.args.slice(0, 4),
+    ['exec', '--offline', '--yes=false', '--']
+  );
+  assert.strictEqual(unixInvocation.args[4], 'ecc');
+  assert.ok(!unixInvocation.args.some(argument => argument.includes('node_modules')));
+});
+
+console.log(`\nPassed: ${passed}`);
+console.log(`Failed: ${failed}`);
+process.exit(failed > 0 ? 1 : 0);
diff --git a/tests/ci/release-packed-artifact-workflow.test.js b/tests/ci/release-packed-artifact-workflow.test.js
new file mode 100644
index 000000000..a44c43065
--- /dev/null
+++ b/tests/ci/release-packed-artifact-workflow.test.js
@@ -0,0 +1,167 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const repoRoot = path.resolve(__dirname, '..', '..');
+const workflowPaths = [
+  '.github/workflows/release.yml',
+  '.github/workflows/reusable-release.yml',
+];
+const lifecycleRunnerSource = load('tests/ci/packed-artifact-lifecycle.js');
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ✓ ${name}`);
+    passed += 1;
+  } catch (error) {
+    console.log(`  ✗ ${name}`);
+    console.log(`    Error: ${error.message}`);
+    failed += 1;
+  }
+}
+
+function load(relativePath) {
+  return fs.readFileSync(path.join(repoRoot, relativePath), 'utf8').replace(/\r\n/g, '\n');
+}
+
+function jobBlock(source, jobName, nextJobName) {
+  const startMarker = `\n  ${jobName}:\n`;
+  const start = source.indexOf(startMarker);
+  assert.ok(start >= 0, `missing ${jobName} job`);
+
+  if (!nextJobName) {
+    return source.slice(start);
+  }
+
+  const end = source.indexOf(`\n  ${nextJobName}:\n`, start + startMarker.length);
+  assert.ok(end > start, `missing ${nextJobName} job after ${jobName}`);
+  return source.slice(start, end);
+}
+
+console.log('\n=== Testing packed-artifact release workflows ===\n');
+
+for (const workflowPath of workflowPaths) {
+  const source = load(workflowPath);
+
+  test(`${workflowPath} packs once and exports the package name and SHA-256`, () => {
+    assert.strictEqual(
+      (source.match(/npm pack --json/g) || []).length,
+      1,
+      'release workflow must pack exactly once'
+    );
+    assert.match(source, /package_sha256:\s*\$\{\{ steps\.pack\.outputs\.package_sha256 \}\}/);
+    assert.match(source, /createHash\(['"]sha256['"]\)/);
+    assert.match(source, /package_sha256=['"]? \+ digest/);
+    assert.match(source, /release_commit:\s*\$\{\{ steps\.source\.outputs\.release_commit \}\}/);
+    assert.match(source, /release_commit=\$\{RELEASE_COMMIT\}/);
+  });
+
+  test(`${workflowPath} invokes only test files present in the release source`, () => {
+    const referencedTests = [...source.matchAll(/\bnode (tests\/[A-Za-z0-9_./-]+\.js)\b/g)]
+      .map(match => match[1]);
+    assert.ok(referencedTests.length > 0, 'release workflow should run repository tests');
+    for (const testPath of referencedTests) {
+      assert.ok(fs.existsSync(path.join(repoRoot, testPath)), `missing workflow test: ${testPath}`);
+    }
+  });
+
+  test(`${workflowPath} uploads the one packed tgz as the release artifact`, () => {
+    const verify = jobBlock(source, 'verify', 'lifecycle');
+    const packIndex = verify.indexOf('name: Pack npm artifact');
+    const uploadIndex = verify.indexOf('name: Upload release artifacts');
+
+    assert.ok(packIndex >= 0, 'missing pack step');
+    assert.ok(uploadIndex > packIndex, 'artifact upload must happen after pack and hash');
+    assert.match(verify, /name:\s*ecc-release-artifacts/);
+    assert.match(verify, /\$\{\{ steps\.pack\.outputs\.package_file \}\}/);
+  });
+
+  test(`${workflowPath} fails retries when npm already has different bytes`, () => {
+    const verify = jobBlock(source, 'verify', 'lifecycle');
+    assert.match(verify, /name:\s*Verify existing npm artifact matches candidate/);
+    assert.match(verify, /if:\s*steps\.npm_publish_state\.outputs\.already_published == 'true'/);
+    assert.match(verify, /npm view "\$\{PACKAGE_NAME\}@\$\{PACKAGE_VERSION\}" dist\.integrity/);
+    assert.match(verify, /createHash\(['"]sha512['"]\)/);
+    assert.match(verify, /Existing npm artifact does not match tested candidate/);
+  });
+
+  test(`${workflowPath} verifies the same tgz on Node 20 across three operating systems`, () => {
+    const lifecycle = jobBlock(source, 'lifecycle', 'publish');
+
+    assert.match(lifecycle, /needs:\s*verify/);
+    assert.match(lifecycle, /os:\s*\[ubuntu-latest, macos-latest, windows-latest\]/);
+    assert.match(lifecycle, /runs-on:\s*\$\{\{ matrix\.os \}\}/);
+    assert.match(lifecycle, /node-version:\s*['"]20\.x['"]/);
+    assert.match(lifecycle, /uses:\s*actions\/download-artifact@/);
+    assert.match(lifecycle, /name:\s*ecc-release-artifacts/);
+    assert.match(lifecycle, /ECC_RELEASE_PACKAGE:\s*release-artifacts\/\$\{\{ needs\.verify\.outputs\.package_file \}\}/);
+    assert.match(lifecycle, /ECC_RELEASE_SHA256:\s*\$\{\{ needs\.verify\.outputs\.package_sha256 \}\}/);
+    assert.match(lifecycle, /node tests\/ci\/packed-artifact-lifecycle\.js/);
+    assert.match(lifecycle, /ref:\s*\$\{\{ needs\.verify\.outputs\.release_commit \}\}/);
+    assert.doesNotMatch(lifecycle, /\bsecrets\s*:/, 'lifecycle job must not receive secrets');
+    assert.doesNotMatch(lifecycle, /\$\{\{\s*secrets\./, 'lifecycle job must not reference secrets');
+  });
+
+  test(`${workflowPath} blocks publishing on packed-artifact lifecycle success`, () => {
+    const publish = jobBlock(source, 'publish');
+
+    assert.match(publish, /needs:\s*\[verify, lifecycle\]/);
+    assert.match(publish, /ECC_RELEASE_PACKAGE:\s*\$\{\{ needs\.verify\.outputs\.package_file \}\}/);
+    assert.match(publish, /npm publish "\.\/\$\{ECC_RELEASE_PACKAGE\}"/);
+    assert.match(publish, /name:\s*Verify artifact before publish/);
+    assert.match(publish, /ECC_RELEASE_SHA256:\s*\$\{\{ needs\.verify\.outputs\.package_sha256 \}\}/);
+    assert.match(publish, /createHash\(['"]sha256['"]\)/);
+    assert.match(publish, /ecc-universal-\[0-9A-Za-z\.\+-\]/);
+    assert.ok(
+      publish.indexOf('name: Verify artifact before publish')
+        < publish.indexOf('name: Create GitHub Release'),
+      'publish must verify the independently downloaded archive before creating the release'
+    );
+  });
+}
+
+test('reusable release requires its input to resolve through the tag namespace', () => {
+  const source = load('.github/workflows/reusable-release.yml');
+  const verify = jobBlock(source, 'verify', 'lifecycle');
+  assert.match(verify, /ref:\s*refs\/tags\/\$\{\{ inputs\.tag \}\}/);
+});
+
+test('pull-request CI packs once and exports the exact installer artifact identity', () => {
+  const source = load('.github/workflows/ci.yml');
+  const pack = jobBlock(source, 'pack-installer', 'packed-install-lifecycle');
+  assert.strictEqual((pack.match(/npm pack --json/g) || []).length, 1);
+  assert.match(pack, /package_file:\s*\$\{\{ steps\.pack\.outputs\.package_file \}\}/);
+  assert.match(pack, /package_sha256:\s*\$\{\{ steps\.pack\.outputs\.package_sha256 \}\}/);
+  assert.match(pack, /createHash\(['"]sha256['"]\)/);
+  assert.match(pack, /name:\s*ecc-ci-installer-artifact/);
+});
+
+test('pull-request CI runs the same packed installer on Linux, macOS, and Windows', () => {
+  const source = load('.github/workflows/ci.yml');
+  const lifecycle = jobBlock(source, 'packed-install-lifecycle', 'validate');
+  assert.match(lifecycle, /needs:\s*pack-installer/);
+  assert.match(lifecycle, /os:\s*\[ubuntu-latest, macos-latest, windows-latest\]/);
+  assert.match(lifecycle, /node-version:\s*['"]20\.x['"]/);
+  assert.match(lifecycle, /name:\s*ecc-ci-installer-artifact/);
+  assert.match(lifecycle, /ECC_RELEASE_PACKAGE:\s*release-artifacts\/\$\{\{ needs\.pack-installer\.outputs\.package_file \}\}/);
+  assert.match(lifecycle, /ECC_RELEASE_SHA256:\s*\$\{\{ needs\.pack-installer\.outputs\.package_sha256 \}\}/);
+  assert.match(lifecycle, /node tests\/ci\/packed-artifact-lifecycle\.js/);
+  assert.doesNotMatch(lifecycle, /\$\{\{\s*secrets\./);
+});
+
+test('packed lifecycle invokes installed public bins, including setup help', () => {
+  assert.match(lifecycleRunnerSource, /getNpmExecInvocation/);
+  assert.match(lifecycleRunnerSource, /\['ecc-universal', 'setup', '--help'\]/);
+  assert.match(lifecycleRunnerSource, /\['ecc', \.\.\.args\]/);
+  assert.doesNotMatch(lifecycleRunnerSource, /node_modules.*scripts.*ecc\.js/);
+});
+
+console.log(`\nPassed: ${passed}`);
+console.log(`Failed: ${failed}`);
+process.exit(failed > 0 ? 1 : 0);
diff --git a/tests/lib/antigravity-legacy-migration.test.js b/tests/lib/antigravity-legacy-migration.test.js
new file mode 100644
index 000000000..64b44e260
--- /dev/null
+++ b/tests/lib/antigravity-legacy-migration.test.js
@@ -0,0 +1,659 @@
+/**
+ * Focused coverage for migrating Antigravity installs from .agent to .agents.
+ */
+
+const assert = require('assert');
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { applyInstallPlan } = require('../../scripts/lib/install/apply');
+const {
+  buildDoctorReport,
+  discoverInstalledStates,
+  repairInstalledStates,
+  uninstallInstalledStates,
+} = require('../../scripts/lib/install-lifecycle');
+const {
+  createInstallState,
+  readInstallState,
+  writeInstallState,
+} = require('../../scripts/lib/install-state');
+
+const REPO_ROOT = path.join(__dirname, '..', '..');
+const PACKAGE_VERSION = require('../../package.json').version;
+const MANIFEST_VERSION = require('../../manifests/install-modules.json').version;
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  \u2713 ${name}`);
+    return true;
+  } catch (error) {
+    console.log(`  \u2717 ${name}`);
+    console.log(`    Error: ${error.message}`);
+    return false;
+  }
+}
+
+function digest(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function managedCopy(destinationPath, sourceRelativePath, content) {
+  return {
+    kind: 'copy-file',
+    moduleId: 'rules-core',
+    sourceRelativePath,
+    destinationPath,
+    strategy: 'copy-file',
+    ownership: 'managed',
+    scaffoldOnly: false,
+    contentSha256: digest(content),
+  };
+}
+
+function createAntigravityState(targetRoot, installStatePath, operations = []) {
+  return createInstallState({
+    adapter: { id: 'antigravity-project', target: 'antigravity', kind: 'project' },
+    targetRoot,
+    installStatePath,
+    request: {
+      profile: null,
+      modules: [],
+      includeComponents: [],
+      excludeComponents: [],
+      legacyLanguages: ['typescript'],
+      legacyMode: true,
+    },
+    resolution: {
+      selectedModules: ['legacy-antigravity-install'],
+      skippedModules: [],
+    },
+    source: {
+      repoVersion: PACKAGE_VERSION,
+      repoCommit: 'test-commit',
+      manifestVersion: MANIFEST_VERSION,
+    },
+    operations,
+  });
+}
+
+function seedLegacyState(projectRoot, entries = []) {
+  const targetRoot = path.join(projectRoot, '.agent');
+  const installStatePath = path.join(targetRoot, 'ecc-install-state.json');
+  const operations = entries.map(entry => {
+    const destinationPath = path.join(targetRoot, entry.relativePath);
+    fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+    fs.writeFileSync(destinationPath, entry.recordedContent, 'utf8');
+    return managedCopy(destinationPath, entry.sourceRelativePath, entry.recordedContent);
+  });
+  writeInstallState(
+    installStatePath,
+    createAntigravityState(targetRoot, installStatePath, operations)
+  );
+  return { targetRoot, installStatePath, operations };
+}
+
+function createCanonicalPlan(projectRoot, sourcePath) {
+  const targetRoot = path.join(projectRoot, '.agents');
+  const installStatePath = path.join(targetRoot, 'ecc-install-state.json');
+  const operation = {
+    kind: 'copy-file',
+    moduleId: 'rules-core',
+    sourcePath,
+    sourceRelativePath: 'rules/common/coding-style.md',
+    destinationPath: path.join(targetRoot, 'rules', 'coding-style.md'),
+    strategy: 'copy-file',
+    ownership: 'managed',
+    scaffoldOnly: false,
+  };
+
+  return {
+    mode: 'legacy',
+    sourceRoot: REPO_ROOT,
+    target: 'antigravity',
+    adapter: { id: 'antigravity-project', target: 'antigravity', kind: 'project' },
+    targetRoot,
+    installRoot: targetRoot,
+    installStatePath,
+    operations: [operation],
+    warnings: [],
+    statePreview: createAntigravityState(targetRoot, installStatePath, [operation]),
+  };
+}
+
+function runTests() {
+  console.log('\n=== Testing Antigravity legacy migration ===\n');
+
+  let passed = 0;
+  let failed = 0;
+
+  if (test('writes canonical state before removing unchanged legacy-managed files', () => {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-migrate-'));
+    try {
+      const legacy = seedLegacyState(projectRoot, [{
+        relativePath: 'rules/common-coding-style.md',
+        sourceRelativePath: 'rules/common/coding-style.md',
+        recordedContent: fs.readFileSync(
+          path.join(REPO_ROOT, 'rules', 'common', 'coding-style.md'),
+          'utf8'
+        ),
+      }]);
+      const sourcePath = path.join(projectRoot, 'source.md');
+      fs.writeFileSync(sourcePath, 'canonical managed\n', 'utf8');
+      const plan = createCanonicalPlan(projectRoot, sourcePath);
+
+      applyInstallPlan(plan, {
+        writeInstallState(filePath, state) {
+          assert.ok(fs.existsSync(legacy.installStatePath));
+          assert.ok(fs.existsSync(legacy.operations[0].destinationPath));
+          return writeInstallState(filePath, state);
+        },
+      });
+
+      assert.ok(fs.existsSync(plan.installStatePath));
+      assert.ok(fs.existsSync(plan.operations[0].destinationPath));
+      assert.ok(!fs.existsSync(legacy.operations[0].destinationPath));
+      assert.ok(!fs.existsSync(legacy.installStatePath));
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  if (test('does not clean legacy files when canonical state persistence fails', () => {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-migrate-fail-'));
+    try {
+      const legacy = seedLegacyState(projectRoot, [{
+        relativePath: 'rules/common-coding-style.md',
+        sourceRelativePath: 'rules/common/coding-style.md',
+        recordedContent: fs.readFileSync(
+          path.join(REPO_ROOT, 'rules', 'common', 'coding-style.md'),
+          'utf8'
+        ),
+      }]);
+      const sourcePath = path.join(projectRoot, 'source.md');
+      fs.writeFileSync(sourcePath, 'canonical managed\n', 'utf8');
+
+      assert.throws(
+        () => applyInstallPlan(createCanonicalPlan(projectRoot, sourcePath), {
+          writeInstallState() {
+            throw new Error('simulated canonical state failure');
+          },
+        }),
+        /simulated canonical state failure/
+      );
+
+      assert.ok(fs.existsSync(legacy.operations[0].destinationPath));
+      assert.ok(fs.existsSync(legacy.installStatePath));
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  if (test('preserves recorded legacy content when the current ECC source has changed', () => {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-source-drift-'));
+    try {
+      const legacy = seedLegacyState(projectRoot, [{
+        relativePath: 'rules/common-coding-style.md',
+        sourceRelativePath: 'rules/common/coding-style.md',
+        recordedContent: 'historical ECC content\n',
+      }]);
+      const sourcePath = path.join(projectRoot, 'source.md');
+      fs.writeFileSync(sourcePath, 'canonical managed\n', 'utf8');
+
+      const result = applyInstallPlan(createCanonicalPlan(projectRoot, sourcePath));
+
+      assert.ok(fs.existsSync(legacy.operations[0].destinationPath));
+      assert.ok(fs.existsSync(legacy.installStatePath));
+      assert.ok(result.warnings.some(warning => warning.includes(
+        'current ECC source differs from the recorded installed content'
+      )));
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  if (test('preserves drifted and unmanaged legacy files and retains legacy state', () => {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-migrate-partial-'));
+    try {
+      const legacy = seedLegacyState(projectRoot, [
+        {
+          relativePath: 'rules/common-coding-style.md',
+          sourceRelativePath: 'rules/common/coding-style.md',
+          recordedContent: fs.readFileSync(
+            path.join(REPO_ROOT, 'rules', 'common', 'coding-style.md'),
+            'utf8'
+          ),
+        },
+        {
+          relativePath: 'rules/common-patterns.md',
+          sourceRelativePath: 'rules/common/patterns.md',
+          recordedContent: fs.readFileSync(
+            path.join(REPO_ROOT, 'rules', 'common', 'patterns.md'),
+            'utf8'
+          ),
+        },
+      ]);
+      fs.writeFileSync(legacy.operations[1].destinationPath, 'customer edit\n', 'utf8');
+      const unmanagedPath = path.join(legacy.targetRoot, 'customer-note.md');
+      fs.writeFileSync(unmanagedPath, 'keep me\n', 'utf8');
+      const sourcePath = path.join(projectRoot, 'source.md');
+      fs.writeFileSync(sourcePath, 'canonical managed\n', 'utf8');
+
+      applyInstallPlan(createCanonicalPlan(projectRoot, sourcePath));
+
+      assert.ok(!fs.existsSync(legacy.operations[0].destinationPath));
+      assert.strictEqual(fs.readFileSync(legacy.operations[1].destinationPath, 'utf8'), 'customer edit\n');
+      assert.strictEqual(fs.readFileSync(unmanagedPath, 'utf8'), 'keep me\n');
+      assert.ok(fs.existsSync(legacy.installStatePath));
+      const remainingLegacyState = readInstallState(legacy.installStatePath);
+      assert.strictEqual(remainingLegacyState.operations.length, 2);
+      const report = buildDoctorReport({
+        repoRoot: REPO_ROOT,
+        projectRoot,
+        targets: ['antigravity'],
+      });
+      const legacyReport = report.results.find(result => result.legacy);
+      assert.ok(legacyReport.issues.some(issue => issue.code === 'legacy-antigravity-layout'));
+      assert.ok(legacyReport.issues.some(issue => issue.code === 'drifted-managed-files'));
+      assert.ok(legacyReport.issues.some(issue => issue.code === 'missing-managed-files'));
+
+      const uninstall = uninstallInstalledStates({ projectRoot, targets: ['antigravity'] });
+      assert.strictEqual(
+        fs.readFileSync(legacy.operations[1].destinationPath, 'utf8'),
+        'customer edit\n'
+      );
+      assert.strictEqual(fs.readFileSync(unmanagedPath, 'utf8'), 'keep me\n');
+      assert.ok(fs.existsSync(legacy.installStatePath));
+      assert.strictEqual(uninstall.summary.partialCount, 1);
+      const dryRun = uninstallInstalledStates({
+        projectRoot,
+        targets: ['antigravity'],
+        dryRun: true,
+      });
+      const legacyDryRun = dryRun.results.find(result => (
+        result.installStatePath === legacy.installStatePath
+      ));
+      assert.deepStrictEqual(legacyDryRun.plannedRemovals, []);
+      assert.ok(legacyDryRun.retainedPaths.includes(legacy.operations[1].destinationPath));
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  if (test('does not trust a forged legacy digest to delete customer content', () => {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-migrate-forged-'));
+    try {
+      const legacy = seedLegacyState(projectRoot, [
+        {
+          relativePath: 'rules/common-coding-style.md',
+          sourceRelativePath: 'rules/common/coding-style.md',
+          recordedContent: 'customer-owned content\n',
+        },
+        {
+          relativePath: 'customer-note.md',
+          sourceRelativePath: 'rules/common/patterns.md',
+          recordedContent: 'customer note\n',
+        },
+        {
+          relativePath: 'README.md',
+          sourceRelativePath: 'commands/../README.md',
+          recordedContent: fs.readFileSync(path.join(REPO_ROOT, 'README.md'), 'utf8'),
+        },
+      ]);
+      const sourcePath = path.join(projectRoot, 'source.md');
+      fs.writeFileSync(sourcePath, 'canonical managed\n', 'utf8');
+
+      const result = applyInstallPlan(createCanonicalPlan(projectRoot, sourcePath));
+
+      assert.strictEqual(
+        fs.readFileSync(legacy.operations[0].destinationPath, 'utf8'),
+        'customer-owned content\n'
+      );
+      assert.strictEqual(
+        fs.readFileSync(legacy.operations[1].destinationPath, 'utf8'),
+        'customer note\n'
+      );
+      assert.ok(fs.existsSync(legacy.operations[2].destinationPath));
+      assert.ok(fs.existsSync(legacy.installStatePath));
+      assert.ok(result.warnings.some(warning => warning.includes('migration is incomplete')));
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  if (test('warns when digestless legacy files require manual migration', () => {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-migrate-digestless-'));
+    try {
+      const legacy = seedLegacyState(projectRoot, [{
+        relativePath: 'rules/common-coding-style.md',
+        sourceRelativePath: 'rules/common/coding-style.md',
+        recordedContent: fs.readFileSync(
+          path.join(REPO_ROOT, 'rules', 'common', 'coding-style.md'),
+          'utf8'
+        ),
+      }]);
+      const legacyState = readInstallState(legacy.installStatePath);
+      delete legacyState.operations[0].contentSha256;
+      writeInstallState(legacy.installStatePath, legacyState);
+      const sourcePath = path.join(projectRoot, 'source.md');
+      fs.writeFileSync(sourcePath, 'canonical managed\n', 'utf8');
+
+      const result = applyInstallPlan(createCanonicalPlan(projectRoot, sourcePath));
+
+      assert.ok(fs.existsSync(legacy.operations[0].destinationPath));
+      assert.ok(fs.existsSync(legacy.installStatePath));
+      assert.ok(result.warnings.some(warning => (
+        warning.includes('Legacy Antigravity migration is incomplete')
+        && warning.includes('.agent')
+      )));
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  if (test('preserves unrelated empty legacy directories after complete cleanup', () => {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-migrate-empty-dir-'));
+    try {
+      const legacy = seedLegacyState(projectRoot, [{
+        relativePath: 'rules/common-coding-style.md',
+        sourceRelativePath: 'rules/common/coding-style.md',
+        recordedContent: fs.readFileSync(
+          path.join(REPO_ROOT, 'rules', 'common', 'coding-style.md'),
+          'utf8'
+        ),
+      }]);
+      const userDirectory = path.join(legacy.targetRoot, 'customer-empty-directory');
+      fs.mkdirSync(userDirectory);
+      const sourcePath = path.join(projectRoot, 'source.md');
+      fs.writeFileSync(sourcePath, 'canonical managed\n', 'utf8');
+
+      applyInstallPlan(createCanonicalPlan(projectRoot, sourcePath));
+
+      assert.ok(fs.existsSync(userDirectory));
+      assert.ok(!fs.existsSync(legacy.installStatePath));
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  if (test('list discovery and doctor report both canonical and remaining legacy states', () => {
+    const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-home-'));
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-discover-'));
+    try {
+      const canonicalRoot = path.join(projectRoot, '.agents');
+      const canonicalStatePath = path.join(canonicalRoot, 'ecc-install-state.json');
+      writeInstallState(
+        canonicalStatePath,
+        createAntigravityState(canonicalRoot, canonicalStatePath)
+      );
+      const legacy = seedLegacyState(projectRoot);
+
+      const records = discoverInstalledStates({
+        homeDir,
+        projectRoot,
+        targets: ['antigravity'],
+      }).filter(record => record.exists);
+      assert.deepStrictEqual(
+        records.map(record => record.installStatePath).sort(),
+        [canonicalStatePath, legacy.installStatePath].sort()
+      );
+
+      const report = buildDoctorReport({
+        repoRoot: REPO_ROOT,
+        homeDir,
+        projectRoot,
+        targets: ['antigravity'],
+      });
+      assert.strictEqual(report.results.length, 2);
+      assert.strictEqual(report.summary.checkedCount, 2);
+      const legacyReport = report.results.find(result => result.legacy);
+      assert.ok(legacyReport);
+      assert.ok(legacyReport.issues.some(issue => (
+        issue.severity === 'warning'
+        && issue.code === 'legacy-antigravity-layout'
+      )));
+
+      fs.rmSync(canonicalStatePath);
+      const legacyOnlyRecords = discoverInstalledStates({
+        homeDir,
+        projectRoot,
+        targets: ['antigravity'],
+      }).filter(record => record.exists);
+      assert.strictEqual(legacyOnlyRecords.length, 1);
+      assert.strictEqual(legacyOnlyRecords[0].installStatePath, legacy.installStatePath);
+      assert.strictEqual(legacyOnlyRecords[0].legacy, true);
+    } finally {
+      fs.rmSync(homeDir, { recursive: true, force: true });
+      fs.rmSync(projectRoot, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  if (test('uninstall discovers and removes both canonical and legacy states', () => {
+    const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-home-'));
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-uninstall-'));
+    try {
+      const canonicalRoot = path.join(projectRoot, '.agents');
+      const canonicalStatePath = path.join(canonicalRoot, 'ecc-install-state.json');
+      writeInstallState(
+        canonicalStatePath,
+        createAntigravityState(canonicalRoot, canonicalStatePath)
+      );
+      const legacy = seedLegacyState(projectRoot);
+
+      const dryRun = uninstallInstalledStates({
+        homeDir,
+        projectRoot,
+        targets: ['antigravity'],
+        dryRun: true,
+      });
+      assert.strictEqual(dryRun.results.length, 2);
+      assert.ok(dryRun.results.some(result => result.installStatePath === canonicalStatePath));
+      assert.ok(dryRun.results.some(result => result.installStatePath === legacy.installStatePath));
+
+      const result = uninstallInstalledStates({
+        homeDir,
+        projectRoot,
+        targets: ['antigravity'],
+      });
+      assert.strictEqual(result.summary.uninstalledCount, 2);
+      assert.ok(!fs.existsSync(canonicalStatePath));
+      assert.ok(!fs.existsSync(legacy.installStatePath));
+    } finally {
+      fs.rmSync(homeDir, { recursive: true, force: true });
+      fs.rmSync(projectRoot, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  if (test('does not repair residual legacy state over preserved customer edits', () => {
+    const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-home-'));
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-repair-'));
+    try {
+      const canonicalRoot = path.join(projectRoot, '.agents');
+      const canonicalStatePath = path.join(canonicalRoot, 'ecc-install-state.json');
+      writeInstallState(
+        canonicalStatePath,
+        createAntigravityState(canonicalRoot, canonicalStatePath)
+      );
+      const legacy = seedLegacyState(projectRoot, [{
+        relativePath: 'rules/coding-style.md',
+        sourceRelativePath: 'rules/common/coding-style.md',
+        recordedContent: fs.readFileSync(
+          path.join(REPO_ROOT, 'rules', 'common', 'coding-style.md'),
+          'utf8'
+        ),
+      }]);
+      fs.writeFileSync(legacy.operations[0].destinationPath, 'customer edit\n', 'utf8');
+
+      const result = repairInstalledStates({
+        repoRoot: REPO_ROOT,
+        homeDir,
+        projectRoot,
+        targets: ['antigravity'],
+      });
+
+      assert.strictEqual(
+        fs.readFileSync(legacy.operations[0].destinationPath, 'utf8'),
+        'customer edit\n'
+      );
+      assert.ok(!result.results.some(entry => entry.installStatePath === legacy.installStatePath));
+    } finally {
+      fs.rmSync(homeDir, { recursive: true, force: true });
+      fs.rmSync(projectRoot, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  if (test('does not discover mismatched or symlinked legacy state', () => {
+    const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-home-'));
+    const mismatchedProject = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-mismatch-'));
+    const symlinkProject = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-symlink-'));
+    const externalRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-external-'));
+    try {
+      const mismatchedRoot = path.join(mismatchedProject, '.agent');
+      const mismatchedStatePath = path.join(mismatchedRoot, 'ecc-install-state.json');
+      writeInstallState(mismatchedStatePath, createInstallState({
+        adapter: { id: 'cursor-project', target: 'cursor', kind: 'project' },
+        targetRoot: mismatchedRoot,
+        installStatePath: mismatchedStatePath,
+        request: {
+          profile: null,
+          modules: [],
+          includeComponents: [],
+          excludeComponents: [],
+          legacyLanguages: [],
+          legacyMode: true,
+        },
+        resolution: { selectedModules: [], skippedModules: [] },
+        source: {
+          repoVersion: PACKAGE_VERSION,
+          repoCommit: 'test-commit',
+          manifestVersion: MANIFEST_VERSION,
+        },
+        operations: [],
+      }));
+
+      const mismatchedRecords = discoverInstalledStates({
+        homeDir,
+        projectRoot: mismatchedProject,
+        targets: ['antigravity'],
+      }).filter(record => record.exists);
+      assert.strictEqual(mismatchedRecords.length, 0);
+
+      if (process.platform !== 'win32') {
+        const symlinkStatePath = path.join(externalRoot, 'ecc-install-state.json');
+        const linkedRoot = path.join(symlinkProject, '.agent');
+        fs.symlinkSync(externalRoot, linkedRoot, 'dir');
+        writeInstallState(
+          symlinkStatePath,
+          createAntigravityState(linkedRoot, path.join(linkedRoot, 'ecc-install-state.json'))
+        );
+
+        const symlinkRecords = discoverInstalledStates({
+          homeDir,
+          projectRoot: symlinkProject,
+          targets: ['antigravity'],
+        }).filter(record => record.exists);
+        assert.strictEqual(symlinkRecords.length, 0);
+      }
+    } finally {
+      fs.rmSync(homeDir, { recursive: true, force: true });
+      fs.rmSync(mismatchedProject, { recursive: true, force: true });
+      fs.rmSync(symlinkProject, { recursive: true, force: true });
+      fs.rmSync(externalRoot, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  if (test('reports corrupt legacy state instead of treating it as absent', () => {
+    const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-home-'));
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-corrupt-'));
+    try {
+      const legacyRoot = path.join(projectRoot, '.agent');
+      const legacyStatePath = path.join(legacyRoot, 'ecc-install-state.json');
+      fs.mkdirSync(legacyRoot, { recursive: true });
+      fs.writeFileSync(legacyStatePath, '{not valid json\n', 'utf8');
+
+      const records = discoverInstalledStates({
+        homeDir,
+        projectRoot,
+        targets: ['antigravity'],
+      }).filter(record => record.exists);
+      assert.strictEqual(records.length, 1);
+      assert.strictEqual(records[0].legacy, true);
+      assert.match(records[0].error, /Unable to inspect legacy Antigravity install-state/);
+
+      const sourcePath = path.join(projectRoot, 'source.md');
+      fs.writeFileSync(sourcePath, 'canonical managed\n', 'utf8');
+      const result = applyInstallPlan(createCanonicalPlan(projectRoot, sourcePath));
+      assert.ok(result.warnings.some(warning => warning.includes(
+        'Unable to inspect legacy Antigravity install-state'
+      )));
+      assert.ok(fs.existsSync(legacyStatePath));
+    } finally {
+      fs.rmSync(homeDir, { recursive: true, force: true });
+      fs.rmSync(projectRoot, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  if (test('doctor and repair compare Antigravity agents using transformed content', () => {
+    const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-home-'));
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'antigravity-transform-health-'));
+    try {
+      const sourcePath = path.join(REPO_ROOT, 'agents', 'architect.md');
+      const targetRoot = path.join(projectRoot, '.agents');
+      const installStatePath = path.join(targetRoot, 'ecc-install-state.json');
+      const operation = {
+        kind: 'copy-file',
+        moduleId: 'agents-core',
+        sourcePath,
+        sourceRelativePath: 'agents/architect.md',
+        destinationPath: path.join(targetRoot, 'agents', 'architect.md'),
+        strategy: 'copy-file',
+        ownership: 'managed',
+        scaffoldOnly: false,
+        contentTransform: 'antigravity-agent-frontmatter',
+      };
+      const plan = {
+        mode: 'legacy',
+        target: 'antigravity',
+        adapter: { id: 'antigravity-project', target: 'antigravity', kind: 'project' },
+        targetRoot,
+        installRoot: targetRoot,
+        installStatePath,
+        operations: [operation],
+        warnings: [],
+        statePreview: createAntigravityState(targetRoot, installStatePath, [operation]),
+      };
+      applyInstallPlan(plan);
+      const installedContent = fs.readFileSync(operation.destinationPath, 'utf8');
+      assert.notStrictEqual(installedContent, fs.readFileSync(sourcePath, 'utf8'));
+
+      const report = buildDoctorReport({
+        repoRoot: REPO_ROOT,
+        homeDir,
+        projectRoot,
+        targets: ['antigravity'],
+      });
+      assert.ok(!report.results[0].issues.some(issue => issue.code === 'drifted-managed-files'));
+
+      fs.writeFileSync(operation.destinationPath, 'drifted\n', 'utf8');
+      const repair = repairInstalledStates({
+        repoRoot: REPO_ROOT,
+        homeDir,
+        projectRoot,
+        targets: ['antigravity'],
+      });
+      assert.strictEqual(repair.results[0].status, 'repaired');
+      assert.strictEqual(fs.readFileSync(operation.destinationPath, 'utf8'), installedContent);
+    } finally {
+      fs.rmSync(homeDir, { recursive: true, force: true });
+      fs.rmSync(projectRoot, { recursive: true, force: true });
+    }
+  })) passed++; else failed++;
+
+  console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+runTests();
diff --git a/tests/lib/codex-legacy-sync.test.js b/tests/lib/codex-legacy-sync.test.js
new file mode 100644
index 000000000..f860671c6
--- /dev/null
+++ b/tests/lib/codex-legacy-sync.test.js
@@ -0,0 +1,521 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const {
+  beginLegacySyncState,
+  finalizeLegacySyncState,
+  recordLegacySyncPath,
+  rollbackLegacyCodexSync,
+  uninstallLegacyCodexSync,
+} = require('../../scripts/lib/codex-legacy-sync');
+
+function tempDir(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function readStateStatus(statePath) {
+  return JSON.parse(fs.readFileSync(statePath, 'utf8')).status;
+}
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ✓ ${name}`);
+    return true;
+  } catch (error) {
+    console.log(`  ✗ ${name}`);
+    console.log(`    Error: ${error.message}`);
+    return false;
+  }
+}
+
+function runTests() {
+  console.log('\n=== Testing Codex legacy sync lifecycle ===\n');
+  let passed = 0;
+  let failed = 0;
+
+  if (test('manifest uninstall restores previous files, removes owned files, markers, and hooks path', () => {
+    const homeDir = tempDir('legacy-codex-home-');
+    const codexHome = path.join(homeDir, '.codex');
+    const backupDir = path.join(codexHome, 'backups', 'ecc-test');
+    const configPath = path.join(codexHome, 'config.toml');
+    const agentsPath = path.join(codexHome, 'AGENTS.md');
+    const promptPath = path.join(codexHome, 'prompts', 'ecc-plan.md');
+    const hooksPath = path.join(codexHome, 'git-hooks');
+    fs.mkdirSync(path.dirname(promptPath), { recursive: true });
+    fs.mkdirSync(hooksPath, { recursive: true });
+    fs.writeFileSync(configPath, 'model = "user"\n');
+    fs.writeFileSync(agentsPath, '# User instructions\n');
+    fs.writeFileSync(promptPath, '# User prompt with the same name\n');
+
+    const statePath = beginLegacySyncState({
+      codexHome,
+      backupDir,
+      previousHooksPath: '/tmp/user-hooks',
+      installedHooksPath: hooksPath,
+    });
+    for (const filePath of [configPath, agentsPath, promptPath, path.join(hooksPath, 'pre-commit')]) {
+      recordLegacySyncPath({ statePath, filePath });
+    }
+
+    fs.writeFileSync(configPath, 'model = "user"\napproval_policy = "on-request"\n');
+    fs.writeFileSync(
+      agentsPath,
+      '# User instructions\n\n<!-- BEGIN ECC -->\n# ECC managed\n<!-- END ECC -->\n'
+    );
+    fs.writeFileSync(promptPath, '# ECC generated prompt\n');
+    fs.writeFileSync(path.join(hooksPath, 'pre-commit'), '#!/bin/sh\nexit 0\n');
+    finalizeLegacySyncState({ statePath });
+
+    let hooksValue = hooksPath;
+    const result = uninstallLegacyCodexSync({
+      codexHome,
+      getGlobalHooksPath: () => hooksValue,
+      setGlobalHooksPath: value => { hooksValue = value; },
+    });
+
+    assert.strictEqual(result.status, 'uninstalled');
+    assert.strictEqual(fs.readFileSync(configPath, 'utf8'), 'model = "user"\n');
+    assert.strictEqual(fs.readFileSync(agentsPath, 'utf8'), '# User instructions\n');
+    assert.strictEqual(fs.readFileSync(promptPath, 'utf8'), '# User prompt with the same name\n');
+    assert.ok(!fs.existsSync(path.join(hooksPath, 'pre-commit')));
+    assert.strictEqual(hooksValue, '/tmp/user-hooks');
+    assert.ok(!fs.existsSync(statePath));
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  })) passed += 1; else failed += 1;
+
+  if (test('dry-run is non-mutating and drifted artifacts are retained', () => {
+    const homeDir = tempDir('legacy-codex-home-');
+    const codexHome = path.join(homeDir, '.codex');
+    const backupDir = path.join(codexHome, 'backups', 'ecc-test');
+    const promptPath = path.join(codexHome, 'prompts', 'ecc-plan.md');
+    fs.mkdirSync(path.dirname(promptPath), { recursive: true });
+    const statePath = beginLegacySyncState({ codexHome, backupDir, previousHooksPath: '' });
+    recordLegacySyncPath({ statePath, filePath: promptPath });
+    fs.writeFileSync(promptPath, '# ECC generated prompt\n');
+    finalizeLegacySyncState({ statePath });
+    fs.writeFileSync(promptPath, '# customer edit\n');
+
+    const dryRun = uninstallLegacyCodexSync({ codexHome, dryRun: true });
+    assert.strictEqual(dryRun.status, 'planned');
+    assert.ok(fs.existsSync(statePath));
+    assert.strictEqual(fs.readFileSync(promptPath, 'utf8'), '# customer edit\n');
+
+    const applied = uninstallLegacyCodexSync({ codexHome });
+    assert.strictEqual(applied.status, 'partial');
+    assert.deepStrictEqual(applied.retainedPaths, [promptPath]);
+    assert.ok(fs.existsSync(promptPath));
+    assert.ok(fs.existsSync(statePath));
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  })) passed += 1; else failed += 1;
+
+  if (test('uninstall preserves config and AGENTS edits made after legacy sync', () => {
+    const homeDir = tempDir('legacy-codex-home-');
+    const codexHome = path.join(homeDir, '.codex');
+    const configPath = path.join(codexHome, 'config.toml');
+    const agentsPath = path.join(codexHome, 'AGENTS.md');
+    fs.mkdirSync(codexHome, { recursive: true });
+    fs.writeFileSync(configPath, 'model = "user"\n');
+    fs.writeFileSync(agentsPath, '# User instructions\n');
+    const statePath = beginLegacySyncState({
+      codexHome,
+      backupDir: path.join(codexHome, 'backups', 'ecc-test'),
+    });
+    recordLegacySyncPath({ statePath, filePath: configPath });
+    recordLegacySyncPath({ statePath, filePath: agentsPath });
+    fs.writeFileSync(configPath, 'model = "user"\napproval_policy = "on-request"\n');
+    fs.writeFileSync(agentsPath, '# User instructions\n\n<!-- BEGIN ECC -->\n# ECC\n<!-- END ECC -->\n');
+    finalizeLegacySyncState({ statePath });
+    fs.appendFileSync(configPath, '# user edit after sync\n');
+    fs.appendFileSync(agentsPath, '\n# user edit after sync\n');
+
+    const result = uninstallLegacyCodexSync({ codexHome });
+    assert.strictEqual(result.status, 'partial');
+    assert.ok(fs.readFileSync(configPath, 'utf8').includes('# user edit after sync'));
+    assert.ok(fs.readFileSync(agentsPath, 'utf8').includes('# user edit after sync'));
+    assert.ok(result.retainedPaths.includes(configPath));
+    assert.ok(result.retainedPaths.includes(agentsPath));
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  })) passed += 1; else failed += 1;
+
+  if (test('pre-manifest cleanup removes only the ECC marker block and preserves all other artifacts', () => {
+    const homeDir = tempDir('legacy-codex-home-');
+    const codexHome = path.join(homeDir, '.codex');
+    const agentsPath = path.join(codexHome, 'AGENTS.md');
+    const promptPath = path.join(codexHome, 'prompts', 'ecc-plan.md');
+    fs.mkdirSync(path.dirname(promptPath), { recursive: true });
+    fs.writeFileSync(
+      agentsPath,
+      '# User\n\n<!-- BEGIN ECC -->\n# Old ECC\n<!-- END ECC -->\n\n# More user\n'
+    );
+    fs.writeFileSync(promptPath, '# unverifiable legacy prompt\n');
+
+    const result = uninstallLegacyCodexSync({ codexHome });
+    assert.strictEqual(result.status, 'partial');
+    assert.ok(!fs.readFileSync(agentsPath, 'utf8').includes('BEGIN ECC'));
+    assert.ok(fs.readFileSync(agentsPath, 'utf8').includes('# User'));
+    assert.ok(fs.readFileSync(agentsPath, 'utf8').includes('# More user'));
+    assert.ok(fs.existsSync(promptPath));
+    assert.ok(result.retainedPaths.includes(promptPath));
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  })) passed += 1; else failed += 1;
+
+  if (test('pre-manifest cleanup preserves inline, fenced, and symlinked AGENTS markers', () => {
+    const homeDir = tempDir('legacy-codex-home-');
+    const codexHome = path.join(homeDir, '.codex');
+    const agentsPath = path.join(codexHome, 'AGENTS.md');
+    const outsidePath = path.join(homeDir, 'outside-agents.md');
+    fs.mkdirSync(codexHome, { recursive: true });
+    const examples = '# User\nInline <!-- BEGIN ECC --> example <!-- END ECC -->\n```md\n<!-- BEGIN ECC -->\n# Example\n<!-- END ECC -->\n```\n````md\n```md\n<!-- BEGIN ECC -->\n# Nested example\n<!-- END ECC -->\n```\n````\n';
+    fs.writeFileSync(agentsPath, examples);
+    const examplesResult = uninstallLegacyCodexSync({ codexHome });
+    assert.strictEqual(examplesResult.status, 'not-found');
+    assert.strictEqual(fs.readFileSync(agentsPath, 'utf8'), examples);
+
+    fs.writeFileSync(outsidePath, '<!-- BEGIN ECC -->\n# Outside\n<!-- END ECC -->\n');
+    fs.rmSync(agentsPath);
+    fs.symlinkSync(outsidePath, agentsPath);
+    const symlinkResult = uninstallLegacyCodexSync({ codexHome });
+    assert.strictEqual(symlinkResult.status, 'partial');
+    assert.ok(symlinkResult.retainedPaths.includes(agentsPath));
+    assert.strictEqual(fs.readFileSync(outsidePath, 'utf8'), '<!-- BEGIN ECC -->\n# Outside\n<!-- END ECC -->\n');
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  })) passed += 1; else failed += 1;
+
+  if (test('interrupted sync rollback restores overwritten files and removes newly created files', () => {
+    const homeDir = tempDir('legacy-codex-home-');
+    const codexHome = path.join(homeDir, '.codex');
+    const backupDir = path.join(codexHome, 'backups', 'ecc-test');
+    const existingPath = path.join(codexHome, 'prompts', 'ecc-plan.md');
+    const createdPath = path.join(codexHome, 'prompts', 'ecc-review.md');
+    fs.mkdirSync(path.dirname(existingPath), { recursive: true });
+    fs.writeFileSync(existingPath, '# User prompt\n', { mode: 0o640 });
+
+    const statePath = beginLegacySyncState({
+      codexHome,
+      backupDir,
+      previousHooksPath: '/tmp/user-hooks',
+      installedHooksPath: path.join(codexHome, 'git-hooks'),
+    });
+    recordLegacySyncPath({ statePath, filePath: existingPath });
+    recordLegacySyncPath({ statePath, filePath: createdPath });
+    fs.writeFileSync(existingPath, '# Partial ECC write\n');
+    fs.writeFileSync(createdPath, '# Partial new file\n');
+
+    let hooksValue = path.join(codexHome, 'git-hooks');
+    const result = rollbackLegacyCodexSync({
+      statePath,
+      getGlobalHooksPath: () => hooksValue,
+      setGlobalHooksPath: value => { hooksValue = value; },
+    });
+
+    assert.strictEqual(result.status, 'rolled-back');
+    assert.strictEqual(fs.readFileSync(existingPath, 'utf8'), '# User prompt\n');
+    assert.strictEqual(fs.statSync(existingPath).mode & 0o777, 0o640);
+    assert.ok(!fs.existsSync(createdPath));
+    assert.strictEqual(hooksValue, '/tmp/user-hooks');
+    assert.ok(!fs.existsSync(statePath));
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  })) passed += 1; else failed += 1;
+
+  if (test('recording refuses symlink targets before the sync can write through them', () => {
+    const homeDir = tempDir('legacy-codex-home-');
+    const codexHome = path.join(homeDir, '.codex');
+    const outsidePath = path.join(homeDir, 'outside.md');
+    const linkedPath = path.join(codexHome, 'prompts', 'ecc-plan.md');
+    fs.mkdirSync(path.dirname(linkedPath), { recursive: true });
+    fs.writeFileSync(outsidePath, '# Outside\n');
+    fs.symlinkSync(outsidePath, linkedPath);
+    const statePath = beginLegacySyncState({
+      codexHome,
+      backupDir: path.join(codexHome, 'backups', 'ecc-test'),
+    });
+
+    assert.throws(
+      () => recordLegacySyncPath({ statePath, filePath: linkedPath }),
+      /Refusing to manage non-regular legacy sync path/
+    );
+    assert.strictEqual(fs.readFileSync(outsidePath, 'utf8'), '# Outside\n');
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  })) passed += 1; else failed += 1;
+
+  if (test('recording refuses a symlinked parent directory before any managed write', () => {
+    const homeDir = tempDir('legacy-codex-home-');
+    const codexHome = path.join(homeDir, '.codex');
+    const outsideDir = path.join(homeDir, 'outside');
+    fs.mkdirSync(codexHome, { recursive: true });
+    fs.mkdirSync(outsideDir, { recursive: true });
+    fs.symlinkSync(outsideDir, path.join(codexHome, 'prompts'));
+    const statePath = beginLegacySyncState({
+      codexHome,
+      backupDir: path.join(codexHome, 'backups', 'ecc-test'),
+    });
+
+    assert.throws(
+      () => recordLegacySyncPath({
+        statePath,
+        filePath: path.join(codexHome, 'prompts', 'ecc-plan.md'),
+      }),
+      /Refusing to manage legacy sync path through symlinked ancestor/
+    );
+    assert.deepStrictEqual(fs.readdirSync(outsideDir), []);
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  })) passed += 1; else failed += 1;
+
+  if (test('uninstall preserves a managed path replaced by a symlink', () => {
+    const homeDir = tempDir('legacy-codex-home-');
+    const codexHome = path.join(homeDir, '.codex');
+    const promptPath = path.join(codexHome, 'prompts', 'ecc-plan.md');
+    const outsidePath = path.join(homeDir, 'outside.md');
+    fs.mkdirSync(path.dirname(promptPath), { recursive: true });
+    fs.writeFileSync(outsidePath, '# ECC generated prompt\n');
+    const statePath = beginLegacySyncState({
+      codexHome,
+      backupDir: path.join(codexHome, 'backups', 'ecc-test'),
+    });
+    recordLegacySyncPath({ statePath, filePath: promptPath });
+    fs.writeFileSync(promptPath, '# ECC generated prompt\n');
+    finalizeLegacySyncState({ statePath });
+    fs.rmSync(promptPath);
+    fs.symlinkSync(outsidePath, promptPath);
+
+    const result = uninstallLegacyCodexSync({ codexHome });
+    assert.strictEqual(result.status, 'partial');
+    assert.ok(fs.lstatSync(promptPath).isSymbolicLink());
+    assert.strictEqual(fs.readFileSync(outsidePath, 'utf8'), '# ECC generated prompt\n');
+    assert.ok(result.retainedPaths.includes(promptPath));
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  })) passed += 1; else failed += 1;
+
+  if (test('repeat sync preserves the original pre-ECC baseline through uninstall', () => {
+    const homeDir = tempDir('legacy-codex-home-');
+    const codexHome = path.join(homeDir, '.codex');
+    const promptPath = path.join(codexHome, 'prompts', 'ecc-plan.md');
+    fs.mkdirSync(path.dirname(promptPath), { recursive: true });
+    fs.writeFileSync(promptPath, '# Original user prompt\n');
+
+    let statePath = beginLegacySyncState({
+      codexHome,
+      backupDir: path.join(codexHome, 'backups', 'ecc-first'),
+    });
+    recordLegacySyncPath({ statePath, filePath: promptPath });
+    fs.writeFileSync(promptPath, '# ECC v1\n');
+    finalizeLegacySyncState({ statePath });
+
+    statePath = beginLegacySyncState({
+      codexHome,
+      backupDir: path.join(codexHome, 'backups', 'ecc-second'),
+    });
+    recordLegacySyncPath({ statePath, filePath: promptPath });
+    fs.writeFileSync(promptPath, '# ECC v2\n');
+    finalizeLegacySyncState({ statePath });
+
+    const result = uninstallLegacyCodexSync({ codexHome });
+    assert.strictEqual(result.status, 'uninstalled');
+    assert.strictEqual(fs.readFileSync(promptPath, 'utf8'), '# Original user prompt\n');
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  })) passed += 1; else failed += 1;
+
+  if (test('repeat sync refuses drift instead of overwriting a post-install user edit', () => {
+    const homeDir = tempDir('legacy-codex-home-');
+    const codexHome = path.join(homeDir, '.codex');
+    const promptPath = path.join(codexHome, 'prompts', 'ecc-plan.md');
+    fs.mkdirSync(path.dirname(promptPath), { recursive: true });
+    const statePath = beginLegacySyncState({
+      codexHome,
+      backupDir: path.join(codexHome, 'backups', 'ecc-first'),
+    });
+    recordLegacySyncPath({ statePath, filePath: promptPath });
+    fs.writeFileSync(promptPath, '# ECC v1\n');
+    finalizeLegacySyncState({ statePath });
+    fs.appendFileSync(promptPath, '# User edit\n');
+
+    assert.throws(
+      () => beginLegacySyncState({
+        codexHome,
+        backupDir: path.join(codexHome, 'backups', 'ecc-second'),
+      }),
+      /Refusing to replace modified legacy Codex artifact/
+    );
+    assert.ok(fs.readFileSync(promptPath, 'utf8').includes('# User edit'));
+    assert.strictEqual(readStateStatus(statePath), 'installed');
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  })) passed += 1; else failed += 1;
+
+  if (test('custom external hooks root is separately trusted and retains original ownership', () => {
+    const homeDir = tempDir('legacy-codex-home-');
+    const codexHome = path.join(homeDir, '.codex');
+    const hooksRoot = path.join(homeDir, 'custom-hooks');
+    const hookPath = path.join(hooksRoot, 'pre-commit');
+    fs.mkdirSync(hooksRoot, { recursive: true });
+    fs.writeFileSync(hookPath, '#!/bin/sh\necho user\n', { mode: 0o700 });
+    const statePath = beginLegacySyncState({
+      codexHome,
+      backupDir: path.join(codexHome, 'backups', 'ecc-test'),
+      previousHooksPath: hooksRoot,
+      installedHooksPath: hooksRoot,
+    });
+    recordLegacySyncPath({ statePath, filePath: hookPath });
+    fs.writeFileSync(hookPath, '#!/bin/sh\necho ecc\n', { mode: 0o700 });
+    finalizeLegacySyncState({ statePath });
+
+    const result = uninstallLegacyCodexSync({
+      codexHome,
+      getGlobalHooksPath: () => hooksRoot,
+      setGlobalHooksPath() {},
+    });
+    assert.strictEqual(result.status, 'uninstalled');
+    assert.strictEqual(fs.readFileSync(hookPath, 'utf8'), '#!/bin/sh\necho user\n');
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  })) passed += 1; else failed += 1;
+
+  if (test('repeat sync rollback remains recoverable after changing custom hooks roots', () => {
+    const homeDir = tempDir('legacy-codex-home-');
+    const codexHome = path.join(homeDir, '.codex');
+    const hooksRootA = path.join(homeDir, 'custom-hooks-a');
+    const hooksRootB = path.join(homeDir, 'custom-hooks-b');
+    const hookPathA = path.join(hooksRootA, 'pre-commit');
+    const hookPathB = path.join(hooksRootB, 'pre-commit');
+    fs.mkdirSync(hooksRootA, { recursive: true });
+    fs.mkdirSync(hooksRootB, { recursive: true });
+    fs.writeFileSync(hookPathA, '#!/bin/sh\necho user-a\n');
+
+    let statePath = beginLegacySyncState({
+      codexHome,
+      installedHooksPath: hooksRootA,
+      previousHooksPath: '',
+    });
+    recordLegacySyncPath({ statePath, filePath: hookPathA });
+    fs.writeFileSync(hookPathA, '#!/bin/sh\necho ecc-a\n');
+    finalizeLegacySyncState({ statePath });
+    const priorInstalledState = fs.readFileSync(statePath, 'utf8');
+
+    statePath = beginLegacySyncState({
+      codexHome,
+      installedHooksPath: hooksRootB,
+      previousHooksPath: hooksRootA,
+    });
+    recordLegacySyncPath({ statePath, filePath: hookPathB });
+    fs.writeFileSync(hookPathA, '#!/bin/sh\necho partial-a\n');
+    fs.writeFileSync(hookPathB, '#!/bin/sh\necho partial-b\n');
+
+    let hooksValue = hooksRootB;
+    const rollback = rollbackLegacyCodexSync({
+      statePath,
+      getGlobalHooksPath: () => hooksValue,
+      setGlobalHooksPath: value => { hooksValue = value; },
+    });
+    assert.strictEqual(rollback.status, 'rolled-back');
+    assert.strictEqual(fs.readFileSync(hookPathA, 'utf8'), '#!/bin/sh\necho ecc-a\n');
+    assert.ok(!fs.existsSync(hookPathB));
+    assert.strictEqual(hooksValue, hooksRootA);
+    assert.strictEqual(fs.readFileSync(statePath, 'utf8'), priorInstalledState);
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  })) passed += 1; else failed += 1;
+
+  if (test('repeat sync uninstall restores all custom hooks roots after a root change', () => {
+    const homeDir = tempDir('legacy-codex-home-');
+    const codexHome = path.join(homeDir, '.codex');
+    const hooksRootA = path.join(homeDir, 'custom-hooks-a');
+    const hooksRootB = path.join(homeDir, 'custom-hooks-b');
+    const hookPathA = path.join(hooksRootA, 'pre-commit');
+    const hookPathB = path.join(hooksRootB, 'pre-commit');
+    fs.mkdirSync(hooksRootA, { recursive: true });
+    fs.mkdirSync(hooksRootB, { recursive: true });
+    fs.writeFileSync(hookPathA, '#!/bin/sh\necho user-a\n');
+
+    let statePath = beginLegacySyncState({
+      codexHome,
+      installedHooksPath: hooksRootA,
+      previousHooksPath: '',
+    });
+    recordLegacySyncPath({ statePath, filePath: hookPathA });
+    fs.writeFileSync(hookPathA, '#!/bin/sh\necho ecc-a\n');
+    finalizeLegacySyncState({ statePath });
+
+    statePath = beginLegacySyncState({
+      codexHome,
+      installedHooksPath: hooksRootB,
+      previousHooksPath: hooksRootA,
+    });
+    recordLegacySyncPath({ statePath, filePath: hookPathB });
+    fs.writeFileSync(hookPathB, '#!/bin/sh\necho ecc-b\n');
+    finalizeLegacySyncState({ statePath });
+
+    let hooksValue = hooksRootB;
+    const uninstall = uninstallLegacyCodexSync({
+      codexHome,
+      getGlobalHooksPath: () => hooksValue,
+      setGlobalHooksPath: value => { hooksValue = value; },
+    });
+    assert.strictEqual(uninstall.status, 'uninstalled');
+    assert.strictEqual(fs.readFileSync(hookPathA, 'utf8'), '#!/bin/sh\necho user-a\n');
+    assert.ok(!fs.existsSync(hookPathB));
+    assert.strictEqual(hooksValue, '');
+    assert.ok(!fs.existsSync(statePath));
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  })) passed += 1; else failed += 1;
+
+  if (test('rollback preserves a managed path replaced by a dangling symlink', () => {
+    const homeDir = tempDir('legacy-codex-home-');
+    const codexHome = path.join(homeDir, '.codex');
+    const promptPath = path.join(codexHome, 'prompts', 'ecc-plan.md');
+    const outsidePath = path.join(homeDir, 'missing-outside.md');
+    fs.mkdirSync(path.dirname(promptPath), { recursive: true });
+    fs.writeFileSync(promptPath, '# Original user prompt\n');
+    const statePath = beginLegacySyncState({
+      codexHome,
+      backupDir: path.join(codexHome, 'backups', 'ecc-test'),
+    });
+    recordLegacySyncPath({ statePath, filePath: promptPath });
+    fs.rmSync(promptPath);
+    fs.symlinkSync(outsidePath, promptPath);
+
+    const result = rollbackLegacyCodexSync({ statePath });
+    assert.strictEqual(result.status, 'partial');
+    assert.ok(result.retainedPaths.includes(promptPath));
+    assert.ok(fs.lstatSync(promptPath).isSymbolicLink());
+    assert.ok(!fs.existsSync(outsidePath));
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  })) passed += 1; else failed += 1;
+
+  if (test('failed repeat sync restores the prior installed ownership manifest', () => {
+    const homeDir = tempDir('legacy-codex-home-');
+    const codexHome = path.join(homeDir, '.codex');
+    const promptPath = path.join(codexHome, 'prompts', 'ecc-plan.md');
+    fs.mkdirSync(path.dirname(promptPath), { recursive: true });
+    fs.writeFileSync(promptPath, '# Original user prompt\n');
+    let statePath = beginLegacySyncState({
+      codexHome,
+      backupDir: path.join(codexHome, 'backups', 'ecc-first'),
+    });
+    recordLegacySyncPath({ statePath, filePath: promptPath });
+    fs.writeFileSync(promptPath, '# ECC v1\n');
+    finalizeLegacySyncState({ statePath });
+    const priorInstalledState = fs.readFileSync(statePath, 'utf8');
+
+    statePath = beginLegacySyncState({
+      codexHome,
+      backupDir: path.join(codexHome, 'backups', 'ecc-second'),
+    });
+    fs.writeFileSync(promptPath, '# Partial ECC v2\n');
+    const rollback = rollbackLegacyCodexSync({ statePath });
+    assert.strictEqual(rollback.status, 'rolled-back');
+    assert.strictEqual(fs.readFileSync(promptPath, 'utf8'), '# ECC v1\n');
+    assert.strictEqual(fs.readFileSync(statePath, 'utf8'), priorInstalledState);
+
+    const uninstall = uninstallLegacyCodexSync({ codexHome });
+    assert.strictEqual(uninstall.status, 'uninstalled');
+    assert.strictEqual(fs.readFileSync(promptPath, 'utf8'), '# Original user prompt\n');
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  })) passed += 1; else failed += 1;
+
+  console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+runTests();
diff --git a/tests/lib/harness-capabilities.test.js b/tests/lib/harness-capabilities.test.js
index 8c24e0450..bbf14b280 100644
--- a/tests/lib/harness-capabilities.test.js
+++ b/tests/lib/harness-capabilities.test.js
@@ -88,7 +88,7 @@ function runTests() {
   if (test('keeps every advanced target attached to its registered root and scope', () => {
     const expected = {
       cursor: ['project', './.cursor'],
-      antigravity: ['project', './.agent'],
+      antigravity: ['project', './.agents'],
       gemini: ['project', './.gemini'],
       opencode: ['home', '~/.opencode'],
       codebuddy: ['project', './.codebuddy'],
@@ -103,6 +103,7 @@ function runTests() {
       const harness = getHarnessCapability(id);
       assert.strictEqual(harness.guidedReady, false, id);
       assert.strictEqual(harness.availability, 'advanced', id);
+      assert.strictEqual(harness.destination, root, id);
       assert.deepStrictEqual(harness.scopes, [
         { id: scopeId, targetId: id, root },
       ], id);
diff --git a/tests/lib/install-executor.test.js b/tests/lib/install-executor.test.js
index a348063af..9e58b4182 100644
--- a/tests/lib/install-executor.test.js
+++ b/tests/lib/install-executor.test.js
@@ -54,6 +54,10 @@ function writeLegacySourceFixture(root) {
   writeFile(root, path.join('rules', 'common', 'nested', 'shared.md'), '# Shared\n');
   writeFile(root, path.join('rules', 'common', 'node_modules', 'ignored.md'), '# Ignored\n');
   writeFile(root, path.join('rules', 'common', '.git', 'ignored.md'), '# Ignored\n');
+  writeFile(root, path.join('rules', 'common', '__pycache__', 'ignored.cpython-314.pyc'), 'ignored\n');
+  writeFile(root, path.join('rules', 'common', 'stray.pyc'), 'ignored\n');
+  writeFile(root, path.join('rules', 'common', 'stray.pyo'), 'ignored\n');
+  writeFile(root, path.join('rules', 'common', 'stray.pyd'), 'ignored\n');
   writeFile(root, path.join('rules', 'typescript', 'testing.md'), '# TS\n');
   writeFile(root, path.join('rules', 'python', 'testing.md'), '# Python\n');
 
@@ -111,6 +115,10 @@ function writeManifestSourceFixture(root) {
   writeFile(root, path.join('src', 'nested', 'feature.js'), 'console.log("feature");\n');
   writeFile(root, path.join('src', 'node_modules', 'ignored.js'), 'console.log("ignored");\n');
   writeFile(root, path.join('src', '.git', 'ignored.js'), 'console.log("ignored");\n');
+  writeFile(root, path.join('src', '__pycache__', 'ignored.cpython-314.pyc'), 'ignored\n');
+  writeFile(root, path.join('src', 'stray.pyc'), 'ignored\n');
+  writeFile(root, path.join('src', 'stray.pyo'), 'ignored\n');
+  writeFile(root, path.join('src', 'stray.pyd'), 'ignored\n');
   writeFile(root, path.join('src', 'nested', 'ecc-install-state.json'), '{}\n');
   writeFile(root, path.join('rules', 'common', 'coding-style.md'), '# Common\n');
   writeFile(root, path.join('skills', 'demo', 'SKILL.md'), '# Demo\n');
@@ -192,6 +200,8 @@ function runTests() {
       assert.ok(operationFor(plan, path.join('custom-rules', 'typescript', 'testing.md')));
       assert.ok(!plan.operations.some(operation => operation.sourceRelativePath.includes('node_modules')));
       assert.ok(!plan.operations.some(operation => operation.sourceRelativePath.includes('.git')));
+      assert.ok(!plan.operations.some(operation => operation.sourceRelativePath.includes('__pycache__')));
+      assert.ok(!plan.operations.some(operation => /\.(?:pyc|pyo|pyd)$/.test(operation.sourceRelativePath)));
       assert.deepStrictEqual(plan.statePreview.request.legacyLanguages, ['typescript', 'missing-lang', '../bad']);
       assert.strictEqual(plan.statePreview.request.legacyMode, true);
       assert.strictEqual(plan.statePreview.source.repoVersion, '9.8.7');
@@ -297,7 +307,7 @@ function runTests() {
     const homeDir = createTempDir('install-executor-home-');
     try {
       writeLegacySourceFixture(sourceRoot);
-      writeFile(projectRoot, path.join('.agent', 'rules', 'existing.md'), '# Existing\n');
+      writeFile(projectRoot, path.join('.agents', 'rules', 'existing.md'), '# Existing\n');
 
       const plan = createLegacyInstallPlan({
         sourceRoot,
@@ -307,15 +317,21 @@ function runTests() {
         languages: ['typescript', 'missing-lang', 'bad/name'],
       });
 
-      assert.strictEqual(plan.installRoot, path.join(projectRoot, '.agent'));
+      assert.strictEqual(plan.installRoot, path.join(projectRoot, '.agents'));
       assert.ok(plan.warnings.some(warning => warning.includes('files may be overwritten')));
       assert.ok(plan.warnings.some(warning => warning.includes("rules/missing-lang/ does not exist")));
       assert.ok(plan.warnings.some(warning => warning.includes("Invalid language name 'bad/name'")));
-      assert.ok(operationFor(plan, path.join('.agent', 'rules', 'common-coding-style.md')));
-      assert.ok(operationFor(plan, path.join('.agent', 'rules', 'typescript-testing.md')));
-      assert.ok(operationFor(plan, path.join('.agent', 'workflows', 'plan.md')));
-      assert.ok(operationFor(plan, path.join('.agent', 'skills', 'architect.md')));
-      assert.ok(operationFor(plan, path.join('.agent', 'skills', 'demo', 'SKILL.md')));
+      assert.ok(operationFor(plan, path.join('.agents', 'rules', 'common-coding-style.md')));
+      assert.ok(operationFor(plan, path.join('.agents', 'rules', 'typescript-testing.md')));
+      assert.ok(operationFor(plan, path.join('.agents', 'workflows', 'plan.md')));
+      const agentOperation = plan.operations.find(operation => (
+        operation.destinationPath.endsWith(path.join('.agents', 'agents', 'architect.md'))
+      ));
+      assert.ok(agentOperation);
+      assert.strictEqual(agentOperation.contentTransform, 'antigravity-agent-frontmatter');
+      assert.ok(plan.operations.some(operation => (
+        operation.destinationPath.endsWith(path.join('.agents', 'skills', 'demo', 'SKILL.md'))
+      )));
       assert.strictEqual(plan.statePreview.target.id, 'antigravity-project');
     } finally {
       cleanup(sourceRoot);
@@ -354,6 +370,8 @@ function runTests() {
       assert.ok(!normalizedSources.includes('src/nested/ecc-install-state.json'));
       assert.ok(!normalizedSources.some(source => source.includes('node_modules')));
       assert.ok(!normalizedSources.some(source => source.includes('.git')));
+      assert.ok(!normalizedSources.some(source => source.includes('__pycache__')));
+      assert.ok(!normalizedSources.some(source => /\.(?:pyc|pyo|pyd)$/.test(source)));
       assert.ok(plan.operations.some(operation => (
         operation.sourceRelativePath === path.join('.claude-plugin', 'plugin.json')
         && operation.destinationPath === path.join(homeDir, '.claude', 'plugin.json')
diff --git a/tests/lib/install-lifecycle.test.js b/tests/lib/install-lifecycle.test.js
index e8f1511d1..80423c155 100644
--- a/tests/lib/install-lifecycle.test.js
+++ b/tests/lib/install-lifecycle.test.js
@@ -3,6 +3,7 @@
  */
 
 const assert = require('assert');
+const crypto = require('crypto');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
@@ -14,6 +15,7 @@ const {
   repairInstalledStates,
   uninstallInstalledStates,
 } = require('../../scripts/lib/install-lifecycle');
+const { applyInstallPlan } = require('../../scripts/lib/install/apply');
 const { getInstallTargetAdapter } = require('../../scripts/lib/install-targets/registry');
 const {
   createInstallState,
@@ -635,6 +637,59 @@ function runTests() {
     }
   })) passed++; else failed++;
 
+  if (test('no-op repair preserves recorded source metadata until upgraded bytes are installed', () => {
+    const homeDir = createTempDir('install-lifecycle-home-');
+    const projectRoot = createTempDir('install-lifecycle-project-');
+
+    try {
+      const targetRoot = path.join(projectRoot, '.cursor');
+      const destinationPath = path.join(targetRoot, 'rules', 'coding-style.md');
+      const sourcePath = path.join(REPO_ROOT, 'rules', 'common', 'coding-style.md');
+      fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+      fs.copyFileSync(sourcePath, destinationPath);
+      const contentSha256 = crypto.createHash('sha256')
+        .update(fs.readFileSync(destinationPath))
+        .digest('hex');
+      const fixture = writeCursorState(projectRoot, {
+        source: {
+          repoVersion: '1.0.0',
+          repoCommit: 'old-commit',
+          manifestVersion: CURRENT_MANIFEST_VERSION,
+        },
+        operations: [
+          managedOperation('copy-file', destinationPath, {
+            sourceRelativePath: 'rules/common/coding-style.md',
+            strategy: 'copy-file',
+            contentSha256,
+          }),
+        ],
+      });
+
+      const repair = repairInstalledStates({
+        repoRoot: REPO_ROOT,
+        homeDir,
+        projectRoot,
+        targets: ['cursor'],
+      });
+      const stateAfterRepair = readInstallState(fixture.installStatePath);
+      const doctor = buildDoctorReport({
+        repoRoot: REPO_ROOT,
+        homeDir,
+        projectRoot,
+        targets: ['cursor'],
+      });
+
+      assert.strictEqual(repair.results[0].status, 'ok');
+      assert.strictEqual(repair.results[0].stateRefreshed, true);
+      assert.strictEqual(stateAfterRepair.source.repoVersion, '1.0.0');
+      assert.strictEqual(stateAfterRepair.source.manifestVersion, CURRENT_MANIFEST_VERSION);
+      assert.ok(doctor.results[0].issues.some(issue => issue.code === 'repo-version-mismatch'));
+    } finally {
+      cleanup(homeDir);
+      cleanup(projectRoot);
+    }
+  })) passed++; else failed++;
+
   if (test('Claude repair and dry-run preserve user-owned flat skills during legacy migration', () => {
     const homeDir = createTempDir('install-lifecycle-home-');
     const projectRoot = createTempDir('install-lifecycle-project-');
@@ -1460,6 +1515,140 @@ function runTests() {
     }
   })) passed++; else failed++;
 
+  if (test('doctor reproduces install-time link rewrites for managed copy files', () => {
+    const homeDir = createTempDir('install-lifecycle-home-');
+    const projectRoot = createTempDir('install-lifecycle-project-');
+
+    try {
+      const targetRoot = path.join(projectRoot, '.agents');
+      const statePath = path.join(targetRoot, 'ecc-install-state.json');
+      const operations = ['code-review.md', 'testing.md'].map(fileName => ({
+        kind: 'copy-file',
+        moduleId: 'rules-core',
+        sourcePath: path.join(REPO_ROOT, 'rules', 'common', fileName),
+        sourceRelativePath: path.join('rules', 'common', fileName),
+        destinationPath: path.join(targetRoot, 'rules', `common-${fileName}`),
+        strategy: 'flatten-copy',
+        ownership: 'managed',
+        scaffoldOnly: false,
+      }));
+      const state = createInstallState({
+        adapter: { id: 'antigravity-project', target: 'antigravity', kind: 'project' },
+        targetRoot,
+        installStatePath: statePath,
+        request: {
+          profile: null,
+          modules: [],
+          legacyLanguages: ['typescript'],
+          legacyMode: true,
+        },
+        resolution: {
+          selectedModules: ['rules-core'],
+          skippedModules: [],
+        },
+        operations,
+        source: {
+          repoVersion: CURRENT_PACKAGE_VERSION,
+          repoCommit: 'abc123',
+          manifestVersion: CURRENT_MANIFEST_VERSION,
+        },
+      });
+      applyInstallPlan({
+        mode: 'legacy',
+        target: 'antigravity',
+        adapter: { id: 'antigravity-project', target: 'antigravity', kind: 'project' },
+        targetRoot,
+        installRoot: targetRoot,
+        installStatePath: statePath,
+        operations,
+        warnings: [],
+        statePreview: state,
+      });
+
+      const report = buildDoctorReport({
+        repoRoot: REPO_ROOT,
+        homeDir,
+        projectRoot,
+        targets: ['antigravity'],
+      });
+      assert.ok(!report.results[0].issues.some(issue => issue.code === 'drifted-managed-files'));
+
+      fs.writeFileSync(operations[0].destinationPath, 'customer edit\n');
+      const driftedReport = buildDoctorReport({
+        repoRoot: REPO_ROOT,
+        homeDir,
+        projectRoot,
+        targets: ['antigravity'],
+      });
+      assert.ok(driftedReport.results[0].issues.some(issue => issue.code === 'drifted-managed-files'));
+
+      const repair = repairInstalledStates({
+        repoRoot: REPO_ROOT,
+        homeDir,
+        projectRoot,
+        targets: ['antigravity'],
+      });
+      assert.strictEqual(repair.results[0].status, 'repaired');
+      assert.ok(
+        fs.readFileSync(operations[0].destinationPath, 'utf8').includes('(common-testing.md)')
+      );
+      const repairedState = readInstallState(statePath);
+      assert.match(repairedState.operations[0].contentSha256, /^[a-f0-9]{64}$/);
+      const repairedReport = buildDoctorReport({
+        repoRoot: REPO_ROOT,
+        homeDir,
+        projectRoot,
+        targets: ['antigravity'],
+      });
+      assert.ok(!repairedReport.results[0].issues.some(issue => issue.code === 'drifted-managed-files'));
+    } finally {
+      cleanup(homeDir);
+      cleanup(projectRoot);
+    }
+  })) passed++; else failed++;
+
+  if (test('doctor trusts a recorded installed digest before comparing a newer source tree', () => {
+    const homeDir = createTempDir('install-lifecycle-home-');
+    const projectRoot = createTempDir('install-lifecycle-project-');
+
+    try {
+      const targetRoot = path.join(projectRoot, '.cursor');
+      const destinationPath = path.join(targetRoot, 'rules', 'coding-style.md');
+      const installedContent = 'installed from an older verified release\n';
+      fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+      fs.writeFileSync(destinationPath, installedContent);
+      const contentSha256 = crypto.createHash('sha256').update(installedContent).digest('hex');
+      const installStatePath = path.join(targetRoot, 'ecc-install-state.json');
+
+      writeState(installStatePath, createCursorStateOptions(projectRoot, {
+        operations: [managedOperation('copy-file', destinationPath, {
+          sourceRelativePath: path.join('rules', 'common', 'coding-style.md'),
+          contentSha256,
+        })],
+      }));
+
+      const report = buildDoctorReport({
+        repoRoot: REPO_ROOT,
+        homeDir,
+        projectRoot,
+        targets: ['cursor'],
+      });
+      assert.ok(!report.results[0].issues.some(issue => issue.code === 'drifted-managed-files'));
+
+      fs.writeFileSync(destinationPath, 'customer edit\n');
+      const drifted = buildDoctorReport({
+        repoRoot: REPO_ROOT,
+        homeDir,
+        projectRoot,
+        targets: ['cursor'],
+      });
+      assert.ok(drifted.results[0].issues.some(issue => issue.code === 'drifted-managed-files'));
+    } finally {
+      cleanup(homeDir);
+      cleanup(projectRoot);
+    }
+  })) passed++; else failed++;
+
   if (test('doctor reports manifest resolution drift for non-legacy installs', () => {
     const homeDir = createTempDir('install-lifecycle-home-');
     const projectRoot = createTempDir('install-lifecycle-project-');
diff --git a/tests/lib/install-manifests.test.js b/tests/lib/install-manifests.test.js
index 481f0d092..f2d9574d2 100644
--- a/tests/lib/install-manifests.test.js
+++ b/tests/lib/install-manifests.test.js
@@ -265,7 +265,7 @@ function runTests() {
     assert.ok(!plan.skippedModuleIds.includes('platform-configs'));
     assert.ok(!plan.skippedModuleIds.includes('workflow-quality'));
     assert.strictEqual(plan.targetAdapterId, 'antigravity-project');
-    assert.strictEqual(plan.targetRoot, path.join(projectRoot, '.agent'));
+    assert.strictEqual(plan.targetRoot, path.join(projectRoot, '.agents'));
   })) passed++; else failed++;
 
   if (test('resolves minimal profile without the hook runtime', () => {
@@ -529,10 +529,14 @@ function runTests() {
   if (test('keeps antigravity legacy compatibility selections target-safe', () => {
     const selection = resolveLegacyCompatibilitySelection({
       target: 'antigravity',
-      legacyLanguages: ['typescript'],
+      legacyLanguages: ['c', 'go', 'kotlin'],
     });
 
-    assert.deepStrictEqual(selection.moduleIds, ['rules-core', 'agents-core', 'commands-core']);
+    assert.deepStrictEqual(selection.ruleLanguages, ['cpp', 'golang', 'kotlin']);
+    assert.deepStrictEqual(
+      selection.moduleIds,
+      ['rules-core', 'agents-core', 'commands-core', 'skill-unified-memory', 'workflow-quality']
+    );
   })) passed++; else failed++;
 
   if (test('rejects unknown legacy compatibility languages', () => {
@@ -875,8 +879,11 @@ function runTests() {
         'Unsupported antigravity paths should be filtered from planned operations'
       );
       assert.ok(
-        plan.operations.every(operation => operation.sourceRelativePath !== 'skills/example'),
-        'ECC skills should be filtered: antigravity .agent/skills holds ECC agents'
+        plan.operations.some(operation => (
+          operation.sourceRelativePath === 'skills/example'
+          && operation.destinationPath === path.join('/workspace/app', '.agents', 'skills', 'example')
+        )),
+        'Canonical skill sources should be installed into native Antigravity skills'
       );
       assert.ok(
         plan.operations.some(operation => operation.sourceRelativePath === 'commands/example'),
diff --git a/tests/lib/install-state-projection.test.js b/tests/lib/install-state-projection.test.js
new file mode 100644
index 000000000..9977fcc16
--- /dev/null
+++ b/tests/lib/install-state-projection.test.js
@@ -0,0 +1,347 @@
+/**
+ * Regression tests for projecting canonical JSON install state into the
+ * SQLite status store (#2750).
+ */
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const crypto = require('crypto');
+
+const {
+  buildInstallStateStoreRecord,
+  createStateStore,
+  reconcileInstallStateProjections,
+} = require('../../scripts/lib/state-store');
+const {
+  projectCanonicalInstallState,
+  reconcileCanonicalInstallStates,
+} = require('../../scripts/lib/install-state-store-sync');
+const { createInstallState, writeInstallState } = require('../../scripts/lib/install-state');
+
+const STATUS_SCRIPT = path.join(__dirname, '..', '..', 'scripts', 'status.js');
+
+async function test(name, fn) {
+  try {
+    await fn();
+    console.log(`  \u2713 ${name}`);
+    return true;
+  } catch (error) {
+    console.log(`  \u2717 ${name}`);
+    console.log(`    Error: ${error.stack || error.message}`);
+    return false;
+  }
+}
+
+function createTempDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-install-projection-'));
+}
+
+function createState(options = {}) {
+  const targetRoot = options.targetRoot;
+  const installStatePath = options.installStatePath || path.join(targetRoot, 'ecc-install-state.json');
+  return createInstallState({
+    adapter: {
+      id: options.targetId || 'claude-home',
+      target: options.target || 'claude',
+      kind: options.kind || 'home',
+    },
+    targetRoot,
+    installStatePath,
+    request: {
+      profile: 'developer',
+      modules: ['rules-core'],
+      includeComponents: [],
+      excludeComponents: [],
+      legacyLanguages: [],
+      legacyMode: false,
+    },
+    resolution: {
+      selectedModules: ['rules-core'],
+      skippedModules: [],
+    },
+    operations: Array.isArray(options.operations) ? options.operations : [],
+    source: {
+      repoVersion: '2.2.0',
+      repoCommit: 'abc123',
+      manifestVersion: 1,
+    },
+    installedAt: '2026-08-13T12:00:00.000Z',
+  });
+}
+
+function discoveryRecord(state, options = {}) {
+  const targetId = options.targetId || state.target.id;
+  const targetRoot = options.targetRoot || state.target.root;
+  return {
+    adapter: {
+      id: targetId,
+      target: options.target || state.target.target || 'claude',
+      kind: options.kind || state.target.kind || 'home',
+    },
+    targetRoot,
+    installStatePath: options.installStatePath || state.target.installStatePath,
+    exists: options.exists !== undefined ? options.exists : true,
+    state: options.state !== undefined ? options.state : state,
+    error: options.error || null,
+    legacy: false,
+  };
+}
+
+async function runTests() {
+  console.log('\n=== Testing install-state projection ===\n');
+  let passed = 0;
+  let failed = 0;
+
+  if (await test('maps canonical install state to the status-store projection', () => {
+    const state = createState({ targetRoot: '/tmp/home/.claude' });
+    assert.deepStrictEqual(buildInstallStateStoreRecord(state), {
+      targetId: 'claude-home',
+      targetRoot: '/tmp/home/.claude',
+      profile: 'developer',
+      modules: ['rules-core'],
+      operations: [],
+      installedAt: '2026-08-13T12:00:00.000Z',
+      sourceVersion: '2.2.0',
+    });
+  })) passed += 1; else failed += 1;
+
+  if (await test('reconciles present and absent discoverable targets without deleting other scopes', async () => {
+    const store = await createStateStore({ dbPath: ':memory:' });
+    try {
+      const currentRoot = '/tmp/current/.claude';
+      const absentRoot = '/tmp/current/.codex';
+      const otherRoot = '/tmp/other/.claude';
+      store.upsertInstallState({
+        targetId: 'codex-home',
+        targetRoot: absentRoot,
+        installedAt: '2026-08-01T00:00:00.000Z',
+        sourceVersion: '2.1.0',
+      });
+      store.upsertInstallState({
+        targetId: 'claude-home',
+        targetRoot: otherRoot,
+        installedAt: '2026-08-01T00:00:00.000Z',
+        sourceVersion: '2.1.0',
+      });
+
+      const state = createState({ targetRoot: currentRoot });
+      const result = reconcileInstallStateProjections(store, [
+        discoveryRecord(state),
+        {
+          adapter: { id: 'codex-home', target: 'codex', kind: 'home' },
+          targetRoot: absentRoot,
+          installStatePath: path.join(absentRoot, 'ecc-install-state.json'),
+          exists: false,
+          state: null,
+          error: null,
+          legacy: false,
+        },
+      ]);
+      const installations = store.getStatus().installHealth.installations;
+
+      assert.strictEqual(result.status, 'ok');
+      assert.strictEqual(result.projectedCount, 1);
+      assert.strictEqual(result.removedCount, 1);
+      assert.deepStrictEqual(
+        installations.map(row => [row.targetId, row.targetRoot]).sort(),
+        [
+          ['claude-home', currentRoot],
+          ['claude-home', otherRoot],
+        ].sort()
+      );
+    } finally {
+      store.close();
+    }
+  })) passed += 1; else failed += 1;
+
+  if (await test('removes only the discoverable stale row when canonical state is invalid', async () => {
+    const store = await createStateStore({ dbPath: ':memory:' });
+    try {
+      const targetRoot = '/tmp/current/.claude';
+      store.upsertInstallState({
+        targetId: 'claude-home',
+        targetRoot,
+        installedAt: '2026-08-01T00:00:00.000Z',
+        sourceVersion: '2.1.0',
+      });
+
+      const state = createState({ targetRoot });
+      const result = reconcileInstallStateProjections(store, [
+        discoveryRecord(state, {
+          state: null,
+          error: 'Invalid install-state',
+        }),
+      ]);
+
+      assert.strictEqual(result.status, 'warning');
+      assert.strictEqual(result.removedCount, 1);
+      assert.strictEqual(result.warningCount, 1);
+      assert.strictEqual(result.warnings[0].code, 'invalid-install-state');
+      assert.strictEqual(store.getStatus().installHealth.totalCount, 0);
+    } finally {
+      store.close();
+    }
+  })) passed += 1; else failed += 1;
+
+  if (await test('returns projection failures as warnings and continues reconciling', () => {
+    const first = createState({ targetRoot: '/tmp/one/.claude' });
+    const second = createState({ targetRoot: '/tmp/two/.claude' });
+    const projected = [];
+    const store = {
+      upsertInstallState(record) {
+        if (record.targetRoot.includes('/one/')) {
+          throw new Error('database is read-only');
+        }
+        projected.push(record.targetRoot);
+      },
+      deleteInstallState() {
+        return false;
+      },
+    };
+
+    const result = reconcileInstallStateProjections(store, [
+      discoveryRecord(first),
+      discoveryRecord(second),
+    ]);
+
+    assert.strictEqual(result.status, 'warning');
+    assert.strictEqual(result.projectedCount, 1);
+    assert.strictEqual(result.warningCount, 1);
+    assert.strictEqual(result.warnings[0].code, 'projection-write-failed');
+    assert.deepStrictEqual(projected, ['/tmp/two/.claude']);
+  })) passed += 1; else failed += 1;
+
+  if (await test('status discovers canonical JSON state before querying install health', async () => {
+    const tempDir = createTempDir();
+    const homeDir = path.join(tempDir, 'home');
+    const projectDir = path.join(tempDir, 'project');
+    const targetRoot = path.join(homeDir, '.claude');
+    const installStatePath = path.join(targetRoot, 'ecc', 'install-state.json');
+    const dbPath = path.join(tempDir, 'state.db');
+    fs.mkdirSync(projectDir, { recursive: true });
+    writeInstallState(installStatePath, createState({ targetRoot, installStatePath }));
+
+    try {
+      const result = spawnSync(process.execPath, [STATUS_SCRIPT, '--db', dbPath, '--json'], {
+        cwd: projectDir,
+        encoding: 'utf8',
+        env: { ...process.env, HOME: homeDir },
+      });
+      assert.strictEqual(result.status, 0, result.stderr);
+      const payload = JSON.parse(result.stdout);
+      assert.strictEqual(payload.installHealth.status, 'healthy');
+      assert.strictEqual(payload.installHealth.totalCount, 1);
+      assert.strictEqual(payload.installHealth.installations[0].targetRoot, targetRoot);
+      assert.strictEqual(payload.installStateProjection.status, 'ok');
+      assert.strictEqual(payload.installStateProjection.projectedCount, 1);
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  })) passed += 1; else failed += 1;
+
+  if (await test('status reports warning health when a canonical managed file is drifted or missing', async () => {
+    const tempDir = createTempDir();
+    const homeDir = path.join(tempDir, 'home');
+    const projectDir = path.join(tempDir, 'project');
+    const targetRoot = path.join(homeDir, '.claude');
+    const installStatePath = path.join(targetRoot, 'ecc', 'install-state.json');
+    const destinationPath = path.join(targetRoot, 'managed-package.json');
+    const sourcePath = path.join(__dirname, '..', '..', 'package.json');
+    const sourceRelativePath = 'package.json';
+    const dbPath = path.join(tempDir, 'state.db');
+    const contentSha256 = crypto.createHash('sha256').update(fs.readFileSync(sourcePath)).digest('hex');
+    fs.mkdirSync(projectDir, { recursive: true });
+    fs.mkdirSync(targetRoot, { recursive: true });
+    fs.writeFileSync(destinationPath, 'drifted content');
+    writeInstallState(installStatePath, createState({
+      targetRoot,
+      installStatePath,
+      operations: [{
+        kind: 'copy-file',
+        moduleId: 'rules-core',
+        sourceRelativePath,
+        destinationPath,
+        strategy: 'preserve-relative-path',
+        ownership: 'managed',
+        scaffoldOnly: false,
+        contentSha256,
+      }],
+    }));
+
+    try {
+      const result = spawnSync(process.execPath, [STATUS_SCRIPT, '--db', dbPath, '--json'], {
+        cwd: projectDir,
+        encoding: 'utf8',
+        env: { ...process.env, HOME: homeDir },
+      });
+      assert.strictEqual(result.status, 0, result.stderr);
+      const payload = JSON.parse(result.stdout);
+      assert.strictEqual(payload.installHealth.status, 'warning');
+      assert.strictEqual(payload.installHealth.healthyCount, 0);
+      assert.strictEqual(payload.installHealth.warningCount, 1);
+      assert.strictEqual(payload.installHealth.installations[0].status, 'warning');
+      assert.ok(payload.installHealth.installations[0].issues.some(
+        issue => issue.code === 'drifted-managed-files'
+      ));
+      assert.strictEqual(payload.readiness.status, 'attention');
+
+      fs.unlinkSync(destinationPath);
+      const missingResult = spawnSync(process.execPath, [STATUS_SCRIPT, '--db', dbPath, '--json'], {
+        cwd: projectDir,
+        encoding: 'utf8',
+        env: { ...process.env, HOME: homeDir },
+      });
+      assert.strictEqual(missingResult.status, 0, missingResult.stderr);
+      const missingPayload = JSON.parse(missingResult.stdout);
+      assert.strictEqual(missingPayload.installHealth.status, 'warning');
+      assert.ok(missingPayload.installHealth.installations[0].issues.some(
+        issue => issue.code === 'missing-managed-files'
+      ));
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  })) passed += 1; else failed += 1;
+
+  if (await test('command-boundary sync projects and removes canonical install state', async () => {
+    const tempDir = createTempDir();
+    const homeDir = path.join(tempDir, 'home');
+    const projectDir = path.join(tempDir, 'project');
+    const dbPath = path.join(tempDir, 'state.db');
+    const targetRoot = path.join(homeDir, '.claude');
+    const installStatePath = path.join(targetRoot, 'ecc', 'install-state.json');
+    fs.mkdirSync(projectDir, { recursive: true });
+    const state = createState({ targetRoot, installStatePath });
+
+    try {
+      const projected = await projectCanonicalInstallState(state, { dbPath, homeDir });
+      assert.strictEqual(projected.status, 'projected');
+
+      const store = await createStateStore({ dbPath });
+      assert.strictEqual(store.getStatus().installHealth.totalCount, 1);
+      store.close();
+
+      const reconciled = await reconcileCanonicalInstallStates({ dbPath, homeDir, projectRoot: projectDir });
+      assert.strictEqual(reconciled.status, 'ok');
+      assert.strictEqual(reconciled.removedCount, 1);
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  })) passed += 1; else failed += 1;
+
+  if (await test('command-boundary sync isolates database failures as warnings', async () => {
+    const state = createState({ targetRoot: '/tmp/home/.claude' });
+    const result = await projectCanonicalInstallState(state, {
+      createStore: async () => { throw new Error('database unavailable'); },
+    });
+    assert.strictEqual(result.status, 'warning');
+    assert.strictEqual(result.warning.code, 'projection-open-failed');
+  })) passed += 1; else failed += 1;
+
+  console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+runTests();
diff --git a/tests/lib/install-targets.test.js b/tests/lib/install-targets.test.js
index 2be3b4b74..0a1ddc805 100644
--- a/tests/lib/install-targets.test.js
+++ b/tests/lib/install-targets.test.js
@@ -479,7 +479,7 @@ function runTests() {
     );
   })) passed++; else failed++;
 
-  if (test('plans antigravity remaps for workflows, skills, and flat rules', () => {
+  if (test('plans native Antigravity 2.0 rules, workflows, skills, and agents', () => {
     const repoRoot = path.join(__dirname, '..', '..');
     const projectRoot = '/workspace/app';
 
@@ -494,7 +494,11 @@ function runTests() {
         },
         {
           id: 'agents-core',
-          paths: ['agents'],
+          paths: ['.agents', 'agents', 'AGENTS.md'],
+        },
+        {
+          id: 'workflow-quality',
+          paths: ['skills/tdd-workflow'],
         },
         {
           id: 'rules-core',
@@ -506,24 +510,35 @@ function runTests() {
     assert.ok(
       plan.operations.some(operation => (
         operation.sourceRelativePath === 'commands'
-        && operation.destinationPath === path.join(projectRoot, '.agent', 'workflows')
+        && operation.destinationPath === path.join(projectRoot, '.agents', 'workflows')
       )),
       'Should remap commands into workflows'
     );
     assert.ok(
       plan.operations.some(operation => (
         operation.sourceRelativePath === 'agents'
-        && operation.destinationPath === path.join(projectRoot, '.agent', 'skills')
+        && operation.destinationPath === path.join(projectRoot, '.agents', 'agents')
       )),
-      'Should remap agents into skills'
+      'Should remap agents into native agents'
+    );
+    assert.ok(
+      plan.operations.some(operation => (
+        operation.sourceRelativePath === 'skills/tdd-workflow'
+        && operation.destinationPath === path.join(projectRoot, '.agents', 'skills', 'tdd-workflow')
+      )),
+      'Should remap canonical skills into native skills'
     );
     assert.ok(
       plan.operations.some(operation => (
         normalizedRelativePath(operation.sourceRelativePath) === 'rules/common/coding-style.md'
-        && operation.destinationPath === path.join(projectRoot, '.agent', 'rules', 'common-coding-style.md')
+        && operation.destinationPath === path.join(projectRoot, '.agents', 'rules', 'common-coding-style.md')
       )),
       'Should flatten common rules for antigravity'
     );
+    assert.ok(
+      plan.operations.every(operation => !['.agents', 'AGENTS.md'].includes(operation.sourceRelativePath)),
+      'Should exclude Codex-only .agents metadata and root AGENTS.md'
+    );
   })) passed++; else failed++;
 
   if (test('exposes validate and planOperations on adapters', () => {
diff --git a/tests/lib/state-store.test.js b/tests/lib/state-store.test.js
index 57b9ef3e6..b632cec7f 100644
--- a/tests/lib/state-store.test.js
+++ b/tests/lib/state-store.test.js
@@ -359,6 +359,68 @@ async function runTests() {
     }
   })) passed += 1; else failed += 1;
 
+  if (await test('creates private state-store directories and atomically persists a private database file', async () => {
+    const testDir = createTempDir('ecc-state-private-');
+    const privateParent = path.join(testDir, 'new-parent', 'ecc');
+    const dbPath = path.join(privateParent, 'state.db');
+
+    try {
+      const store = await createStateStore({ dbPath });
+      store.close();
+
+      if (process.platform !== 'win32') {
+        assert.strictEqual(fs.statSync(path.join(testDir, 'new-parent')).mode & 0o777, 0o700);
+        assert.strictEqual(fs.statSync(privateParent).mode & 0o777, 0o700);
+        assert.strictEqual(fs.statSync(dbPath).mode & 0o777, 0o600);
+      }
+      assert.deepStrictEqual(
+        fs.readdirSync(privateParent).sort(),
+        ['state.db']
+      );
+    } finally {
+      cleanupTempDir(testDir);
+    }
+  })) passed += 1; else failed += 1;
+
+  if (await test('refuses a final state database symlink without changing its target', async () => {
+    const testDir = createTempDir('ecc-state-final-link-');
+    const targetPath = path.join(testDir, 'outside.db');
+    const dbPath = path.join(testDir, 'state.db');
+
+    try {
+      fs.writeFileSync(targetPath, 'do not overwrite');
+      fs.symlinkSync(targetPath, dbPath);
+
+      await assert.rejects(
+        () => createStateStore({ dbPath }),
+        /symlink/i
+      );
+      assert.strictEqual(fs.readFileSync(targetPath, 'utf8'), 'do not overwrite');
+    } finally {
+      cleanupTempDir(testDir);
+    }
+  })) passed += 1; else failed += 1;
+
+  if (await test('refuses an intermediate state database symlink without writing outside the requested tree', async () => {
+    const testDir = createTempDir('ecc-state-parent-link-');
+    const outsideDir = path.join(testDir, 'outside');
+    const linkedParent = path.join(testDir, 'linked-parent');
+    const dbPath = path.join(linkedParent, 'ecc', 'state.db');
+
+    try {
+      fs.mkdirSync(outsideDir);
+      fs.symlinkSync(outsideDir, linkedParent, process.platform === 'win32' ? 'junction' : 'dir');
+
+      await assert.rejects(
+        () => createStateStore({ dbPath }),
+        /symlink/i
+      );
+      assert.strictEqual(fs.existsSync(path.join(outsideDir, 'ecc', 'state.db')), false);
+    } finally {
+      cleanupTempDir(testDir);
+    }
+  })) passed += 1; else failed += 1;
+
   if (await test('stores sessions and returns detailed session views with workers, skill runs, and decisions', async () => {
     const testDir = createTempDir('ecc-state-db-');
     const dbPath = path.join(testDir, 'state.db');
@@ -658,6 +720,37 @@ async function runTests() {
     }
   })) passed += 1; else failed += 1;
 
+  if (await test('deletes install projections by exact target id and root', async () => {
+    const store = await createStateStore({ dbPath: ':memory:' });
+    try {
+      store.upsertInstallState({
+        targetId: 'claude-home',
+        targetRoot: '/tmp/one/.claude',
+        sourceVersion: '2.2.0',
+      });
+      store.upsertInstallState({
+        targetId: 'claude-home',
+        targetRoot: '/tmp/two/.claude',
+        sourceVersion: '2.2.0',
+      });
+
+      assert.strictEqual(store.deleteInstallState({
+        targetId: 'claude-home',
+        targetRoot: '/tmp/one/.claude',
+      }), true);
+      assert.strictEqual(store.deleteInstallState({
+        targetId: 'claude-home',
+        targetRoot: '/tmp/missing/.claude',
+      }), false);
+      assert.deepStrictEqual(
+        store.getStatus().installHealth.installations.map(row => row.targetRoot),
+        ['/tmp/two/.claude']
+      );
+    } finally {
+      store.close();
+    }
+  })) passed += 1; else failed += 1;
+
   if (await test('rejects invalid limits and unserializable JSON payloads', async () => {
     const testDir = createTempDir('ecc-state-errors-');
     const dbPath = path.join(testDir, 'state.db');
diff --git a/tests/scripts/auto-update.test.js b/tests/scripts/auto-update.test.js
index 6528eadae..6d21a2c08 100644
--- a/tests/scripts/auto-update.test.js
+++ b/tests/scripts/auto-update.test.js
@@ -388,6 +388,120 @@ function runTests() {
     }
   })) passed += 1; else failed += 1;
 
+  if (test('runAutoUpdate excludes residual legacy Antigravity records', () => {
+    const homeDir = createTempDir('auto-update-home-');
+    const projectRoot = createTempDir('auto-update-project-');
+    const repoRoot = createTempDir('auto-update-repo-');
+
+    try {
+      ensureFakeRepo(repoRoot);
+      const canonical = makeRecord({
+        repoRoot,
+        homeDir,
+        projectRoot,
+        adapter: { id: 'antigravity-project', target: 'antigravity', kind: 'project' },
+        request: {
+          profile: null,
+          modules: [],
+          includeComponents: [],
+          excludeComponents: [],
+          legacyLanguages: ['typescript'],
+          legacyMode: true,
+        },
+        resolution: { selectedModules: ['legacy-antigravity-install'], skippedModules: [] },
+        operations: [],
+      });
+      const legacy = {
+        ...canonical,
+        installStatePath: path.join(projectRoot, '.agent', 'ecc-install-state.json'),
+        legacy: true,
+      };
+      const commands = [];
+
+      const result = runAutoUpdate(
+        {
+          homeDir,
+          projectRoot,
+          repoRoot,
+          dryRun: true,
+        },
+        {
+          discoverInstalledStates: () => [canonical, legacy],
+          runExternalCommand(command, args) {
+            commands.push({ command, args });
+            return {
+              stdout: JSON.stringify({ dryRun: true, plan: {} }),
+              stderr: '',
+            };
+          },
+        }
+      );
+
+      assert.strictEqual(result.summary.checkedCount, 1);
+      assert.strictEqual(result.summary.updatedCount, 1);
+      assert.strictEqual(commands.length, 1);
+      assert.strictEqual(commands[0].command, process.execPath);
+    } finally {
+      cleanup(homeDir);
+      cleanup(projectRoot);
+      cleanup(repoRoot);
+    }
+  })) passed += 1; else failed += 1;
+
+  if (test('runAutoUpdate explains a legacy-only Antigravity install', () => {
+    const homeDir = createTempDir('auto-update-home-');
+    const projectRoot = createTempDir('auto-update-project-');
+    const repoRoot = createTempDir('auto-update-repo-');
+
+    try {
+      ensureFakeRepo(repoRoot);
+      const legacy = {
+        ...makeRecord({
+          repoRoot,
+          homeDir,
+          projectRoot,
+          adapter: { id: 'antigravity-project', target: 'antigravity', kind: 'project' },
+          request: {
+            profile: null,
+            modules: [],
+            includeComponents: [],
+            excludeComponents: [],
+            legacyLanguages: ['typescript'],
+            legacyMode: true,
+          },
+          resolution: { selectedModules: ['legacy-antigravity-install'], skippedModules: [] },
+          operations: [],
+        }),
+        installStatePath: path.join(projectRoot, '.agent', 'ecc-install-state.json'),
+        legacy: true,
+      };
+      const commands = [];
+
+      const result = runAutoUpdate(
+        { homeDir, projectRoot, repoRoot, dryRun: true },
+        {
+          discoverInstalledStates: () => [legacy],
+          runExternalCommand(command, args) {
+            commands.push({ command, args });
+          },
+        }
+      );
+
+      assert.deepStrictEqual(result.results, []);
+      assert.strictEqual(result.summary.checkedCount, 0);
+      assert.strictEqual(result.summary.updatedCount, 0);
+      assert.strictEqual(result.summary.errorCount, 0);
+      assert.strictEqual(commands.length, 0);
+      assert.ok(result.warnings.some(warning => warning.includes(
+        'Run the Antigravity installer once to migrate it to .agents'
+      )));
+    } finally {
+      cleanup(homeDir);
+      cleanup(projectRoot);
+      cleanup(repoRoot);
+    }
+  })) passed += 1; else failed += 1;
+
   console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
   process.exit(failed > 0 ? 1 : 0);
 }
diff --git a/tests/scripts/install-apply.test.js b/tests/scripts/install-apply.test.js
index d8b4ec516..e011a572f 100644
--- a/tests/scripts/install-apply.test.js
+++ b/tests/scripts/install-apply.test.js
@@ -7,6 +7,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execFileSync, spawnSync } = require('child_process');
+const yaml = require('js-yaml');
 const { applyInstallPlan } = require('../../scripts/lib/install/apply');
 
 const SCRIPT = path.join(__dirname, '..', '..', 'scripts', 'install-apply.js');
@@ -24,6 +25,13 @@ function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, 'utf8'));
 }
 
+function readMarkdownFrontmatter(filePath) {
+  const source = fs.readFileSync(filePath, 'utf8');
+  const match = source.match(/^---\n([\s\S]*?)\n---\n/);
+  assert.ok(match, `Expected YAML frontmatter in ${filePath}`);
+  return yaml.load(match[1]);
+}
+
 function run(args = [], options = {}) {
   const homeDir = options.homeDir || process.env.HOME;
   const env = {
@@ -279,20 +287,48 @@ function runTests() {
       const result = run(['--target', 'antigravity', 'typescript'], { cwd: projectDir, homeDir });
       assert.strictEqual(result.code, 0, result.stderr);
 
-      assert.ok(fs.existsSync(path.join(projectDir, '.agent', 'rules', 'common-coding-style.md')));
-      assert.ok(fs.existsSync(path.join(projectDir, '.agent', 'rules', 'typescript-testing.md')));
-      assert.ok(fs.existsSync(path.join(projectDir, '.agent', 'workflows', 'plan.md')));
-      assert.ok(fs.existsSync(path.join(projectDir, '.agent', 'skills', 'architect.md')));
+      assert.ok(fs.existsSync(path.join(projectDir, '.agents', 'rules', 'common-coding-style.md')));
+      assert.ok(fs.existsSync(path.join(projectDir, '.agents', 'rules', 'typescript-testing.md')));
+      assert.ok(!fs.existsSync(path.join(projectDir, '.agents', 'rules', 'python-testing.md')));
+      assert.ok(fs.existsSync(path.join(projectDir, '.agents', 'workflows', 'plan.md')));
+      assert.ok(fs.existsSync(path.join(projectDir, '.agents', 'skills', 'tdd-workflow', 'SKILL.md')));
+      assert.ok(fs.existsSync(path.join(projectDir, '.agents', 'agents', 'architect.md')));
+      const tddGuide = readMarkdownFrontmatter(
+        path.join(projectDir, '.agents', 'agents', 'tdd-guide.md')
+      );
+      assert.deepStrictEqual(
+        tddGuide.tools,
+        ['view_file', 'write_to_file', 'replace_file_content', 'run_command', 'grep_search']
+      );
+      assert.strictEqual(tddGuide.model, 'pro');
+      const docsLookup = readMarkdownFrontmatter(
+        path.join(projectDir, '.agents', 'agents', 'docs-lookup.md')
+      );
+      assert.deepStrictEqual(docsLookup.tools, ['view_file', 'grep_search']);
+      const harnessOptimizer = readMarkdownFrontmatter(
+        path.join(projectDir, '.agents', 'agents', 'harness-optimizer.md')
+      );
+      assert.ok(!Object.hasOwn(harnessOptimizer, 'color'), 'Should omit Claude-only color metadata');
 
-      const statePath = path.join(projectDir, '.agent', 'ecc-install-state.json');
+      const statePath = path.join(projectDir, '.agents', 'ecc-install-state.json');
       const state = readJson(statePath);
       assert.strictEqual(state.target.id, 'antigravity-project');
       assert.deepStrictEqual(state.request.legacyLanguages, ['typescript']);
       assert.strictEqual(state.request.legacyMode, true);
-      assert.deepStrictEqual(state.resolution.selectedModules, ['rules-core', 'agents-core', 'commands-core']);
+      assert.deepStrictEqual(
+        state.resolution.selectedModules,
+        [
+          'rules-core',
+          'agents-core',
+          'commands-core',
+          'platform-configs',
+          'skill-unified-memory',
+          'workflow-quality',
+        ]
+      );
       assert.ok(
         state.operations.some(operation => (
-          operation.destinationPath.endsWith(path.join('.agent', 'workflows', 'plan.md'))
+          operation.destinationPath.endsWith(path.join('.agents', 'workflows', 'plan.md'))
         )),
         'Should record manifest command file copy operation'
       );
@@ -302,6 +338,35 @@ function runTests() {
     }
   })) passed++; else failed++;
 
+  if (test('maps legacy language aliases to Antigravity rule namespaces', () => {
+    const homeDir = createTempDir('install-apply-home-');
+    const projectDir = createTempDir('install-apply-project-');
+
+    try {
+      const result = run(
+        ['--target', 'antigravity', 'c', 'go', 'kotlin', 'javascript', 'rails', 'harmonyos'],
+        { cwd: projectDir, homeDir }
+      );
+      assert.strictEqual(result.code, 0, result.stderr);
+
+      const rulesDir = path.join(projectDir, '.agents', 'rules');
+      for (const fileName of [
+        'golang-testing.md',
+        'kotlin-testing.md',
+        'typescript-testing.md',
+        'ruby-testing.md',
+        'arkts-testing.md',
+        'cpp-testing.md',
+      ]) {
+        assert.ok(fs.existsSync(path.join(rulesDir, fileName)), `Expected ${fileName}`);
+      }
+      assert.ok(!fs.existsSync(path.join(rulesDir, 'python-testing.md')));
+    } finally {
+      cleanup(homeDir);
+      cleanup(projectDir);
+    }
+  })) passed++; else failed++;
+
   if (test('installs JoyCode profile through managed install-state', () => {
     const homeDir = createTempDir('install-apply-home-');
     const projectDir = createTempDir('install-apply-project-');
@@ -613,15 +678,16 @@ function runTests() {
       const result = run(['--target', 'antigravity', '--profile', 'core'], { cwd: projectDir, homeDir });
       assert.strictEqual(result.code, 0, result.stderr);
 
-      assert.ok(fs.existsSync(path.join(projectDir, '.agent', 'rules', 'common-coding-style.md')));
-      assert.ok(fs.existsSync(path.join(projectDir, '.agent', 'skills', 'architect.md')));
-      assert.ok(fs.existsSync(path.join(projectDir, '.agent', 'workflows', 'plan.md')));
-      // .agent/skills is where antigravity keeps its agents, and ECC agents are
-      // already mapped there. Installing ECC skills into the same directory made
-      // the two collide, so skills are no longer an antigravity source path.
-      assert.ok(!fs.existsSync(path.join(projectDir, '.agent', 'skills', 'tdd-workflow', 'SKILL.md')));
+      assert.ok(fs.existsSync(path.join(projectDir, '.agents', 'rules', 'common-coding-style.md')));
+      assert.ok(
+        fs.existsSync(path.join(projectDir, '.agents', 'rules', 'python-testing.md')),
+        'Manifest profiles should retain broad rule coverage'
+      );
+      assert.ok(fs.existsSync(path.join(projectDir, '.agents', 'agents', 'architect.md')));
+      assert.ok(fs.existsSync(path.join(projectDir, '.agents', 'workflows', 'plan.md')));
+      assert.ok(fs.existsSync(path.join(projectDir, '.agents', 'skills', 'tdd-workflow', 'SKILL.md')));
 
-      const state = readJson(path.join(projectDir, '.agent', 'ecc-install-state.json'));
+      const state = readJson(path.join(projectDir, '.agents', 'ecc-install-state.json'));
       assert.strictEqual(state.request.profile, 'core');
       assert.strictEqual(state.request.legacyMode, false);
       assert.deepStrictEqual(
diff --git a/tests/scripts/npm-publish-surface.test.js b/tests/scripts/npm-publish-surface.test.js
index 97a30841b..3ca4662cc 100644
--- a/tests/scripts/npm-publish-surface.test.js
+++ b/tests/scripts/npm-publish-surface.test.js
@@ -78,6 +78,10 @@ function buildExpectedPublishPaths(repoRoot) {
     "scripts/welcome.js",
     "scripts/gemini-adapt-agents.js",
     "scripts/sync-ecc-to-codex.sh",
+    "scripts/codex/legacy-sync-state.js",
+    "scripts/codex/install-global-git-hooks.sh",
+    "scripts/codex/check-codex-global-state.sh",
+    "scripts/codex-git-hooks",
     "scripts/codex/check-plugin-cache.js",
     "scripts/codex/merge-codex-config.js",
     "scripts/codex/merge-mcp-config.js",
@@ -166,6 +170,11 @@ function main() {
         "scripts/work-items.js",
         "scripts/platform-audit.js",
         "scripts/sync-ecc-to-codex.sh",
+        "scripts/codex/legacy-sync-state.js",
+        "scripts/codex/install-global-git-hooks.sh",
+        "scripts/codex/check-codex-global-state.sh",
+        "scripts/codex-git-hooks/pre-commit",
+        "scripts/codex-git-hooks/pre-push",
         "scripts/setup.js",
         "scripts/codex/check-plugin-cache.js",
         ".gemini/GEMINI.md",
diff --git a/tests/scripts/release-publish.test.js b/tests/scripts/release-publish.test.js
index 3f5bcdca9..0788b9391 100644
--- a/tests/scripts/release-publish.test.js
+++ b/tests/scripts/release-publish.test.js
@@ -54,7 +54,8 @@ for (const workflow of [
   });
 
   test(`${workflow} publishes new tag versions to npm`, () => {
-    assert.match(content, /npm publish "\$\{\{ needs\.verify\.outputs\.package_file \}\}" --access public --provenance/);
+    assert.match(content, /ECC_RELEASE_PACKAGE:\s*\$\{\{ needs\.verify\.outputs\.package_file \}\}/);
+    assert.match(content, /npm publish "\.\/\$\{ECC_RELEASE_PACKAGE\}" --access public --provenance/);
     assert.match(content, /NODE_AUTH_TOKEN:\s*\$\{\{\s*secrets\.NPM_TOKEN\s*\}\}/);
   });
 
diff --git a/tests/scripts/release.test.js b/tests/scripts/release.test.js
index fe809808a..30567ffaf 100644
--- a/tests/scripts/release.test.js
+++ b/tests/scripts/release.test.js
@@ -161,11 +161,11 @@ function runTests() {
 
   if (test('reusable release checks out the requested tag before validating and publishing', () => {
     const checkoutIndex = reusableReleaseWorkflowSource.indexOf('uses: actions/checkout@');
-    const refIndex = reusableReleaseWorkflowSource.indexOf('ref: ${{ inputs.tag }}');
+    const refIndex = reusableReleaseWorkflowSource.indexOf('ref: refs/tags/${{ inputs.tag }}');
     const validateIndex = reusableReleaseWorkflowSource.indexOf('name: Validate version tag');
 
     assert.ok(checkoutIndex >= 0, 'reusable-release.yml should check out repository content');
-    assert.ok(refIndex >= 0, 'reusable-release.yml checkout should use inputs.tag as ref');
+    assert.ok(refIndex >= 0, 'reusable-release.yml checkout should require inputs.tag to resolve as a tag');
     assert.ok(validateIndex >= 0, 'reusable-release.yml should validate requested tag');
     assert.ok(
       checkoutIndex < refIndex && refIndex < validateIndex,
diff --git a/tests/scripts/sync-ecc-to-codex.test.js b/tests/scripts/sync-ecc-to-codex.test.js
index 61a5b128e..4ef47d6f5 100644
--- a/tests/scripts/sync-ecc-to-codex.test.js
+++ b/tests/scripts/sync-ecc-to-codex.test.js
@@ -104,6 +104,23 @@ function runTests() {
     assert.ok(source.includes('node - "$file"'), 'extract_context7_key should use Node-based parsing');
   })) passed++; else failed++;
 
+  if (test('sync records a versioned ownership manifest before mutating Codex state', () => {
+    const beginIndex = source.indexOf('"$LEGACY_STATE_HELPER" begin');
+    const configMergeIndex = source.indexOf('node "$BASELINE_MERGE_SCRIPT" "$CONFIG_FILE"');
+    const finalizeIndex = source.indexOf('"$LEGACY_STATE_HELPER" finalize');
+    assert.ok(beginIndex > -1, 'legacy manifest begin is missing');
+    assert.ok(configMergeIndex > beginIndex, 'manifest must begin before config mutation');
+    assert.ok(finalizeIndex > configMergeIndex, 'manifest must finalize after managed writes');
+    assert.ok(source.includes('record_managed_path "$out"'), 'generated prompts must be recorded');
+    assert.ok(source.includes('record_managed_path "${ECC_GLOBAL_HOOKS_DIR:-$CODEX_HOME/git-hooks}/pre-commit"'));
+  })) passed++; else failed++;
+
+  if (test('sync inherits its ERR trap so helper failures trigger rollback', () => {
+    assert.match(source, /^set -Eeuo pipefail$/m);
+    assert.ok(source.includes("trap 'rollback_legacy_sync $?' ERR"));
+    assert.ok(source.includes('node "$LEGACY_STATE_HELPER" rollback --state "$LEGACY_STATE_PATH"'));
+  })) passed++; else failed++;
+
   console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
   process.exit(failed > 0 ? 1 : 0);
 }
diff --git a/tests/scripts/uninstall.test.js b/tests/scripts/uninstall.test.js
index e31ae3dbe..f01dc0305 100644
--- a/tests/scripts/uninstall.test.js
+++ b/tests/scripts/uninstall.test.js
@@ -282,6 +282,77 @@ function runTests() {
     }
   })) passed++; else failed++;
 
+  if (test('reports preserved legacy Antigravity files as an incomplete uninstall', () => {
+    const homeDir = createTempDir('uninstall-home-');
+    const projectRoot = createTempDir('uninstall-project-');
+
+    try {
+      const targetRoot = path.join(projectRoot, '.agent');
+      fs.mkdirSync(path.join(targetRoot, 'rules'), { recursive: true });
+      const normalizedTargetRoot = fs.realpathSync(targetRoot);
+      const statePath = path.join(normalizedTargetRoot, 'ecc-install-state.json');
+      const editedPath = path.join(normalizedTargetRoot, 'rules', 'common-coding-style.md');
+      fs.writeFileSync(editedPath, 'customer edit\n');
+
+      writeState(statePath, {
+        adapter: { id: 'antigravity-project', target: 'antigravity', kind: 'project' },
+        targetRoot: normalizedTargetRoot,
+        installStatePath: statePath,
+        request: {
+          profile: null,
+          modules: [],
+          includeComponents: [],
+          excludeComponents: [],
+          legacyLanguages: ['typescript'],
+          legacyMode: true,
+        },
+        resolution: {
+          selectedModules: ['legacy-antigravity-install'],
+          skippedModules: [],
+        },
+        operations: [{
+          kind: 'copy-file',
+          moduleId: 'rules-core',
+          sourceRelativePath: 'rules/common/coding-style.md',
+          destinationPath: editedPath,
+          strategy: 'flatten-copy',
+          ownership: 'managed',
+          scaffoldOnly: false,
+        }],
+        source: {
+          repoVersion: CURRENT_PACKAGE_VERSION,
+          repoCommit: 'abc123',
+          manifestVersion: CURRENT_MANIFEST_VERSION,
+        },
+      });
+
+      const dryRun = run(['--target', 'antigravity', '--dry-run', '--json'], {
+        cwd: projectRoot,
+        homeDir,
+      });
+      assert.strictEqual(dryRun.code, 1);
+      const parsed = JSON.parse(dryRun.stdout);
+      assert.strictEqual(parsed.results[0].status, 'partial');
+      assert.deepStrictEqual(parsed.results[0].plannedRemovals, []);
+      assert.deepStrictEqual(parsed.results[0].retainedPaths, [editedPath]);
+      assert.strictEqual(parsed.summary.partialCount, 1);
+
+      const applied = run(['--target', 'antigravity'], {
+        cwd: projectRoot,
+        homeDir,
+      });
+      assert.strictEqual(applied.code, 1);
+      assert.ok(applied.stdout.includes('Status: PARTIAL'));
+      assert.ok(applied.stdout.includes('Legacy Antigravity files were preserved'));
+      assert.ok(applied.stdout.includes(editedPath));
+      assert.ok(fs.existsSync(editedPath));
+      assert.ok(fs.existsSync(statePath));
+    } finally {
+      cleanup(homeDir);
+      cleanup(projectRoot);
+    }
+  })) passed++; else failed++;
+
   console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
   process.exit(failed > 0 ? 1 : 0);
 }
diff --git a/tests/skills/repo-scan-install.test.js b/tests/skills/repo-scan-install.test.js
new file mode 100644
index 000000000..0d8602ebc
--- /dev/null
+++ b/tests/skills/repo-scan-install.test.js
@@ -0,0 +1,353 @@
+/**
+ * Regression tests for #2774: repo-scan installation must be reproducible.
+ */
+
+'use strict';
+
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const repoRoot = path.resolve(__dirname, '..', '..');
+const skillFiles = [
+  {
+    relativePath: path.join('skills', 'repo-scan', 'SKILL.md'),
+    heading: '## Installation',
+    descriptionTerms: ['bootstrap', 'external', 'install'],
+    reinvocationText: 'Reload your agent harness, then invoke `repo-scan` again',
+  },
+  {
+    relativePath: path.join('docs', 'zh-CN', 'skills', 'repo-scan', 'SKILL.md'),
+    heading: '## 安装',
+    descriptionTerms: ['引导', '外部', '安装'],
+    reinvocationText: '重新加载智能体运行环境，然后再次调用 `repo-scan`',
+  },
+  {
+    relativePath: path.join('docs', 'ja-JP', 'skills', 'repo-scan', 'SKILL.md'),
+    heading: '## インストール',
+    descriptionTerms: ['ブートストラップ', '外部', 'インストール'],
+    reinvocationText: 'エージェントハーネスを再読み込みしてから、`repo-scan` を再度呼び出してください',
+  }
+];
+const pinnedCommit = '2742664ebcad1450c208eda0ae45d3c17fad5dd8';
+const bashBinary = process.env.ECC_TEST_BASH || (process.platform === 'win32' ? null : 'bash');
+
+function run(command, args, options = {}) {
+  return spawnSync(command, args, {
+    encoding: 'utf8',
+    ...options,
+    env: { ...process.env, ...(options.env || {}) },
+  });
+}
+
+function toShellPath(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  return normalized.replace(/^([A-Za-z]):\//, (_, drive) => `/${drive.toLowerCase()}/`);
+}
+
+function writeExecutable(filePath, content) {
+  fs.writeFileSync(filePath, content, { encoding: 'utf8', mode: 0o755 });
+  fs.chmodSync(filePath, 0o755);
+}
+
+function requireShellCommand(command) {
+  const result = run(bashBinary, ['-lc', `command -v ${command}`]);
+  assert.strictEqual(result.status, 0, result.stderr);
+  return result.stdout.trim();
+}
+
+function createLocalSource(root) {
+  const sourceRepo = path.join(root, 'source-repo');
+  fs.mkdirSync(sourceRepo, { recursive: true });
+  assert.strictEqual(run('git', ['init', '--quiet'], { cwd: sourceRepo }).status, 0);
+  fs.writeFileSync(path.join(sourceRepo, 'SKILL.md'), 'pinned fixture\n');
+  fs.mkdirSync(path.join(sourceRepo, 'scripts'));
+  fs.writeFileSync(path.join(sourceRepo, 'scripts', 'scan.sh'), '#!/bin/sh\n');
+  assert.strictEqual(run('git', ['add', '.'], { cwd: sourceRepo }).status, 0);
+  const commit = run('git', ['commit', '--quiet', '-m', 'fixture'], {
+    cwd: sourceRepo,
+    env: {
+      GIT_AUTHOR_NAME: 'Test',
+      GIT_AUTHOR_EMAIL: 'test@example.com',
+      GIT_COMMITTER_NAME: 'Test',
+      GIT_COMMITTER_EMAIL: 'test@example.com',
+    },
+  });
+  assert.strictEqual(commit.status, 0, commit.stderr);
+  return sourceRepo;
+}
+
+function createCommandShims(root) {
+  const binDir = path.join(root, 'bin');
+  fs.mkdirSync(binDir);
+  writeExecutable(path.join(binDir, 'git'), `#!/usr/bin/env bash
+set -euo pipefail
+if [ "\${1:-}" = clone ]; then
+  target="\${!#}"
+  exec "$REAL_GIT" clone --quiet "$LOCAL_REPO" "$target"
+fi
+if [ "\${1:-}" = -C ] && [ "\${3:-}" = checkout ]; then
+  exec "$REAL_GIT" -C "$2" checkout --quiet --detach HEAD
+fi
+if [ "\${1:-}" = -C ] && [ "\${3:-}" = archive ]; then
+  exec "$REAL_GIT" -C "$2" archive HEAD
+fi
+exec "$REAL_GIT" "$@"
+`);
+  writeExecutable(path.join(binDir, 'mv'), `#!/usr/bin/env bash
+set -euo pipefail
+original_args=("$@")
+no_target=0
+positional=()
+for arg in "$@"; do
+  case "$arg" in
+    -T) no_target=1 ;;
+    --) ;;
+    *) positional+=("$arg") ;;
+  esac
+done
+source_path="\${positional[0]:-}"
+destination="\${positional[1]:-}"
+case "$source_path" in
+  */mv-probe-source)
+    case "\${REPO_SCAN_TEST_MV_FAILURE:-}" in
+      *-portable) if [ "$no_target" -eq 1 ]; then exit 64; fi ;;
+    esac
+    exec "$REAL_MV" "\${original_args[@]}"
+    ;;
+esac
+case "$source_path" in
+  */stage-*)
+    case "\${REPO_SCAN_TEST_MV_FAILURE:-}" in
+      replace|rollback) exit 73 ;;
+      rollback-target-conflict|rollback-target-conflict-portable) exit 73 ;;
+      target-conflict|target-conflict-portable)
+        if [ ! -e "$SHIM_DIR/conflict-created" ]; then
+          mkdir -p -- "$destination"
+          printf 'concurrent installation\n' > "$destination/concurrent-marker.txt"
+          : > "$SHIM_DIR/conflict-created"
+        fi
+        ;;
+    esac
+    ;;
+  */backup-*)
+    case "\${REPO_SCAN_TEST_MV_FAILURE:-}" in
+      rollback) exit 74 ;;
+      rollback-target-conflict|rollback-target-conflict-portable)
+        if [ ! -e "$SHIM_DIR/conflict-created" ]; then
+          mkdir -p -- "$destination"
+          printf 'concurrent installation\n' > "$destination/concurrent-marker.txt"
+          : > "$SHIM_DIR/conflict-created"
+        fi
+        ;;
+    esac
+    ;;
+esac
+exec "$REAL_MV" "\${original_args[@]}"
+`);
+  return binDir;
+}
+
+function transactionDirs(installParent) {
+  if (!fs.existsSync(installParent)) return [];
+  return fs.readdirSync(installParent).filter(
+    name => name.startsWith('.repo-scan-install.') && name !== '.repo-scan-install.lock'
+  );
+}
+
+function prepareInstallScenario(installParent, installDir, scenario) {
+  if (scenario === 'fresh') return;
+  fs.mkdirSync(installDir, { recursive: true });
+  fs.writeFileSync(path.join(installDir, 'old-marker.txt'), 'previous installation\n');
+  if (scenario === 'lock-held') {
+    fs.mkdirSync(path.join(installParent, '.repo-scan-install.lock'));
+  }
+}
+
+function failureMode(scenario) {
+  if (scenario === 'replacement-failure') return 'replace';
+  if (scenario === 'rollback-failure') return 'rollback';
+  if (scenario.includes('target-conflict')) return scenario;
+  return '';
+}
+
+function assertPreservedBackup(result, installParent) {
+  const workspaces = transactionDirs(installParent);
+  assert.strictEqual(workspaces.length, 1, result.stderr);
+  const workspace = path.join(installParent, workspaces[0]);
+  const backupName = fs.readdirSync(workspace).find(name => name.startsWith('backup-'));
+  assert.ok(backupName, result.stderr);
+  const preservedBackup = path.join(workspace, backupName);
+  assert.strictEqual(
+    fs.readFileSync(path.join(preservedBackup, 'old-marker.txt'), 'utf8'),
+    'previous installation\n'
+  );
+}
+
+function assertInstallationResult({ result, scenario, installDir, installParent }) {
+  const lockDir = path.join(installParent, '.repo-scan-install.lock');
+  if (scenario === 'fresh' || scenario === 'existing') {
+    assert.strictEqual(result.status, 0, result.stderr);
+    assert.strictEqual(fs.readFileSync(path.join(installDir, 'SKILL.md'), 'utf8').trim(), 'pinned fixture');
+    assert.ok(!fs.existsSync(path.join(installDir, '.git')));
+    assert.ok(!fs.existsSync(path.join(installDir, 'old-marker.txt')));
+    assert.deepStrictEqual(transactionDirs(installParent), []);
+    assert.ok(!fs.existsSync(lockDir));
+    return;
+  }
+
+  assert.notStrictEqual(result.status, 0, 'forced installation failure must propagate');
+  if (scenario === 'replacement-failure' || scenario === 'lock-held') {
+    assert.strictEqual(
+      fs.readFileSync(path.join(installDir, 'old-marker.txt'), 'utf8'),
+      'previous installation\n'
+    );
+    assert.deepStrictEqual(transactionDirs(installParent), []);
+    assert.strictEqual(fs.existsSync(lockDir), scenario === 'lock-held');
+    if (scenario === 'lock-held') assert.match(result.stderr, /holds the lock/);
+    return;
+  }
+
+  assertPreservedBackup(result, installParent);
+  assert.ok(!fs.existsSync(lockDir));
+  if (scenario.includes('target-conflict')) {
+    assert.ok(fs.existsSync(path.join(installDir, 'concurrent-marker.txt')));
+    assert.ok(
+      !fs.readdirSync(installDir).some(name => /^(stage|backup)-/.test(name)),
+      'native mv must not leave staged or backup directories nested in the target'
+    );
+    assert.match(result.stderr, /target was recreated|rollback failed/);
+  } else {
+    assert.match(result.stderr, /previous installation preserved at/);
+  }
+}
+
+function executeInstallation(block, scenario) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-repo-scan-install-'));
+  try {
+    const sourceRepo = createLocalSource(root);
+    const binDir = createCommandShims(root);
+    const configDir = path.join(root, 'config');
+    const installParent = path.join(configDir, 'skills');
+    const installDir = path.join(installParent, 'repo-scan');
+    prepareInstallScenario(installParent, installDir, scenario);
+    const result = run(bashBinary, ['-c', `export PATH="$SHIM_DIR:$PATH"\n${block}`], {
+      input: 'install\n',
+      cwd: repoRoot,
+      env: {
+        CLAUDE_CONFIG_DIR: toShellPath(configDir),
+        LOCAL_REPO: toShellPath(sourceRepo),
+        REAL_GIT: requireShellCommand('git'),
+        REAL_MV: requireShellCommand('mv'),
+        REPO_SCAN_TEST_MV_FAILURE: failureMode(scenario),
+        SHIM_DIR: toShellPath(binDir),
+      },
+      timeout: 30000,
+    });
+    assertInstallationResult({ result, scenario, installDir, installParent });
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function installationBlock({ relativePath, heading }) {
+  const source = fs.readFileSync(path.join(repoRoot, relativePath), 'utf8');
+  const headingStart = source.indexOf(`${heading}\n`);
+  assert.notStrictEqual(headingStart, -1, `${relativePath} must contain ${heading}`);
+  const afterHeading = source.slice(headingStart + heading.length + 1);
+  const nextHeading = afterHeading.search(/^## /m);
+  const installationSection = nextHeading === -1 ? afterHeading : afterHeading.slice(0, nextHeading);
+  const match = installationSection.match(/```bash\n([\s\S]*?)```/);
+  assert.ok(match, `${relativePath} must contain a bash installation block`);
+  return match[1];
+}
+
+function assertPointerContract({ relativePath, descriptionTerms, reinvocationText }) {
+  const source = fs.readFileSync(path.join(repoRoot, relativePath), 'utf8');
+  const frontmatter = source.match(/^---\n([\s\S]*?)\n---/);
+  assert.ok(frontmatter, `${relativePath} must contain YAML frontmatter`);
+  const description = frontmatter[1].match(/^description:\s*(.+)$/m);
+  assert.ok(description, `${relativePath} must contain a frontmatter description`);
+  for (const term of descriptionTerms) {
+    assert.ok(
+      description[1].toLocaleLowerCase().includes(term.toLocaleLowerCase()),
+      `${relativePath} description must identify this as an external installer pointer (${term})`
+    );
+  }
+  assert.ok(
+    source.includes(reinvocationText),
+    `${relativePath} must tell users to reload and invoke repo-scan again after installation`
+  );
+}
+
+console.log('\nrepo-scan installation docs (#2774):');
+
+const blocks = skillFiles.map(installationBlock);
+let passed = 0;
+for (const skillFile of skillFiles) {
+  assertPointerContract(skillFile);
+  passed++;
+}
+for (const [index, block] of blocks.entries()) {
+  const { relativePath } = skillFiles[index];
+  assert.ok(block.includes(`REPO_SCAN_COMMIT=${pinnedCommit}`), `${relativePath} must pin the full commit SHA`);
+  assert.ok(block.includes('set -euo pipefail'), `${relativePath} must fail closed`);
+  assert.ok(block.includes('mktemp -d "$REPO_SCAN_INSTALL_PARENT/'), `${relativePath} must stage on the target filesystem`);
+  assert.ok(block.includes('REPO_SCAN_KEEP_TMP=0'), `${relativePath} must track cleanup safety`);
+  assert.ok(block.includes('REPO_SCAN_LOCK_HELD=0'), `${relativePath} must track lock ownership`);
+  assert.ok(block.includes('REPO_SCAN_MV_HAS_NO_TARGET=0'), `${relativePath} must probe no-target moves`);
+  assert.ok(block.includes('trap cleanup_repo_scan_install EXIT'), `${relativePath} must use conditional cleanup`);
+  assert.ok(block.includes('mv -T -- "$REPO_SCAN_MOVE_SOURCE"'), `${relativePath} must reject an existing GNU mv destination`);
+  assert.ok(block.includes('move_repo_scan_dir()'), `${relativePath} must guard portable directory moves`);
+  assert.ok(block.includes('git clone --filter=blob:none --no-checkout'), `${relativePath} must clone before checkout`);
+  assert.ok(block.includes('checkout --detach "$REPO_SCAN_COMMIT"'), `${relativePath} must detach at the pin`);
+  assert.ok(block.includes('archive "$REPO_SCAN_COMMIT"'), `${relativePath} must archive the exact pinned commit`);
+  assert.ok(block.includes('tar -xf - -C "$REPO_SCAN_STAGE"'), `${relativePath} must extract into a fresh staging directory`);
+  assert.ok(block.includes('# Review "$REPO_SCAN_TMP/source"'), `${relativePath} must instruct source review`);
+  assert.ok(block.includes('read -r REPO_SCAN_CONFIRM'), `${relativePath} must require explicit confirmation`);
+  assert.ok(block.includes('mkdir -- "$REPO_SCAN_LOCK"'), `${relativePath} must serialize replacement`);
+  assert.ok(block.includes('[ "$REPO_SCAN_CONFIRM" != install ]'), `${relativePath} must default-deny installation`);
+  assert.ok(block.includes('move_repo_scan_dir "$REPO_SCAN_STAGE" "$REPO_SCAN_INSTALL_DIR"'), `${relativePath} must use guarded replacement`);
+  assert.ok(block.indexOf('read -r REPO_SCAN_CONFIRM') < block.indexOf('move_repo_scan_dir "$REPO_SCAN_STAGE"'), `${relativePath} must confirm before replacing the target`);
+  assert.ok(block.indexOf('mkdir -- "$REPO_SCAN_LOCK"') < block.indexOf('move_repo_scan_dir "$REPO_SCAN_STAGE"'), `${relativePath} must lock before replacing the target`);
+  assert.ok(!block.includes('rm -rf "$REPO_SCAN_INSTALL_DIR"'), `${relativePath} must preserve the old target until replacement succeeds`);
+  assert.ok(block.includes('${CLAUDE_CONFIG_DIR:-$HOME/.claude}'), `${relativePath} must honor CLAUDE_CONFIG_DIR`);
+  assert.ok(!block.includes('cp -r .'), `${relativePath} must not copy .git metadata`);
+  assert.ok(!block.includes('git fetch --depth 1 origin 2742664\n'), `${relativePath} must not fetch the short SHA`);
+  assert.ok(block.includes('REPO_SCAN_KEEP_TMP=1'), `${relativePath} must preserve a failed rollback backup`);
+  passed++;
+}
+
+for (const block of blocks.slice(1)) {
+  assert.strictEqual(block, blocks[0], 'translated installation commands must stay synchronized');
+  passed++;
+}
+
+if (bashBinary) {
+  for (const block of blocks) {
+    const syntax = run(bashBinary, ['-n'], { input: block });
+    assert.strictEqual(syntax.status, 0, syntax.stderr);
+    passed++;
+    for (const scenario of [
+      'fresh',
+      'existing',
+      'replacement-failure',
+      'rollback-failure',
+      'target-conflict',
+      'target-conflict-portable',
+      'rollback-target-conflict',
+      'rollback-target-conflict-portable',
+      'lock-held',
+    ]) {
+      executeInstallation(block, scenario);
+      passed++;
+    }
+  }
+} else {
+  console.log('  Integration coverage skipped on Windows without ECC_TEST_BASH');
+}
+
+console.log(`  Passed: ${passed}`);
+console.log('  Failed: 0');
diff --git a/yarn.lock b/yarn.lock
index e76633da5..aa0af3415 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -586,6 +586,7 @@ __metadata:
     c8: "npm:11.0.0"
     eslint: "npm:10.6.0"
     globals: "npm:17.4.0"
+    js-yaml: "npm:4.3.1"
     markdownlint-cli: "npm:0.48.0"
     sql.js: "npm:1.14.1"
     typescript: "npm:6.0.3"
@@ -1068,14 +1069,14 @@ __metadata:
   languageName: node
   linkType: hard
 
-"js-yaml@npm:4.3.0":
-  version: 4.3.0
-  resolution: "js-yaml@npm:4.3.0"
+"js-yaml@npm:4.3.1":
+  version: 4.3.1
+  resolution: "js-yaml@npm:4.3.1"
   dependencies:
     argparse: "npm:^2.0.1"
   bin:
     js-yaml: bin/js-yaml.js
-  checksum: 10c0/058b30473d6915ca5b4feb11e2f7d4d97242f98d00a798ed48dd90b46b7c640398afe9128c5db22c5300f8c6528fe2a174b9a93f351a70ebc28c6203938d8bff
+  checksum: 10c0/13c500ca322e0c3f8c81686e6ecda96d2ea37b45247a420c17c7db36932d6965cc27391abc2d1a104501600e7f0d947a5f8b7be6db619c4fefa87901b3512807
   languageName: node
   linkType: hard