Merge remote-tracking branch 'origin/main' into fix/1123-local-settings-hooks

# Conflicts:
#	cmd/entire/cli/settings/settings.go

Author: gtrrz-victor

.github/workflows/codeql-actions.yml

@@ -24,13 +24,13 @@ jobs:
           ref: ${{ github.event.pull_request.head.sha }}
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
+        uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
         with:
           languages: actions
           queries: security-extended,security-and-quality
 
       - name: Perform CodeQL analysis
-        uses: github/codeql-action/analyze@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
+        uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
         with:
           category: /language:actions
           # Fork PRs receive a read-only GITHUB_TOKEN, so SARIF upload to the

.github/workflows/e2e.yml

@@ -208,7 +208,7 @@ jobs:
           } >> "$GITHUB_OUTPUT"
 
       - name: Notify Slack of E2E failure
-        uses: slackapi/slack-github-action@45a88b9581bfab2566dc881e2cd66d334e621e2c # v3.0.3
+        uses: slackapi/slack-github-action@0d95c9a7becc1e6e297d76df9bc735c44f4cbcbc # v3.0.5
         with:
           webhook: ${{ secrets.E2E_SLACK_WEBHOOK_URL }}
           webhook-type: incoming-webhook

.github/workflows/release.yml

@@ -195,7 +195,7 @@ jobs:
     if: ${{ always() && (needs.release.result == 'failure' || needs.mirror-nightly.result == 'failure') }}
     steps:
       - name: Notify Slack of release failure
-        uses: slackapi/slack-github-action@45a88b9581bfab2566dc881e2cd66d334e621e2c # v3.0.3
+        uses: slackapi/slack-github-action@0d95c9a7becc1e6e297d76df9bc735c44f4cbcbc # v3.0.5
         with:
           webhook: ${{ secrets.E2E_SLACK_WEBHOOK_URL }}
           webhook-type: incoming-webhook

.goreleaser.yaml

@@ -26,6 +26,11 @@ builds:
       - -X github.com/entireio/cli/cmd/entire/cli/versioninfo.Commit={{.ShortCommit}}
       - -X github.com/entireio/cli/cmd/entire/cli/telemetry.PostHogAPIKey={{.Env.POSTHOG_API_KEY}}
       - -X github.com/entireio/cli/cmd/entire/cli/telemetry.PostHogEndpoint={{.Env.POSTHOG_ENDPOINT}}
+      # Experimental-command visibility: hide in stable releases, keep visible
+      # in nightly (prerelease) builds. .Prerelease is empty for a stable tag
+      # (vX.Y.Z) and non-empty for a nightly tag (vX.Y.Z-nightly.*). Local
+      # builds carry no stamp and use the package default ("true" = visible).
+      - -X github.com/entireio/cli/cmd/entire/cli/experimental.Visible={{ if .Prerelease }}true{{ else }}false{{ end }}
 
   # git-remote-entire is the git remote helper for entire:// URLs (see
   # cmd/git-remote-entire). A small, dedicated binary shipped alongside
@@ -100,7 +105,14 @@ release:
   prerelease: auto
 
 scoops:
-  - repository:
+  # Name the manifest (and therefore the Scoop app directory) "entire". Without
+  # this, goreleaser defaults the manifest name to the project name, which
+  # resolves to the repo name ("cli"), so `scoop install` lands the binary in
+  # …\scoop\apps\cli\current\entire.exe. That mismatched app-dir name is
+  # surprising ("scoop install cli"?) and fed the Windows hook-path bug in
+  # https://github.com/entireio/cli/issues/1424.
+  - name: entire
+    repository:
       owner: entireio
       name: scoop-bucket
       token: "{{ .Env.TAP_GITHUB_TOKEN }}"

CLAUDE.md

@@ -26,8 +26,18 @@ The visible CLI is organized around a set of noun groups plus a small set of
 top-level verbs. The groups are the canonical home for each verb; legacy
 top-level shortcuts remain functional but hidden, and emit a deprecation hint
 pointing at the canonical group form. Newer experimental command families are
