acstack 0.53.0 → 0.54.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "acstack",
   "description": "Agentic coding stack where planning grows only as far as needed: a map of decisions, tasks, checks, and handoffs behind a pluggable tracker.",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "author": {
     "name": "ac8318740"
   },

package/README.md

@@ -61,11 +61,11 @@ Then, in your project:
 /acstack:setup
 ```
 
-- `/acstack:setup` detects the project type, then writes `.acstack/project.yaml` with workflow settings
-- All ACStack-owned project records stay local by default under `.acstack/`
-    - Setup asks which parts to track, with none selected by default
-    - Native exceptions after the root `.gitignore` baseline let you track configuration, specs, decisions, or any other part independently
-    - See [Project data and migration](docs/config-reference.md#project-data-stays-local-by-default) for canonical paths and commands
+- `/acstack:setup` detects the project type, then writes `project.yaml` with workflow settings into the project folder
+- All ACStack-owned project records live in one project folder per repository, shared by all of its worktrees
+    - `~/.claude/acstack/bin/acstack project-data path` prints it; by default it is `~/.acstack/projects/<key>/`, outside the repository
+    - Run `acstack project-data mode tracked` to keep the records in the repository's `.acstack/` and commit them instead
+    - See [Where project data lives](docs/config-reference.md#where-project-data-lives) for paths, modes, and commands
 - Update installed ACStack tools before migrating an older project
     - Stop old agents and reviews, run `~/.claude/acstack/bin/acstack project-data migrate`, then restart with updated tools
     - Migration aborts on collisions without overwrites or Git index changes; tracked old paths become pending deletions
@@ -141,7 +141,7 @@ The three commands:
     - Each question comes with the agent's recommended answer
     - You provide feedback on the agent's recommended answer instead of prompting from scratch
     - Some requests only need one question
-    - The agent writes that decision down as a short note under `.acstack/decisions/`
+    - The agent writes that decision down as a short note under `<project folder>/decisions/`
     - A big feature may need dozens of questions
     - The agent stores those questions as a **map**
     - You work through the map across several sessions
@@ -169,7 +169,7 @@ Each node also records six things.
 - **Who answers it**: you, or the agent working alone
 - **What kind it is**: a destination, a standing note, a decision, research, or work
 - **A short name**, which labels the node in a diagram
-- **Where it lives**: a GitHub issue by default, or a markdown file under `.acstack/maps/` with no GitHub remote
+- **Where it lives**: a GitHub issue by default, or a markdown file under `<project folder>/maps/` with no GitHub remote
 
 Almost every node explains itself with a diagram.
 
@@ -193,9 +193,9 @@ For the full picture of each step and how they connect, read [docs/workflows.md]
 
 *The project states what to run. The machine states what it can do.*
 
-- `.acstack/project.yaml` holds every project-scoped setting
+- `project.yaml` in the project folder holds every project-scoped setting
     - [docs/config-reference.md](docs/config-reference.md) gives each key, its values, its default and what changes
-- `~/.config/acstack/config.json` holds the nine `host.*` axes
+- `~/.acstack/config.json` holds the nine `host.*` axes
     - `/acstack:host` writes eight of them once per machine, and `/acstack:setup` writes the ninth
     - [docs/dev-setups.md](docs/dev-setups.md) gives every axis, what reads it, and how to describe a fresh machine
 - `/acstack:setup` copies the commands and directories from one of three language profiles
@@ -216,7 +216,7 @@ ACStack ships a Node.js CLI: `acstack config`, `acstack list`, `acstack node ...
         - The first line of every issue body carries all of that node's edges
         - One call therefore reads the whole map
         - A sub-issue and an issue dependency mirror those edges, so GitHub's own interface draws the map
-    - Markdown files are the fallback, one per node under `.acstack/maps/<name>/`
+    - Markdown files are the fallback, one per node under `<project folder>/maps/<name>/`
 - The CLI builds everything else on those four operations
     - `acstack node frontier` lists what is ready to start now, closest to the original goal first
     - `acstack node walk` packs the whole map into one brief for a fresh session, in the order the decisions happened
