From 224bdd8ab180631bb563a93d0d1e6a8e3824efd0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=96mer=20Can=20G=C3=BCm=C3=BC=C5=9F?=
 <omercangumus3@gmail.com>
Date: Sat, 11 Jul 2026 11:40:33 +0300
Subject: [PATCH] docs: align external-state page with actual
 externalize/internalize behavior
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The page promised gitignore behavior the code never had: externalize
only ignores .squad/config.json (the machine-specific marker), not all
of .squad/, and internalize doesn't touch .gitignore at all. The marker
example was also missing the version/teamRoot/projectKey fields the
command actually writes, the stateLocation table listed an "internal"
value that is never written (absence means internal), and the git
status sample showed a gitignored file as untracked, which git doesn't
do. Internalize copies state back rather than moving it — the external
copy stays in place (#1401 tracks whether that should become a move).

Documents current behavior only, no code change.

Fixes #1400
Part of #1402

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../content/docs/features/external-state.md   | 30 +++++++++++--------
 1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/docs/src/content/docs/features/external-state.md b/docs/src/content/docs/features/external-state.md
index 925b0e9a4..702ca13cd 100644
--- a/docs/src/content/docs/features/external-state.md
+++ b/docs/src/content/docs/features/external-state.md
@@ -94,13 +94,16 @@ squad externalize
 **What happens:**
 1. Resolves platform-specific global path (e.g., `~/Library/Application Support/squad/projects/my-repo/`)
 2. Moves `.squad/` contents to global path
-3. Creates thin marker file `.squad/config.json` in working tree:
+3. Creates thin marker file `.squad/config.json` in working tree (existing config fields are preserved):
    ```json
    {
+     "version": 1,
+     "teamRoot": ".",
+     "projectKey": "my-repo",
      "stateLocation": "external"
    }
    ```
-4. Adds `.squad/` to `.gitignore` (if not already present)
+4. Adds `.squad/config.json` to `.gitignore` (if not already present) — the marker is machine-specific and must not be committed
 
 **After externalization:**
 - Working tree has only `.squad/config.json` (gitignored marker)
@@ -119,9 +122,9 @@ squad internalize
 
 **What happens:**
 1. Reads marker file to find external state location
-2. Moves state from global directory back to `.squad/`
-3. Removes marker file
-4. Removes `.squad/` from `.gitignore`
+2. Copies state from the global directory back to `.squad/` (the external copy is left in place)
+3. Removes the external-state fields (`stateLocation`, `teamRoot`, `projectKey`) from `.squad/config.json` — the file is deleted when no other settings remain
+4. Leaves `.gitignore` unchanged
 
 **After internalization:**
 - `.squad/` lives in working tree again
@@ -136,19 +139,22 @@ The thin marker file `.squad/config.json` tracks state location:
 
 ```json
 {
+  "version": 1,
+  "teamRoot": ".",
+  "projectKey": "my-repo",
   "stateLocation": "external"
 }
 ```
 
-| Value | Meaning |
+| `stateLocation` | Meaning |
 |-------|---------|
-| `"internal"` | State lives in working tree (`.squad/` in repo) |
+| absent (or no marker file) | State lives in working tree (`.squad/` in repo) |
 | `"external"` | State lives in global directory (platform-specific path) |
 
 **Notes:**
 - Marker file is created by `squad externalize`
 - Marker file is gitignored — not committed to repo
-- Marker file is removed by `squad internalize`
+- `squad internalize` removes the external-state fields from the file (and deletes it when nothing else remains)
 
 ---
 
@@ -210,19 +216,19 @@ No cross-repo state pollution.
 
 ## Git Integration
 
-After externalization, `.squad/` is gitignored. Only the thin marker file exists in the working tree:
+After externalization, only the thin marker file exists in the working tree, and it is gitignored:
 
 ```bash
 $ git status
 On branch feature-branch
-Untracked files:
-  .squad/config.json    # gitignored marker — not committed
+nothing to commit, working tree clean
+# .squad/config.json exists on disk but is gitignored — not committed
 ```
 
 This means:
 - PRs never show squad state changes
 - Branch switches don't affect squad data
-- `git clean -fdx` doesn't delete squad state
+- `git clean -fdx` doesn't delete squad state (it lives outside the repo — though it does remove the gitignored marker, which `squad externalize` can recreate)
 
 ---