From b3fd0aa3ee0997af91e18855eb8928144bdede2b Mon Sep 17 00:00:00 2001
From: morluto <76467478+morluto@users.noreply.github.com>
Date: Tue, 27 Oct 2026 22:52:33 +0800
Subject: [PATCH] test(setup): align Hermes symlink preview expectations

---
 docs/client-configuration.md                  | 20 +++++++------------
 .../setup/hermesClientSetup.test.ts           |  2 +-
 2 files changed, 8 insertions(+), 14 deletions(-)

diff --git a/docs/client-configuration.md b/docs/client-configuration.md
index 8fdb5b6732..0ef0a2c063 100644
--- a/docs/client-configuration.md
+++ b/docs/client-configuration.md
@@ -507,9 +507,9 @@ another definition later reuses the same anchor name.
 Hermes personal skills install under the active Hermes home's `skills` directory.
 Setup, doctor and uninstall share REA's sticky-profile resolver.
 A custom `HERMES_HOME` outside the platform default home
-reads its own `active_profile`. An existing override directory physically inside
-the default home uses that default home's sticky selection and profile root
-together.
+reads its own `active_profile`. An override physically inside the default home
+uses that default home's sticky selection and profile root together, including
+when the final override directory does not yet exist.
 
 For example, with `HERMES_HOME=~/.hermes/sub` and `~/.hermes/active_profile` set
 to `coder`, setup selects `~/.hermes/profiles/coder/config.yaml` and that
@@ -527,16 +527,10 @@ the profile Hermes actually uses and point `HERMES_HOME` directly at that
 `profiles/<name>` directory before setup. Compatibility is tracked in
 [#3939](https://github.com/morluto/rea/issues/3939).
 
-Before setup, create an override directory whose path includes a symlink,
-junction, or another prefix that resolves to a different spelling. When the
-override does not exist, REA falls back to its lexical spelling for containment.
-This can miss physical containment — for example, beneath a symlinked default
-home or `HOME`/`USERPROFILE`/`LOCALAPPDATA` ancestor — ignoring the outer selection
-and planning the override root's configuration. It can also falsely assume
-containment: if `~/.hermes/link` points outside the default home,
-`HERMES_HOME=~/.hermes/link/new` can select the default home's profile even though
-the override lies outside it. Once the override directory exists, REA checks its
-physical location. Inspect setup's previewed destinations before applying changes.
+REA resolves existing ancestors when checking containment, including symlinks
+and junctions, even if the final override directory is missing. An unresolved
+home path is reported instead of guessing its location. Inspect setup's
+previewed destinations before applying changes.
 
 An explicit `HERMES_HOME` pointing to `profiles/<name>` selects that named
 profile directly, bypassing sticky selection. An invalid, missing or deleted
diff --git a/tests/acceptance/setup/hermesClientSetup.test.ts b/tests/acceptance/setup/hermesClientSetup.test.ts
index d6361fe519..41888d87ed 100644
--- a/tests/acceptance/setup/hermesClientSetup.test.ts
+++ b/tests/acceptance/setup/hermesClientSetup.test.ts
@@ -561,7 +561,7 @@ for (const layout of ["symlinked-default", "escaping-prefix"] as const) {
       await writeFile(join(native, "active_profile"), "coder");
       for (const exists of [false, true]) {
         if (exists) await mkdir(root);
-        const usesNative = layout === "symlinked-default" ? exists : !exists;
+        const usesNative = layout === "symlinked-default";
         const selected = usesNative ? profile : root;
         const plan = await cli.run({
           arguments: ["setup", "--client", "hermes", "--dry-run", "--json"],