@@ -260,7 +260,7 @@ For work with open decisions, chart it with `/acstack:map` first.
 
 | Skill | Description |
 |-------|-------------|
-| `/acstack:commit` | Commit, and update the specs under `.acstack/specs/` from the diff first |
+| `/acstack:commit` | Commit, and update the specs under `<project folder>/specs/` from the diff first |
 | `/acstack:archive` | Verify implemented specs and current design approval, retain review evidence, then dispose of temporary map nodes |
 | `/acstack:sync` | Update the specs from code changes, outside a commit |
 | `/acstack:handoff` | Hand work to a visible agent, a new one in its own pane or one already running, with acknowledgement |

package/agents/codex/frontend-verifier.toml

@@ -22,7 +22,7 @@ You review screenshots. You report results. You do not need user approval.
 
 ## Project configuration
 
-Read `.acstack/project.yaml` for frontend settings:
+ACStack keeps project data in the project folder, the path `~/.claude/acstack/bin/acstack project-data path` prints. Read `<project folder>/project.yaml` for frontend settings:
 
 - `frontend.directory` – frontend source directory
 - `frontend.dev_server_url` – dev server URL
@@ -33,14 +33,15 @@ Read `.acstack/project.yaml` for frontend settings:
 
 You do not read `frontend.browser.mode` or `frontend.browser.fallback`. Step 3 asks the ACStack CLI which browser mode to use, and the CLI reads both.
 
-If `.acstack/project.yaml` has no `frontend` section, report SKIP and exit.
+If `<project folder>/project.yaml` has no `frontend` section, report SKIP and exit.
 
 ## Step 0: Read the knowledge base
 
 Before doing anything, check for a knowledge base:
 
 ```bash
-cat .acstack/verification/VERIFICATION-KNOWLEDGE.md 2>/dev/null
+project="$(~/.claude/acstack/bin/acstack project-data path)"
+cat "$project/verification/VERIFICATION-KNOWLEDGE.md" 2>/dev/null
 ```
 
 This file contains URL patterns, element patterns, gotchas, and lessons learned. Read it if it exists. If not, you'll create it in Step 7.
@@ -199,10 +200,10 @@ Track whether you launched the browser so you can clean it up in Step 8.
 
 ## Step 4: Verify with agent-browser
 
-Select the project's browser config explicitly from the project root:
+Select the project's browser config explicitly by its absolute path:
 
 ```bash
-export AGENT_BROWSER_CONFIG="$(pwd)/.acstack/agent-browser.json"
+export AGENT_BROWSER_CONFIG="$(~/.claude/acstack/bin/acstack project-data path)/agent-browser.json"
 ```
 
 Require the file for configured verification; do not assume root config autodiscovery.
@@ -293,13 +294,13 @@ After every verification run, update the knowledge base if you learned something
 
 ### Knowledge base
 
-`.acstack/verification/VERIFICATION-KNOWLEDGE.md` – URL patterns, element patterns, gotchas, lessons learned.
+`<project folder>/verification/VERIFICATION-KNOWLEDGE.md` – URL patterns, element patterns, gotchas, lessons learned.
 
 If it doesn't exist, create it with what you learned during this run.
 
 ### Rules
 
-- All verification knowledge lives in `.acstack/verification/VERIFICATION-KNOWLEDGE.md`.
+- All verification knowledge lives in `<project folder>/verification/VERIFICATION-KNOWLEDGE.md`.
 - Do NOT create knowledge files anywhere else.
 - If a selector or element pattern stops working, update the knowledge base.
 - If you discover a new pattern, add it.

package/agents/codex/task-checker.toml

@@ -15,7 +15,7 @@ You are read-only: do not edit source, tests, or specs.
 ## Establish scope and ownership
 
 Read the supplied requirements, affected paths, known risks, and available command results.