-discoverable through `entire labs` and may remain hidden from root help while
-their canonical paths are still runnable.
+discoverable through `entire labs` and their canonical paths are always
+runnable.
+
+Experimental commands are gated by a build-time visibility flag (the
+`cmd/entire/cli/experimental` package): they are shown — grouped under an
+"Experimental commands:" help section — in developer and nightly builds, and
+hidden in stable release builds. Visibility is toggled by `experimental.Visible`
+(default `"true"`), which GoReleaser stamps `"false"` only on stable tags
+(`.Prerelease` empty); nightly (`vX.Y.Z-nightly.*`) and local builds leave it at
+the default. Register a command as experimental with `experimental.Register(parent,
+child)` instead of `parent.AddCommand(child)`. Gating only controls visibility —
+the commands are always runnable in every build.
 
 - `session` (alias: `sessions`): `list`, `info`, `tokens`, `stop`, `attach`, `adopt`, `resume`, `current`.
   `resume` with a branch arg switches to it and resumes its session; with no arg
@@ -66,9 +76,12 @@ their canonical paths are still runnable.
 - `grant`: manage access grants and org membership — `org`, `project`, and `repo`
   each support `add` / `list` / `remove`
 
-Experimental command families advertised through `entire labs`:
-
-- `tokens`: `profile` (hidden from root help while token diagnostics mature)
+Experimental commands (gated by the build-time visibility flag above — visible
+and grouped under "Experimental commands:" in developer/nightly builds, hidden
+in stable releases, always runnable): `tokens`, `import`, `review`,
+`investigate`, `blame`, `why`, the top-level `search` shortcut, `experts`,
+`runner`, and `checkpoint policy`. `tokens` is also advertised through `entire
+labs`. The canonical `checkpoint search` is not gated and stays visible.
 
 Top-level lifecycle and standalone commands: `enable`, `disable`, `status`,
 `login`, `logout`, `clean`, `version`, `dispatch`, `activity`, `help`,
@@ -91,7 +104,10 @@ one command's current flags; `--json` emits structured output. It is the single
 source of truth the first-turn context injection and the `--agent-help-skill`
 skill point agents at, instead of enumerating a surface that goes stale.
 Hidden commands opt into being advertised here by setting
