dreamcontext 0.14.1 → 0.14.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dreamcontext",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "description": "dreamcontext — the persistent brain for your AI agents. Remembers what you built, knows how your project works.",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -91,7 +91,7 @@ dreamcontext is **more than memory files**. Every capability below is real and s
 | **Web dashboard** | Local React UI: Kanban, Eisenhower matrix, brain graph, sleep tracker, council hall | [integrations.md](references/integrations.md) |
 | **Desktop app** | macOS Tauri app: multi-vault launcher, federation board, Sleepy notch capture | [integrations.md](references/integrations.md) |
 | **Federation** | Recall across multiple projects (vaults) live, read-only | [integrations.md](references/integrations.md) |
-| **✅ Team brain sync (shared repo)** | **Yes — a team can share ONE brain.** The whole `_dream_context/` becomes its own git repo (separate from the code repo); `sleep done` auto fetch→merge→commit→pushes it, and the `/dream-sync` skill resolves prose conflicts. Different from federation (read-only cross-project recall) and cloud task sync (tasks only). CLI shipped; one-click desktop flow is M2/pending. | [integrations.md](references/integrations.md) |
+| **✅ Team brain sync (shared repo)** | **Yes — a team OR one person across machines can share ONE brain.** The brain is git-synced to a GitHub remote in one of **three modes** — `separate` (brain in its own repo), `full-repo` (whole project → its `origin`), `in-tree` (commit-only default). `sleep done` auto fetch→merge→commit→pushes it; the `/dream-sync` skill resolves prose conflicts. Different from federation (read-only cross-project recall) and cloud task sync (tasks only). Each machine needs its own token. | [brain-sync.md](references/brain-sync.md) |
 | **Council** | Structured multi-persona debates with a synthesized verdict | [integrations.md](references/integrations.md) |
 | **Marketing (`mk`)** | Meta marketing skill: cohorts, campaigns, competitor ingest | [integrations.md](references/integrations.md) |
 | **Versions / releases** | Planning versions and releases unify in RELEASES.json | [tasks-and-features.md](references/tasks-and-features.md) |
@@ -364,7 +364,7 @@ All sub-agents get a lightweight context briefing via the SubagentStart hook. Wh
 - `dreamcontext upgrade` — upgrade the CLI, then (one command) update the desktop app if installed and offer to refresh **every registered project** to match (`--yes` does it all non-interactively). **Keeping projects + app updated is the CLI's job — you should not run per-project updates by hand or ask the user to.**
 - `dreamcontext doctor` — validate `_dream_context/` structure.
 - `dreamcontext dashboard` — open the web UI. `dreamcontext app install|update|status` — the desktop app.
-- **Team collaboration / shared brain** — when the user wants to **use one brain with other people** ("share the brain", "collaborate on tasks/knowledge together", "put the brain in its own repo"), that's the **shared brain repo**: `dreamcontext brain init` (create) / `brain attach <url>` (join) / `brain status`, auto-synced at `sleep done`, prose conflicts resolved by the **`/dream-sync`** skill. **Guide them into it — don't say "unsupported".** Setup is CLI-only today (the one-click desktop login/attach is M2/pending). Full surface → [integrations.md](references/integrations.md).
+- **Team collaboration / shared brain / second machine** — when the user wants to **use one brain with other people or on another computer** ("share the brain", "collaborate on tasks/knowledge together", "put the brain in its own repo", "sync my brain to GitHub", "set it up on my other machine"), that's the **shared brain repo**: `dreamcontext brain init` (create) / `brain attach <url>` (join) / `brain status`, auto-synced at `sleep done`, prose conflicts resolved by the **`/dream-sync`** skill. **Guide them into it — don't say "unsupported".** Three modes (separate / full-repo / in-tree), per-machine token, and cross-OS setup → [brain-sync.md](references/brain-sync.md).
 
 ---
 
@@ -414,5 +414,6 @@ Open these with `Read` when the task needs depth:
 - **[tasks-and-features.md](references/tasks-and-features.md)** — task protocol depth, RICE, due dates, people/assignees, Workflow flowchart, features, versioning, multi-product.
 - **[knowledge-and-recall.md](references/knowledge-and-recall.md)** — knowledge files, pinning, recall modes, taxonomy, Excalidraw/diagrams.
 - **[sleep.md](references/sleep.md)** — full consolidation flow, specialist contracts, deep sleep, epoch safety, reflect, marketing/council passes.