-Read `.acstack/project.yaml` for commands, directories, environment activation, and applicable frontend gates.
+Read `project.yaml` in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for commands, directories, environment activation, and applicable frontend gates.
 
 - Distinguish focused review from ownership of completion verification
 - If the assignment is unclear, clarify it with the delegating session before duplicating checks

package/agents/codex/task-executor.toml

@@ -17,7 +17,7 @@ Implement the assigned requirements under the shared Implementation discipline i
 
 ## Project configuration
 
-Read `.acstack/project.yaml` for project-specific settings:
+Read `project.yaml` in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for project-specific settings:
 
 - `directories.source` – where to write source code
 - `directories.tests` – test directory, subject to assigned ownership

package/agents/codex/test-writer.toml

@@ -26,7 +26,7 @@ You write tests from requirements and application programming interface (API) co
 
 ## Project configuration
 
-Read `.acstack/project.yaml` for project-specific settings:
+Read `project.yaml` in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for project-specific settings:
 
 - `directories.tests` – where to create test files
 - `directories.source` – source code root (for mirroring structure)

package/agents/frontend-verifier.md

@@ -22,7 +22,7 @@ You review screenshots. You report results. You do not need user approval.
 
 ## Project configuration
 
-Read `.acstack/project.yaml` for frontend settings:
+ACStack keeps project data in the project folder, the path `~/.claude/acstack/bin/acstack project-data path` prints. Read `<project folder>/project.yaml` for frontend settings:
 
 - `frontend.directory` – frontend source directory
 - `frontend.dev_server_url` – dev server URL
@@ -33,14 +33,15 @@ Read `.acstack/project.yaml` for frontend settings:
 
 You do not read `frontend.browser.mode` or `frontend.browser.fallback`. Step 3 asks the ACStack CLI which browser mode to use, and the CLI reads both.
 
-If `.acstack/project.yaml` has no `frontend` section, report SKIP and exit.
+If `<project folder>/project.yaml` has no `frontend` section, report SKIP and exit.
 
 ## Step 0: Read the knowledge base
 
 Before doing anything, check for a knowledge base:
 
 ```bash
-cat .acstack/verification/VERIFICATION-KNOWLEDGE.md 2>/dev/null
+project="$(~/.claude/acstack/bin/acstack project-data path)"
+cat "$project/verification/VERIFICATION-KNOWLEDGE.md" 2>/dev/null
 ```
 
 This file contains URL patterns, element patterns, gotchas, and lessons learned. Read it if it exists. If not, you'll create it in Step 7.
@@ -199,10 +200,10 @@ Track whether you launched the browser so you can clean it up in Step 8.
 
 ## Step 4: Verify with agent-browser
 
-Select the project's browser config explicitly from the project root:
+Select the project's browser config explicitly by its absolute path:
 
 ```bash
-export AGENT_BROWSER_CONFIG="$(pwd)/.acstack/agent-browser.json"
+export AGENT_BROWSER_CONFIG="$(~/.claude/acstack/bin/acstack project-data path)/agent-browser.json"
 ```
 
 Require the file for configured verification; do not assume root config autodiscovery.
@@ -293,13 +294,13 @@ After every verification run, update the knowledge base if you learned something
 
 ### Knowledge base
 
-`.acstack/verification/VERIFICATION-KNOWLEDGE.md` – URL patterns, element patterns, gotchas, lessons learned.
+`<project folder>/verification/VERIFICATION-KNOWLEDGE.md` – URL patterns, element patterns, gotchas, lessons learned.
 
 If it doesn't exist, create it with what you learned during this run.
 
 ### Rules
 
-- All verification knowledge lives in `.acstack/verification/VERIFICATION-KNOWLEDGE.md`.
+- All verification knowledge lives in `<project folder>/verification/VERIFICATION-KNOWLEDGE.md`.
 - Do NOT create knowledge files anywhere else.
 - If a selector or element pattern stops working, update the knowledge base.
 - If you discover a new pattern, add it.

package/agents/task-checker.md