-`Annotations[agentHelpAnnotation] = "true"` (e.g. `trail`).
+`Annotations[agentHelpAnnotation] = "true"` (e.g. `trail`). Because `agent-help`
+renders live and lists non-hidden commands, the experimental commands appear in
+`agent-help` in developer/nightly builds and are absent in stable releases — the
+advertised surface is build-dependent, matching what `entire help` shows.
 No-channel agents (Cursor, Copilot CLI, Factory Droid, MCP hosts — no
 context-injection channel and no agent-help skill template) reach it without an
 active push. All of them can discover it passively: it is visible in `entire
@@ -107,7 +123,9 @@ Hidden top-level shortcuts (functional, emit a one-line deprecation hint):
 `resume` → `session resume`, `attach` → `session attach`, `explain` →
 `checkpoint explain`, `trace` → `doctor trace`.
 Cobra-native aliases (no hint): `sessions` → `session`, `cp`/`checkpoints` →
-`checkpoint`. The `search` top-level remains hidden without a hint.
+`checkpoint`. The `search` top-level is experimental (see the visibility gate
+above), so it follows the build-dependent visibility rather than being
+unconditionally hidden.
 
 Deprecated top-level commands (functional, print a cobra deprecation message):
 `reset` → `clean`, and `rewind` (no replacement, announces removal — same
@@ -583,7 +601,7 @@ The manual-commit strategy (`manual_commit*.go`) does not modify the active bran
 - **Shadow branch migration** - if user does stash/pull/rebase (HEAD changes without commit), shadow branch is automatically moved to new base commit
 - **Orphaned branch cleanup** - if a shadow branch exists without a corresponding session state file, it is automatically reset when a new session starts
 - PrePush hook can push `entire/checkpoints/v1` branch alongside user pushes
-- **OPF (OpenAI Privacy Filter) runs at pre-push, not post-commit**: when `redaction.openai_privacy_filter.enabled` is true, the PrePush hook re-redacts unpushed `entire/checkpoints/v1` commits with the OPF 8th layer, builds new commits carrying an `Entire-OPF-Applied: true` trailer, and atomically updates the local v1 ref before pushing. Per-commit condensation stays on the fast 7-layer pipeline. See `strategy/manual_commit_opf_rewrite.go` and `docs/security-and-privacy.md` for the full flow, including divergence detection, bootstrap caps, and CAS-on-conflict semantics.
+- **OPF (OpenAI Privacy Filter) runs at pre-push, not post-commit**: when `redaction.openai_privacy_filter.enabled` is true, the PrePush hook re-redacts unpushed `entire/checkpoints/v1` commits with the OPF 9th layer, builds new commits carrying an `Entire-OPF-Applied: true` trailer, and atomically updates the local v1 ref before pushing. Per-commit condensation stays on the fast 8-layer pipeline. See `strategy/manual_commit_opf_rewrite.go` and `docs/security-and-privacy.md` for the full flow, including divergence detection, bootstrap caps, and CAS-on-conflict semantics.
 - Safe to use on main/master since it never modifies commit history
 
 #### Key Files
@@ -604,6 +622,7 @@ The phase state machine, metadata directory layout, sharded checkpoint format, m
 
 - [Sessions and Checkpoints](docs/architecture/sessions-and-checkpoints.md) - domain model, storage layout, checkpoint ID linking, commit trailers, package structure
 - [Checkpoint Scenarios](docs/architecture/checkpoint-scenarios.md) - phase state machine and worked condensation scenarios
+- [Ref-Based Checkpoint Backend](docs/architecture/ref-checkpoint-backend.md) - git-refs backend: primary/mirror taxonomy, ref layout + sharding, push-discovery queue, read routing, config + rollout
 
 #### When Modifying the Strategy
 

README.md

@@ -25,6 +25,7 @@ With Entire, you can:
 - [Key Concepts](#key-concepts)
   - [How It Works](#how-it-works)
   - [Strategy](#strategy)
+- [Headless & CI Authentication](#headless--ci-authentication)
 - [Local Device Auth Testing](#local-device-auth-testing)
 - [Commands Reference](#commands-reference)
 - [Configuration](#configuration)
@@ -206,6 +207,44 @@ Entire works seamlessly with [git worktrees](https://git-scm.com/docs/git-worktr
 
 Multiple AI sessions can run on the same commit. If you start a second session while another has uncommitted work, Entire warns you and tracks them separately. Both sessions' checkpoints are preserved and can be rewound independently.
 
+## Headless & CI Authentication
+
+By default `entire login` stores tokens in the OS keyring (macOS Keychain,
+Linux Secret Service, Windows Credential Manager). Machines without a usable
+keyring — headless servers, containers, minimal VMs, CI runners — have two
+supported paths:
+
+### Interactive login on a headless machine
+
+Use the file-backed token store. The device-auth flow already works without a
+local browser (the CLI prints an approval URL you can open on any machine);
+only token storage needs the override:
+
+```bash
+ENTIRE_TOKEN_STORE=file entire login
+```
+
+Tokens are written with `0600` permissions to `tokens.json` in your Entire
+config directory (`~/.config/entire` by default). Override the location with
+`ENTIRE_TOKEN_STORE_PATH`. Set `ENTIRE_TOKEN_STORE=file` persistently (e.g. in
+your shell profile) so later commands read from the same store.
+
+### Non-interactive automation (CI, workload identity)
+
+Skip login and storage entirely by injecting a token per invocation:
+
+```bash
+ENTIRE_TOKEN=<login-or-sa-session-JWT> entire ...
+```
+
+`ENTIRE_TOKEN` bypasses stored credentials; the CLI derives the control-plane
+endpoint from the token itself. Nothing is written to disk. This is the right
+path for CI pipelines and service accounts.
+
+> **Seeing `save login` / `failed to unlock correct collection` errors from
+> `entire login`?** That's the OS keyring being unavailable — use one of the
+> two paths above.
+
 ## Local Device Auth Testing
 
 If you're working on the CLI device auth flow against a local `entire.io` checkout: