From ffbe5c6819b3ae70d52f94ee3e2851fb030fd762 Mon Sep 17 00:00:00 2001
From: Pyuyi <136783609@qq.com>
Date: Tue, 26 May 2026 10:20:41 +0800
Subject: [PATCH] Fix Windows PowerShell installer parity (#242)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rewrite the Windows PowerShell installer to use flat per-skill junctions instead of nested-junction layout, matching the Unix installer's safety model.

Two rounds of cross-model review caught: CRLF noise (eliminated; .gitattributes added with LF normalization); UPDATE_TARGET silently overwriting user-customized junctions (now guarded by inside-repo check); missing legacy nested migration (added -FromOld / -MigrateCopy keep-user|prefer-upstream); missing .aris/tools junction parity; tests effectively never running (added Windows GitHub Actions matrix for both powershell.exe and pwsh).

Author then self-found a narrower variant: parent-path-component reparse points. Resolve-ReparseChain now walks root → leaf rewriting at the first junction/symlink component, with cycle detection (40-depth limit + HashSet of seen paths). 12 tests passing on both PS hosts.

Maintainer rebased onto post-RENDER_HTML + post-drift-fix main; resolved 3 conflicts (README_CN.md, SKILLS_CATALOG.md, wiki-enrich Codex mirror) by taking the previously codex-reviewed origin/main version.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .gitattributes                               |    2 +
 .github/workflows/check-skills-inventory.yml |    2 +
 .github/workflows/test-install-aris-ps1.yml  |   31 +
 README.md                                    |    5 +-
 docs/ARIS_INTRO.html                         |   12 +-
 docs/ARIS_INTRO.review.json                  |    2 +-
 tests/test_codex_skill_mirror.py             |    2 +-
 tests/test_install_aris_ps1.py               |  356 ++++++
 tools/install_aris.ps1                       | 1096 ++++++++++++++----
 9 files changed, 1286 insertions(+), 222 deletions(-)
 create mode 100644 .github/workflows/test-install-aris-ps1.yml
 create mode 100644 tests/test_install_aris_ps1.py

diff --git a/.gitattributes b/.gitattributes
index 8e25262..39723e5 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,3 +1,5 @@
+* text=auto eol=lf
+
 skills/paper-write/templates/* linguist-vendored
 skills/skills-codex/paper-write/templates/* linguist-vendored
 skills/skills-codex-claude-review/paper-write/templates/* linguist-vendored
diff --git a/.github/workflows/check-skills-inventory.yml b/.github/workflows/check-skills-inventory.yml
index 50558d4..6cf4ada 100644
--- a/.github/workflows/check-skills-inventory.yml
+++ b/.github/workflows/check-skills-inventory.yml
@@ -24,6 +24,8 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: '3.x'
+      - name: Install pytest
+        run: python -m pip install pytest
       - name: Check skill inventory drift
         run: python tools/check_skills_inventory.py
       - name: Check Codex skill mirror semantics
diff --git a/.github/workflows/test-install-aris-ps1.yml b/.github/workflows/test-install-aris-ps1.yml
new file mode 100644
index 0000000..0b54609
--- /dev/null
+++ b/.github/workflows/test-install-aris-ps1.yml
@@ -0,0 +1,31 @@
+name: Windows PowerShell installer tests
+
+on:
+  pull_request:
+    paths:
+      - 'tools/install_aris.ps1'
+      - 'tests/test_install_aris_ps1.py'
+      - '.github/workflows/test-install-aris-ps1.yml'
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: windows-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        powershell:
+          - powershell.exe
+          - pwsh
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Install pytest
+        run: python -m pip install pytest
+      - name: Run installer tests with ${{ matrix.powershell }}
+        env:
+          ARIS_TEST_POWERSHELL: ${{ matrix.powershell }}
+        run: python -m pytest tests/test_install_aris_ps1.py -q
diff --git a/README.md b/README.md
index 584fd9c..35c1c7e 100644
--- a/README.md
+++ b/README.md
@@ -1507,8 +1507,9 @@ bash ~/aris_repo/tools/install_aris.sh --dry-run        # show plan, no changes
 bash ~/aris_repo/tools/install_aris.sh --uninstall      # remove only managed symlinks (per manifest)
 bash ~/aris_repo/tools/install_aris.sh --from-old       # migrate from old nested .claude/skills/aris/
 
-# Windows (PowerShell, requires admin or developer mode for junctions):
-.\tools\install_aris.ps1 C:\path\to\your-paper-project
+# Windows (PowerShell, no WSL required; creates flat per-skill junctions):
+.\tools\install_aris.ps1 C:\path\to\your-paper-project -Platform claude
+.\tools\install_aris.ps1 C:\path\to\your-codex-project -Platform codex
 ```
 
 **Why "git pull" alone isn't enough for new/removed skills:** the flat layout uses one symlink per skill, so upstream additions/deletions don't propagate until the installer is re-run. The trade-off bought us Claude Code's automatic slash-command discovery (which only scans one directory level deep).
diff --git a/docs/ARIS_INTRO.html b/docs/ARIS_INTRO.html
index f42c60e..bd1efb6 100644
--- a/docs/ARIS_INTRO.html
+++ b/docs/ARIS_INTRO.html
@@ -7,8 +7,8 @@
 
 <meta name="generator" content="ARIS render-html (academic, v1)">
 <meta name="aris:source-path" content="docs/ARIS_INTRO.md">
-<meta name="aris:source-sha256" content="c590a8e8f63dd5b69c511a2c0cc51dc72e5c0a3144beaa85c0cb617796db8820">
-<meta name="aris:generated-at" content="2026-05-24 17:22 UTC">
+<meta name="aris:source-sha256" content="7757b71ab1b1bacc6a4df7c7dc1909d74acd17542bfe815ee6a25522a908d0eb">
+<meta name="aris:generated-at" content="2026-05-25 08:00 UTC">
 
 <!-- MathJax 3 -->
 <script>
@@ -372,8 +372,8 @@ footer.aris-footer a { color: var(--ink-muted); border-bottom: 1px dotted var(--
   <p class="byline">By <strong>Ruofeng Yang (杨若峰), Shanghai Jiao Tong University</strong></p>
   <div class="meta">
     <span><strong>Source:</strong> <code>docs/ARIS_INTRO.md</code></span>
-    <span><strong>SHA256:</strong> <code>c590a8e8f63d</code></span>
-    <span><strong>Rendered:</strong> 2026-05-24 17:22 UTC</span>
+    <span><strong>SHA256:</strong> <code>7757b71ab1b1</code></span>
+    <span><strong>Rendered:</strong> 2026-05-25 08:00 UTC</span>
     
   </div>
 </header>
@@ -530,8 +530,8 @@ claude
 <footer class="aris-footer">
   Generated by <a href="https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep/blob/main/skills/render-html/SKILL.md">ARIS <code>/render-html</code></a> ·
   source path <code>docs/ARIS_INTRO.md</code> ·
-  SHA256 <code>c590a8e8f63d</code> ·
-  generated at 2026-05-24 17:22 UTC.
+  SHA256 <code>7757b71ab1b1</code> ·
+  generated at 2026-05-25 08:00 UTC.
   This is a generated view — edit the source Markdown, then re-render.
 </footer>
 </main>
diff --git a/docs/ARIS_INTRO.review.json b/docs/ARIS_INTRO.review.json
index 07c9ad2..63de232 100644
--- a/docs/ARIS_INTRO.review.json
+++ b/docs/ARIS_INTRO.review.json
@@ -1,7 +1,7 @@
 {
   "skill": "render-html",
   "source": "docs/ARIS_INTRO.md",
-  "source_sha256": "c590a8e8f63dd5b69c511a2c0cc51dc72e5c0a3144beaa85c0cb617796db8820",
+  "source_sha256": "7757b71ab1b1bacc6a4df7c7dc1909d74acd17542bfe815ee6a25522a908d0eb",
   "output": "docs/ARIS_INTRO.html",
   "author": "Ruofeng Yang (杨若峰), Shanghai Jiao Tong University",
   "reviewer": "codex gpt-5.5 xhigh, fresh thread per run (never codex-reply)",
diff --git a/tests/test_codex_skill_mirror.py b/tests/test_codex_skill_mirror.py
index 5d78f15..a6c1ed6 100644
--- a/tests/test_codex_skill_mirror.py
+++ b/tests/test_codex_skill_mirror.py
@@ -34,7 +34,7 @@ def has_send_input_block(text: str) -> bool:
 def test_codex_skill_set_matches_mainline() -> None:
     main_names = skill_names(MAIN_SKILLS)
     codex_names = skill_names(CODEX_SKILLS)
-    assert len(main_names) == 76
+    assert len(main_names) == 77
     assert main_names == codex_names
 
 
diff --git a/tests/test_install_aris_ps1.py b/tests/test_install_aris_ps1.py
new file mode 100644
index 0000000..5ff63e6
--- /dev/null
+++ b/tests/test_install_aris_ps1.py
@@ -0,0 +1,356 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+INSTALL_PS1 = REPO_ROOT / "tools" / "install_aris.ps1"
+
+
+def resolve_powershell() -> str | None:
+    override = os.environ.get("ARIS_TEST_POWERSHELL")
+    if override:
+        return shutil.which(override) or override
+    return shutil.which("pwsh") or shutil.which("powershell") or shutil.which("powershell.exe")
+
+
+PS_EXE = resolve_powershell()
+
+pytestmark = pytest.mark.skipif(
+    os.name != "nt" or PS_EXE is None,
+    reason="install_aris.ps1 manages Windows junctions via Windows PowerShell",
+)
+
+
+def run_ps(args: list[str], *, check: bool = True) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [PS_EXE, "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", str(INSTALL_PS1), *args],
+        cwd=REPO_ROOT,
+        text=True,
+        encoding="utf-8",
+        capture_output=True,
+        check=check,
+    )
+
+
+def ps_value(command: str) -> str:
+    result = subprocess.run(
+        [PS_EXE, "-NoProfile", "-Command", command],
+        cwd=REPO_ROOT,
+        text=True,
+        encoding="utf-8",
+        capture_output=True,
+        check=True,
+    )
+    return result.stdout.strip()
+
+
+def path_item_exists(path: Path) -> bool:
+    command = f"if (Get-Item -LiteralPath '{path}' -Force -ErrorAction SilentlyContinue) {{ 'true' }} else {{ 'false' }}"
+    return ps_value(command) == "true"
+
+
+def junction_target(path: Path) -> Path:
+    target = ps_value(f"(Get-Item -LiteralPath '{path}' -Force).Target")
+    return Path(target)
+
+
+def junction_type(path: Path) -> str:
+    return ps_value(f"(Get-Item -LiteralPath '{path}' -Force).LinkType")
+
+
+def make_junction(path: Path, target: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    ps_value(f"New-Item -ItemType Junction -Path '{path}' -Target '{target}' | Out-Null")
+
+
+def remove_link(path: Path) -> None:
+    ps_value(f"[System.IO.Directory]::Delete('{path}', $false)")
+
+
+def make_skill(path: Path, body: str = "# skill\n") -> None:
+    path.mkdir(parents=True, exist_ok=True)
+    (path / "SKILL.md").write_text(body, encoding="utf-8")
+
+
+def make_minimal_repo(root: Path) -> Path:
+    repo = root / "aris"
+    make_skill(repo / "skills" / "alpha", "# claude alpha\n")
+    make_skill(repo / "skills" / "beta", "# claude beta\n")
+    make_skill(repo / "skills" / "skills-codex" / "alpha", "# codex alpha\n")
+    make_skill(repo / "skills" / "skills-codex" / "beta", "# codex beta\n")
+    make_skill(repo / "skills" / "skills-codex-claude-review" / "alpha", "# overlay alpha\n")
+    (repo / "skills" / "shared-references").mkdir(parents=True)
+    (repo / "skills" / "shared-references" / "routing.md").write_text("claude support\n", encoding="utf-8")
+    (repo / "skills" / "skills-codex" / "shared-references").mkdir(parents=True)
+    (repo / "skills" / "skills-codex" / "shared-references" / "routing.md").write_text(
+        "codex support\n", encoding="utf-8"
+    )
+    (repo / "tools").mkdir(parents=True)
+    (repo / "tools" / "helper.py").write_text("# helper\n", encoding="utf-8")
+    return repo
+
+
+def test_install_aris_ps1_codex_dry_run_has_no_project_writes(tmp_path: Path) -> None:
+    repo = make_minimal_repo(tmp_path)
+    project = tmp_path / "project"
+    project.mkdir()
+
+    result = run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo), "-DryRun"])
+
+    assert "DRY-RUN" in result.stdout
+    assert not (project / ".aris").exists()
+    assert not (project / ".agents").exists()
+    assert not (project / "AGENTS.md").exists()
+
+
+def test_install_aris_ps1_codex_apply_reconcile_and_uninstall(tmp_path: Path) -> None:
+    repo = make_minimal_repo(tmp_path)
+    project = tmp_path / "project"
+    project.mkdir()
+
+    run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo)])
+
+    manifest = project / ".aris" / "installed-skills-codex.txt"
+    assert manifest.exists()
+    manifest_text = manifest.read_text(encoding="utf-8")
+    assert f"repo_root\t{repo}" in manifest_text
+    assert "\tskills/skills-codex/alpha\t.agents/skills/alpha\tjunction" in manifest_text
+    assert junction_type(project / ".agents" / "skills" / "alpha") == "Junction"
+    assert junction_target(project / ".agents" / "skills" / "alpha") == repo / "skills" / "skills-codex" / "alpha"
+    assert junction_target(project / ".agents" / "skills" / "shared-references") == (
+        repo / "skills" / "skills-codex" / "shared-references"
+    )
+    assert junction_type(project / ".aris" / "tools") == "Junction"
+    assert junction_target(project / ".aris" / "tools") == repo / "tools"
+    agents_text = (project / "AGENTS.md").read_text(encoding="utf-8")
+    assert "ARIS Codex Skill Scope" in agents_text
+    assert ".agents/skills/<skill-name>" in agents_text
+    assert ".agents/skills/aris" not in agents_text
+
+    (project / ".agents" / "skills" / "local-only").mkdir()
+    (repo / "skills" / "skills-codex" / "alpha" / "SKILL.md").unlink()
+    (repo / "skills" / "skills-codex" / "alpha").rmdir()
+    make_skill(repo / "skills" / "skills-codex" / "gamma", "# codex gamma\n")
+
+    run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo), "-Reconcile"])
+
+    assert not path_item_exists(project / ".agents" / "skills" / "alpha")
+    assert junction_target(project / ".agents" / "skills" / "gamma") == repo / "skills" / "skills-codex" / "gamma"
+    assert (project / ".agents" / "skills" / "local-only").exists()
+
+    run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo), "-Uninstall", "-DryRun"])
+    assert (project / ".aris" / "installed-skills-codex.txt").exists()
+    assert "ARIS Codex Skill Scope" in (project / "AGENTS.md").read_text(encoding="utf-8")
+
+    run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo), "-Uninstall"])
+
+    assert (project / ".agents" / "skills" / "local-only").exists()
+    assert not (project / ".agents" / "skills" / "beta").exists()
+    assert not (project / ".aris" / "tools").exists()
+    assert not (project / ".aris" / "installed-skills-codex.txt").exists()
+    assert (project / ".aris" / "installed-skills-codex.txt.prev").exists()
+    assert "ARIS Codex Skill Scope" not in (project / "AGENTS.md").read_text(encoding="utf-8")
+
+
+def test_install_aris_ps1_claude_uses_mainline_flat_junctions(tmp_path: Path) -> None:
+    repo = make_minimal_repo(tmp_path)
+    project = tmp_path / "project"
+    project.mkdir()
+
+    run_ps([str(project), "-Platform", "claude", "-ArisRepo", str(repo)])
+
+    assert (project / ".aris" / "installed-skills.txt").exists()
+    assert junction_target(project / ".claude" / "skills" / "alpha") == repo / "skills" / "alpha"
+    assert junction_target(project / ".claude" / "skills" / "shared-references") == repo / "skills" / "shared-references"
+    assert not (project / ".claude" / "skills" / "skills-codex").exists()
+    assert not (project / ".claude" / "skills" / "aris").exists()
+    claude_text = (project / "CLAUDE.md").read_text(encoding="utf-8")
+    assert ".claude/skills/<skill-name>" in claude_text
+    assert ".claude/skills/aris" not in claude_text
+
+
+def test_install_aris_ps1_skips_upstream_junctions_outside_repo(tmp_path: Path) -> None:
+    repo = make_minimal_repo(tmp_path)
+    project = tmp_path / "project"
+    project.mkdir()
+    external = tmp_path / "external-source" / "escape"
+    make_skill(external, "# external escape\n")
+    make_junction(repo / "skills" / "skills-codex" / "escape", external)
+
+    result = run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo)])
+
+    assert "skipping upstream link leading outside ARIS repo" in result.stderr + result.stdout
+    assert not path_item_exists(project / ".agents" / "skills" / "escape")
+    assert "escape" not in (project / ".aris" / "installed-skills-codex.txt").read_text(encoding="utf-8")
+
+
+def test_install_aris_ps1_skips_upstream_source_root_junction_outside_repo(tmp_path: Path) -> None:
+    repo = make_minimal_repo(tmp_path)
+    project = tmp_path / "project"
+    project.mkdir()
+    codex_root = repo / "skills" / "skills-codex"
+    external_root = tmp_path / "external-source"
+    make_skill(external_root / "escape", "# external escape\n")
+    shutil.rmtree(codex_root)
+    make_junction(codex_root, external_root)
+
+    result = run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo)], check=False)
+
+    assert result.returncode != 0
+    assert "skipping upstream link leading outside ARIS repo" in result.stderr + result.stdout
+    assert not path_item_exists(project / ".agents" / "skills" / "escape")
+
+
+def test_install_aris_ps1_replace_link_rejects_indirect_external_target(tmp_path: Path) -> None:
+    repo = make_minimal_repo(tmp_path)
+    project = tmp_path / "project"
+    project.mkdir()
+    external = tmp_path / "external-source" / "beta"
+    make_skill(external, "# external beta\n")
+    shutil.rmtree(repo / "skills" / "skills-codex" / "beta")
+    make_junction(repo / "skills" / "skills-codex" / "beta", external)
+    alpha_link = project / ".agents" / "skills" / "alpha"
+    make_junction(alpha_link, repo / "skills" / "skills-codex" / "beta")
+
+    result = run_ps(
+        [str(project), "-Platform", "codex", "-ArisRepo", str(repo), "-ReplaceLink", "alpha"],
+        check=False,
+    )
+
+    assert result.returncode != 0
+    assert "CONFLICT" in result.stderr + result.stdout
+    assert junction_target(alpha_link) == repo / "skills" / "skills-codex" / "beta"
+
+
+def test_install_aris_ps1_manifest_retargeted_external_parent_junction_conflicts(tmp_path: Path) -> None:
+    repo = make_minimal_repo(tmp_path)
+    project = tmp_path / "project"
+    project.mkdir()
+    run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo)])
+
+    external_root = tmp_path / "user-fork"
+    make_skill(external_root / "alpha", "# user fork alpha\n")
+    alias = repo / "skills" / "skills-codex" / "alias"
+    make_junction(alias, external_root)
+    apparent_external = alias / "alpha"
+    alpha_link = project / ".agents" / "skills" / "alpha"
+    remove_link(alpha_link)
+    make_junction(alpha_link, apparent_external)
+
+    result = run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo), "-Reconcile"], check=False)
+
+    assert result.returncode != 0
+    assert "CONFLICT" in result.stderr + result.stdout
+    assert junction_target(alpha_link) == apparent_external
+
+
+def test_install_aris_ps1_uninstall_keeps_tools_for_other_platform_manifest(tmp_path: Path) -> None:
+    repo = make_minimal_repo(tmp_path)
+    project = tmp_path / "project"
+    project.mkdir()
+
+    run_ps([str(project), "-Platform", "claude", "-ArisRepo", str(repo)])
+    run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo)])
+
+    run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo), "-Uninstall"])
+
+    assert junction_target(project / ".aris" / "tools") == repo / "tools"
+    assert (project / ".aris" / "installed-skills.txt").exists()
+    assert not (project / ".aris" / "installed-skills-codex.txt").exists()
+
+    run_ps([str(project), "-Platform", "claude", "-ArisRepo", str(repo), "-Uninstall"])
+
+    assert not path_item_exists(project / ".aris" / "tools")
+
+
+def test_install_aris_ps1_conflicts_stop_and_replace_link_relinks_junction(tmp_path: Path) -> None:
+    repo = make_minimal_repo(tmp_path)
+    project = tmp_path / "project"
+    project.mkdir()
+    conflicting_real = project / ".agents" / "skills" / "alpha"
+    conflicting_real.mkdir(parents=True)
+    (conflicting_real / "SKILL.md").write_text("# user-owned\n", encoding="utf-8")
+
+    result = run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo)], check=False)
+
+    assert result.returncode != 0
+    assert "CONFLICT" in result.stderr + result.stdout
+    assert (conflicting_real / "SKILL.md").read_text(encoding="utf-8") == "# user-owned\n"
+
+    shutil.rmtree(conflicting_real)
+    wrong_target = repo / "skills" / "skills-codex" / "beta"
+    make_junction(conflicting_real, wrong_target)
+
+    result = run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo)], check=False)
+    assert result.returncode != 0
+    assert junction_target(conflicting_real) == wrong_target
+
+    run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo), "-ReplaceLink", "alpha"])
+    assert junction_target(conflicting_real) == repo / "skills" / "skills-codex" / "alpha"
+
+
+def test_install_aris_ps1_manifest_retargeted_external_junction_conflicts(tmp_path: Path) -> None:
+    repo = make_minimal_repo(tmp_path)
+    project = tmp_path / "project"
+    project.mkdir()
+    run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo)])
+
+    alpha_link = project / ".agents" / "skills" / "alpha"
+    external = tmp_path / "user-fork" / "alpha"
+    make_skill(external, "# user fork alpha\n")
+    remove_link(alpha_link)
+    make_junction(alpha_link, external)
+
+    result = run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo), "-Reconcile"], check=False)
+    assert result.returncode != 0
+    assert "CONFLICT" in result.stderr + result.stdout
+    assert junction_target(alpha_link) == external
+
+    result = run_ps(
+        [str(project), "-Platform", "codex", "-ArisRepo", str(repo), "-Reconcile", "-ReplaceLink", "alpha"],
+        check=False,
+    )
+    assert result.returncode != 0
+    assert "CONFLICT" in result.stderr + result.stdout
+    assert junction_target(alpha_link) == external
+
+
+def test_install_aris_ps1_from_old_removes_nested_legacy_junction(tmp_path: Path) -> None:
+    repo = make_minimal_repo(tmp_path)
+    project = tmp_path / "project"
+    project.mkdir()
+    legacy = project / ".agents" / "skills" / "aris"
+    make_junction(legacy, repo / "skills" / "skills-codex")
+
+    result = run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo)], check=False)
+    assert result.returncode != 0
+    assert legacy.exists()
+
+    run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo), "-FromOld"])
+
+    assert not legacy.exists()
+    assert junction_target(project / ".agents" / "skills" / "alpha") == repo / "skills" / "skills-codex" / "alpha"
+
+
+def test_install_aris_ps1_clear_stale_lock(tmp_path: Path) -> None:
+    repo = make_minimal_repo(tmp_path)
+    project = tmp_path / "project"
+    project.mkdir()
+    lock_dir = project / ".aris" / ".install-codex.lock.d"
+    lock_dir.mkdir(parents=True)
+    (lock_dir / "owner.pid").write_text("999999\n", encoding="utf-8")
+    (lock_dir / "owner.host").write_text("stale-host\n", encoding="utf-8")
+
+    result = run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo)], check=False)
+    assert result.returncode != 0
+    assert lock_dir.exists()
+
+    run_ps([str(project), "-Platform", "codex", "-ArisRepo", str(repo), "-ClearStaleLock"])
+    assert not lock_dir.exists()
+    assert junction_target(project / ".agents" / "skills" / "alpha") == repo / "skills" / "skills-codex" / "alpha"
diff --git a/tools/install_aris.ps1 b/tools/install_aris.ps1
index 9dd6df0..3bc06a8 100644
--- a/tools/install_aris.ps1
+++ b/tools/install_aris.ps1
@@ -1,61 +1,18 @@
 #Requires -Version 5.1
 <#
 .SYNOPSIS
-    Project-local ARIS skill installation via junction (Windows symlink equivalent).
+    Project-local ARIS skill installation for Windows.
 
 .DESCRIPTION
-    [DEPRECATED behavior — see warning below]
-    Recommended over global install for projects that mix ARIS with other skill packs.
-    Creates a junction in <project>/.claude/skills/aris (or .agents/skills/aris) pointing
-    to the cloned ARIS repository's skills directory.
+    Creates one flat junction per ARIS skill so Claude Code and Codex can
+    discover slash commands at one directory level:
 
-.NOTES
-    ⚠️  KNOWN BUG: this script creates a NESTED junction at .claude/skills/aris/, which
-    Claude Code's slash-command discovery does NOT find (CC only scans one directory level).
-    The Bash version (install_aris.sh) was rewritten in v0.4.4 to use flat per-skill
-    symlinks + a manifest-tracked re-runnable installer. PowerShell parity is pending.
+      Claude: <project>\.claude\skills\<skill-name>
+      Codex:  <project>\.agents\skills\<skill-name>
 
-    Recommended for Windows users:
-      Option A (best):    Use WSL2 with the Bash installer:
-                            wsl bash ~/aris_repo/tools/install_aris.sh
-      Option B (manual):  Create flat junctions yourself, one per skill:
-                            $repo = "C:\path\to\aris_repo"
-                            $proj = "C:\path\to\your-project"
-                            New-Item -ItemType Directory -Force "$proj\.claude\skills" | Out-Null
-                            Get-ChildItem "$repo\skills" -Directory |
-                              Where-Object { $_.Name -ne 'skills-codex' -and (Test-Path "$($_.FullName)\SKILL.md") } |
-                              ForEach-Object {
-                                $link = "$proj\.claude\skills\$($_.Name)"
-                                if (-not (Test-Path $link)) {
-                                  New-Item -ItemType Junction -Path $link -Target $_.FullName | Out-Null
-                                }
-                              }
-      Option C (legacy):  Continue with this script — but Claude Code's slash-command
-                          autocomplete will NOT see your skills (you'd have to invoke
-                          them via /skills <name> or copy them out manually).
-
-.PARAMETER ProjectPath
-    Path to the project root. Defaults to current directory.
-
-.PARAMETER Platform
-    auto (default), claude, or codex. Auto-detects from project markers.
-
-.PARAMETER ArisRepo
-    Override path to ARIS repo. Defaults to auto-detect.
-
-.PARAMETER Force
-    Replace existing target. Existing target is backed up to aris.backup.<timestamp>.
-
-.PARAMETER NoDoc
-    Skip updating CLAUDE.md / AGENTS.md.
-
-.PARAMETER DryRun
-    Print plan without making changes.
-
-.EXAMPLE
-    .\tools\install_aris.ps1
-    .\tools\install_aris.ps1 C:\projects\my-paper -Platform codex
-    .\tools\install_aris.ps1 -ArisRepo C:\Users\PC\.codex\Auto-claude-code-research-in-sleep -Force
+    Managed entries are tracked in .aris manifests. The script never replaces
+    real files or user-owned skill directories; conflicts must be resolved
+    explicitly.
 #>
 
 [CmdletBinding()]
@@ -68,208 +25,923 @@ param(
 
     [string]$ArisRepo = '',
 
-    [switch]$Force,
+    [switch]$DryRun,
     [switch]$NoDoc,
-    [switch]$DryRun
+    [switch]$Reconcile,
+    [switch]$Uninstall,
+    [string[]]$ReplaceLink = @(),
+    [switch]$FromOld,
+    [ValidateSet('', 'keep-user', 'prefer-upstream')]
+    [string]$MigrateCopy = '',
+    [switch]$ClearStaleLock,
+
+    # Kept only to preserve CLI recognition. It is intentionally unsafe for
+    # this installer and is rejected in favor of per-skill -ReplaceLink.
+    [switch]$Force
 )
 
 $ErrorActionPreference = 'Stop'
+$Utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+$ManifestVersion = '1'
+$SafeNameRegex = '^[A-Za-z0-9][A-Za-z0-9._-]*$'
+$SupportNames = @('shared-references')
+$script:LockDir = $null
+$script:LockAcquired = $false
 
-# ─── Resolve project path ─────────────────────────────────────────────────────
-if (-not (Test-Path $ProjectPath -PathType Container)) {
-    Write-Host "Error: project path does not exist: $ProjectPath" -ForegroundColor Red; exit 1
+function Die {
+    param([string]$Message)
+    throw $Message
+}
+
+function Normalize-PathString {
+    param([string]$Path)
+    return ([System.IO.Path]::GetFullPath($Path)).TrimEnd([char[]]@('\', '/'))
+}
+
+function Same-Path {
+    param([string]$Left, [string]$Right)
+    return [System.StringComparer]::OrdinalIgnoreCase.Equals((Normalize-PathString $Left), (Normalize-PathString $Right))
+}
+
+function Test-PathInside {
+    param([string]$Path, [string]$Root)
+    $normalizedPath = Normalize-PathString $Path
+    $normalizedRoot = Normalize-PathString $Root
+    if ([System.StringComparer]::OrdinalIgnoreCase.Equals($normalizedPath, $normalizedRoot)) {
+        return $true
+    }
+    $prefix = $normalizedRoot + [System.IO.Path]::DirectorySeparatorChar
+    return $normalizedPath.StartsWith($prefix, [System.StringComparison]::OrdinalIgnoreCase)
+}
+
+function Join-PathSegments {
+    param([string]$Root, [string[]]$Segments)
+    $path = $Root
+    foreach ($segment in $Segments) {
+        if ([string]::IsNullOrEmpty($path)) {
+            $path = $segment
+        } else {
+            $path = Join-Path $path $segment
+        }
+    }
+    return $path
+}
+
+function Get-PathSegments {
+    param([string]$Path)
+    $full = [System.IO.Path]::GetFullPath($Path)
+    $root = [System.IO.Path]::GetPathRoot($full)
+    if (-not $root) {
+        $root = ''
+    }
+    $rest = $full.Substring($root.Length).TrimEnd([char[]]@('\', '/'))
+    [string[]]$segments = @()
+    if ($rest) {
+        $segments = @($rest -split '[\\/]' | Where-Object { $_ -ne '' })
+    }
+    return [pscustomobject]@{
+        Root = $root
+        Segments = $segments
+    }
+}
+
+function Resolve-ReparseChain {
+    param([string]$Path)
+    $current = [System.IO.Path]::GetFullPath($Path)
+    $seen = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
+    for ($depth = 0; $depth -lt 40; $depth++) {
+        $normalizedCurrent = Normalize-PathString $current
+        if (-not $seen.Add($normalizedCurrent)) {
+            Die "reparse point cycle detected while resolving: $Path"
+        }
+        $parts = Get-PathSegments $current
+        $candidate = $parts.Root
+        $rewrote = $false
+        for ($index = 0; $index -lt $parts.Segments.Count; $index++) {
+            if ([string]::IsNullOrEmpty($candidate)) {
+                $candidate = $parts.Segments[$index]
+            } else {
+                $candidate = Join-Path $candidate $parts.Segments[$index]
+            }
+            $item = Get-PathItem $candidate
+            if ($null -eq $item) {
+                return $normalizedCurrent
+            }
+            if (-not (Test-LinkItem $item)) {
+                continue
+            }
+            $target = Get-LinkTarget $candidate
+            if (-not $target) {
+                return $normalizedCurrent
+            }
+            [string[]]$remaining = @()
+            if (($index + 1) -lt $parts.Segments.Count) {
+                $remaining = @($parts.Segments[($index + 1)..($parts.Segments.Count - 1)])
+            }
+            $current = Join-PathSegments $target $remaining
+            $rewrote = $true
+            break
+        }
+        if (-not $rewrote) {
+            return $normalizedCurrent
+        }
+    }
+    Die "reparse point chain too deep while resolving: $Path"
+}
+
+function Test-ResolvedPathInside {
+    param([string]$Path, [string]$Root)
+    return Test-PathInside (Resolve-ReparseChain $Path) (Resolve-ReparseChain $Root)
+}
+
+function Read-Text {
+    param([string]$Path)
+    return [System.IO.File]::ReadAllText($Path, [System.Text.Encoding]::UTF8)
+}
+
+function Write-Text {
+    param([string]$Path, [string]$Text)
+    [System.IO.File]::WriteAllText($Path, $Text, $Utf8NoBom)
+}
+
+function Get-PathItem {
+    param([string]$Path)
+    try {
+        return Get-Item -LiteralPath $Path -Force -ErrorAction Stop
+    } catch {
+        return $null
+    }
+}
+
+function Test-LinkItem {
+    param($Item)
+    return $null -ne $Item -and $Item.LinkType -in @('Junction', 'SymbolicLink')
+}
+
+function Get-LinkTarget {
+    param([string]$Path)
+    $item = Get-PathItem $Path
+    if (-not (Test-LinkItem $item)) {
+        return ''
+    }
+    $target = $item.Target
+    if ($target -is [array]) {
+        $target = $target[0]
+    }
+    if (-not [System.IO.Path]::IsPathRooted([string]$target)) {
+        $target = Join-Path (Split-Path -Parent $Path) ([string]$target)
+    }
+    return Normalize-PathString ([string]$target)
+}
+
+function Join-RelativePath {
+    param([string]$Root, [string]$Relative)
+    return Join-Path $Root ($Relative.Replace([char]'/', [char][System.IO.Path]::DirectorySeparatorChar))
 }
-$ProjectPath = (Resolve-Path $ProjectPath).Path
 
-# ─── Resolve ARIS repo location ───────────────────────────────────────────────
 function Resolve-ArisRepo {
     if ($ArisRepo) {
-        if (Test-Path (Join-Path $ArisRepo 'skills')) { return (Resolve-Path $ArisRepo).Path }
-        Write-Host "Error: -ArisRepo path has no skills/ subdir: $ArisRepo" -ForegroundColor Red; throw
+        if (-not (Test-Path -LiteralPath (Join-Path $ArisRepo 'skills') -PathType Container)) {
+            Die "-ArisRepo path has no skills directory: $ArisRepo"
+        }
+        return (Resolve-Path -LiteralPath $ArisRepo).ProviderPath
     }
-    $parent = Split-Path $PSScriptRoot -Parent
-    if (Test-Path (Join-Path $parent 'skills')) { return $parent }
-    if ($env:ARIS_REPO -and (Test-Path (Join-Path $env:ARIS_REPO 'skills'))) {
-        return (Resolve-Path $env:ARIS_REPO).Path
+
+    $parent = Split-Path -Parent $PSScriptRoot
+    if (Test-Path -LiteralPath (Join-Path $parent 'skills') -PathType Container) {
+        return (Resolve-Path -LiteralPath $parent).ProviderPath
     }
-    foreach ($p in @(
+    if ($env:ARIS_REPO -and (Test-Path -LiteralPath (Join-Path $env:ARIS_REPO 'skills') -PathType Container)) {
+        return (Resolve-Path -LiteralPath $env:ARIS_REPO).ProviderPath
+    }
+    foreach ($candidate in @(
+        (Join-Path $env:USERPROFILE 'Auto-claude-code-research-in-sleep'),
         (Join-Path $env:USERPROFILE 'aris_repo'),
-        (Join-Path $env:USERPROFILE 'Desktop\aris_repo'),
-        (Join-Path $env:USERPROFILE '.aris'),
         (Join-Path $env:USERPROFILE 'Desktop\Auto-claude-code-research-in-sleep'),
         (Join-Path $env:USERPROFILE '.codex\Auto-claude-code-research-in-sleep'),
         (Join-Path $env:USERPROFILE '.claude\Auto-claude-code-research-in-sleep')
     )) {
-        if (Test-Path (Join-Path $p 'skills')) { return $p }
+        if (Test-Path -LiteralPath (Join-Path $candidate 'skills') -PathType Container) {
+            return (Resolve-Path -LiteralPath $candidate).ProviderPath
+        }
     }
-    Write-Host "Error: cannot find ARIS repo. Use -ArisRepo PATH or set `$env:ARIS_REPO." -ForegroundColor Red
-    throw
+    Die 'cannot find ARIS repo. Use -ArisRepo PATH or set ARIS_REPO.'
 }
 
-$ArisRepoResolved = Resolve-ArisRepo
-
-# ─── Resolve platform ─────────────────────────────────────────────────────────
 function Detect-Platform {
-    $hasClaude = (Test-Path (Join-Path $ProjectPath 'CLAUDE.md')) -or `
-                 (Test-Path (Join-Path $ProjectPath '.claude\skills')) -or `
-                 (Test-Path (Join-Path $ProjectPath '.claude\settings.json'))
-    $hasCodex  = (Test-Path (Join-Path $ProjectPath 'AGENTS.md')) -or `
-                 (Test-Path (Join-Path $ProjectPath '.agents\skills')) -or `
-                 (Test-Path (Join-Path $ProjectPath '.codex\config.toml'))
-    $hasCursor = (Test-Path (Join-Path $ProjectPath '.cursor')) -or `
-                 (Test-Path (Join-Path $ProjectPath '.cursor\rules')) -or `
-                 (Test-Path (Join-Path $ProjectPath '.cursor\mcp.json'))
-
-    if ($hasCursor -and (-not $hasClaude) -and (-not $hasCodex)) { return 'cursor' }
-    if ($hasClaude -and $hasCodex) { return 'ambiguous' }
+    param([string]$ProjectRoot)
+    $hasClaude = (Test-Path -LiteralPath (Join-Path $ProjectRoot 'CLAUDE.md')) -or
+        (Test-Path -LiteralPath (Join-Path $ProjectRoot '.claude\skills')) -or
+        (Test-Path -LiteralPath (Join-Path $ProjectRoot '.claude\settings.json'))
+    $hasCodex = (Test-Path -LiteralPath (Join-Path $ProjectRoot 'AGENTS.md')) -or
+        (Test-Path -LiteralPath (Join-Path $ProjectRoot '.agents\skills')) -or
+        (Test-Path -LiteralPath (Join-Path $ProjectRoot '.codex\config.toml'))
+    if ($hasClaude -and $hasCodex) {
+        Die 'project has both Claude and Codex markers; pass -Platform claude or -Platform codex'
+    }
     if ($hasClaude) { return 'claude' }
-    if ($hasCodex)  { return 'codex' }
-    return 'unknown'
+    if ($hasCodex) { return 'codex' }
+    Die 'cannot auto-detect platform; pass -Platform claude or -Platform codex'
 }
 
-if ($Platform -eq 'auto') {
-    $detected = Detect-Platform
-    switch ($detected) {
-        'claude' { $Platform = 'claude' }
-        'codex'  { $Platform = 'codex' }
-        'cursor' {
-            Write-Host "Error: Cursor does not use a project skills directory; see docs\CURSOR_ADAPTATION.md" -ForegroundColor Red; exit 1
+function New-Config {
+    param([string]$ProjectRoot, [string]$RepoRoot, [string]$SelectedPlatform)
+    if ($SelectedPlatform -eq 'claude') {
+        return [pscustomobject]@{
+            Platform = 'claude'
+            RepoRoot = $RepoRoot
+            SourceRoot = Join-Path $RepoRoot 'skills'
+            SourceRelPrefix = 'skills'
+            TargetRel = '.claude\skills'
+            TargetRelDisplay = '.claude/skills'
+            LegacyNestedRel = '.claude\skills\aris'
+            ManifestName = 'installed-skills.txt'
+            ManifestPrevName = 'installed-skills.txt.prev'
+            LockName = '.install.lock.d'
+            DocName = 'CLAUDE.md'
+            BlockBegin = '<!-- ARIS:BEGIN -->'
+            BlockEnd = '<!-- ARIS:END -->'
+            Title = 'ARIS Skill Scope'
         }
-        'ambiguous' {
-            Write-Host "Error: project has both Claude and Codex markers; pass -Platform claude or -Platform codex" -ForegroundColor Red; exit 1
+    }
+    return [pscustomobject]@{
+        Platform = 'codex'
+        RepoRoot = $RepoRoot
+        SourceRoot = Join-Path $RepoRoot 'skills\skills-codex'
+        SourceRelPrefix = 'skills/skills-codex'
+        TargetRel = '.agents\skills'
+        TargetRelDisplay = '.agents/skills'
+        LegacyNestedRel = '.agents\skills\aris'
+        ManifestName = 'installed-skills-codex.txt'
+        ManifestPrevName = 'installed-skills-codex.txt.prev'
+        LockName = '.install-codex.lock.d'
+        DocName = 'AGENTS.md'
+        BlockBegin = '<!-- ARIS-CODEX:BEGIN -->'
+        BlockEnd = '<!-- ARIS-CODEX:END -->'
+        Title = 'ARIS Codex Skill Scope'
+    }
+}
+
+function Test-SafeName {
+    param([string]$Name)
+    return $Name -match $SafeNameRegex
+}
+
+function Build-Inventory {
+    param($Config)
+    if (-not (Test-Path -LiteralPath $Config.SourceRoot -PathType Container)) {
+        Die "source skills directory does not exist: $($Config.SourceRoot)"
+    }
+
+    $entries = New-Object System.Collections.Generic.List[object]
+    $resolvedRepoRoot = Resolve-ReparseChain $Config.RepoRoot
+    foreach ($dir in Get-ChildItem -LiteralPath $Config.SourceRoot -Directory | Sort-Object Name) {
+        $name = $dir.Name
+        if (-not (Test-SafeName $name)) {
+            Write-Warning "skipping unsafe upstream name: $name"
+            continue
         }
-        'unknown' {
-            Write-Host "Error: cannot auto-detect platform (no CLAUDE.md/AGENTS.md/.claude/.agents found)" -ForegroundColor Red
-            Write-Host "       Pass -Platform claude or -Platform codex" -ForegroundColor Yellow
-            exit 1
+        $resolved = Resolve-ReparseChain $dir.FullName
+        if (-not (Test-PathInside $resolved $resolvedRepoRoot)) {
+            Write-Warning "skipping upstream link leading outside ARIS repo: $name -> $resolved"
+            continue
+        }
+        $kind = $null
+        if ($SupportNames -contains $name) {
+            $kind = 'support'
+        } elseif (Test-Path -LiteralPath (Join-Path $dir.FullName 'SKILL.md') -PathType Leaf) {
+            $kind = 'skill'
+        } else {
+            continue
+        }
+        $sourceRel = "$($Config.SourceRelPrefix)/$name"
+        $targetRel = ($Config.TargetRelDisplay + '/' + $name)
+        $entries.Add([pscustomobject]@{
+            Kind = $kind
+            Name = $name
+            SourceRel = $sourceRel
+            TargetRel = $targetRel
+            ExpectedTarget = (Normalize-PathString $dir.FullName)
+        })
+    }
+    if ($entries.Count -eq 0) {
+        Die "upstream inventory is empty: $($Config.SourceRoot)"
+    }
+    return $entries.ToArray()
+}
+
+function Load-Manifest {
+    param([string]$Path)
+    $result = [pscustomobject]@{
+        Headers = @{}
+        Entries = @()
+        ByName = @{}
+    }
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+        return $result
+    }
+    $lines = Get-Content -LiteralPath $Path -Encoding UTF8
+    $inBody = $false
+    $entries = New-Object System.Collections.Generic.List[object]
+    foreach ($line in $lines) {
+        if ($line -eq 'kind	name	source_rel	target_rel	mode') {
+            $inBody = $true
+            continue
+        }
+        if (-not $inBody) {
+            $parts = $line -split "`t", 2
+            if ($parts.Count -eq 2) {
+                $result.Headers[$parts[0]] = $parts[1]
+            }
+            continue
+        }
+        $fields = $line -split "`t"
+        if ($fields.Count -ne 5) { continue }
+        $entry = [pscustomobject]@{
+            Kind = $fields[0]
+            Name = $fields[1]
+            SourceRel = $fields[2]
+            TargetRel = $fields[3]
+            Mode = $fields[4]
+        }
+        $entries.Add($entry)
+        $result.ByName[$entry.Name] = $entry
+    }
+    if ($result.Headers.ContainsKey('version') -and $result.Headers['version'] -ne $ManifestVersion) {
+        Die "manifest version mismatch in $Path"
+    }
+    $result.Entries = $entries.ToArray()
+    return $result
+}
+
+function Test-NameInReplaceList {
+    param([string]$Name)
+    return $ReplaceLink -contains $Name
+}
+
+function Compute-Plan {
+    param($Inventory, $Manifest, $Config, [string]$ProjectRoot, [string]$ManifestPath)
+    $plan = New-Object System.Collections.Generic.List[object]
+    $targetRoot = Join-Path $ProjectRoot $Config.TargetRel
+
+    foreach ($entry in $Inventory) {
+        $targetPath = Join-Path $targetRoot $entry.Name
+        $item = Get-PathItem $targetPath
+        $inManifest = $Manifest.ByName.ContainsKey($entry.Name)
+
+        if ($null -eq $item) {
+            $action = 'CREATE'
+            $extra = ''
+        } elseif (Test-LinkItem $item) {
+            $currentTarget = Get-LinkTarget $targetPath
+            if (Same-Path $currentTarget $entry.ExpectedTarget) {
+                $action = $(if ($inManifest) { 'REUSE' } else { 'ADOPT' })
+                $extra = ''
+            } elseif (($inManifest -or (Test-NameInReplaceList $entry.Name)) -and (Test-ResolvedPathInside $currentTarget $Config.RepoRoot)) {
+                $action = 'UPDATE_TARGET'
+                $extra = $currentTarget
+            } else {
+                $action = 'CONFLICT'
+                $extra = "link_to:$currentTarget"
+            }
+        } else {
+            $action = 'CONFLICT'
+            $extra = 'real_path'
+        }
+
+        $plan.Add([pscustomobject]@{
+            Action = $action
+            Kind = $entry.Kind
+            Name = $entry.Name
+            SourceRel = $entry.SourceRel
+            TargetRel = $entry.TargetRel
+            ExpectedTarget = $entry.ExpectedTarget
+            TargetPath = $targetPath
+            Extra = $extra
+        })
+    }
+
+    $inventoryNames = @{}
+    foreach ($entry in $Inventory) {
+        $inventoryNames[$entry.Name] = $true
+    }
+    $recordedRepo = ''
+    if ($Manifest.Headers.ContainsKey('repo_root')) {
+        $recordedRepo = $Manifest.Headers['repo_root']
+    }
+    foreach ($entry in $Manifest.Entries) {
+        if ($inventoryNames.ContainsKey($entry.Name)) {
+            continue
+        }
+        if (-not $recordedRepo) {
+            Die "manifest missing repo_root: $ManifestPath"
+        }
+        $plan.Add([pscustomobject]@{
+            Action = 'REMOVE'
+            Kind = $entry.Kind
+            Name = $entry.Name
+            SourceRel = $entry.SourceRel
+            TargetRel = $entry.TargetRel
+            ExpectedTarget = (Join-RelativePath $recordedRepo $entry.SourceRel)
+            TargetPath = (Join-RelativePath $ProjectRoot $entry.TargetRel)
+            Extra = (Join-RelativePath $recordedRepo $entry.SourceRel)
+        })
+    }
+    return $plan.ToArray()
+}
+
+function Print-Plan {
+    param($Plan, [string]$Mode)
+    Write-Host ''
+    Write-Host "ARIS Windows Install Plan"
+    Write-Host "  Mode: $Mode"
+    foreach ($action in @('CREATE', 'ADOPT', 'UPDATE_TARGET', 'REUSE', 'REMOVE', 'CONFLICT')) {
+        $count = @($Plan | Where-Object { $_.Action -eq $action }).Count
+        Write-Host ("  {0}: {1}" -f $action, $count)
+    }
+    $conflicts = @($Plan | Where-Object { $_.Action -eq 'CONFLICT' })
+    if ($conflicts.Count -gt 0) {
+        Write-Host ''
+        Write-Host 'CONFLICT entries:'
+        foreach ($item in $conflicts) {
+            Write-Host "  - $($item.Name): $($item.Extra)"
         }
     }
 }
 
-# ─── Compute paths ────────────────────────────────────────────────────────────
-switch ($Platform) {
-    'claude' {
-        $SourceDir = Join-Path $ArisRepoResolved 'skills'
-        $TargetRelative = '.claude\skills\aris'
-        $DocFile = Join-Path $ProjectPath 'CLAUDE.md'
-        $TargetRelDisplay = '.claude/skills/aris'
-    }
-    'codex' {
-        $SourceDir = Join-Path $ArisRepoResolved 'skills\skills-codex'
-        $TargetRelative = '.agents\skills\aris'
-        $DocFile = Join-Path $ProjectPath 'AGENTS.md'
-        $TargetRelDisplay = '.agents/skills/aris'
-    }
-}
-$TargetDir = Join-Path $ProjectPath $TargetRelative
-$TargetParent = Split-Path $TargetDir -Parent
-
-if (-not (Test-Path $SourceDir -PathType Container)) {
-    Write-Host "Error: source skill directory does not exist: $SourceDir" -ForegroundColor Red; exit 1
-}
-
-# ─── Print plan ───────────────────────────────────────────────────────────────
-Write-Host ""
-Write-Host "ARIS Project Install Plan"
-Write-Host "  Project:        $ProjectPath"
-Write-Host "  Platform:       $Platform"
-Write-Host "  ARIS repo:      $ArisRepoResolved"
-Write-Host "  Source:         $SourceDir"
-Write-Host "  Target:         $TargetDir  (relative: $TargetRelDisplay)"
-Write-Host "  Doc file:       $DocFile"
-if ($DryRun) { Write-Host "  Mode:           DRY-RUN (no changes)" -ForegroundColor Yellow }
-else         { Write-Host "  Mode:           APPLY" -ForegroundColor Green }
-Write-Host ""
-
-# ─── Idempotency check ────────────────────────────────────────────────────────
-if (Test-Path $TargetDir) {
-    $item = Get-Item $TargetDir -Force
-    if ($item.LinkType -in @('Junction', 'SymbolicLink')) {
-        $existingTarget = $item.Target | Select-Object -First 1
-        if ($existingTarget -eq $SourceDir) {
-            Write-Host "✓ Already installed (junction points to $SourceDir)" -ForegroundColor Green
-            exit 0
+function Check-NoSymlinkedParents {
+    param([string[]]$Paths)
+    foreach ($path in $Paths) {
+        $item = Get-PathItem $path
+        if (Test-LinkItem $item) {
+            Die "$path is a link; refusing to mutate linked parent directories"
         }
-        if (-not $Force) {
-            Write-Host "Error: target exists and points elsewhere:" -ForegroundColor Red
-            Write-Host "  Target:    $TargetDir"
-            Write-Host "  Currently: $existingTarget"
-            Write-Host "  Expected:  $SourceDir"
-            Write-Host "  Use -Force to backup and replace." -ForegroundColor Yellow
-            exit 1
-        }
-    } elseif (-not $Force) {
-        Write-Host "Error: target exists and is not a junction: $TargetDir" -ForegroundColor Red
-        Write-Host "  Use -Force to backup (as aris.backup.<timestamp>) and replace." -ForegroundColor Yellow
-        exit 1
     }
 }
 
-# ─── Apply ────────────────────────────────────────────────────────────────────
-if ($DryRun) {
-    Write-Host "(dry-run) would create junction: $TargetDir -> $SourceDir"
-    if (-not $NoDoc) { Write-Host "(dry-run) would update doc:  $DocFile" }
-    Write-Host "(dry-run) would record metadata: $ProjectPath\.aris\skill-source.txt"
-    exit 0
+function Test-ActiveLock {
+    param([string]$LockPath)
+    $pidPath = Join-Path $LockPath 'owner.pid'
+    $hostPath = Join-Path $LockPath 'owner.host'
+    if (-not (Test-Path -LiteralPath $pidPath) -or -not (Test-Path -LiteralPath $hostPath)) {
+        return $false
+    }
+    $ownerPid = (Get-Content -LiteralPath $pidPath -ErrorAction SilentlyContinue | Select-Object -First 1)
+    $ownerHost = (Get-Content -LiteralPath $hostPath -ErrorAction SilentlyContinue | Select-Object -First 1)
+    if ($ownerHost -ne [Environment]::MachineName) {
+        return $false
+    }
+    $pidNumber = 0
+    if (-not [int]::TryParse($ownerPid, [ref]$pidNumber)) {
+        return $false
+    }
+    return $null -ne (Get-Process -Id $pidNumber -ErrorAction SilentlyContinue)
 }
 
-# Backup if force-replacing
-if ((Test-Path $TargetDir) -and $Force) {
-    $backup = "${TargetDir}.backup.$(Get-Date -Format 'yyyyMMdd_HHmmss')"
-    Move-Item $TargetDir $backup
-    Write-Host "Backed up existing target to: $backup" -ForegroundColor Yellow
+function Acquire-Lock {
+    param([string]$ArisDir, [string]$LockPath)
+    if ($DryRun) { return }
+    New-Item -ItemType Directory -Force -Path $ArisDir | Out-Null
+    try {
+        New-Item -ItemType Directory -Path $LockPath -ErrorAction Stop | Out-Null
+    } catch {
+        if (-not $ClearStaleLock) {
+            Die "installer lock exists at $LockPath; rerun with -ClearStaleLock if no install is running"
+        }
+        if (Test-ActiveLock $LockPath) {
+            Die "installer lock at $LockPath belongs to a running process"
+        }
+        Remove-Item -LiteralPath $LockPath -Recurse -Force
+        New-Item -ItemType Directory -Path $LockPath -ErrorAction Stop | Out-Null
+    }
+    Write-Text (Join-Path $LockPath 'owner.pid') "$PID`n"
+    Write-Text (Join-Path $LockPath 'owner.host') "$([Environment]::MachineName)`n"
+    Write-Text (Join-Path $LockPath 'owner.json') "{`"host`":`"$([Environment]::MachineName)`",`"pid`":$PID,`"tool`":`"install_aris.ps1`"}`n"
+    $script:LockDir = $LockPath
+    $script:LockAcquired = $true
 }
 
-# Create parent dir + junction
-New-Item -ItemType Directory -Force -Path $TargetParent | Out-Null
-New-Item -ItemType Junction -Path $TargetDir -Target $SourceDir | Out-Null
-Write-Host "✓ Created junction: $TargetDir -> $SourceDir" -ForegroundColor Green
+function Release-Lock {
+    if (-not $script:LockAcquired -or -not $script:LockDir) { return }
+    Remove-Item -LiteralPath $script:LockDir -Recurse -Force -ErrorAction SilentlyContinue
+}
 
-# Record metadata
-$arisDir = Join-Path $ProjectPath '.aris'
-New-Item -ItemType Directory -Force -Path $arisDir | Out-Null
-$arisCommit = try { (git -C $ArisRepoResolved rev-parse HEAD 2>$null).Trim() } catch { 'unknown' }
-if (-not $arisCommit) { $arisCommit = 'unknown' }
-$installedAt = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
-$metaContent = @"
-platform=$Platform
-link_mode=junction
-project_path=$ProjectPath
-link_path=$TargetDir
-aris_repo=$ArisRepoResolved
-skill_source=$SourceDir
-aris_commit=$arisCommit
-installed_at=$installedAt
-"@
-Set-Content -Path (Join-Path $arisDir 'skill-source.txt') -Value $metaContent -NoNewline
-Write-Host "✓ Recorded metadata: $arisDir\skill-source.txt" -ForegroundColor Green
+function New-Junction {
+    param([string]$Path, [string]$Target)
+    New-Item -ItemType Junction -Path $Path -Target $Target | Out-Null
+}
 
-# Update managed block in CLAUDE.md / AGENTS.md
-if (-not $NoDoc) {
-    $blockBegin = '<!-- ARIS:BEGIN -->'
-    $blockEnd   = '<!-- ARIS:END -->'
-    $blockBody = @"
-$blockBegin
-## ARIS Skill Scope
-For ARIS workflows in this project, use only the project-local ARIS skills under ``$TargetRelDisplay``.
-Do not use global skills or non-ARIS project skills unless the user explicitly asks to mix them.
-$blockEnd
-"@
+function Remove-LinkPath {
+    param([string]$Path)
+    [System.IO.Directory]::Delete($Path, $false)
+}
 
-    if ((Test-Path $DocFile) -and ((Get-Content $DocFile -Raw) -match [regex]::Escape($blockBegin))) {
-        $text = Get-Content $DocFile -Raw
-        $pattern = [regex]::Escape($blockBegin) + '.*?' + [regex]::Escape($blockEnd)
-        $new = [regex]::Replace($text, $pattern, $blockBody, [System.Text.RegularExpressions.RegexOptions]::Singleline)
-        Set-Content -Path $DocFile -Value $new -NoNewline
-        Write-Host "✓ Updated managed ARIS block in: $DocFile" -ForegroundColor Green
+function Get-LegacyState {
+    param($Config, [string]$ProjectRoot)
+    $path = Join-Path $ProjectRoot $Config.LegacyNestedRel
+    $item = Get-PathItem $path
+    if ($null -eq $item) {
+        return [pscustomobject]@{ Kind = 'none'; Path = $path; Target = '' }
+    }
+    if (Test-LinkItem $item) {
+        $target = Get-LinkTarget $path
+        if (Same-Path $target $Config.SourceRoot) {
+            return [pscustomobject]@{ Kind = 'link_to_repo'; Path = $path; Target = $target }
+        }
+        return [pscustomobject]@{ Kind = 'link_to_other'; Path = $path; Target = $target }
+    }
+    if ($item.PSIsContainer) {
+        return [pscustomobject]@{ Kind = 'real_dir'; Path = $path; Target = '' }
+    }
+    return [pscustomobject]@{ Kind = 'real_file'; Path = $path; Target = '' }
+}
+
+function Assert-LegacyMigrationAllowed {
+    param($Legacy)
+    if ($Legacy.Kind -eq 'none') { return }
+    if (-not $FromOld) {
+        Die "legacy nested install detected at $($Legacy.Path); rerun with -FromOld to migrate"
+    }
+    switch ($Legacy.Kind) {
+        'link_to_repo' { return }
+        'link_to_other' { Die "legacy nested link points outside expected ARIS source: $($Legacy.Path) -> $($Legacy.Target)" }
+        'real_file' { Die "legacy nested path is a real file; move it manually before installing: $($Legacy.Path)" }
+        'real_dir' {
+            if (-not $MigrateCopy) {
+                Die "legacy nested copy detected at $($Legacy.Path); pass -MigrateCopy keep-user or -MigrateCopy prefer-upstream"
+            }
+            return
+        }
+    }
+}
+
+function Apply-LegacyMigration {
+    param($Legacy, [string]$ArisDir)
+    if ($Legacy.Kind -eq 'none') { return }
+    if ($Legacy.Kind -eq 'link_to_repo') {
+        if ($DryRun) {
+            Write-Host "  (dry-run) remove legacy nested link $($Legacy.Path)"
+        } else {
+            Remove-LinkPath $Legacy.Path
+            Write-Host "  - legacy nested link"
+        }
+    }
+}
+
+function Archive-LegacyCopy {
+    param($Legacy, [string]$ArisDir)
+    if ($Legacy.Kind -ne 'real_dir' -or $MigrateCopy -ne 'prefer-upstream') { return }
+    if ($DryRun) {
+        Write-Host "  (dry-run) archive legacy nested copy $($Legacy.Path)"
+        return
+    }
+    New-Item -ItemType Directory -Force -Path $ArisDir | Out-Null
+    $stamp = (Get-Date).ToUniversalTime().ToString('yyyyMMddTHHmmssZ')
+    $archive = Join-Path $ArisDir "legacy-copy-backup-$stamp"
+    Move-Item -LiteralPath $Legacy.Path -Destination $archive
+    Write-Host "  - archived legacy nested copy to $archive"
+}
+
+function Ensure-ToolsJunction {
+    param([string]$ArisDir, [string]$RepoRoot)
+    $linkPath = Join-Path $ArisDir 'tools'
+    $expectedTarget = Join-Path $RepoRoot 'tools'
+    if (-not (Test-Path -LiteralPath $expectedTarget -PathType Container)) {
+        Write-Warning "ARIS tools directory not found: $expectedTarget"
+        return
+    }
+    $item = Get-PathItem $linkPath
+    if (Test-LinkItem $item) {
+        $currentTarget = Get-LinkTarget $linkPath
+        if (Same-Path $currentTarget $expectedTarget) { return }
+        Write-Warning ".aris\tools already points to $currentTarget; leaving it unchanged"
+        return
+    }
+    if ($null -ne $item) {
+        Write-Warning ".aris\tools already exists as a real path; leaving it unchanged"
+        return
+    }
+    if ($DryRun) {
+        Write-Host "  (dry-run) junction $linkPath -> $expectedTarget"
+        return
+    }
+    New-Item -ItemType Directory -Force -Path $ArisDir | Out-Null
+    New-Junction $linkPath $expectedTarget
+    Write-Host "  + .aris\tools"
+}
+
+function Remove-ToolsJunction {
+    param([string]$ArisDir, [string]$RepoRoot, [string]$CurrentManifestName = '')
+    $linkPath = Join-Path $ArisDir 'tools'
+    $expectedTarget = Join-Path $RepoRoot 'tools'
+    $item = Get-PathItem $linkPath
+    if (-not (Test-LinkItem $item)) { return }
+    $currentTarget = Get-LinkTarget $linkPath
+    if (-not (Same-Path $currentTarget $expectedTarget)) { return }
+    foreach ($manifestName in @('installed-skills.txt', 'installed-skills-codex.txt')) {
+        if ($manifestName -eq $CurrentManifestName) { continue }
+        $otherManifestPath = Join-Path $ArisDir $manifestName
+        if (-not (Test-Path -LiteralPath $otherManifestPath -PathType Leaf)) { continue }
+        $otherManifest = Load-Manifest $otherManifestPath
+        if ($otherManifest.Headers.ContainsKey('repo_root') -and (Same-Path $otherManifest.Headers['repo_root'] $RepoRoot)) {
+            Write-Host "  = .aris\tools (kept; $manifestName still uses this ARIS repo)"
+            return
+        }
+    }
+    if ($DryRun) {
+        Write-Host "  (dry-run) remove $linkPath"
     } else {
-        if ((Test-Path $DocFile) -and ((Get-Item $DocFile).Length -gt 0)) {
-            Add-Content -Path $DocFile -Value ""
-        }
-        Add-Content -Path $DocFile -Value $blockBody
-        Write-Host "✓ Appended managed ARIS block to: $DocFile" -ForegroundColor Green
+        Remove-LinkPath $linkPath
+        Write-Host "  - .aris\tools"
     }
 }
 
-Write-Host ""
-Write-Host "Install complete. Update with: cd $ArisRepoResolved; git pull" -ForegroundColor Cyan
+function Apply-Plan {
+    param($Plan, [string]$RepoRoot)
+    foreach ($entry in $Plan) {
+        switch ($entry.Action) {
+            'REUSE' { continue }
+            'ADOPT' { continue }
+            'CREATE' {
+                if ($DryRun) {
+                    Write-Host "  (dry-run) junction $($entry.TargetPath) -> $($entry.ExpectedTarget)"
+                    continue
+                }
+                if (Get-PathItem $entry.TargetPath) {
+                    Die "path appeared during install: $($entry.TargetPath)"
+                }
+                New-Item -ItemType Directory -Force -Path (Split-Path -Parent $entry.TargetPath) | Out-Null
+                New-Junction $entry.TargetPath $entry.ExpectedTarget
+                Write-Host "  + $($entry.Name)"
+            }
+            'UPDATE_TARGET' {
+                if ($DryRun) {
+                    Write-Host "  (dry-run) relink $($entry.TargetPath) -> $($entry.ExpectedTarget)"
+                    continue
+                }
+                $currentTarget = Get-LinkTarget $entry.TargetPath
+                if (-not (Same-Path $currentTarget $entry.Extra)) {
+                    Die "link target changed during install for $($entry.Name)"
+                }
+                if (-not (Test-ResolvedPathInside $currentTarget $RepoRoot)) {
+                    Die "refusing to relink $($entry.Name); current target is outside ARIS repo: $currentTarget"
+                }
+                Remove-LinkPath $entry.TargetPath
+                New-Junction $entry.TargetPath $entry.ExpectedTarget
+                Write-Host "  > $($entry.Name)"
+            }
+            'REMOVE' {
+                $item = Get-PathItem $entry.TargetPath
+                if ($null -eq $item) {
+                    Write-Host "  - $($entry.Name) (already absent)"
+                    continue
+                }
+                if (-not (Test-LinkItem $item)) {
+                    Write-Warning "skipping $($entry.Name); target is no longer a junction/symlink"
+                    continue
+                }
+                $currentTarget = Get-LinkTarget $entry.TargetPath
+                if (-not (Same-Path $currentTarget $entry.Extra)) {
+                    Write-Warning "skipping $($entry.Name); target changed to $currentTarget"
+                    continue
+                }
+                if ($DryRun) {
+                    Write-Host "  (dry-run) remove $($entry.TargetPath)"
+                } else {
+                    Remove-LinkPath $entry.TargetPath
+                    Write-Host "  - $($entry.Name)"
+                }
+            }
+            'CONFLICT' {
+                Die "conflict reached apply phase for $($entry.Name)"
+            }
+        }
+    }
+}
+
+function New-ManifestContent {
+    param($Plan, [string]$RepoRoot, [string]$ProjectRoot, [string]$PlatformName)
+    $lines = New-Object System.Collections.Generic.List[string]
+    $lines.Add("version`t$ManifestVersion")
+    $lines.Add("repo_root`t$RepoRoot")
+    $lines.Add("project_root`t$ProjectRoot")
+    $lines.Add("platform`t$PlatformName")
+    $lines.Add("generated`t$((Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ'))")
+    $lines.Add("kind`tname`tsource_rel`ttarget_rel`tmode")
+    foreach ($entry in $Plan | Where-Object { $_.Action -in @('REUSE', 'ADOPT', 'CREATE', 'UPDATE_TARGET') } | Sort-Object Name) {
+        $lines.Add("$($entry.Kind)`t$($entry.Name)`t$($entry.SourceRel)`t$($entry.TargetRel)`tjunction")
+    }
+    return ($lines -join "`n") + "`n"
+}
+
+function Commit-Manifest {
+    param([string]$ManifestPath, [string]$ManifestPrevPath, [string]$Content)
+    if ($DryRun) {
+        Write-Host "  (dry-run) would commit manifest $ManifestPath"
+        return
+    }
+    $manifestDir = Split-Path -Parent $ManifestPath
+    New-Item -ItemType Directory -Force -Path $manifestDir | Out-Null
+    $tmp = "$ManifestPath.tmp.$PID"
+    Write-Text $tmp $Content
+    if (Test-Path -LiteralPath $ManifestPath -PathType Leaf) {
+        Copy-Item -LiteralPath $ManifestPath -Destination "$ManifestPrevPath.tmp" -Force
+        Move-Item -LiteralPath "$ManifestPrevPath.tmp" -Destination $ManifestPrevPath -Force
+    }
+    Move-Item -LiteralPath $tmp -Destination $ManifestPath -Force
+}
+
+function Update-ManagedDoc {
+    param($Config, [string]$DocPath, [string]$RepoRoot, [string]$ProjectRoot, [int]$Count)
+    if ($NoDoc) { return }
+    $reconcileCommand = "powershell -NoProfile -ExecutionPolicy Bypass -File `"$RepoRoot\tools\install_aris.ps1`" `"$ProjectRoot`" -Platform $($Config.Platform) -Reconcile"
+    $block = @"
+$($Config.BlockBegin)
+## $($Config.Title)
+ARIS skills installed in this project: $Count entries.
+Manifest: ``.aris/$($Config.ManifestName)``
+ARIS repo root: ``$RepoRoot``
+Project skill path: ``$($Config.TargetRelDisplay)/<skill-name>``
+For ARIS workflows, prefer the project-local skills under ``$($Config.TargetRelDisplay)/``.
+Do not edit or delete junctioned skills in place; update upstream or rerun:
+``$reconcileCommand``
+$($Config.BlockEnd)
+"@
+    $original = ''
+    if (Test-Path -LiteralPath $DocPath -PathType Leaf) {
+        $original = Read-Text $DocPath
+    }
+    $newContent = $null
+    if ($original.Contains($Config.BlockBegin)) {
+        $pattern = [regex]::Escape($Config.BlockBegin) + '.*?' + [regex]::Escape($Config.BlockEnd)
+        $newContent = [regex]::Replace(
+            $original,
+            $pattern,
+            [System.Text.RegularExpressions.MatchEvaluator]{ param($m) $block },
+            [System.Text.RegularExpressions.RegexOptions]::Singleline
+        )
+    } else {
+        $separator = ''
+        if ($original.Length -gt 0 -and -not $original.EndsWith("`n")) {
+            $separator = "`n"
+        }
+        $newContent = $original + $separator + $block + "`n"
+    }
+    Write-Text $DocPath $newContent
+}
+
+function Remove-ManagedDocBlock {
+    param($Config, [string]$DocPath)
+    if ($NoDoc -or -not (Test-Path -LiteralPath $DocPath -PathType Leaf)) { return }
+    if ($DryRun) {
+        Write-Host "  (dry-run) would remove managed block from $DocPath"
+        return
+    }
+    $original = Read-Text $DocPath
+    if (-not $original.Contains($Config.BlockBegin)) { return }
+    $pattern = "`r?`n?" + [regex]::Escape($Config.BlockBegin) + '.*?' + [regex]::Escape($Config.BlockEnd) + "`r?`n?"
+    $newContent = [regex]::Replace(
+        $original,
+        $pattern,
+        [System.Text.RegularExpressions.MatchEvaluator]{ param($m) "`n" },
+        [System.Text.RegularExpressions.RegexOptions]::Singleline
+    ).TrimStart("`r", "`n")
+    Write-Text $DocPath $newContent
+}
+
+function Do-Uninstall {
+    param($Config, [string]$ProjectRoot, [string]$ManifestPath, [string]$ManifestPrevPath, [string]$DocPath)
+    if (-not (Test-Path -LiteralPath $ManifestPath -PathType Leaf)) {
+        Die "no manifest at $ManifestPath; nothing to uninstall"
+    }
+    $manifest = Load-Manifest $ManifestPath
+    if (-not $manifest.Headers.ContainsKey('repo_root')) {
+        Die "manifest missing repo_root: $ManifestPath"
+    }
+    $recordedRepo = $manifest.Headers['repo_root']
+    Write-Host ''
+    Write-Host 'Uninstall plan:'
+    foreach ($entry in $manifest.Entries) {
+        Write-Host "  - $($entry.Name) ($($entry.Kind))"
+    }
+    foreach ($entry in $manifest.Entries) {
+        $targetPath = Join-RelativePath $ProjectRoot $entry.TargetRel
+        $expectedTarget = Join-RelativePath $recordedRepo $entry.SourceRel
+        $item = Get-PathItem $targetPath
+        if ($null -eq $item) { continue }
+        if (-not (Test-LinkItem $item)) {
+            Write-Warning "skipping $($entry.Name); target path is not a junction/symlink"
+            continue
+        }
+        $currentTarget = Get-LinkTarget $targetPath
+        if (Same-Path $currentTarget $expectedTarget) {
+            if ($DryRun) {
+                Write-Host "  (dry-run) remove $targetPath"
+            } else {
+                Remove-LinkPath $targetPath
+                Write-Host "  - removed $($entry.Name)"
+            }
+        } else {
+            Write-Warning "skipping $($entry.Name); target changed to $currentTarget"
+        }
+    }
+    Remove-ToolsJunction (Split-Path -Parent $ManifestPath) $recordedRepo $Config.ManifestName
+    if (-not $DryRun) {
+        Move-Item -LiteralPath $ManifestPath -Destination $ManifestPrevPath -Force
+    }
+    Remove-ManagedDocBlock $Config $DocPath
+}
+
+function Invoke-Main {
+    if ($Force) {
+        Die '-Force is no longer supported. Use -ReplaceLink NAME for a specific existing junction/symlink; real files are never overwritten.'
+    }
+    if ($Reconcile -and $Uninstall) {
+        Die '-Reconcile and -Uninstall are mutually exclusive'
+    }
+    if (-not (Test-Path -LiteralPath $ProjectPath -PathType Container)) {
+        Die "project path does not exist: $ProjectPath"
+    }
+    $projectRoot = (Resolve-Path -LiteralPath $ProjectPath).ProviderPath
+    $repoRoot = Resolve-ArisRepo
+    $selectedPlatform = $Platform
+    if ($selectedPlatform -eq 'auto') {
+        $selectedPlatform = Detect-Platform $projectRoot
+    }
+    $config = New-Config $projectRoot $repoRoot $selectedPlatform
+    $arisDir = Join-Path $projectRoot '.aris'
+    $manifestPath = Join-Path $arisDir $config.ManifestName
+    $manifestPrevPath = Join-Path $arisDir $config.ManifestPrevName
+    $docPath = Join-Path $projectRoot $config.DocName
+    $targetRoot = Join-Path $projectRoot $config.TargetRel
+    $lockPath = Join-Path $arisDir $config.LockName
+    $mode = $(if ($DryRun) { 'DRY-RUN' } elseif ($Uninstall) { 'UNINSTALL' } elseif ($Reconcile) { 'RECONCILE' } else { 'APPLY' })
+
+    Write-Host ''
+    Write-Host 'ARIS Project Install'
+    Write-Host "  Project:  $projectRoot"
+    Write-Host "  Platform: $selectedPlatform"
+    Write-Host "  Repo:     $repoRoot"
+    Write-Host "  Target:   $targetRoot"
+    Write-Host "  Mode:     $mode"
+
+    Check-NoSymlinkedParents @($arisDir, (Split-Path -Parent $targetRoot), $targetRoot)
+
+    if ($Uninstall) {
+        if (-not $DryRun) { Acquire-Lock $arisDir $lockPath }
+        Do-Uninstall $config $projectRoot $manifestPath $manifestPrevPath $docPath
+        return
+    }
+
+    $legacy = Get-LegacyState $config $projectRoot
+    Assert-LegacyMigrationAllowed $legacy
+
+    if ($Reconcile -and -not (Test-Path -LiteralPath $manifestPath -PathType Leaf)) {
+        Die "-Reconcile requires existing manifest; none found at $manifestPath"
+    }
+
+    $inventory = Build-Inventory $config
+    $manifest = Load-Manifest $manifestPath
+    $plan = Compute-Plan $inventory $manifest $config $projectRoot $manifestPath
+    Print-Plan $plan $mode
+
+    $conflicts = @($plan | Where-Object { $_.Action -eq 'CONFLICT' })
+    if ($conflicts.Count -gt 0) {
+        Die "CONFLICT: $($conflicts.Count) existing path(s) must be resolved before install"
+    }
+
+    if ($DryRun) {
+        Apply-LegacyMigration $legacy $arisDir
+        Archive-LegacyCopy $legacy $arisDir
+        Ensure-ToolsJunction $arisDir $repoRoot
+        Write-Host ''
+        Write-Host '(dry-run) no changes made'
+        return
+    }
+
+    Acquire-Lock $arisDir $lockPath
+    Apply-LegacyMigration $legacy $arisDir
+    New-Item -ItemType Directory -Force -Path $targetRoot | Out-Null
+    Write-Host ''
+    Write-Host 'Applying:'
+    Apply-Plan $plan $repoRoot
+    $manifestContent = New-ManifestContent $plan $repoRoot $projectRoot $selectedPlatform
+    Commit-Manifest $manifestPath $manifestPrevPath $manifestContent
+    Ensure-ToolsJunction $arisDir $repoRoot
+    Archive-LegacyCopy $legacy $arisDir
+    $managedCount = @($plan | Where-Object { $_.Action -in @('REUSE', 'ADOPT', 'CREATE', 'UPDATE_TARGET') }).Count
+    Update-ManagedDoc $config $docPath $repoRoot $projectRoot $managedCount
+    Write-Host ''
+    Write-Host "Install complete. Managed entries: $managedCount"
+}
+
+$exitCode = 0
+try {
+    Invoke-Main
+} catch {
+    Write-Error $_.Exception.Message
+    $exitCode = 1
+} finally {
+    Release-Lock
+}
+exit $exitCode