@@ -15,7 +15,7 @@ You are read-only: do not edit source, tests, or specs.
 ## Establish scope and ownership
 
 Read the supplied requirements, affected paths, known risks, and available command results.
-Read `.acstack/project.yaml` for commands, directories, environment activation, and applicable frontend gates.
+Read `project.yaml` in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for commands, directories, environment activation, and applicable frontend gates.
 
 - Distinguish focused review from ownership of completion verification
 - If the assignment is unclear, clarify it with the delegating session before duplicating checks

package/agents/task-executor.md

@@ -17,7 +17,7 @@ Implement the assigned requirements under the shared Implementation discipline i
 
 ## Project configuration
 
-Read `.acstack/project.yaml` for project-specific settings:
+Read `project.yaml` in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for project-specific settings:
 
 - `directories.source` – where to write source code
 - `directories.tests` – test directory, subject to assigned ownership

package/agents/test-writer.md

@@ -26,7 +26,7 @@ You write tests from requirements and application programming interface (API) co
 
 ## Project configuration
 
-Read `.acstack/project.yaml` for project-specific settings:
+Read `project.yaml` in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for project-specific settings:
 
 - `directories.tests` – where to create test files
 - `directories.source` – source code root (for mirroring structure)

package/assets/playwriter-bridge/doctor.ps1

@@ -163,7 +163,7 @@ if (-not (Test-Path $openerToken)) {
     # A token here is only half of it: the dev machine needs the same bytes, and
     # nothing on this side can see whether it has them. Say so rather than
     # calling it green and leaving a VM that gets 401 on every request.
-    Add-Result 'Opener token' 'green' 'present here (each VM needs the same copy at ~/.config/acstack/opener.token)'
+    Add-Result 'Opener token' 'green' 'present here (each VM needs the same copy at ~/.acstack/opener.token)'
 }
 
 if ($openerListener -and (Test-Path $openerToken)) {

package/assets/playwriter-bridge/register-tasks.ps1

@@ -258,7 +258,7 @@ if (-not (Test-Path $sshExe)) {
         # A warning, never a throw. The tasks are already registered by this
         # point and the start loop is still ahead, so throwing here left every
         # task registered and none of them running.
-        Write-Warning "ssh.exe not found, so the opener token was not pushed. Enable the Windows OpenSSH Client optional feature, then copy $tokenFile to ~/.config/acstack/opener.token on each VM by hand."
+        Write-Warning "ssh.exe not found, so the opener token was not pushed. Enable the Windows OpenSSH Client optional feature, then copy $tokenFile to ~/.acstack/opener.token on each VM by hand."
         $sshExe = $null
     }
 }
@@ -268,7 +268,7 @@ foreach ($vm in $VMs) {
     # Single-quoted on the remote side so the shell there cannot interpret it,
     # and 0600 because it is a bearer credential for opening pages on this
     # screen.
-    $cmd = "mkdir -p ~/.config/acstack && umask 077 && printf '%s' '$token' > ~/.config/acstack/opener.token"
+    $cmd = "mkdir -p ~/.acstack && umask 077 && printf '%s' '$token' > ~/.acstack/opener.token"
     # $ErrorActionPreference is 'Stop' for this script, and merging a native
     # command's stderr into the pipeline under it turns any stderr line into a
     # terminating NativeCommandError. ssh writes one on a first connection:
@@ -281,9 +281,9 @@ foreach ($vm in $VMs) {
     $sshCode = $LASTEXITCODE
     $ErrorActionPreference = $prevEap
     if ($sshCode -eq 0) {
-        Write-Host "  $vm : token installed at ~/.config/acstack/opener.token"
+        Write-Host "  $vm : token installed at ~/.acstack/opener.token"
     } else {
-        Write-Warning "  $vm : could not push the token (ssh exit $sshCode). Copy $tokenFile to ~/.config/acstack/opener.token on that VM by hand."
+        Write-Warning "  $vm : could not push the token (ssh exit $sshCode). Copy $tokenFile to ~/.acstack/opener.token on that VM by hand."
     }
 }
 

package/assets/terminal-workspace/config.example.yaml

@@ -1,5 +1,5 @@
 # ACStack terminal workspace.
-# Copy to ~/.config/acstack/terminal-workspace.yaml, edit, then run
+# Copy to ~/.acstack/terminal-workspace.yaml, edit, then run
 # setup.sh apply.
 #
 # This is machine-level, not per-project. It installs binaries and writes
@@ -190,7 +190,7 @@ harlequin:
   # schema, or a single connection_name pointing at a connection in
   # ~/.snowflake/connections.toml. Prefer the second: it keeps the secret out
   # of this file.
-  config_path: "~/.config/acstack/harlequin.toml"
+  config_path: "~/.acstack/harlequin.toml"
 
 pi:
   # Off by default, because it writes into pi's own config in ~/.pi/agent.

package/assets/terminal-workspace/helpers/acstack-bridge

@@ -17,7 +17,7 @@ set -uo pipefail
 
 BRIDGE="${ACSTACK_BRIDGE_URL:-http://127.0.0.1:19988}"
 OPENER="${ACSTACK_OPENER_URL:-http://127.0.0.1:19989}"
-OPENER_TOKEN="${XDG_CONFIG_HOME:-$HOME/.config}/acstack/opener.token"
+OPENER_TOKEN="${ACSTACK_HOME:-$HOME/.acstack}/opener.token"
 FREE_PORT="${ACSTACK_FREE_PORT:-$HOME/.claude/acstack/bin/vm-free-port.sh}"
 
 CMD="${1:-status}"
@@ -120,6 +120,8 @@ case "$CMD" in
       echo "opener:  reachable - $(printf '%s' "$health" | tr -d '[:space:]')"
     elif [ -z "$(tok)" ]; then
       echo "opener:  no token at $OPENER_TOKEN (run register-tasks.ps1 on the laptop)"
+      [ -e "$HOME/.config/acstack/opener.token" ] \
+        && echo "         an old one is in ~/.config/acstack: run ~/.claude/acstack/bin/acstack project-data migrate"
     else
       echo "opener:  not reachable on $OPENER"
     fi

package/assets/terminal-workspace/helpers/acstack-db

@@ -9,7 +9,7 @@
 set -uo pipefail
 # apply rewrites this line from harlequin.config_path. What ships here is the
 # default, so the helper is right even on a machine nothing rewrote it on.
-DB_CFG_DEFAULT="~/.config/acstack/harlequin.toml"  # acstack:config_path
+DB_CFG_DEFAULT="~/.acstack/harlequin.toml"  # acstack:config_path
 CFG="${ACSTACK_DB_CONFIG:-$DB_CFG_DEFAULT}"
 # A human writes ~ for home, and a human writes this config. Expanding it here
 # rather than at write time keeps the helper right on a machine whose HOME is

package/assets/terminal-workspace/helpers/acstack-md

@@ -29,7 +29,7 @@ BRIDGE="${ACSTACK_BRIDGE_URL:-http://127.0.0.1:19988}"
 OPENER="${ACSTACK_OPENER_URL:-http://127.0.0.1:19989}"
 # The opener refuses anything without this, so its absence is the same as the
 # opener being down - which is exactly how the route probe treats it.
-OPENER_TOKEN="${XDG_CONFIG_HOME:-$HOME/.config}/acstack/opener.token"
+OPENER_TOKEN="${ACSTACK_HOME:-$HOME/.acstack}/opener.token"
 SERVE=0; ONLY=0; PREVIEW=0; HTML=0; BROWSER=0; NUMBERED=0; TOGGLE=0
 usage() { echo "usage: acstack-md [--preview] [--numbered] [--toggle-line-numbers] [--diagram N] [--serve|--html|--browser] FILE.md" >&2; exit 1; }
 # The preview pane and the key that flips it are two processes that never meet,
@@ -155,6 +155,8 @@ case "$(command -v acstack-open >/dev/null 2>&1 && acstack-open --why 2>/dev/nul
     if [ -z "$tok" ]; then
       echo "acstack-md: no opener token at $OPENER_TOKEN." >&2
       echo "  run register-tasks.ps1 on the laptop to install one." >&2
+      [ -e "$HOME/.config/acstack/opener.token" ] \
+        && echo "  or move the old one: ~/.claude/acstack/bin/acstack project-data migrate" >&2
       exit 1
     fi
     hex() { od -An -v -tx1 | tr -d ' \n'; }
@@ -163,7 +165,7 @@ case "$(command -v acstack-open >/dev/null 2>&1 && acstack-open --why 2>/dev/nul
     # Vendored mermaid, uploaded once so diagrams draw without reaching a
     # CDN. Best effort throughout: the opener redirects to the CDN when it
     # has no copy, so a failure here costs nothing but an outbound fetch.
-    vendored="$HOME/.local/share/acstack/mermaid.min.js"
+    vendored="${ACSTACK_HOME:-$HOME/.acstack}/cache/mermaid.min.js"
     # tr, because whitespace inside JSON carries no meaning and a match that
     # depends on its absence is a match waiting to break. Same reasoning as
     # acstack-open's /json/list check.

package/assets/terminal-workspace/helpers/acstack-md-lib

@@ -105,14 +105,14 @@ if [ "${ACSTACK_MD_OPENER:-0}" = "1" ] && [ "$HTML" = "1" ]; then MODE=opener; f
 # exec -a names the process. Without it a running server is just "python3 -"
 # and there is nothing sensible to pkill.
 exec -a "$NAME" python3 - "$FILE" "$PORT" "$MODE" <<'PY'
-import html, http.server, pathlib, re, socketserver, sys
+import html, http.server, os, pathlib, re, socketserver, sys
 try:
   import markdown
 except ImportError:
   sys.exit("acstack-md: needs the python markdown package: pip install --user markdown")
 
 src, port, MODE = pathlib.Path(sys.argv[1]), int(sys.argv[2]), sys.argv[3]
-VENDOR = pathlib.Path.home() / ".local/share/acstack/mermaid.min.js"
+VENDOR = pathlib.Path(os.environ.get("ACSTACK_HOME") or pathlib.Path.home() / ".acstack") / "cache/mermaid.min.js"
 
 CSS = """*{box-sizing:border-box}body{max-width:54rem;margin:0 auto;padding:2rem 1.25rem;
 font:16px/1.65 -apple-system,Segoe UI,system-ui,sans-serif;color:#1a1a1a;background:#fff}

package/assets/terminal-workspace/helpers/acstack-open

@@ -23,7 +23,7 @@ BRIDGE="${ACSTACK_BRIDGE_URL:-${AGENT_BROWSER_CDP:-http://127.0.0.1:19988}}"
 OPENER="${ACSTACK_OPENER_URL:-http://127.0.0.1:19989}"
 # The opener refuses anything without this, so its absence is the same as the
 # opener being down - which is exactly how the route probe treats it.
-OPENER_TOKEN="${XDG_CONFIG_HOME:-$HOME/.config}/acstack/opener.token"
+OPENER_TOKEN="${ACSTACK_HOME:-$HOME/.acstack}/opener.token"
 
 WHY=0
 [ "${1:-}" = "--why" ] && { WHY=1; shift; }

package/assets/terminal-workspace/lib/apply-herdr-numbers.sh

@@ -2,7 +2,7 @@ apply_herdr_numbers() {
   have herdr || return 0
   [ "$(cfg_get herdr.renumber_plugin true)" = "true" ] || return 0
 
-  local dir="$HOME/.config/acstack/herdr-numbers"
+  local dir="$ACSTACK_ROOT/herdr-numbers"
   mkdir -p "$dir"
   # An absolute command: herdr runs argv without a shell and resolves relative
   # commands from the plugin root, not from PATH.

package/assets/terminal-workspace/lib/apply-tools.sh

@@ -4,7 +4,7 @@ apply_markdown() {
   install_binary glow charmbracelet/glow Linux_x86_64
   # Vendored so the preview page pulls nothing from a CDN: it works offline,
   # and on a managed laptop there is no third-party fetch to explain.
-  local share="$HOME/.local/share/acstack"
+  local share="$ACSTACK_ROOT/cache"
   mkdir -p "$share"
   if [ ! -s "$share/mermaid.min.js" ]; then
     curl -fsSL -o "$share/mermaid.min.js" \

package/assets/terminal-workspace/lib/apply-tuicr.sh

@@ -65,7 +65,7 @@ managed = set()
 if from_fork == "true":
     block += [
         "# These two keys exist only in the fork build. See the tuicr section",
-        "# of ~/.config/acstack/terminal-workspace.yaml.",
+        "# of ~/.acstack/terminal-workspace.yaml.",
         f"show_file_line_stats = {stats}",
         f"file_list_width = {width}",
         "# A local build must not be replaced by a stock release.",
@@ -81,7 +81,7 @@ else:
 # terminal. Pinning the value sidesteps the whole detection path.
 if appearance:
     block += ["# Pinned rather than detected. See the tuicr section of",
-              "# ~/.config/acstack/terminal-workspace.yaml.",
+              "# ~/.acstack/terminal-workspace.yaml.",
               f'appearance = "{appearance}"']
     managed.add("appearance")
 block.append(end)

package/assets/terminal-workspace/lib/commands.sh

@@ -238,7 +238,7 @@ PY
     # By prefix, which is why helpers are named acstack-*: anything this
     # script ever wrote goes, including helpers retired in an older version.
     herdr plugin unlink acstack.herdr-numbers >/dev/null 2>&1 || true
-    rm -rf "$HOME/.config/acstack/herdr-numbers"
+    rm -rf "$ACSTACK_ROOT/herdr-numbers"
     rm -f "$BIN"/acstack-*
     # The xclip stand-in is the one managed file without the prefix.
     grep -q "Installed by acstack" "$BIN/xclip" 2>/dev/null && rm -f "$BIN/xclip"

package/assets/terminal-workspace/lib/helper-install.sh

@@ -15,7 +15,7 @@ write_helpers() {
 
   # The one helper with a path in the config. The source holds the default, so
   # this carries nothing but a value the user chose.
-  ACSTACK_DB_CFG="$(cfg_get harlequin.config_path "~/.config/acstack/harlequin.toml")" \
+  ACSTACK_DB_CFG="$(cfg_get harlequin.config_path "~/.acstack/harlequin.toml")" \
     py "$BIN/acstack-db" <<'PY'
 import os, re, sys
 # A bash single-quoted literal, so a path with a space or a quote in it reaches

package/assets/terminal-workspace/setup.sh

@@ -20,7 +20,12 @@ set -uo pipefail
 
 SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "${BASH_SOURCE[0]:-$0}")" && pwd)"
 
-CFG="${ACSTACK_TW_CONFIG:-$HOME/.config/acstack/terminal-workspace.yaml}"
+# ACStack's machine-wide root. An empty ACSTACK_HOME counts as unset.
+ACSTACK_ROOT="${ACSTACK_HOME:-$HOME/.acstack}"
+CFG="${ACSTACK_TW_CONFIG:-$ACSTACK_ROOT/terminal-workspace.yaml}"
+# The old home is never read, only named, so a move is one command away.
+[ ! -e "$CFG" ] && [ -e "$HOME/.config/acstack/terminal-workspace.yaml" ] \
+  && echo "acstack: config is still at ~/.config/acstack; run ~/.claude/acstack/bin/acstack project-data migrate" >&2
 BIN="${ACSTACK_TW_BIN:-$HOME/.local/bin}"
 # Everything installs into $BIN, and the config steps then ask `have <tool>`
 # whether it worked. On a fresh machine $BIN is not on PATH yet, so without