Address CodeRabbit review findings (1, 2, 6, 7)

- CHANGELOG.md: Add #### Documentation subsection under Changed, add
  #### Scripts subsection under Removed for consistent structure
- CLAUDE.md: Document CLAUDE_AUTH_TOKEN, .credentials.json auto-creation,
  skip-if-exists behavior, sk-ant-* validation, and named volume persistence
- setup-auth.sh: Detect printf subshell write failure — report warning
  instead of false success when .credentials.json write fails
- setup-migrate-claude.sh: Verify cp exit status before printing success —
  warn if copy failed instead of unconditional "Migration complete"
- docs/reference/changelog.md: Mirror CHANGELOG structure fixes

Findings 3-5 (feature $HOME fallback) confirmed as false positives:
postStartCommand runs as vscode user, CLAUDE_CONFIG_DIR is exported
by setup.sh before hooks execute.

Author: AnExiledDev

.devcontainer/CHANGELOG.md

@@ -21,7 +21,13 @@
 - Replaced `setup-symlink-claude.sh` with `setup-migrate-claude.sh` (one-time migration)
 - Auto-migrates from `/workspaces/.claude/` if `.credentials.json` present
 
+#### Documentation
+- All docs now reference `~/.claude` as default config path
+- Added `CLAUDE_AUTH_TOKEN` setup flow to README, configuration reference, and troubleshooting
+
 ### Removed
+
+#### Scripts
 - `setup-symlink-claude.sh` — no longer needed with native home directory location
 
 ## [v1.14.2] - 2026-02-24

.devcontainer/CLAUDE.md

@@ -77,11 +77,18 @@ Rules in `config/defaults/rules/` deploy to `.claude/rules/` on every container
 | Variable | Value |
 |----------|-------|
 | `CLAUDE_CONFIG_DIR` | `/home/vscode/.claude` |
+| `CLAUDE_AUTH_TOKEN` | Long-lived token from `claude setup-token` (optional, via `.secrets` or Codespaces secrets) |
 | `ANTHROPIC_MODEL` | `claude-opus-4-6` |
 | `WORKSPACE_ROOT` | `/workspaces` |
 
 All experimental feature flags are in `settings.json` under `env`. Setup steps controlled by boolean flags in `.env`.
 
+## Authentication & Persistence
+
+The `~/.claude/` directory is backed by a Docker named volume (`codeforge-claude-config-${devcontainerId}`), persisting config, credentials, and session data across container rebuilds. Each devcontainer instance gets an isolated volume.
+
+**Token authentication:** Set `CLAUDE_AUTH_TOKEN` in `.devcontainer/.secrets` (or as a Codespaces secret) with a long-lived token from `claude setup-token`. On container start, `setup-auth.sh` auto-creates `~/.claude/.credentials.json` with `600` permissions. If `.credentials.json` already exists, token injection is skipped (idempotent). Tokens must match `sk-ant-*` format.
+
 ## Modifying Behavior
 
 1. **Change model**: Edit `config/defaults/settings.json` → `"model"` field

.devcontainer/scripts/setup-auth.sh

@@ -89,9 +89,12 @@ if [ -n "$CLAUDE_AUTH_TOKEN" ]; then
         # Write credentials with restrictive permissions from the start (no race window).
         # Uses printf '%s' to avoid shell expansion of token value (defense against
         # metacharacters in the token string — backticks, $(), quotes).
-        ( umask 077; printf '{\n  "claudeAiOauth": {\n    "accessToken": "%s",\n    "refreshToken": "%s",\n    "expiresAt": 9999999999999,\n    "scopes": ["user:inference", "user:profile"]\n  }\n}\n' "$CLAUDE_AUTH_TOKEN" "$CLAUDE_AUTH_TOKEN" > "$CLAUDE_CRED_FILE" )
-        echo "[setup-auth] Claude auth token configured"
-        AUTH_CONFIGURED=true
+        if ( umask 077; printf '{\n  "claudeAiOauth": {\n    "accessToken": "%s",\n    "refreshToken": "%s",\n    "expiresAt": 9999999999999,\n    "scopes": ["user:inference", "user:profile"]\n  }\n}\n' "$CLAUDE_AUTH_TOKEN" "$CLAUDE_AUTH_TOKEN" > "$CLAUDE_CRED_FILE" ); then
+            echo "[setup-auth] Claude auth token configured"
+            AUTH_CONFIGURED=true
+        else
+            echo "[setup-auth] WARNING: Failed to write .credentials.json — check permissions on $CLAUDE_CRED_DIR"
+        fi
     fi
     unset CLAUDE_AUTH_TOKEN
 else

.devcontainer/scripts/setup-migrate-claude.sh

@@ -36,5 +36,8 @@ mkdir -p "$NEW_DIR"
 # --no-dereference: copy symlinks as symlinks (don't follow them)
 # -n: no-clobber (don't overwrite existing files)
 # -r: recursive
-cp -rn --no-dereference "$OLD_DIR/." "$NEW_DIR/" 2>/dev/null || true
-echo "[setup-migrate] Migration complete. You can safely remove /workspaces/.claude/"
+if cp -rn --no-dereference "$OLD_DIR/." "$NEW_DIR/" 2>/dev/null; then
+    echo "[setup-migrate] Migration complete. You can safely remove /workspaces/.claude/"
+else
+    echo "[setup-migrate] WARNING: Some files may not have been copied — verify $NEW_DIR before removing /workspaces/.claude/"
+fi

docs/src/content/docs/reference/changelog.md

@@ -68,7 +68,13 @@ For minor and patch updates, you can usually just rebuild the container. Check t
 - Replaced `setup-symlink-claude.sh` with `setup-migrate-claude.sh` (one-time migration)
 - Auto-migrates from `/workspaces/.claude/` if `.credentials.json` present
 
+#### Documentation
+- All docs now reference `~/.claude` as default config path
+- Added `CLAUDE_AUTH_TOKEN` setup flow to README, configuration reference, and troubleshooting
+
 ### Removed
+
+#### Scripts
 - `setup-symlink-claude.sh` — no longer needed with native home directory location
 
 ---