acstack 0.53.1 → 0.54.0

package/skills/handoff/SKILL.md

@@ -53,7 +53,7 @@ its answer looks wrong. It says why a child must stop, and what it checks.
 ## First: is this yours to invoke?
 
 If the user asked for a handoff, proceed. If you invoke it on your own
-initiative, first read `workflow.handoff.self_invoke` from `.acstack/project.yaml`.
+initiative, first read `workflow.handoff.self_invoke` from `project.yaml` in the folder `~/.claude/acstack/bin/acstack project-data path` prints.
 
 If it is `false`, stop. Tell the user a handoff looks warranted and why. Ask
 permission.
@@ -101,8 +101,8 @@ it should run the command.
 | Map state and reading order | `~/.claude/acstack/bin/acstack node walk --map <name>` (reading order of the map)  |
 | What can be worked next     | `~/.claude/acstack/bin/acstack node frontier --map <name>` (what is workable now)  |
 | Files in flight             | `git status --short` and `git diff`                                                |
-| Test baseline, last result  | `.acstack/.test-baseline` and referenced check logs; reuse valid evidence under the shared policy |
-| What the code does          | the living specs in `.acstack/specs/`                                               |
+| Test baseline, last result  | `<project folder>/.test-baseline` and referenced check logs; reuse valid evidence under the shared policy |
+| What the code does          | the living specs in `<project folder>/specs/`                                               |
 
 On GitHub, `--map` refuses – pipe `gh issue list` into `--stdin` per the
 map skill's `trackers/github.md`.