-- **[integrations.md](references/integrations.md)** — ClickUp/GitHub task sync (one cloud backend at a time), **team brain sync (shared brain repo — `brain init`/`attach`/`sync`, `/dream-sync` conflict resolution)**, dashboard, desktop app, federation/vaults, council, marketing.
+- **[brain-sync.md](references/brain-sync.md)** — **shared brain repo / GitHub cloud sync**: the three modes (separate/full-repo/in-tree), setup, per-machine token + auth, shared vs machine-local config, lifecycle, **cross-OS setup**, and the silent-failure troubleshooting playbook.
+- **[integrations.md](references/integrations.md)** — ClickUp/GitHub task sync (one cloud backend at a time), dashboard, desktop app, federation/vaults, council, marketing. (Brain sync has its own reference above.)
 - **[improving-dreamcontext.md](references/improving-dreamcontext.md)** — the feedback loop, when and how to file.

package/skill/references/brain-sync.md

@@ -0,0 +1,131 @@
+# Brain sync (GitHub cloud sync for the brain)
+
+The one reference for the **shared brain repo** — what it is, the three modes, how it's set up, how it authenticates, what it syncs, the cross-machine / cross-OS setup, and how to diagnose it when it silently stops. This is a *different* feature from **cloud task sync** (ClickUp/GitHub Issues — tasks only) and **federation** (read-only recall across your own separate projects — nothing is copied). Say so if the user conflates them.
+
+**Guide the user into this** the moment they say *"use this with my team / on another machine," "share the brain," "put the brain in its own repo," "sync my brain to GitHub."* Do NOT answer "we don't support that" — this is the feature.
+
+## What it is
+
+The brain (`_dream_context/`) is mirrored to a **GitHub remote** and kept in sync across people/machines. Local markdown + JSON on disk stays canonical (local-first); **git is just the transport**, not a new database. Merges are **agent-assisted and semantic**: the CLI auto-resolves deterministic files itself and only defers overlapping *prose* edits to the `/dream-sync` skill.
+
+A **master switch** (cloud sync ON/OFF) gates everything: `dreamcontext brain enable` / `brain disable`, resolved and shown by `dreamcontext brain status`.
+
+## The three sync modes
+
+Mode lives in `_dream_context/state/.config.json` under `brainRepo.mode`. **Anything not `separate`/`full-repo` resolves to `in-tree`.**
+
+| Mode | Git root | Remote | Branch | What lands on the remote | Auto-push? |
+|---|---|---|---|---|---|
+| **`separate`** | `_dream_context/` (the brain is its OWN repo) | a dedicated brain repo (`brainRepo.remote`) | always `main` | the **contents of `_dream_context/`** at the repo root (core/, knowledge/, state/…) | **Yes** |
+| **`full-repo`** | the **project root** (whole project is the repo) | the project's own `origin` | the **current** branch (never assumes `main`) | the **entire project** — code + `_dream_context/` nested inside it | **Yes** |
+| **`in-tree`** (default) | — | — | — | nothing pushed — **commit-only**, stages `_dream_context/` and commits locally | **No, never** |
+
+- **`separate`** is the classic "team shares one brain repo, separate from the code repo." Created by `brain init` / joined by `brain attach`.
+- **`full-repo`** makes the whole project folder the synced repo (brain nested under `_dream_context/`, plus root `CLAUDE.md` / `.claude/` if present). It **refuses on a detached HEAD** (`detached-head`) and force-writes machine-local excludes into the project-root `.gitignore` before every sync so secrets/lock files never get staged by `git add -A`.
+- **`in-tree`** is the safe default: it commits the brain alongside your code but **never pushes** — you sync manually or promote to another mode.
+
+**Switching modes:** there is **no `brain scope` / `brain mode` CLI command.** Switching to/from `full-repo` is done from the **dashboard** (Settings → Brain → Sync scope; server route `POST /api/brain/scope`). `full-repo` requires the project to already have a GitHub `origin` (it errors `no_origin` otherwise). To go the other way it becomes `separate` if a brain remote exists, else `in-tree`. `brain init` produces `separate`; a project with no brain config is `in-tree`.
+
+## Set it up (CLI)
+
+```bash
+# 0. Token FIRST — init/attach and every push need it (see Auth for scope + resolution order).
+dreamcontext config github-token "$(gh auth token)"   # per-MACHINE token; gitignored, never travels with the repo
+
+# Create a brand-new shared brain repo (PRIVATE by default), scrubbed first push → separate mode
+dreamcontext brain init --owner <you-or-org> --name <repo>   # --code-repo <url> pins the paired code repo
+
+# OR join an existing brain repo (a TRUST decision — it loads into every session)
+dreamcontext brain discover                      # list repos tagged `dreamcontext-brain` you can access
+dreamcontext brain attach <brain-repo-url>       # trust warning + read-only diff preview, then confirm
+
+dreamcontext brain status                        # verify: mode, remote, resolved cloud-sync switch
+```
+
+`brain init` creates the GitHub repo through the API with the **same resolved token**, so set the token (or be logged into dreamcontext for the global store) *before* `init`/`attach`. (PowerShell/cmd have no `$(…)` — use `dreamcontext config github-token <token>` or set `GITHUB_TOKEN`.)
+
+Carry the Claude Code layer with the brain so a fresh clone is ready to use:
+
+```bash
+dreamcontext brain platform        # moves CLAUDE.md + .claude/ into _dream_context/platform/ and symlinks from root
+dreamcontext brain platform --status
+```
+(Separate mode only — its repo is rooted at `_dream_context/`, so root files wouldn't sync otherwise. In `full-repo` the root files sync natively and `brain platform` is unnecessary. Every `brain sync` re-creates missing root symlinks on a fresh clone; `doctor` flags broken links.)
+
+## Auth — how the brain repo authenticates (NOT gh, NOT the keychain)
+
+The token is resolved by **`resolveBrainSyncToken`, secrets-first, env-last**:
+
+1. per-project `_dream_context/state/.secrets.json` → `github.token` (set via `dreamcontext config github-token`)
+2. global `~/.dreamcontext/.secrets.json` → `github.token` (the account you logged into dreamcontext as)
+3. env `GITHUB_TOKEN`, then `GH_TOKEN`
+
+**The `gh` CLI and git credential helpers are never consulted** — helpers are actively disabled on every networked git call (`-c credential.helper=`), and the token is handed to git only through a `GIT_ASKPASS` helper pointed at a fresh **0600** temp file (never in the remote URL or argv). `.secrets.json` is written **gitignore-first** (the write aborts if it can't be ignored) and chmod **0600**.
+
+> **Required scope (this bites people):** brain sync **pushes repo contents**, so the token needs classic **`repo`** scope, or a fine-grained PAT with **Contents: read & write** (add **Administration: read & write** on the owner if you'll `brain init` to *create* the repo). `config github-token` writes the SAME per-project store the GitHub-Issues *task* backend uses — but a fine-grained **Issues-only** token (enough for task sync) will authenticate that and yet **silently fail every brain push**. When in doubt, use a classic `repo` token or a fine-grained PAT that includes Contents:write.
+
+## Shared vs machine-local config (important)
+
+- **`state/.config.json` — SYNCS** across machines/teammates. It holds the whole `brainRepo` block: **`mode`, `enabled`, `remote`, `autoSync`**. Consequence: **an explicit `mode` or `enabled` propagates to everyone** on the next sync — they are a *shared* decision, not per-machine. (This is deliberate: one remote can only have one structure, so all machines must agree on the mode.)
+- **`state/.brain-local.json` — MACHINE-LOCAL** (gitignored). Only runtime bookkeeping: `lastFetchAt`, `pulledUpdates`, `pendingAgentMerge`, `needsTaskSync`, `codeRepoPath`. This is what keeps two machines from clobbering each other's sync state.
+- **`enabled` resolution:** an explicit `true`/`false` in `.config.json` wins (and is shared). If **absent**, it's **derived per-machine** — ON iff this machine is GitHub-connected (local `origin` is github.com, OR `taskBackend=github`, OR `brainRepo.remote` is set), else OFF. So the *default* is per-machine; an *explicit* toggle is global.
+
+## Lifecycle — when sync happens
+
+- **Session start:** a **detached, non-blocking** `brain sync --pull-only` fires in the background (only when `enabled` + mode `separate`/`full-repo` + `autoSync`; honors `DREAMCONTEXT_BRAIN_SYNC=0`). Its results land on the **NEXT** session (you see the previous pull's `pulledUpdates`).
+- **`sleep done`:** runs a foreground `brain sync` (fetch → merge → commit → push) when `autoSync` is set. **Sync failure never fails sleep** — but on a prose conflict it pauses with `awaiting-agent` and prints the `/dream-sync` prompt.
+- **Manual, any time:** `dreamcontext brain sync` (flags: `--pull-only`, `--push-only`, `--strict`, `--continue`, `--resume`).
+- **Commit messages** (so you can recognize them): `chore(brain): sync` (separate/in-tree), `chore: sync project (dreamcontext)` (full-repo), `chore(brain): merge team updates` (auto-merge), `… (agent-resolved)` (after `/dream-sync`).
+
+**Conflicts:** deterministic files — JSON (changelog/releases/config/taxonomy) and task `.md` — are auto-merged by the CLI. Only overlapping edits to the **same `##` section of a knowledge/feature (prose) doc** defer to the agent (`awaiting-agent`): a report with base/ours/theirs snapshots is written to `state/.brain-merge/`, the `/dream-sync` skill writes the real merge, and `brain sync --continue` commits it. In `full-repo`, real **code** conflicts go to the human with native git markers (never to the agent). A **scrub gate** runs before every commit and push (BLOCK always stops it; WARN stops only under `--strict` or a headless pull-only).
+
+## Cross-machine / cross-OS setup
+
+The brain is portable, but each machine needs a few things right. **The #1 real-world failure is a machine with no token — sync then silently no-ops.**
+
+- **Every machine needs its own token.** `.secrets.json` is gitignored, so the token does **not** travel with the repo. On each new machine run **`dreamcontext config github-token "$(gh auth token)"`** (or set `GITHUB_TOKEN`, or log in so the global `~/.dreamcontext/.secrets.json` is populated). No `gh`/keychain fallback exists — if none of the three token sources is set, push/pull just quietly do nothing.
+- **The brain folder must be its OWN git root (the enclosing-repo trap).** In `separate` mode the repo root must be `_dream_context/`; in `full-repo` it must be the project folder. Verify: `git -C <that folder> rev-parse --show-toplevel` should print *that* folder — **not climb into an enclosing parent repo** (e.g. a home-directory `~/.git` or a wrapping code repo). dreamcontext guards this at `init`/`attach`/disconnect, but the per-sync path only checks "is a git repo," so a misplaced enclosing `.git` can hijack resolution. If sync targets the wrong tree, hunt for a parent `.git` above the folder and remove its stray `origin`.
+- **Windows / WSL — line endings.** dreamcontext does **not** normalize CRLF. On Windows, set `git config core.autocrlf false` (or commit a `.gitattributes` with `* text=lf`) in the brain repo to avoid phantom whole-file conflicts on markdown/JSON. A mixed Windows⇄WSL checkout of the *same* folder is the highest-risk setup — pick one.
+- **Node/npx must be on PATH for GUI-launched agents.** The background pull launches via the node binary directly (not a bare `dreamcontext`), so a minimal Finder/Explorer PATH is tolerated — but the CLI itself must be installed on each machine.
+- **Credential helpers are bypassed by design**, so macOS Keychain / Windows Credential Manager / libsecret differences don't matter — auth is only the resolved token via askpass.
+- **Windows symlinks (separate mode).** `brain platform` shares CLAUDE.md/.claude by **symlinking** them from the project root, and every `brain sync` re-creates missing links. On Windows, creating symlinks normally needs **Developer Mode enabled or an elevated shell** — otherwise `brain platform` fails. On a Windows brain, prefer **`full-repo` mode**, where root files sync natively and no symlinks are involved.
+
+**Per-OS quick matrix**
+
+| | macOS | Linux | Windows / WSL |
+|---|---|---|---|
+| Token | `config github-token "$(gh auth token)"` | same | same (in WSL use the WSL `gh`; native Windows: `GITHUB_TOKEN` or dashboard login) |
+| Line endings | fine | fine | **set `core.autocrlf false`** |
+| Git root check | `rev-parse --show-toplevel` | same | same |
+| Keychain/helper | bypassed | bypassed | bypassed |
+| `brain platform` symlinks | native | native | **need Developer Mode / elevated shell** — or use `full-repo` (root files sync natively) |
+| Token scope | `repo` / Contents:write | same | same (an Issues-only fine-grained token won't push) |
+
+**Operating rule — sleep before you leave a machine.** `sleep done` pushes the consolidated state, so the next machine pulls clean. Skipping it is the main way two machines drift into an avoidable prose conflict.
+
+## Onboarding a second machine (same user) — checklist
+
+**On Windows, read the Cross-OS section first** — the token syntax (step 2), symlink privilege (step 3), and `core.autocrlf` (step 6) all differ.
+
+1. `git clone <brain-or-project-url>` (or `dreamcontext brain attach <url>` in an existing checkout).
+2. `dreamcontext config github-token "$(gh auth token)"` — the per-machine token (Windows: `config github-token <token>` or `GITHUB_TOKEN`; scope must include Contents:write).
+3. `dreamcontext brain platform` — re-create root `CLAUDE.md` / `.claude/` symlinks (separate mode; Windows needs Developer Mode/elevation, or use `full-repo` mode).
+4. `dreamcontext brain status` — confirm mode, remote, cloud-sync ON, right git root.
+5. `dreamcontext brain sync --pull-only` — take the latest, verify a clean pull.
+6. On Windows: `git config core.autocrlf false` first.
+
+## When sync is "silently failing" (troubleshooting)
+
+Failures are swallowed by design (they never fail sleep or block a session). When a user says *"my teammate isn't seeing my changes"* / *"the other machine is stale,"* run this, in order:
+
+1. **`dreamcontext brain status`** — is cloud sync ON (and *why* — explicit vs derived)? Right `mode` and `remote`? Any `mergeInProgress` / `pendingAgentMerge`?
+2. **Token present?** Check `state/.secrets.json` (or global / `GITHUB_TOKEN`). No token = silent no-op — the most common cause. Set it and retry.
+3. **`dreamcontext brain scrub`** — a scrub-gate BLOCK is the #1 *silent* blocker; it stops the push before anything leaves. Fix the flagged secret/absolute-path and re-sync.
+4. **`dreamcontext brain sync --push-only`** (foreground) — forces the error to the surface instead of the background swallowing it.
+5. **`full-repo` on a detached HEAD** → `detached-head` refusal. Check out a branch.
+6. **Wrong git root** → the enclosing-repo trap above (`rev-parse --show-toplevel`).
+7. **`pendingAgentMerge` / `awaiting-agent`** → a prose conflict is waiting: run **`/dream-sync`**, then `brain sync --continue`.
+
+## `brain` command surface (10 subcommands)
+
+`status`, `enable`, `disable`, `init`, `attach`, `discover`, `platform`, `scrub`, `sync`, `detach`. (`sync` flags: `--pull-only`, `--push-only`, `--strict`, `--continue`, `--resume` — the last two are attended-only; never drive them unattended.) Merge internals live in the `/dream-sync` skill and `skill-sync/references/merge-rules.md`; full feature status in `knowledge/features/brain-repo-sync.md`.

package/skill/references/integrations.md

@@ -218,7 +218,9 @@ dreamcontext federation purge --dry-run            # preview
 
 **Yes, a team can share a single dreamcontext brain.** The whole `_dream_context/` (tasks, knowledge, features, sleep state) becomes **its own git repo** with its own remote — separate from the code repo — and the CLI/desktop app push/pull/merge it the way a team collaborates on code. The brain stays plain markdown/JSON on disk (local-first); git is just the sync transport, not a new database.
 
-**Guide the user here** the moment they say *"I want to use this with my team / with other people," "share the brain," "collaborate on tasks/knowledge together,"* or *"put the brain in its own repo."* Do NOT answer "we don't support that" — this is the feature.
+**Guide the user here** the moment they say *"I want to use this with my team / with other people," "share the brain," "collaborate on tasks/knowledge together," "put the brain in its own repo,"* or *"set it up on my other machine."* Do NOT answer "we don't support that" — this is the feature.
+
+> **Full reference → [brain-sync.md](brain-sync.md)** — the three modes (separate / full-repo / in-tree), per-machine token + auth, shared vs machine-local config, **cross-OS setup**, and the silent-failure troubleshooting playbook. The section below is the quick tour.
 
 **How it differs from its neighbors** (say this if the user conflates them):
 - **Cloud task sync** (ClickUp/GitHub Issues) — mirrors only *tasks* to a task manager, one backend at a time.
@@ -231,11 +233,12 @@ dreamcontext federation purge --dry-run            # preview
 # Person A — create a brand-new shared brain repo (PRIVATE by default) and push a scrubbed first commit
 dreamcontext brain init --code-repo https://github.com/acme/app     # pointer back to the paired code repo
 
-# Person B (and every teammate) — attach the existing brain repo (a TRUST decision: it loads every session)
+# Person B (and every teammate / each new machine) — attach the existing brain repo (a TRUST decision: it loads every session)
 dreamcontext brain discover           # list dreamcontext-brain-topic repos you can access
 dreamcontext brain attach https://github.com/acme/app-brain         # trust warning + diff preview, then confirm
 
-dreamcontext brain status             # mode (separate/in-tree), remote, sync state, cloud-sync switch
+dreamcontext config github-token "$(gh auth token)"   # per-MACHINE token — the token is gitignored, never travels with the repo
+dreamcontext brain status             # mode (separate/full-repo/in-tree), remote, sync state, cloud-sync switch
 ```
 
 ### Day-to-day (mostly automatic)
@@ -258,7 +261,7 @@ missing root symlinks on a fresh clone, and `doctor` flags broken links. Machine
 ### Editing / reconfiguring
 
 - **Turn cloud sync on/off:** `dreamcontext brain enable` / `brain disable`.
-- **Modes:** `separate` (own remote, full auto-sync) vs `in-tree` (brain nested in the code repo — commit-only, **never** auto-pushes; the safe default). Both always run the scrub gate.
+- **Modes:** `separate` (brain in its own remote, full auto-sync) · `full-repo` (whole project → its own `origin`, on the current branch — switch from the dashboard: Settings → Brain → Sync scope) · `in-tree` (commit-only, **never** auto-pushes; the safe default). All run the scrub gate. Full detail + cross-OS setup → [brain-sync.md](brain-sync.md).
 - **Safety rails (always on):** brain repos default **private** (`--public` needs an explicit confirm); a **scrub gate** blocks secrets / absolute local paths before every commit and push; tokens are supplied via `GIT_ASKPASS` (never embedded in the remote URL); per-machine indexes/caches are gitignored and never pushed.
 
 ### From the desktop app? — M2, PENDING (not yet shipped)

package/skill/references/sleep.md

@@ -56,7 +56,7 @@ For non-file-change work (architecture discussion, a decision with no edits): `d
    **Insight-fed objectives:** if `_dream_context/lab/insights/` is non-empty, also run `dreamcontext lab list` — an objective fed by a bound insight (`binding.objective` in the manifest) has a *measured* KR `current` owned by `lab sync`; no specialist hand-writes it. Surface any bound insight whose cache is stale or errored ("KR for `<objective>` is fed by insight `<slug>`, last synced `<date>` — suggest `dreamcontext lab sync <slug>`"). **Sleep NEVER runs `lab sync`** — credentials, latency, non-determinism; refreshing is always an explicit user/agent action outside sleep.
 8. **Marketing pass** if `_dream_context/marketing/` exists: `dreamcontext mk rem-sleep`.
 9. **Council promote check:** `dreamcontext council list --unpromoted` — promote if the user engaged positively.
-10. **`dreamcontext sleep done "<one-paragraph summary stitched from specialist reports>"`** — clears pre-epoch state, resets debt, writes a history entry. (If a remote backend — ClickUp or GitHub — is active and any task pushes failed, this auto-retries once, then errors loudly with the failed slugs.)
+10. **`dreamcontext sleep done "<one-paragraph summary stitched from specialist reports>"`** — clears pre-epoch state, resets debt, writes a history entry. (If a remote backend — ClickUp or GitHub — is active and any task pushes failed, this auto-retries once, then errors loudly with the failed slugs.) **Brain sync also fires here:** if a shared brain repo is active (`brainRepo.autoSync`), `sleep done` runs a foreground `brain sync` (fetch→merge→commit→push). Sync failure never fails sleep — but on a prose conflict it pauses with `awaiting-agent` and prints the `/dream-sync` prompt; run that skill, then `brain sync --continue`. Full model → [brain-sync.md](brain-sync.md).
 11. **Report** the consolidated summary to the user.
 
 ---

package/skill-sync/references/merge-rules.md

@@ -150,8 +150,15 @@ order, BEFORE acquiring the lock:
 
 1. **Flag misuse** → `invalid-flag` + a guiding `note`: `--continue` without `MERGE_HEAD`;
    `--resume` with `MERGE_HEAD` present; `--resume` without a pending handoff.
-2. **`MERGE_HEAD` present** → only `--continue` proceeds; everything else (including `--resume`)
-   returns `already-awaiting-agent`, touching nothing.
+2. **`MERGE_HEAD` present** → only `--continue` proceeds; everything else disambiguates by the
+   **conflict report** (a merge dreamcontext started ALWAYS leaves one; the user's own
+   `git merge`/`rebase` — common in `full-repo`, where the git repo IS the project root —
+   leaves none):
+   - **no report** → `user-merge-in-progress` ("Finish your in-progress git merge first"). Never
+     claims a team merge awaits `/dream-sync` (there's nothing for the agent to resolve).
+   - **report with `codeConflicts`** → `code-conflict` (a full-repo code file for the human's
+     editor — see §16), never an agent job.
+   - **report without `codeConflicts`** → `already-awaiting-agent` (a real prose handoff for `/dream-sync`).
 3. **`pendingAgentMerge && !MERGE_HEAD`** (a LIVE pull-only-deferred handoff) → only `--resume`
    proceeds; everything else returns `already-awaiting-agent`.
 4. **Stale report** (`!MERGE_HEAD && !pendingAgentMerge`, and an existing report) → cleared, then
@@ -213,3 +220,62 @@ lists only `dreamcontext-brain`-topic repos; `Create` defaults private (public r
 confirmed toggle); `Attach` shows the trust warning + incoming diff preview and refuses without
 confirmation; the team-updates badge shows N after a teammate pushes, driven by a background fetch
 (the badge endpoint itself makes no network call in the request path).
+
+## 16. full-repo hardening (2026-07-08) — refuse/defer/recover, never mangle
+
+`full-repo` mode makes the WHOLE project repo the synced unit, so the engine touches real code
+and the user's own git state. Five extra guarantees on top of the separate/in-tree contract:
+
+- **Detached HEAD → refuse.** `full-repo` syncs the CURRENT branch (`git.currentBranch`); on a
+  detached HEAD there is no branch to push. The engine returns **`detached-head`** ("check out a
+  branch") instead of falling back to `main` (which would push detached commits onto the team's
+  `main`). Brain-only modes keep their fixed `main` and never call `currentBranch`.
+- **The user's own merge ≠ a team handoff.** The reentrancy guard (§10.2) distinguishes them by
+  the conflict report's presence. A `MERGE_HEAD` with no report is the user's own `git
+  merge`/`rebase` → **`user-merge-in-progress`**, never `already-awaiting-agent`.
+- **Code conflicts defer to the HUMAN, never to the agent.** A conflicted path OUTSIDE
+  `_dream_context/` is classified **`code`** (`resolveConflicts({fullRepo:true})` →
+  `deferredToHuman`). It is NEVER semantically merged (`merge3Bodies` is for markdown/frontmatter
+  and would mangle source) and NEVER sent to `/dream-sync`. Foreground: git's native 3-way markers
+  are left in the tree for the editor; the human resolves, `git commit`s the merge, and the next
+  sync pushes it (a locally-ahead HEAD now pushes — see below). Headless background pull: aborts to
+  a clean tree (never breaks a working tree with no one watching); the next foreground sync
+  re-surfaces it. The conflict report **separates `codeConflicts` (human) from `deferred` (agent)** so
+  the two never blur → **`code-conflict`** outcome.
+- **Locally-ahead HEAD pushes.** `autoSync` now proceeds (not `noop`) when HEAD is ahead of the
+  remote even with a clean tree and remote-not-ahead — e.g. after the human finishes a code-conflict
+  merge natively. Without this those commits would be silently stranded.
+- **Auto-checkpoint transparency + opt-out.** The pull-only dirty-tree checkpoint reports
+  `checkpointed` + `checkpointSha` (identifiable message, undo via `git reset --soft <sha>^`). The
+  dashboard's on-open pull can pass **`noCheckpoint`** (the "auto-checkpoint on open" preference off) →
+  a dirty tree is left UNTOUCHED (the pull is skipped) instead of auto-committing WIP.
+
+**Failure classification (`src/lib/git-sync/failure.ts`).** Every thrown `GitSyncError` (and a
+token-shaped `no-remote`) maps to a SPECIFIC failure + recovery, never a generic "sync failed":
+`auth` → Reconnect GitHub; `permission` → names the repo + Contents-write scope; `network` →
+"you're offline, will retry" (passive); `push-rejected` (non-fast-forward twice) → Retry sync;
+`unrelated histories` → manual. The `/api/brain/sync` route returns these as `action:'error'` +
+`failure` (200, so the UI renders the recovery affordance). No local work is ever lost — the bar is
+that every failure is surfaced clearly and offers a concrete next step.
+
+**Scrub is MANDATORY over EVERYTHING pushed.** In addition to the staged-commit scrub, EVERY pushing
+path runs a pre-push **`scrubCommitRange`** over the commits about to leave: `autoSync` scrubs
+`origin/main..HEAD` when HEAD is locally ahead; `pushOnlySync` (the `--push-only` CLI path) scrubs
+`(revParse(origin/main) ?? EMPTY_TREE)..HEAD`. So commits made OUTSIDE our staged-commit path (a
+human-finished code-conflict merge, any locally-ahead work) can never reach the remote unscrubbed. A
+block there aborts the push, loudly.
+
+**Scrub-block guidance.** `blocked-scrub` surfaces each `scrub.blocks` entry (file/line/rule); for a
+file whose name marks it a local secret/config (`.env`, `credentials*`, `*.pem`, …) the dashboard
+offers one-click **add-to-`.gitignore`** (`POST /api/brain/scrub/ignore`, server-revalidated). A real
+source file is refused — the secret must be removed, not the file un-tracked. The path is rejected if it
+contains gitignore metacharacters (`! # * ? [ ]`) or control chars: a leading `!` is a NEGATION that
+would UN-ignore an already-excluded secret, so it can never be written.
+
+**Mixed conflicts keep both records.** When one merge conflicts on BOTH a code file (human) and a brain
+prose file (agent), the report records `codeConflicts` AND the agent `deferred` snapshots — the prose
+conflict is never silently dropped.
+
+**Status `mergeKind`.** `GET /api/brain/status` returns `mergeKind: 'agent' | 'code' | 'user' | null`
+(+ `codeConflicts[]`) so the dashboard shows the right banner: Resolve-with-AI (agent), resolve-in-editor
+(code), or finish-your-git-merge (user).

package/dist/dashboard/assets/channel-CTaS69UP.js

@@ -1 +0,0 @@
-import{aq as o,ar as n}from"./index-D85kugqO.js";const t=(r,a)=>o.lang.round(n.parse(r)[a]);export{t as c};

package/dist/dashboard/assets/classDiagram-6PBFFD2Q-DYWavBQh.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-4TB4RGXK-DqrxE_QA.js";import{_ as i}from"./index-D85kugqO.js";import"./chunk-FMBD7UC4-5rx_crEA.js";import"./chunk-YZCP3GAM-Bucdr9No.js";import"./chunk-55IACEB6-D8eCITwq.js";import"./chunk-EDXVE4YY-DBzJ4Kk6.js";var u={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{u as diagram};

package/dist/dashboard/assets/classDiagram-v2-HSJHXN6E-DYWavBQh.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-4TB4RGXK-DqrxE_QA.js";import{_ as i}from"./index-D85kugqO.js";import"./chunk-FMBD7UC4-5rx_crEA.js";import"./chunk-YZCP3GAM-Bucdr9No.js";import"./chunk-55IACEB6-D8eCITwq.js";import"./chunk-EDXVE4YY-DBzJ4Kk6.js";var u={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{u as diagram};

package/dist/dashboard/assets/clone-Dpdgvgqp.js

@@ -1 +0,0 @@
-import{b as r}from"./graph-CJvnKdzN.js";var e=4;function a(o){return r(o,e)}export{a as c};

package/dist/dashboard/assets/stateDiagram-v2-QKLJ7IA2-CFAZrDsQ.js

@@ -1 +0,0 @@
-import{s as t,b as r,a,S as s}from"./chunk-OYMX7WX6-CLE6jH1t.js";import{_ as i}from"./index-D85kugqO.js";import"./chunk-55IACEB6-D8eCITwq.js";import"./chunk-EDXVE4YY-DBzJ4Kk6.js";var l={parser:a,get db(){return new s(2)},renderer:r,styles:t,init:i(e=>{e.state||(e.state={}),e.state.arrowMarkerAbsolute=e.arrowMarkerAbsolute},"init")};export{l as diagram};