dreamcontext 0.14.1 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dreamcontext",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "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 (whole project)** | **Yes — a team OR one person across machines can share ONE brain.** Cloud sync pushes the WHOLE project (code + `.claude/` + `_dream_context/`) to its GitHub `origin` on the current branch (`full-repo`); when off it's `in-tree` (commit-only). `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", "sync my project to GitHub", "set it up on my other machine"), that's **whole-project cloud sync**: `dreamcontext brain enable` (turn it on — needs a GitHub `origin`) / `brain status`, auto-synced at `sleep done`, prose conflicts resolved by the **`/dream-sync`** skill. **Guide them into it — don't say "unsupported".** Two modes (`full-repo` when on / `in-tree` when off), 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)** — **whole-project GitHub cloud sync**: the two modes (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,119 @@
+# Brain sync (GitHub cloud sync for the whole project)
+
+The one reference for **cloud sync** — what it is, the two 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," "sync my project to GitHub."* Do NOT answer "we don't support that" — this is the feature.
+
+## What it is
+
+The project (your code + `.claude/` + the brain under `_dream_context/`) is synced to the project's **own GitHub repo** 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`. There is one shared, whole-project model — `.claude/` and `_dream_context/` live in the code repo and travel together, so there is no separate brain repo and no symlink layer to maintain.
+
+## The two sync modes
+
+Mode lives in `_dream_context/state/.config.json` under `brainRepo.mode`. **Anything not `full-repo` resolves to `in-tree`.**
+
+| Mode | Git root | Remote | Branch | What lands on the remote | Auto-push? |
+|---|---|---|---|---|---|
+| **`full-repo`** | the **project root** (the whole project is the repo) | the project's own `origin` | the **current** branch (never assumes `main`) | the **entire project** — code + `.claude/` + `_dream_context/` nested inside it | **Yes** |
+| **`in-tree`** (default) | the project root | — | — | nothing pushed — **commit-only**, stages `_dream_context/` and commits locally | **No, never** |
+
+- **`full-repo`** is cloud sync turned ON: the whole project folder is the synced repo (brain nested under `_dream_context/`, plus root `CLAUDE.md` / `.claude/`). 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 (cloud sync OFF): it commits the brain alongside your code but **never pushes** — turn cloud sync on to promote it to `full-repo`.
+
+**Turning it on/off:** cloud sync is the master switch. Enable it from the **dashboard** (Settings → Brain → Cloud sync toggle; server route `POST /api/brain/settings`) or the CLI (`dreamcontext brain enable`). Enabling requires the project to already have a GitHub `origin` (it errors `no_origin` otherwise) and flips the mode to `full-repo`; disabling reverts to `in-tree`.
+
+## Set it up (CLI)
+
+```bash
+# 0. Token FIRST — every push needs it (see Auth for scope + resolution order).
+dreamcontext config github-token "$(gh auth token)"   # per-MACHINE token; gitignored, never travels with the repo
+
+# 1. Make sure the project has a GitHub origin (full-repo pushes to it).
+git remote add origin https://github.com/<you-or-org>/<repo>.git   # skip if it already has one
+
+# 2. Turn cloud sync ON — flips the project to full-repo (whole project → origin, current branch).
+dreamcontext brain enable
+
+dreamcontext brain status                        # verify: mode full-repo, remote, resolved cloud-sync switch
+```
+
+Every push uses the **same resolved token**, so set the token (or be logged into dreamcontext for the global store) *before* enabling. (PowerShell/cmd have no `$(…)` — use `dreamcontext config github-token <token>` or set `GITHUB_TOKEN`.) Because the whole project is the synced unit, `CLAUDE.md` and `.claude/` are already at the project root and sync natively — nothing extra to wire up.
+
+## Auth — how sync 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):** sync **pushes repo contents**, so the token needs classic **`repo`** scope, or a fine-grained PAT with **Contents: read & write** on the project 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 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 `brainRepo` block: **`mode`, `enabled`, `autoSync`**. Consequence: **an explicit `mode` or `enabled` propagates to everyone** on the next sync — they are a *shared* decision, not per-machine.
+- **`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`), 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 `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: sync project (dreamcontext)` (full-repo), `chore(brain): sync` (in-tree commit-only), `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. 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 project 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 project must be its OWN git root (the enclosing-repo trap).** In `full-repo` the repo root must be the project folder. Verify: `git -C <project> rev-parse --show-toplevel` should print *that* folder — **not climb into an enclosing parent repo** (e.g. a home-directory `~/.git`). 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 project 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.
+- **No symlinks involved.** Because the whole project syncs natively, `CLAUDE.md`/`.claude/` are plain files at the project root on every OS — no symlink layer, so Windows Developer-Mode / elevation is never required for cloud sync.
+
+**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 |
+| `CLAUDE.md` / `.claude/` | plain files (sync natively) | native | native (no symlinks, no Developer Mode needed) |
+| 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) and `core.autocrlf` (step 5) differ.
+
+1. `git clone <project-url>` — the whole project (code + `.claude/` + `_dream_context/`).
+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 status` — confirm mode `full-repo`, remote, cloud-sync ON, right git root.
+4. `dreamcontext brain sync --pull-only` — take the latest, verify a clean pull.
+5. 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. **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 (5 subcommands)
+
+`status`, `enable`, `disable`, `scrub`, `sync`. (`sync` flags: `--pull-only`, `--push-only`, `--strict`, `--continue`, `--resume` — the last two are attended-only; never drive them unattended.) `brain enable` turns cloud sync ON (whole-project `full-repo` sync — needs a GitHub `origin`); `brain disable` reverts to `in-tree`. 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/cli-reference.md