@@ -157,7 +157,7 @@ Its first line repeats the acknowledgement requirement verbatim, with
 Acknowledge before any other tool call. Run ~/.claude/acstack/bin/acstack handoff ack accept --file <this-file> "<one-line reason>", or ack decline --file <this-file> "<one-line reason>". The command writes <this-file>.ack, which the sender watches.
 ```
 
-This temp file is not `.acstack/HANDOFF.md`, the `compact-and-continue` anchor.
+This temp file is not `<project folder>/HANDOFF.md`, the `compact-and-continue` anchor.
 Never put this line into that anchor, which has to start with `---` frontmatter.
 
 Head the rest with the same skeleton the `compact-and-continue` anchor uses. The

package/skills/host/SKILL.md

@@ -28,8 +28,8 @@ Three terms, before they get used:
 
 ## Why this is per machine, not per project
 
-The answers go to the ACStack CLI's global config, never to
-`.acstack/project.yaml`. Read [`notes.md`](notes.md) when the user asks why.
+The answers go to the ACStack CLI's global config, never to the
+project's `project.yaml`. Read [`notes.md`](notes.md) when the user asks why.
 
 ## What this skill installs
 

package/skills/host/detect-host.sh

@@ -245,11 +245,15 @@ project_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
 # A top-level `frontend:` key in the project config is what turns on frontend
 # verification, so we look for it at column zero only - `frontend:` nested under
 # some other key means something else entirely.
+# The config lives in the repository's project folder, which the CLI reports.
 has_frontend="false"
-if [ -n "$project_root" ] && [ -f "${project_root}/.acstack/project.yaml" ]; then
-  if grep -q '^frontend:' "${project_root}/.acstack/project.yaml" 2>/dev/null; then
-    has_frontend="true"
-  fi
+acstack_cli="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/cli/bin/acstack.js"
+project_folder=""
+if [ -n "$project_root" ] && command -v node >/dev/null 2>&1; then
+  project_folder="$(node "$acstack_cli" project-data path 2>/dev/null || true)"
+fi
+if [ -n "$project_folder" ] && grep -q '^frontend:' "${project_folder}/project.yaml" 2>/dev/null; then
+  has_frontend="true"
 fi
 
 # --- output ----------------------------------------------------------------

package/skills/host/herdr.md

@@ -69,7 +69,7 @@ Copy your own if you want them. Nothing in ACStack needs any of them.
 `assets/terminal-workspace/setup.sh apply` fences `[keys]`, one
 `[[keys.command]]` per binding, and `[worktrees]` between these same two
 markers. It takes the directory from `herdr.worktrees_directory` in
-`~/.config/acstack/terminal-workspace.yaml`. A machine that has run it needs
+`~/.acstack/terminal-workspace.yaml`. A machine that has run it needs
 nothing from this installer.
 
 The installer therefore leaves that block alone. It reports the step as skipped

package/skills/host/install-herdr-block.sh

@@ -348,7 +348,7 @@ if [ -f "$CONFIG" ]; then
         err "$CONFIG holds a block between these markers that this script did not write."
         err "Besides $BLOCK_TABLE that block defines: $FOREIGN_TABLES"
         err "terminal-workspace setup.sh writes that block, and it carries the keymap and the popup key bindings. Replacing it with the four lines this script writes would delete all of it."
-        err "setup.sh writes $BLOCK_TABLE itself, from herdr.worktrees_directory in ~/.config/acstack/terminal-workspace.yaml."
+        err "setup.sh writes $BLOCK_TABLE itself, from herdr.worktrees_directory in ~/.acstack/terminal-workspace.yaml."
         refuse "set the directory there and run terminal-workspace setup.sh apply instead. Nothing has been changed."
       fi
     else

package/skills/host/notes.md

@@ -16,11 +16,12 @@ None of that is a property of the project, so none of it belongs in the
 project's config file.
 
 The answers therefore go to the global config of the ACStack command-line
-interface. That is a JSON file at `~/.config/acstack/config.json`, or under
-`$XDG_CONFIG_HOME` when you set that environment variable. Run
+interface. That is a JSON file at `~/.acstack/config.json`, or under
+`$ACSTACK_HOME` when you set that environment variable. Run
 `~/.claude/acstack/bin/acstack config path` to print the real location.
 
-They do not go in `.acstack/project.yaml`.
+They do not go in the project's `project.yaml`, which sits in the project
+folder that `~/.claude/acstack/bin/acstack project-data path` prints.
 
 Project concerns stay in `project.yaml`. In particular
 `frontend.browser.mode` stays there as the *project's preference*, while
@@ -77,7 +78,7 @@ git worktrees and say so. An environment variable for an orchestrator that was
 never declared is worth a warning, not a refusal.
 
 **The host declares, the project prefers.** `host.browser.*` says what this
-machine can do. `frontend.browser.mode` in `.acstack/project.yaml` says what the
+machine can do. `frontend.browser.mode` in `<project folder>/project.yaml` says what the
 project would like.
 
 Today the only thing that compares the two is the ACStack command-line

package/skills/host/questions.md

@@ -22,7 +22,7 @@ What it reports, and what each field is evidence for:
 | `orca_topology.serve_unit_active` | A user-level service named exactly `orca` is running, which is the shape of a machine serving Orca to a viewer elsewhere. The name is an assumption: whatever provisions the server picks it, and nothing pins it yet. A unit installed under any other name reads here as "no server". The topology recommendation below then comes out `local` when this machine has Orca, and stays empty when it does not |
 | `claude_settings.orca_hooks_present` | `~/.claude/settings.json` mentions Orca somewhere. The match is a loose, case-insensitive search for that word anywhere in the file, so an unrelated path or permission entry containing it counts too – this is evidence that Orca has wired its hooks in, not proof |
 | `claude_settings.backup_exists` | `~/.claude/settings.json.bak` exists |
-| `project.root`, `project.has_frontend` | The git repository the current directory sits in, and whether its `.acstack/project.yaml` configures a frontend |
+| `project.root`, `project.has_frontend` | The git repository the current directory sits in, and whether its `project.yaml` in the project folder configures a frontend |
 
 Several sections also carry a `recommended` field. That is the script's
 mechanical reading of the evidence above it and nothing more. It is a starting

package/skills/host/report.md

@@ -36,7 +36,7 @@ Get the `Config:` line by running the command, not by writing the usual path in:
 ~/.claude/acstack/bin/acstack config path
 ```
 
-`~/.config/acstack/config.json` is only where the file lands by default. Setting
-the `XDG_CONFIG_HOME` environment variable moves it. On a machine that sets that
+`~/.acstack/config.json` is only where the file lands by default. Setting
+the `ACSTACK_HOME` environment variable moves it. On a machine that sets that
 variable, a hardcoded path in the report would point at a file that does not
 exist.

package/skills/implement/SKILL.md

@@ -22,7 +22,8 @@ $ARGUMENTS
 ### 1. Find the work
 
 Check the configured tracker for maps (`workflow.maps.tracker` in
-`.acstack/project.yaml`; the map skill's `trackers/` docs declare the
+`<project folder>/project.yaml`, where the project folder is the path
+`~/.claude/acstack/bin/acstack project-data path` prints; the map skill's `trackers/` docs declare the
 operations – files backend shown below).
 
 **A map exists** (or `$ARGUMENTS` names one):
@@ -55,7 +56,7 @@ small unit of work, and nothing has to declare it small.
 
 ### 2. Read project configuration
 
-Read `.acstack/project.yaml` for build/test/lint commands and directory paths.
+Read `<project folder>/project.yaml` for build/test/lint commands and directory paths.
 
 ### 3. Create feature branch
 
@@ -125,11 +126,11 @@ Apply the shared Implementation discipline to the claimed node or bare request.
 
 
 **Decision log**: on afk nodes, append one row per decision point to
-`<main checkout>/.acstack/decision-logs/<name>.tsv`. A decision point is a fork chosen, a
+`<project folder>/decision-logs/<name>.tsv`. A decision point is a fork chosen, a
 unit verified, a revert, or a blocker.
 
-Read `decision-log.md` before the first row. It holds how to find the main
-checkout, the columns, and the root ignore baseline.
+Read `decision-log.md` before the first row. It holds where the log lives and
+the columns.
 
 **Parallelism**: use teams when independent nodes benefit from parallel work.
 Assign non-overlapping files, and schedule shared-file changes sequentially.

package/skills/implement/decision-log.md

@@ -18,25 +18,20 @@ gets no row.
 
 ## Where the log lives
 
-The log is one file per map, in the main checkout:
-`<main checkout>/.acstack/decision-logs/<name>.tsv`. The `<name>` is the map name
-you pass to `--map`.
-
-Write it in the main checkout, never in a worktree. Removing a worktree
-deletes its gitignored files, so a log there vanishes before `archive` reads
-it. Find the main checkout from any worktree:
+The log is one file per map, in the project folder:
+`<project folder>/decision-logs/<name>.tsv`. The project folder is the path
+`~/.claude/acstack/bin/acstack project-data path` prints. Every worktree of the
+repository shares it, so a log survives when its worktree is removed and
+`archive` can still read it. The `<name>` is the map name you pass to `--map`.
 
 ```bash
-main=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
+log="$(~/.claude/acstack/bin/acstack project-data path)/decision-logs/<name>.tsv"
 ```
 
-- The root managed baseline ignores `.acstack/decision-logs/` by default
-- Check the main checkout's layout before creating or writing the log
-- If it still has legacy project records, stop with an actionable migration error
-- Tell the user to update installed tools, stop old agents and reviews, and explicitly migrate that checkout before restarting
-- Never move another checkout's records automatically or create a partial `.acstack/` there
-- On an already migrated main checkout, run `~/.claude/acstack/bin/acstack project-data ensure` before writing the log
-- Do not add a nested ignore file; native exceptions in the root `.gitignore` alone control tracking
+- If `project-data path` fails because legacy project records exist, stop and pass its message on
+    - Tell the user to update installed tools, stop old agents and review servers, and run `acstack project-data migrate` before restarting
+    - Never move records automatically or create a partial project folder to work around legacy data
+- Create `decision-logs/` in the project folder if it is missing
 
 ## What a row holds
 

package/skills/implement/design-pass.md

@@ -32,7 +32,7 @@ Load that context before your first edit under `frontend.directory`. Load it onc
 
 **Check the design gate first**
 
-The design gate is the set of optional checks impeccable adds to acstack's pipeline. `workflow.design_review` in `.acstack/project.yaml` turns the gate on. Ask acstack for the answer:
+The design gate is the set of optional checks impeccable adds to acstack's pipeline. `workflow.design_review` in `<project folder>/project.yaml` turns the gate on; the project folder is the path `~/.claude/acstack/bin/acstack project-data path` prints. Ask acstack for the answer:
 
 ```bash
 ~/.claude/acstack/bin/acstack design-gate --json
@@ -94,7 +94,7 @@ impeccable installs its own PostToolUse hook, a check Claude Code runs right aft
 - Follow the shared Implementation discipline in `orchestrator/AGENTS.md`
 - The verification owner gathers the file list, completes static checks, and handles the detector
     - A delegated task-checker may own this work, but its presence is optional
-- Read `.acstack/project.yaml` before deriving paths
+- Read `<project folder>/project.yaml` before deriving paths
     - This pass requires a configured `frontend`
     - `frontend.directory` defaults to `frontend/` when omitted
     - If the project configures no frontend, warn that `frontend.directory` is missing and skip this pass

package/skills/map/SKILL.md

@@ -23,7 +23,9 @@ frontier, claim, resolve and walk.
 Two backends ship in this skill's directory: `trackers/github.md` for repos
 with GitHub auth, and `trackers/files.md` as the fallback.
 
-`workflow.maps.tracker` in `.acstack/project.yaml` (`github` or `files`) records
+ACStack keeps project data in the project folder, the path
+`~/.claude/acstack/bin/acstack project-data path` prints.
+`workflow.maps.tracker` in `<project folder>/project.yaml` (`github` or `files`) records
 the project's choice. If the key names a backend, read the matching doc and use
 its operations. If the key is absent, pick at materialisation time – the moment
 you first write the map's nodes down.
@@ -33,7 +35,7 @@ choice with the user. Then write the key, so later sessions need not re-decide.
 ## Which mode
 
 One command runs two modes, and what already exists picks between them. Check
-the configured tracker for existing maps – `ls .acstack/maps/` on the files
+the configured tracker for existing maps – `ls "$(~/.claude/acstack/bin/acstack project-data path)/maps/"` on the files
 backend, `gh label list --search "map:" --json name` on GitHub.
 
 If `$ARGUMENTS` names a map, or exactly one exists, work its frontier – the
@@ -51,7 +53,7 @@ still one map.
 
 2. **Load the frontend branch on a frontend destination.** `frontend.md`
    beside this skill holds five more rules. Read it when the destination
-   touches `frontend.directory`, the path in `.acstack/project.yaml` where the
+   touches `frontend.directory`, the path in `<project folder>/project.yaml` where the
    frontend lives. Every other map skips it.
 
 3. **Open with a breadth-first grill.** Work the conversation frontier in

package/skills/map/frontend.md

@@ -4,8 +4,8 @@ A map whose destination changes the frontend carries five rules that no other
 map loads, and this file holds all five.
 
 `SKILL.md` decides when to read this file. The destination has to touch
-`frontend.directory`, the path in `.acstack/project.yaml` where the frontend
-lives.
+`frontend.directory`, the path in `<project folder>/project.yaml` where the frontend
+lives. The project folder is the path `acstack project-data path` prints.
 
 Two plugins appear in the rules below.
 

package/skills/map/materialising.md

@@ -65,10 +65,12 @@ operation. First the root:
   The root is a parent too, and it draws the whole map.
 
 - When a design is required:
-    - Record `Design entry: <repository-relative-path>` in the root node body
+    - Record `Design entry: <path>` in the root node body
+        - Write the path relative to the project folder, such as `designs/<id>/design.yaml`, or relative to the repository for a design kept in the repository
+        - ACStack resolves it against the project folder first, then the current checkout
     - Bind the entry back to the map with `planning: {tracker: files | github, map: <name>}`
     - Require `design-review status` to return that same `planning` binding before using its approval for this map
     - Record proposals in the node body's `## Design contributions` section using the format in `/acstack:design-doc`
     - Reconcile proposals and saved feedback explicitly; surface conflicts as decision nodes
-- On the files backend, the root Git ignore rules exclude `.acstack/maps/` unless the user opts in
-  ([`trackers/files.md`](trackers/files.md) gives the reason).
+- On the files backend, nodes live in `<project folder>/maps/`, outside the repository unless the project uses tracked mode
+  ([`trackers/files.md`](trackers/files.md) gives the details).

package/skills/map/trackers/files.md

@@ -1,16 +1,18 @@
 # Files tracker
 
 The fallback backend: no auth, works offline, works on any remote. One
-markdown file per node under `.acstack/maps/<name>/`, managed by the ACStack
+markdown file per node under `<project folder>/maps/<name>/`, managed by the ACStack
 CLI. Nodes here are transient working state – scratch discarded once the map
 clears.
 
-The root managed baseline ignores `.acstack/maps/` by default.
-Native exceptions after that baseline let the user opt in to tracking any part.
+The project folder is the path `~/.claude/acstack/bin/acstack project-data path`
+prints. In global mode, the default, it sits outside the repository, so nodes
+are never committed. In tracked mode it is the main checkout's committed
+`.acstack/`, and the developer decides what to commit.
 
 CLI path: `~/.claude/acstack/bin/acstack`
 
-To enumerate a project's maps: `ls .acstack/maps/`.
+To enumerate a project's maps: `ls "$(~/.claude/acstack/bin/acstack project-data path)/maps/"`.
 
 ## The four operations
 

package/skills/pre-commit-review/SKILL.md

@@ -59,7 +59,7 @@ git status --short
 git log --oneline -3  # recent context
 ```
 
-Read `.acstack/project.yaml` to understand the project's directory layout, commands, and conventions.
+Read `<project folder>/project.yaml` to understand the project's directory layout, commands, and conventions. ACStack keeps it in the project folder, the path `~/.claude/acstack/bin/acstack project-data path` prints.
 
 Categorize changed files into scopes using the project configuration:
 
@@ -86,9 +86,9 @@ Read `../../output-styles/ac-writing-style.md` relative to this skill directory;
 
 ```
 Read the living specs relevant to this change:
-- Check .acstack/specs/ directory listing
+- Check the <project folder>/specs/ directory listing
 - Read spec.md files for domains touched by the changed files
-  (use .acstack/domain-map.yaml to map files -> domains)
+  (use <project folder>/domain-map.yaml to map files -> domains)
 - Extract documented conventions, patterns, and requirements (FR-NNN entries)
 Report: list of project conventions and patterns relevant to these changes.
 ```

package/skills/quick-fix/SKILL.md

@@ -95,7 +95,7 @@ Apply the shared policy to the minimal fix.
 ## Step 6: Verify
 
 Use focused regression checks while fixing. One verification owner gathers the
-required final checks from `.acstack/project.yaml` under Build verification in
+required final checks from `project.yaml` in the project folder, the path `~/.claude/acstack/bin/acstack project-data path` prints, under Build verification in
 `orchestrator/AGENTS.md`, reusing valid evidence rather than rerunning commands
 for every fix or handoff.
 

package/skills/record-context/SKILL.md

@@ -25,7 +25,7 @@ an obvious choice buries the ones that matter.
 
 ### Writing one
 
-- Path: `.acstack/decisions/NNNN-slug.md`. The number is the highest existing number plus
+- Path: `<project folder>/decisions/NNNN-slug.md`, in the project folder, the path `~/.claude/acstack/bin/acstack project-data path` prints. The number is the highest existing number plus
   one, zero-padded to four digits. Create the directory lazily.
 
     If the file for that number appeared since you scanned (a parallel teammate
@@ -41,7 +41,7 @@ an obvious choice buries the ones that matter.
 
 ### Example
 
-`.acstack/decisions/0004-invariant-tool-path.md`:
+`<project folder>/decisions/0004-invariant-tool-path.md`:
 
 ```markdown
 # One invariant path for the command line tool
@@ -64,7 +64,7 @@ the hook has not run. The fix is to restart the agent session.
 
 ### You generate the index
 
-After writing any ADR, rewrite `.acstack/decisions/index.md` in full, with one line
+After writing any ADR, rewrite `<project folder>/decisions/index.md` in full, with one line
 per ADR. Sort the lines by number, ascending. Each line takes its number
 and slug from the filename, and its title from the file's first heading:
 
@@ -80,9 +80,9 @@ If you find hand edits in it, regenerate; the files are the truth.
 If the decision fixed what a word means – picked between competing names,
 sharpened a fuzzy term, coined one – record it:
 
-- **Cross-domain terms** go in `.acstack/CONTEXT.md`.
-- **Domain terms** go in `.acstack/specs/<domain>/CONTEXT.md`, beside that
-  domain's `spec.md`. Find the domain in `.acstack/domain-map.yaml`.
+- **Cross-domain terms** go in `<project folder>/CONTEXT.md`.
+- **Domain terms** go in `<project folder>/specs/<domain>/CONTEXT.md`, beside that
+  domain's `spec.md`. Find the domain in `<project folder>/domain-map.yaml`.
 
 - Create both files lazily; there is no index file –
   `domain-map.yaml` already lists every domain.

package/skills/setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup
-description: Set up ACStack in a project, and change how an already configured project is set up. With no .acstack/project.yaml it detects the project type, writes the config, generates the domain map and offers browser verification. With one already there it leads with the health check, then offers to fix each row that failed. Both paths end in the same check, so it is safe to run on the first day and on any day after.
+description: Set up ACStack in a project, and change how an already configured project is set up. With no project.yaml in the project folder it detects the project type, writes the config, generates the domain map and offers browser verification. With one already there it leads with the health check, then offers to fix each row that failed. Both paths end in the same check, so it is safe to run on the first day and on any day after.
 argument-hint: "[what to set up or change]"
 disable-model-invocation: true
 ---
@@ -18,7 +18,7 @@ join at the health check, so this skill states every fix once.
 
 ```mermaid
 flowchart TD
-    HOST["Step 1<br/>declare this machine"] --> FORK{".acstack/project.yaml<br/>is here?"}
+    HOST["Step 1<br/>declare this machine"] --> FORK{"project.yaml in the<br/>project folder?"}
     FORK -- no --> FIRST["Steps 3 to 6<br/>detect, ask, write the config"]
     FORK -- yes --> CHECK
     FIRST --> CHECK["Step 7<br/>acstack config check --json"]
@@ -74,16 +74,25 @@ answers. Come back to Step 2 when it finishes.
 
 ## Step 2: Choose the path
 
-Run `~/.claude/acstack/bin/acstack project-data ensure` before checking for configuration.
-It needs no config, does nothing without `.acstack/`, and preserves user tracking exceptions.
-
-If legacy project records remain, explain the explicit migration procedure in `docs/config-reference.md` before proceeding.
-Never move them silently or run Git index commands.
+ACStack keeps project data in the project folder, one per repository and shared
+by all of its worktrees. `acstack project-data path` prints its absolute path,
+even before the folder exists. These files write its parts as
+`<project folder>/project.yaml` and so on.
 
 ```bash
-test -f .acstack/project.yaml && echo present || echo absent
+project="$(~/.claude/acstack/bin/acstack project-data path)" &&
+  { test -f "$project/project.yaml" && echo present || echo absent; }
 ```
 
+If `project-data path` fails, show its message and stop. Outside a Git
+repository there is no project folder. For legacy project records, orphaned
+entries, or conflicts, the message names the `acstack project-data` command
+that fixes it.
+
+For legacy records, explain the explicit migration procedure in
+`docs/config-reference.md` before proceeding. Never move data silently or run
+Git index commands.
+
 - **absent** – take the first-run path. Go to Step 3.
 - **present** – take the re-run path. Go straight to Step 7.
 
@@ -118,7 +127,7 @@ CLI. An agent testing this branch before the release runs
 It prints one object to standard output and nothing else:
 
 ```json
-{"checks": [{"id": "domain-map", "status": "pass", "message": ".acstack/domain-map.yaml maps 4 domains"}]}
+{"checks": [{"id": "domain-map", "status": "pass", "message": "domain-map.yaml maps 4 domains"}]}
 ```
 
 Each `status` is `pass`, `fail` or `info`. The exit codes carry the same news:
@@ -199,8 +208,8 @@ Read [`report.md`](report.md) on every run, as the last step.
 - `acstack config set <key> <value>` owns the single-key change, in both files.
   It reads the key to decide which one.
 
-    A `host.*` key goes to the global config at `~/.config/acstack/config.json`.
-    Every other key it knows goes to `.acstack/project.yaml`, and the write keeps
+    A `host.*` key goes to the global config at `~/.acstack/config.json`.
+    Every other key it knows goes to `<project folder>/project.yaml`, and the write keeps
     the comments and the key order. It refuses a key neither schema knows, so
     never fall back to editing the file.
 

package/skills/setup/browser.md

@@ -37,10 +37,10 @@ Write the answer as `remote`, `headless` or `local`. Write the port beside it:
 ~/.claude/acstack/bin/acstack config set frontend.browser.cdp_port 19988
 ```
 
-Then write `.acstack/agent-browser.json` with the same port, the way Step 9c in `row-fixes.md` does.
+Then write `<project folder>/agent-browser.json` with the same port, the way Step 9c in `row-fixes.md` does.
 
 On **Skip for now**, leave `frontend.browser` unset and write no
-`.acstack/agent-browser.json`. Say that `docs/config-reference.md` documents the three
+`<project folder>/agent-browser.json`. Say that `docs/config-reference.md` documents the three
 keys for later.
 
 On **Headless**, no setup follows. Tell the user the frontend verifier launches

package/skills/setup/first-run.md

@@ -1,6 +1,6 @@
 # Setup: first run
 
-`SKILL.md` decides when to read this file: Step 2 found no `.acstack/project.yaml`, so the first-run path runs Steps 3 to 6 from here.
+`SKILL.md` decides when to read this file: Step 2 found no `project.yaml` in the project folder, so the first-run path runs Steps 3 to 6 from here.
 
 First-run setup does not migrate legacy records; use the procedure in `docs/config-reference.md`.
 That reference also lists every configuration key.
@@ -81,23 +81,21 @@ paths reach Step 10 through the health check.
 
 ## Step 6: Write the config
 
-1. Create the `.acstack/` directory.
-2. Immediately run `~/.claude/acstack/bin/acstack project-data ensure`, before writing any metadata.
-3. Write `.acstack/project.yaml` from the profile and the answers.
-4. Ask which project-data parts to track with a multi-select question, with nothing selected by default.
-   Offer the parts listed in `docs/config-reference.md` under "Project data stays local by default" in batches if the host limits options.
-   Include every part, not only the files setup creates today.
-5. Leave all parts ignored when the user selects none.
-6. Append native exceptions after existing root `.gitignore` rules, outside the managed baseline.
-    - When the user selects any part, append `!/.acstack/` once before that part's exceptions.
-    - A directory needs both `!/.acstack/specs/` and `!/.acstack/specs/**` (replace `specs` with the selected directory).
-    - A root-level file needs one exception, such as `!/.acstack/project.yaml`.
-    - Reopen parent directories before exceptions for nested files, such as `!/.acstack/verification/`.
-    - Preserve existing user rules; never force-add ignored files or change the Git index.
-7. Leave the project CLAUDE.md alone. The SessionStart hook loads the
+1. Create the project folder:
+
+    ```bash
+    mkdir -p "$(~/.claude/acstack/bin/acstack project-data path)"
+    ```
+
+2. Write `<project folder>/project.yaml` from the profile and the answers.
+3. Ask where the project's records should live, with a structured question.
+    - **Outside the repository (Recommended)** – global mode, the default. The repository holds no ACStack files and needs no `.gitignore` rules
+    - **Committed with the repository** – tracked mode. Run `~/.claude/acstack/bin/acstack project-data mode tracked`, then tell the user to commit `.acstack/` from the main checkout
+    - Never stage or commit `.acstack/` yourself
+4. Leave the project CLAUDE.md alone. The SessionStart hook loads the
    orchestrator instructions.
 
-8. Remove a legacy `@import` line from the project CLAUDE.md, if one is there.
+5. Remove a legacy `@import` line from the project CLAUDE.md, if one is there.
    It points at `.../plugins/cache/ac8318740-plugins/acstack/<version>/CLAUDE.md`.
 
 Then go to Step 7. Everything a fresh project still lacks shows up there as a

package/skills/setup/report.md

@@ -20,9 +20,10 @@ Browser:      [project's preferred mode / not configured]
 Design:       [on / off / not asked]
 Host:         [orchestrators + browser modes declared / not declared]
 Workspace:    [yes / yes, n updates available / not installed / declined / not asked]
-Tracking:     [local only / user-selected parts via root .gitignore exceptions]
-Config:       .acstack/project.yaml
-Domain map:   .acstack/domain-map.yaml ([n] domains / starter – fill in)
+Mode:         [global / tracked]
+Project data: [absolute path from acstack project-data path]
+Config:       <project folder>/project.yaml
+Domain map:   <project folder>/domain-map.yaml ([n] domains / starter – fill in)
 Output style: acstack:ac-writing-style (global) | (project) | not set
 
 Health check: [n] pass, [n] fail, [n] info

package/skills/setup/row-fixes.md

@@ -12,7 +12,7 @@ Offer a row when any of these holds:
 
 - Its `status` is `fail`.
 - Its `id` is `preferred-browser-mode`, its `status` is `info`, and
-  `.acstack/project.yaml` configures a `frontend` block. The project has a
+  `<project folder>/project.yaml` (in the project folder `acstack project-data path` prints) configures a `frontend` block. The project has a
   frontend and has named no browser mode for it.
 
 - Its `id` is `output-style` and its `status` is `info`. The row passes when the
@@ -91,7 +91,7 @@ frontend and has not turned browser verification on. Turn it on:
 
 ### 9a. Generate the domain map
 
-`.acstack/domain-map.yaml` maps source paths to spec domains. Spec sync,
+`<project folder>/domain-map.yaml` maps source paths to spec domains. Spec sync,
 `/acstack:archive`, `/acstack:bootstrap` and `/acstack:pre-commit-review` all
 read it. Without it, every path through spec sync skips in silence, and the
 living specs never update.
@@ -111,7 +111,7 @@ Guidance for the proposal:
 - Leave tests, config, build files and docs unmapped. Consumers skip a path that
   no domain covers.
 
-If `.acstack/specs/` already holds domain directories, propose those names first
+If `<project folder>/specs/` already holds domain directories, propose those names first
 and map the paths onto them. Renaming a domain here orphans its `spec.md`.
 
 Print the proposal and confirm it with the question tool (AskUserQuestion on Claude Code). Ask "Use this domain map,
@@ -145,22 +145,21 @@ npm install -g agent-browser
 
 ### 9c. Write the browser configuration
 
-Create `.acstack/` if needed, then run `~/.claude/acstack/bin/acstack project-data ensure`.
-Write `.acstack/agent-browser.json` to name the CDP port:
+Write `<project folder>/agent-browser.json` to name the CDP port:
 
 ```json
 {"cdp": "<cdp_port>"}
 ```
 
-Take `<cdp_port>` from `frontend.browser.cdp_port` in `.acstack/project.yaml`. With
+Take `<cdp_port>` from `frontend.browser.cdp_port` in `<project folder>/project.yaml`. With
 no value there, the default is `19988` under `mode: remote` and `9555` otherwise.
 The row fails when the two files name different ports, so change one of them.
 
 ### 9d. Create the knowledge base for verification
 
-Create `.acstack/verification/VERIFICATION-KNOWLEDGE.md` for the frontend verifier.
+Create `<project folder>/verification/VERIFICATION-KNOWLEDGE.md` for the frontend verifier.
 Keep helper programs in `frontend.helpers_dir`; do not move that directory or require it for metadata.
-Run `~/.claude/acstack/bin/acstack project-data ensure` after creating `.acstack/`, then write:
+Write:
 
 ```markdown
 # Verification Knowledge Base