@@ -214,13 +214,10 @@ Sync the WHOLE brain (`_dream_context/`) — tasks, knowledge, features, sleep s
 
 | Command | Description |
 |---|---|
-| `brain status` | Show brain-repo mode (`separate`/`in-tree`), remote, sync state, and whether cloud sync is ON. Reports `mergeInProgress` / `pendingAgentMerge` (the `/dream-sync` handoff signals). |
-| `brain init` | Create a NEW brain repo on GitHub (**private by default**) and push a scrubbed first commit. `--public` (requires interactive confirm), `--code-repo <url>` (store a pointer to the paired code repo). |
-| `brain attach <url>` | Attach an EXISTING team brain repo — a **TRUST decision** (S6): prints a trust warning + incoming-diff preview and refuses without confirmation. `-y/--yes` to skip the prompt. |
-| `brain discover` | List `dreamcontext-brain`-topic repos you can access on GitHub. |
+| `brain status` | Show sync mode (`full-repo`/`in-tree`), remote, sync state, and whether cloud sync is ON. Reports `mergeInProgress` / `pendingAgentMerge` (the `/dream-sync` handoff signals). |
+| `brain enable` | Turn cloud sync ON — sync the WHOLE project (code + `.claude/` + `_dream_context/`) to its GitHub `origin` on the current branch (`full-repo`). Needs a GitHub `origin`. |
+| `brain disable` | Turn cloud sync OFF — revert to `in-tree` (the brain is still committed locally, never pushed). |
 | `brain sync` | Fetch → semantic-merge-on-conflict → commit → push (or, in `in-tree` mode, commit-only — never auto-pushes). `--pull-only` (take team content in, never push), `--push-only`, `--strict` (WARN scrub hits block too), `--resume` / `--continue` (the attended `/dream-sync` handoff — see below). |
-| `brain enable` / `brain disable` | Explicit master switch for cloud sync on this project (v3.3). |
-| `brain platform` | Carry the Claude Code layer (CLAUDE.md + `.claude/`) INSIDE the brain repo: moves them into `_dream_context/platform/` and symlinks them back from the project root, so they sync with the team. Missing root symlinks are re-created automatically by every `brain sync` (fresh clones self-wire) and flagged by `doctor`. `--status` reports without changing anything. Machine-local files (`platform/.claude/settings.local.json`, `scheduled_tasks.lock`) never sync. |
 | `brain scrub` | Dry-run the secrets/absolute-path scrub gate against the current staged tree. |
 
 **Automatic sync:** every `dreamcontext sleep done` runs a brain sync (fetch/merge/commit/push); failure never fails sleep. Session-start does a non-blocking background pull. **On an agent-class merge conflict** (two people edited the same prose section) the CLI stops at `already-awaiting-agent` and defers to the **`/dream-sync` skill** — the agent half that reads base/ours/theirs and writes the semantic merge, then `brain sync --continue`. Never drive `--resume`/`--continue` unattended.

package/skill/references/integrations.md

@@ -214,56 +214,49 @@ dreamcontext federation purge --dry-run            # preview
 
 ---
 
-## ✅ Team brain sync (shared brain repo) — collaborate on ONE brain
+## ✅ Team brain sync (whole project) — collaborate on ONE brain
 
-**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.
+**Yes, a team can share a single dreamcontext brain.** Cloud sync pushes the **whole project** — your code, `.claude/`, and the brain nested under `_dream_context/` — to the project's own GitHub `origin` on the current branch, 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. Because `.claude/` and `_dream_context/` already live in the code repo, they travel together — there is no separate brain repo and no symlink layer to maintain.
 
-**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,"* 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 two modes (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.
 - **Federation** — read-only recall across your OWN separate projects; nothing is ever copied.
-- **Shared brain repo (this)** — the *whole* brain is one git-synced artifact several people edit together.
+- **Whole-project sync (this)** — the *whole* project (code + brain) is one git-synced artifact several people edit together.
 
-### Onboarding a team (M1 — CLI, shipped today)
+### Onboarding a team
 
 ```bash
-# 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
+# Each person / each machine — set a per-MACHINE token (gitignored, never travels with the repo)
+dreamcontext config github-token "$(gh auth token)"
 
-# Person B (and every teammate) — 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
+# Make sure the project has a GitHub origin (full-repo pushes to it), then turn cloud sync ON
+git remote add origin https://github.com/acme/app.git   # skip if it already has one
+dreamcontext brain enable              # flips the project to full-repo (whole project → origin)
 
-dreamcontext brain status             # mode (separate/in-tree), remote, sync state, cloud-sync switch
+dreamcontext brain status              # mode (full-repo/in-tree), remote, sync state, cloud-sync switch
 ```
 
+Teammates just `git clone` the project and run the same two steps (token + `brain enable`). Cloud sync can also be toggled from the dashboard (Settings → Brain → Cloud sync).
+
 ### Day-to-day (mostly automatic)
 
-- **Every `sleep done`** fetches → semantic-merges on conflict → commits → pushes the brain (sync failure never fails sleep). **Session start** does a non-blocking background pull. So teammates' consolidated context reaches everyone without a manual step.
+- **Every `sleep done`** fetches → semantic-merges on conflict → commits → pushes the project (sync failure never fails sleep). **Session start** does a non-blocking background pull. So teammates' consolidated context reaches everyone without a manual step.
 - **Manual sync any time:** `dreamcontext brain sync` (or `--pull-only` to just take team content in).
-- **On a prose merge conflict** (two people edited the same `##` section of a knowledge/feature doc), the CLI resolves every deterministic file itself and stops at `already-awaiting-agent`, deferring the rest to the **`/dream-sync` skill** — the agent reads base/ours/theirs snapshots, writes the real semantic merge, and hands back with `brain sync --continue`. (`--resume`/`--continue` are attended-only; never drive them unattended.)
-
-### Platform layer — share CLAUDE.md + .claude with the team
-
-A separate-mode brain repo is rooted at `_dream_context/`, so the Claude Code files at the
-project root (CLAUDE.md, `.claude/` skills/agents/hooks) would never sync on their own.
-`dreamcontext brain platform` fixes that: it moves them into `_dream_context/platform/` and
-symlinks them back from the project root (Claude Code resolves the links transparently).
-From then on they sync with the brain like everything else; every `brain sync` re-creates
-missing root symlinks on a fresh clone, and `doctor` flags broken links. Machine-local files
-(`platform/.claude/settings.local.json`, `scheduled_tasks.lock`) stay gitignored.
-`brain platform --status` reports without changing anything.
+- **On a prose merge conflict** (two people edited the same `##` section of a knowledge/feature doc), the CLI resolves every deterministic file itself and stops at `already-awaiting-agent`, deferring the rest to the **`/dream-sync` skill** — the agent reads base/ours/theirs snapshots, writes the real semantic merge, and hands back with `brain sync --continue`. A real **code** conflict is left for the human's editor with native git markers (never sent to the agent). (`--resume`/`--continue` are attended-only; never drive them unattended.)
 
 ### 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.
-- **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.
+- **Turn cloud sync on/off:** `dreamcontext brain enable` / `brain disable`, or the dashboard Settings → Brain toggle.
+- **Modes:** `full-repo` (cloud sync ON — whole project → its own `origin`, on the current branch; needs a GitHub `origin`) · `in-tree` (cloud sync OFF — commit-only, **never** auto-pushes; the safe default). Both run the scrub gate. Full detail + cross-OS setup → [brain-sync.md](brain-sync.md).
+- **Safety rails (always on):** a **scrub gate** blocks secrets / absolute local paths before every commit and push; the project-root `.gitignore` is force-written with the machine-local brain excludes + secrets before every whole-project stage; 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)
+### From the desktop app
 
-The one-click UX — **GitHub device-flow login from the Launcher, a repo picker over your `dreamcontext-brain`-topic repos, UI "create"/"attach" with the trust preview, and a team-updates badge** — is **M2, still pending**. Today the shared-brain setup is **CLI-only** (a technical user runs `brain init` / `brain attach`). Be honest about this: a non-technical teammate can't yet do the *setup* from the app; once attached, the normal dashboard/app reads the shared brain like any other. (Full status: `knowledge/features/brain-repo-sync.md`; merge internals: `skill-sync/references/merge-rules.md`.)
+**GitHub device-flow login from the Launcher** and the dashboard **Settings → Brain Cloud-sync toggle** turn whole-project sync on/off (with a **team-updates badge** and a one-click "Resolve with AI" for a deferred prose merge). (Full status: `knowledge/features/brain-repo-sync.md`; merge internals: `skill-sync/references/merge-rules.md`.)
 
 ---
 

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/SKILL.md

@@ -66,9 +66,8 @@ Read `_dream_context/state/.brain-merge/report.json`. For each entry in `deferre
    section-by-section — sections only one side touched keep that side's version; sections BOTH
    touched are the ones you're here for — read them and write prose that keeps both people's point,
    reconciling wording, not concatenating raw diffs.
-3. Stage it — run `git add <path>` inside the brain repo (in `separate` mode, the brain repo root
-   IS `_dream_context/`; in `in-tree` mode, it's the code repo root and `path` already carries the
-   `_dream_context/` prefix).
+3. Stage it — run `git add <path>` at the project root (the git root is the project folder, so
+   `path` carries the `_dream_context/` prefix).
 
 Do this for every entry in `deferred` before moving on — `--continue` commits everything staged in
 one shot.

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

@@ -5,23 +5,28 @@ plan v3.3). The CLI (`src/lib/git-sync/*`) implements everything on this page.
 
 ## 1. Modes
 
-- **`separate`** — the brain (`_dream_context/`) lives in its own git repo + remote. Full
-  auto-sync: fetch → merge → commit → push. Opt-in (`dreamcontext brain init`/`attach`).
-- **`in-tree`** — the brain is nested inside the code repo (the default for every existing
-  project). **Commit-only — NEVER auto-pushes** (a push here would push the code repo). The scrub
-  gate still runs before every in-tree commit — an in-tree commit lands in the code repo's history
-  and can be pushed to a public OSS remote by the user's own normal `git push`.
+- **`full-repo`** — cloud sync ON: the WHOLE project (code + `.claude/` + `_dream_context/`) is the
+  synced unit, pushed to the project's own `origin` on the CURRENT branch. Full auto-sync: fetch →
+  merge → commit → push. Enabled via `dreamcontext brain enable` or the Settings toggle (requires a
+  GitHub `origin`).
+- **`in-tree`** (default) — cloud sync OFF: the brain is nested inside the code repo. **Commit-only —
+  NEVER auto-pushes.** The scrub gate still runs before every in-tree commit — an in-tree commit
+  lands in the code repo's history and can be pushed to a public OSS remote by the user's own normal
+  `git push`.
 
 ## 2. Cloud-sync master switch (v3.3)
 
 `brainRepo.enabled` (explicit) always wins. Absent ⇒ derived: **ON** iff the project is already
-GitHub-connected (code repo's `origin` is a `github.com` URL, OR `taskBackend==='github'`, OR a
-`brainRepo.remote` is configured) — **OFF** otherwise (new/unconnected projects stay off until the
-user runs `dreamcontext brain enable` or flips the Settings toggle). When OFF: `sleep done` skips
-the whole block with one dim line, the session-start pull is never spawned, and `brain sync`
-returns `action:'disabled'`.
+GitHub-connected (code repo's `origin` is a `github.com` URL, OR `taskBackend==='github'`) — **OFF**
+otherwise (new/unconnected projects stay off until the user runs `dreamcontext brain enable` or
+flips the Settings toggle). Enabling flips the mode to `full-repo`; disabling reverts to `in-tree`.
+When OFF: `sleep done` skips the whole block with one dim line, the session-start pull is never
+spawned, and `brain sync` returns `action:'disabled'`.
 
-## 3. Tracked vs local — the brain repo's own `.gitignore`
+## 3. Tracked vs local — machine-local excludes under `_dream_context/`
+
+In `full-repo` the whole project is staged with `git add -A` at the project root, so the project's
+own `.gitignore` must exclude the machine-local brain runtime + secrets (prefixed `_dream_context/`).
 
 | Path | `taskBackend=local` | `taskBackend=github`/`clickup` |
 |---|---|---|
@@ -33,21 +38,12 @@ returns `action:'disabled'`.
 | `state/.secrets.json`, `.sleep.json`, `.sleep-history.json`, `.agent-sessions.json`, `.session-digests/`, `.conflicts/`, `.brain-merge/`, `.version-check.json`, `.auto-upgrade.json`, `.brain-local.json`, `.lab-prefs.json`, `.tasks-map.json`, `.tasks-sync.*`, `.tasks-queue.json`, `.obsidian/`, `tmp/`, `**/.env`, `**/.DS_Store` | gitignored | gitignored |
 | `lab/**` (insights + cache) | tracked | tracked |
 | `lab/credentials.json` / `lab/credentials.*` (except the tracked `credentials.example.json`) | gitignored | gitignored |
-| `platform/**` (Claude Code layer: CLAUDE.md + .claude) | tracked | tracked |
-| `platform/.claude/settings.local.json`, `platform/.claude/scheduled_tasks.lock` | gitignored | gitignored |
-
-Built by `buildBrainGitignore(taskBackend)` (`src/lib/git-sync/brain-repo.ts`) and written on
-bootstrap (`brain init`/`attach`); `ensureLocalOnlyArtifacts` re-asserts it after a clone/pull.
 
-## 3b. Platform layer — CLAUDE.md + .claude travel with the brain
-
-A separate-mode brain repo is rooted at `_dream_context/`, so the Claude Code project files at
-the PROJECT root would never sync. `dreamcontext brain platform` migrates them: the real files
-move to `_dream_context/platform/{CLAUDE.md,.claude}` and the project root keeps relative
-symlinks into it (Claude Code resolves them transparently). On every `runBrainSync` the engine
-best-effort re-creates missing root symlinks (`healPlatformLinks`), so a fresh clone of the brain
-is fully wired after its first sync; `doctor` flags missing links and root-vs-platform conflicts.
-Machine-local runtime files inside `platform/.claude/` (see table) never sync.
+The `_dream_context/.gitignore` is built by `buildBrainGitignore(taskBackend)` and the project-root
+excludes by `ensureFullRepoGitignore(projectRoot, taskBackend)` (both `src/lib/git-sync/brain-repo.ts`),
+written gitignore-first before every whole-project stage; `ensureLocalOnlyArtifacts` re-asserts the
+`_dream_context/.gitignore` after a clone/pull. `CLAUDE.md` and `.claude/` are plain files at the
+project root and sync natively — no separate brain repo, no platform-layer symlinks.
 
 ## 4. Credential supply (GIT_ASKPASS — decision F)
 
@@ -74,8 +70,8 @@ global `~/.dreamcontext/.secrets.json` tier between the two.)
 
 ## 6. Scrub gate (decisions — BLOCK vs WARN)
 
-Runs before EVERY brain content commit: in-tree, separate, `brain init`'s first commit, `brain
-detach`, and after every merge (a merge can reintroduce a secret).
+Runs before EVERY commit: in-tree commits, the full-repo whole-project push, and after every merge
+(a merge can reintroduce a secret).
 
 - **BLOCK** (aborts everywhere, loudly, non-zero exit): GitHub PAT/OAuth tokens, AWS/Google/Slack/
   OpenAI/Anthropic/Stripe keys, private-key headers, 3-part JWTs.
@@ -145,13 +141,20 @@ report is a LIVE handoff — never auto-cleared, consumable only via `--resume`.
 
 ## 10. The reentrancy guard — 5-clause precedence (v3.2)
 
-Every `runBrainSync` call (separate mode only — in-tree bypasses this entirely, see §1) checks, in
+Every `runBrainSync` call (full-repo only — in-tree bypasses this entirely, see §1) checks, in
 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
@@ -205,11 +208,70 @@ the fixed `dreamcontext-sync <noreply@dreamcontext.local>` author (passed explic
 takes zero forward dependency on M3. **M3 tier (adds, does not replace):** once a GitHub login
 exists, `mapLoginToPerson(login)` swaps in the resolved `person:` identity on top.
 
-## 15. Manual UI checklist (M2 — appendix)
-
-When M2 (launcher/dashboard) ships, verify by hand: device-flow login (shows `user_code`, opens
-`verification_uri`) AND the PAT-paste fallback, both with the scope disclosure visible; `Discover`
-lists only `dreamcontext-brain`-topic repos; `Create` defaults private (public requires a
-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).
+## 15. Manual UI checklist (dashboard — appendix)
+
+Verify by hand: device-flow login (shows `user_code`, opens `verification_uri`) AND the PAT-paste
+fallback, both with the scope disclosure visible; the **Cloud sync toggle** turns whole-project
+sync on (400 `no_origin` if the project has no GitHub `origin`) and off (reverts to `in-tree`);
+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); a deferred prose merge surfaces a
+one-click **"Resolve with AI"** banner.
+
+## 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 base merge 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};