dreamcontext 0.8.7 → 0.9.0

package/skill/references/cli-reference.md

@@ -0,0 +1,203 @@
+# dreamcontext CLI — Complete Command Reference
+
+Every command and flag, grouped. All commands are prefixed with `dreamcontext`. For reading/searching context files use native tools; use the CLI for everything structured. Run `dreamcontext <command> --help` for live details. Running `dreamcontext` with no args opens an interactive menu.
+
+> Conventions: `<required>`, `[optional]`, `a|b` = choices, `…` = repeatable/multi-word.
+
+---
+
+## Setup & maintenance
+
+| Command | Description |
+|---|---|
+| `setup` | **Front door.** One-shot: init + install-skill + install-instructions, and on macOS offers to install the desktop app. Flags: `--defaults` (claude, no packs, single-product, no prompts), `-y/--yes`, `--platforms <list>`, `--packs <list>`, `--multi-product <list>`, `--keep-native-memory`, `--install-app` (force desktop app), `--skip-app`. (`DREAMCONTEXT_INSTALL_NO_APP=1` also skips the app.) |
+| `init` | *(deprecated standalone)* Scaffold `_dream_context/` only. Flags: `-y/--yes`, `--name`, `--description`, `--user`, `--stack`, `--priority`, `--platforms <list>`, `--multi-product <list>`. |
+| `install-skill` | *(deprecated standalone)* Install skill + agents + hooks. Flags: `--platforms <list>`, `--packs [names...]` (interactive if none), `--skill <name>` (one sub-skill), `--list`. |
+| `install-instructions` | *(deprecated standalone)* Install managed root instructions (CLAUDE.md / AGENTS.md). Flags: `--platforms <list>`, `--mode append\|replace\|skip`. (`install-claude-md` is a legacy alias.) |
+| `update` | Refresh THIS project's installed skill, agents, hooks, packs, references, and root instructions to the latest shipped version. Flags: `--packs-only`, `--core-only`, `-y/--yes`. |
+| `upgrade` | Upgrade the CLI, then update the desktop app (if installed) and offer to refresh **every registered project** — one command brings the whole machine current. Flags: `--check` (print current vs latest, don't install), `-y/--yes` (refresh app + all projects non-interactively). |
+| `doctor` | Validate `_dream_context/` structure and report issues. |
+| `config show` | Print project config (platforms, packs, products, people, native-memory, shareable, task backend). |
+| `config native-memory enable\|disable` | Toggle Claude Code's native auto-memory (disabled by default so dreamcontext owns memory). |
+| `config shareable on\|off` | Toggle whether peer vaults may recall this project (default off/private). |
+| `config people [names...]` | Set the people roster; syncs the `## People` block in `1.user.md`. `--clear` for single-person. |
+| `config task-backend local\|clickup\|github` | **[Advanced]** Switch the task backend — one cloud sync at a time (see [integrations.md](integrations.md)). |
+| `config clickup-token [token]` | Store a ClickUp API key in the gitignored secrets file. `--user <name>` to scope it. |
+| `config clickup-list <teamId> <spaceId> <listId>` | Set the ClickUp sync target. `--migrate` / `--keep` when changing lists. |
+| `config clickup-member <person> <memberId>` | Map a roster person to a ClickUp member id. `--token-env <ENV>`. |
+| `config github-token [token]` | Store a GitHub token in the gitignored secrets file (also reads `GITHUB_TOKEN`/`GH_TOKEN`). `--user <name>` to scope it. |
+| `config github-repo <owner> <repo>` | Set the GitHub sync target (`owner`/`repo`). |
+
+---
+
+## Tasks
+
+| Command | Description |
+|---|---|
+| `tasks list` | List/filter/group tasks (excludes completed by default). Flags: `-s/--status`, `-a/--all`, `--tag <t>` (repeatable, AND), `--any-tag <t>` (repeatable, OR), `--version <id>`, `--priority <level>`, `--feature <slug>`, `-g/--group-by tag\|version\|priority\|status`, `--long`, `--tags`, `--json`. Filters compose (AND), case-insensitive. |
+| `tasks tags` | Distinct task tags with counts. `-a/--all`, `--json`. |
+| `tasks create <name>` | Create a task. Flags: `-d/--description`, `-p/--priority critical\|high\|medium\|low`, `-u/--urgency …`, `-s/--status`, `-t/--tags <csv>`, `-w/--why`, `-v/--version`, `--person <name>`, `--reach <1-10>`, `--impact <1-5>`, `--confidence 25\|50\|75\|100`, `--effort <weeks>`, `--due YYYY-MM-DD`. |
+| `tasks rice <name>` | Print or update RICE values. `--reach`/`--impact`/`--confidence`/`--effort`, `--clear`. |
+| `tasks due <name> <YYYY-MM-DD\|clear>` | Set or clear a due date. |
+| `tasks tag <name> <tags...>` | Add (or `--remove`) tags. `person:<slug>` assigns a person. |
+| `tasks insert <name> <section> <content...>` | Insert into a section: `why`, `user_stories`, `acceptance_criteria`, `constraints`, `technical_details`, `notes`, `changelog`. |
+| `tasks log <name> [content...]` | Add a changelog entry (cross-session continuity). **Use every session.** |
+| `tasks status <name> <todo\|in_progress\|in_review\|completed> [reason...]` | Change status (logs to changelog). |
+| `tasks complete <name> [summary...]` | Mark completed (convenience). |
+| `tasks delete <name>` | Delete a task (propagates to remote backend on sync). `--yes`. |
+| `tasks doctor [name]` | Validate the Workflow flowchart is in sync with Acceptance Criteria (all tasks if name omitted). |
+| `tasks sync [push\|pull\|both]` | Sync with the remote backend (no-op on local). `--hook`, `--json`. |
+| `tasks members` | People with access to the remote list (assignee candidates). `--json`. |
+| `tasks provision` | Create recommended custom fields on the remote list. |
+| `tasks sync-hooks install\|uninstall` | Manage best-effort git sync triggers (post-commit, pre-push). |
+
+Sections for `tasks insert`: `why`, `user_stories`, `acceptance_criteria`, `constraints`, `technical_details`, `notes`, `changelog`. See [tasks-and-features.md](tasks-and-features.md) for the full protocol.
+
+---
+
+## Features
+
+| Command | Description |
+|---|---|
+| `features create <name>` | Create a feature PRD. `-w/--why`, `-t/--tags <csv>`, `-s/--status planning\|in_progress\|in_review\|active\|shipped\|deprecated`, `--related-tasks <csv>`. |
+| `features set <name> <tags\|status\|related_tasks> <value...>` | Set a frontmatter field without hand-editing. |
+| `features insert <name> <section> <content...>` | Insert into a section (replaces template placeholders on first write; `user_stories`/`acceptance_criteria` auto-format as `- [ ]`). |
+| `features doctor` | Check PRDs for staleness, orphans, dangling task refs (read-only). |
+
+Sections for `features insert`: `changelog`, `notes`, `technical_details`, `constraints`, `user_stories`, `acceptance_criteria`, `why`. **Features are sleep-only — do not update during active work.**
+
+---
+
+## Core (changelog & releases)
+
+| Command | Description |
+|---|---|
+| `core changelog add` | Add a changelog entry. `--type feat\|fix\|refactor\|chore\|docs\|perf\|test\|change`, `--scope`, `--description`, `--summary` (≤200 char), `--references <csv>` (`commit:`/`file:`/`knowledge:`/`feature:`/`task:`/`url:`), `--authors <csv>`, `--supersedes <key>`, `--breaking`. |
+| `core releases add` | Create a release (auto-discovers tasks/features/changelog). `-V/--ver`, `-s/--summary`, `--status planning\|released` (default released), `-y/--yes`. |
+| `core releases list` | List recent releases. `-n/--count`. |
+| `core releases active [version]` | Get/set the active planning version (default for new tasks' version). `--clear` to unset. |
+| `core releases show <version>` | Show a release's details. |
+
+---
+
+## Knowledge
+
+| Command | Description |
+|---|---|
+| `knowledge create <name>` | Create a knowledge file. `-d/--description`, `-t/--tags <csv>`, `-c/--content`. |
+| `knowledge index` | Show the knowledge index. `--tag <tag>`, `--plain`. |
+| `knowledge tags` | List standard tags. `--plain`. |
+| `knowledge move <slug> <folder>` | Move `knowledge/<slug>.md` → `knowledge/<folder>/<basename>.md` and rewrite inbound `[[wikilinks]]` atomically (target token only; `\|alias`/`#anchor` preserved). Free-form folders — nothing reserved; nested allowed; path traversal + clobber rejected. Use this instead of `mv` + hand-editing links. |
+| `knowledge touch <slug>` | Record access (decay/staleness tracking + warm loading). |
+
+> `knowledge/**/*.md` is indexed **recursively**, so knowledge organized into context folders (`knowledge/<context>/…`) stays first-class. Group a flat file into a context folder with `knowledge move <slug> <folder>` (atomic move + wikilink rewrite); `sleep-product` calls this same command during consolidation; legacy flat `knowledge/diagrams/` boards are folded by `migrations apply-diagrams`. Never hand-move + hand-edit links. See [knowledge-and-recall.md](knowledge-and-recall.md).
+
+---
+
+## Memory (recall & corpus)
+
+| Command | Description |
+|---|---|
+| `memory recall <query...>` | Search the corpus (knowledge + features + tasks + memory + changelog). `-t/--top <n>`, `--types <csv>`, `--json`, `--plain`, `--vault <name>` (repeatable), `--connected`, `--all-vaults`. |
+| `memory remember <text...>` | Quick-append a CHANGELOG entry (`type=note`, `scope=quick`). `--summary`, `--type`, `--scope`, `--references <csv>`, `--person <csv>`. |
+| `memory update <slug>` | Update a knowledge file. `-d/--description`, `-t/--tags`, `-c/--content`, `--append <text>`, `--pin`, `--unpin`. |
+| `memory delete <slug>` | Delete a knowledge file (irreversible; recover via git). `-f/--force`. |
+| `memory list` | List the corpus by type. `--types <csv>`, `--plain`. |
+| `memory status` | Corpus size + breakdown by type. |
+| `recall status\|on\|off\|raw` | Control recall mode: `on`=haiku (default, LLM picks docs), `raw`=BM25 only, `off`=disabled. |
+
+---
+
+## Sleep / consolidation
+
+| Command | Description |
+|---|---|
+| `sleep status` | Current debt level + history. |
+| `sleep add <score> <description...>` | Record a debt-accumulating action (non-file work). |
+| `sleep start` | Begin consolidation epoch (safe clearing). `--deep` forces deep consolidation (authorizes destructive knowledge ops). |
+| `sleep done <summary...>` | Mark consolidation complete, write history, reset debt. |
+| `sleep debt` | Output the debt number (programmatic). |
+| `sleep history` | Consolidation history log. `-n/--limit`. |
+
+See [sleep.md](sleep.md) for the full flow.
+
+---
+
+## Bookmarks & triggers
+
+| Command | Description |
+|---|---|
+| `bookmark add <message...>` | Tag an important moment. `-s/--salience 1\|2\|3` (default 2), `-t/--task <slug>`. |
+| `bookmark list` / `bookmark clear` | Show / remove all bookmarks. |
+| `trigger add <when> <remind...>` | Create a contextual reminder. `-m/--max-fires` (default 3), `-s/--source`. |
+| `trigger list` / `trigger remove <id>` | Show / remove triggers. |
+
+---
+
+## Taxonomy
+
+| Command | Description |
+|---|---|
+| `taxonomy vocab` | Show the resolved vocabulary (defaults + `core/taxonomy.json`). `--json`, `--facet <facet>`. |
+| `taxonomy audit` | Audit corpus tags against the vocabulary (read-only). `--json`. |
+| `taxonomy init` | Scaffold `core/taxonomy.json` (idempotent). |
+| `taxonomy add <tag>` | Add a tag to the vocabulary. |
+| `taxonomy alias <alias> <canonical>` | Add an alias→canonical mapping. |
+| `taxonomy resolve <tag>` | Show normalized form, classification, canonical resolution. `--json`. |
+
+Never hand-edit `core/taxonomy.json` — mutate via these commands.
+
+---
+
+## Federation / vaults (see [integrations.md](integrations.md))
+
+| Command | Description |
+|---|---|
+| `vaults add\|list\|discover\|remove` | Manage the global vault registry. `discover [root] [--register]`. |
+| `connect <vault>` | Read a peer. `-d/--direction out\|in\|both` (out = read), `--topics <csv>`. |
+| `disconnect <vault>` | Remove a connection. |
+| `connections list` | List this vault's connections. |
+| `federation peers` | Refresh + print readable-peer summaries. |
+| `federation status` | Connections + leftover federated copies. |
+| `federation purge` | Remove leftover `federated:true` copies. `--vault`, `--all`, `--dry-run`. |
+| `federation sync` / `federation drain` | **Disabled no-ops** (copy-based sync is parked). |
+
+---
+
+## Council (see [integrations.md](integrations.md))
+
+`council create`, `council agent create`, `council round start\|end`, `council synthesize`, `council complete`, `council promote`, `council list`, `council show`. Plus sub-agent helpers (`round-context`, `report append`, `summaries`, `research add\|list`).
+
+---
+
+## Other
+
+| Command | Description |
+|---|---|
+| `dashboard` | Open the web UI. `-p/--port`, `--host`, `--no-open`, `--vault`, `--launcher`. |
+| `app install\|update\|status` | Manage the macOS desktop app. `--from <path>`, `--dir <dir>`. |
+| `marketing` / `mk` | Meta marketing skill surface. |
+| `transcript distill <session_id>` | Extract high-signal content from a transcript. `--since <ts>`, `--full`. |
+| `reflect` | Surface recurring cross-session terms as candidates. `--min-sessions`, `--max`, `--write`. |
+| `snapshot` | Output the context snapshot (used by SessionStart). `--tokens`, `--vault <name>`. |
+| `migrations pending\|apply-diagrams\|record` | Inspect/apply brain-structure migrations. `record --files --summary`. |
+| `feedback` | File a gap/bug upstream as a GitHub issue. See [improving-dreamcontext.md](improving-dreamcontext.md). |
+| `hook <name>` | Hook handlers (called by the platform, not you): `session-start`, `stop`, `subagent-start`, `pre-tool-use`, `user-prompt-submit`, `post-tool-use`, `pre-compact`, `ensure-dashboard`, `refresh-asset-drift`. |
+
+---
+
+## Environment variables
+
+| Var | Effect |
+|---|---|
+| `DREAMCONTEXT_MEMORY_HOOK=0` | Disable auto-injected recall on prompts. |
+| `DREAMCONTEXT_RECALL_MODE=haiku\|raw\|off` | Override recall mode for the session (else uses `recall` setting; default `haiku`). |
+| `DREAMCONTEXT_AUTO_DASHBOARD=0` | Don't auto-open the dashboard on session start. |
+| `DREAMCONTEXT_DASHBOARD_PORT` | Default dashboard port (else 4173). |
+| `DREAMCONTEXT_AUTO_UPGRADE=0` | Disable automatic CLI self-upgrade. |
+| `DREAMCONTEXT_VERSION_CHECK=0` | Disable the version-check nag. |
+| `DREAMCONTEXT_PERSON` | Current person for attribution (wins over the roster default). |
+| `DREAMCONTEXT_SNAPSHOT_BUDGET` | Token budget cap for the SessionStart snapshot. |
+| `DREAMCONTEXT_SKILLS_HOOK=0` | Disable skill-suggestion injection on prompts. |
+| `DREAMCONTEXT_DRIFT_CHECK` / `DREAMCONTEXT_APP_AUTO_UPDATE` | Asset-drift check / desktop app auto-update toggles. |
+| `DREAMCONTEXT_DEBUG` | Verbose diagnostics (e.g. recall decisions to stderr). |

package/skill/references/improving-dreamcontext.md

@@ -0,0 +1,39 @@
+# Improving dreamcontext (Agent Feedback Loop)
+
+You are not just a *user* of dreamcontext — you are its field reporter. When dreamcontext gets in your way, the system can only improve if that friction reaches its maintainers. Take responsibility: file it. **Do not silently work around it** — a workaround fixes today; feedback fixes the system.
+
+## Triggers — the moment you notice any of these, consider filing
+
+- You expected a fact to be in memory but `memory recall` didn't surface it (a recall gap, not a missing fact).
+- You wished a CLI command existed and there was no path (e.g. "I want to reopen a completed task" and there's no `tasks reopen`).
+- A command, hook, or doc behaved wrong, was confusing, or crashed.
+- The structure forced an awkward workaround for something the system should support directly.
+
+## The loop (the ONLY sanctioned way to file — never run `gh issue create` by hand)
+
+1. **Draft.** Run `dreamcontext feedback --dry-run` with the category and a complete scenario:
+   ```bash
+   dreamcontext feedback --dry-run \
+     -c <bug|missing-cli|unseen-memory|feature|docs|other> \
+     -t "<concise, specific title>" \
+     -s "<what you were doing>" \
+     -e "<what dreamcontext should have done>" \
+     -g "<what was missing / broken / surprising>" \
+     -r "<exact commands / repro steps>" \
+     -p "<your proposed improvement: command, behavior, doc, or fix>"
+   ```
+   A maintainer who never saw your session must understand it from the issue alone — include the whole scenario.
+2. **Confirm with the user.** Show them the rendered draft and ask permission. This writes to a public repo on their behalf — never file without an explicit yes.
+3. **File.** Re-run the same command without `--dry-run` and with `--yes`. It checks for near-duplicate open issues (skip with `--no-dedup`), applies the `agent-feedback` label, and files to the **dreamcontext upstream project** (`meanllbrl/dreamcontext`) — NOT the user's own repo.
+
+## No GitHub access?
+
+If the command reports `gh` is missing or unauthenticated, relay its guidance: install `gh` + run `gh auth login`; if they have no GitHub account, ask them to create a free one at github.com/signup. They need an account to file. Then re-run the loop.
+
+## Quality bar
+
+One issue per distinct gap, a concrete title, the full scenario, a concrete proposal. Vague feedback ("recall is bad") is noise; a reproducible scenario with a proposed command is signal.
+
+## Categories
+
+`bug` · `missing-cli` · `unseen-memory` (recall gap) · `feature` · `docs` · `other`

package/skill/references/integrations.md

@@ -0,0 +1,236 @@
+# Integrations — ClickUp / GitHub, Dashboard, Desktop App, Federation, Council, Marketing
+
+This reference covers everything beyond the local markdown brain. **If a user asks whether dreamcontext integrates with ClickUp or GitHub Issues, runs a dashboard, syncs across projects, or runs debates — the answer is yes.** Details below.
+
+---
+
+## ✅ Cloud / remote task management (ClickUp _or_ GitHub — one at a time)
+
+**dreamcontext has a first-class cloud task-management integration.** Tasks always stay as local markdown (`state/<task>.md`) — the canonical source of truth, works offline — and a **pluggable remote task backend** mirrors them bidirectionally to a cloud task manager. Two providers ship today: **ClickUp** (issue #11) and **GitHub Issues** (v0.9.0). If a user asks about "a cloud task system," "ClickUp," "GitHub issue sync," or "remote task sync" — **this is it; the answer is yes.**
+
+> **⚠️ Exactly ONE cloud sync at a time — never both.** `taskBackend` is a single value: `local` | `clickup` | `github`. A project syncs to ClickUp **or** GitHub, not both at once. Switching the backend replaces the active sync target — the previous provider's saved coordinates stay on disk but go dormant, because `getTaskBackend()` only ever resolves the one that matches `taskBackend`. It never runs two syncs. Pick one per project.
+
+### ClickUp
+
+#### What it does
+- **Bidirectional sync** (`push`, `pull`, or `both`) between local task files and a ClickUp list.
+- **Status mapping** between dreamcontext statuses (`todo/in_progress/in_review/completed`) and ClickUp statuses.
+- **RICE + custom fields**: provisions recommended ClickUp custom fields (urgency, summary, RICE reach/impact/confidence/effort, …) and round-trips them.
+- **Assignees**: `person:<slug>` tags map to ClickUp member IDs bidirectionally (multi-assignee; the full `assignees[]` set survives push/pull). See "People & assignees" in [tasks-and-features.md](tasks-and-features.md).
+- **Changelog as comments**: task changelog entries post as ClickUp comments (`changelogTarget: 'comments'`).
+- **Conflict safety**: conflicting edits are preserved as conflict files rather than silently overwritten; a sync ledger tracks a watermark, pending pushes, and an op queue.
+- **Rate-limit hardened**: throttles at 90 req/min (under ClickUp's 100/min cap), retries with Retry-After backoff, and a partial push can never look like success — `sleep done` auto-retries once on failed pushes, then errors loudly with the failed slugs.
+- **Git triggers**: best-effort `post-commit` / `pre-push` hooks sync automatically (they never block or fail git).
+
+#### Enabling it (guided)
+```bash
+dreamcontext config task-backend clickup
+```
+Interactively this: gitignores the derived mirror/sync state → prompts for the API key (stored in the gitignored `state/.secrets.json`, mode 0600 — never `.config.json`) → tests the connection → lets you **pick the list from the API** (no URL hunting) → offers to provision custom fields → runs the first sync. Non-interactively it prints the next steps.
+
+#### Manual / scripted configuration
+```bash
+# Store the API key out of shell history (preferred): pipe it
+echo "$CLICKUP_TOKEN" | dreamcontext config clickup-token
+dreamcontext config clickup-token                  # or prompt interactively
+dreamcontext config clickup-token --user <person>  # scope a token to one person
+
+# Set the sync target explicitly
+dreamcontext config clickup-list <teamId> <spaceId> <listId>
+#   --migrate : changing lists → next sync recreates every task in the NEW list
+#   --keep    : tasks were moved within ClickUp itself; keep existing mappings
+
+# Map a roster person to a ClickUp member (assignee round-trip)
+dreamcontext config clickup-member <person> <memberId> [--token-env <ENV>]
+
+# Back to local-only
+dreamcontext config task-backend local
+```
+
+#### Day-to-day sync commands
+```bash
+dreamcontext tasks sync [push|pull|both]   # default: both; no-op on the local backend
+dreamcontext tasks sync --hook             # best-effort mode for git hooks (never fails, exit 0)
+dreamcontext tasks sync --json             # machine-readable sync report
+dreamcontext tasks members [--json]        # people with access to the remote list (assignee candidates)
+dreamcontext tasks provision               # create the recommended custom fields on the list
+dreamcontext tasks sync-hooks install|uninstall   # manage the git sync triggers
+```
+
+#### Inspecting state
+```bash
+dreamcontext config show        # shows task backend, ClickUp token presence (masked), and list id
+```
+The mirror, sync ledger, and conflict files are derived and gitignored — never commit them, never hand-edit them.
+
+### GitHub Issues
+
+The same backend interface, talking **plain GitHub Issues over REST** (no GraphQL). Tasks map ~1:1 onto issues — the **issue body is the task markdown** — and the four-state status is carried by issue `state`/`state_reason` plus `dc:*` labels.
+
+#### What it does
+- **Bidirectional sync** (`push`/`pull`/`both`) between local task files and a repo's Issues.
+- **Status mapping:** `completed` → issue **closed** `state_reason: completed`; `todo`/`in_progress`/`in_review` → **open** + a `dc:*` sub-status label (`dc:in-progress`, `dc:in-review`; `todo` = no label); reopen → **open** `state_reason: reopened`.
+- **Soft-delete (the one divergence from ClickUp):** `tasks delete` **closes** the issue as `state_reason: not_planned` — it NEVER hard-deletes (GitHub REST can't, and issue history is preserved). Inbound, a `not_planned` close removes the local mirror (any unsaved local edits are preserved to `.conflicts/` first).
+- **Fields as labels:** priority/urgency/tags/version ride as labels (`priority:*`, `urgency:*`, `version:*`, plus your plain tags). RICE stays local-only (no custom fields on plain issues — see Tier-2).
+- **Assignees:** `person:<slug>` tags ↔ issue assignees (must be repo collaborators); a non-collaborator assignee is skipped gracefully, never a 4xx that aborts the sync. See "People & assignees" in [tasks-and-features.md](tasks-and-features.md).
+- **Changelog as comments:** task changelog entries post as issue comments (union-merged, deduped — same pattern as ClickUp).
+- **Conflict safety + watermark:** reuses the SAME generic sync engine (ledger / watermark / op-queue / 3-way merge) as ClickUp, unchanged. Watermark is the issue `updated_at` (server time). Delta fetch is `GET /repos/{o}/{r}/issues?state=all&since=<ISO>` with **page-number pagination** (pull-requests filtered out).
+- **Rate-limit hardened:** paces under GitHub's 5000 req/hr cap with Retry-After backoff; a partial push can never look like success.
+
+#### Enabling it (guided)
+```bash
+dreamcontext config task-backend github
+```
+Interactively this: gitignores the derived mirror/sync state → prompts for a token (stored in the gitignored `state/.secrets.json`, mode 0600 — never `.config.json`) → tests the connection (`GET /user`) → lets you **pick the repo from the API** → offers to provision the recommended `dc:*` labels → runs the first sync.
+
+#### Manual / scripted configuration
+```bash
+echo "$GITHUB_TOKEN" | dreamcontext config github-token   # also reads GITHUB_TOKEN / GH_TOKEN from the env
+dreamcontext config github-token                          # or prompt interactively
+dreamcontext config github-repo <owner> <repo>            # set the sync target explicitly
+dreamcontext config task-backend local                    # back to local-only
+```
+Token scope: a classic PAT needs `repo`; a fine-grained token needs **Issues** (read/write) + **Metadata**. The day-to-day sync commands (`tasks sync`, `tasks members`, `tasks provision`, `sync-hooks`) and `config show` work identically to ClickUp — they're backend-generic.
+
+#### Deferred — Tier-2 (GitHub Projects v2)
+Priority/urgency/status as first-class **board fields** would need GitHub **Projects v2**, which is GraphQL-only and doesn't fit the REST adapter cleanly. It's a documented Tier-2 follow-up; this backend ships **plain Issues only**.
+
+**Key mental model:** local markdown is canonical; the cloud provider is a sync *target*, and only ONE is ever active. A user on the local backend has both ClickUp **and** GitHub *available*, just not *enabled* — point them to `dreamcontext config task-backend <clickup|github>`.
+
+---
+
+## Web Dashboard
+
+A local React 19 web UI served by a zero-dependency Node HTTP server (ships in the npm package).
+
+```bash
+dreamcontext dashboard                 # open at http://localhost:4173
+dreamcontext dashboard --port 8080     # custom port (or DREAMCONTEXT_DASHBOARD_PORT)
+dreamcontext dashboard --no-open       # start without opening the browser
+dreamcontext dashboard --host 0.0.0.0  # expose on your network (default: loopback only)
+dreamcontext dashboard --vault <name>  # open a specific registered vault
+dreamcontext dashboard --launcher      # vault-agnostic launcher mode (resolves vault per request)
+```
+A SessionStart hook auto-opens it when a session starts and no server is running (opt out with `DREAMCONTEXT_AUTO_DASHBOARD=0`).
+
+**What's in it:**
+- **Kanban board** — drag-and-drop, multi-select filters (status/priority/urgency/tags/version) with type-ahead, sorting, grouping; Notion-style task detail panel to create tasks, change status, add changelog entries.
+- **Eisenhower matrix** — priority×urgency quadrant planning; **Scatter view** uses RICE scores.
+- **Core editor** — split-pane markdown editing + live preview for soul/user/memory/etc.
+- **Knowledge manager** — search, pin/unpin; **Feature PRD viewer**; **SQL ER diagram** preview for data-structures.
+- **Version manager** — plan and release versions.
+- **Sleep tracker** — debt gauge, session-history timeline, and a list of every manual change made through the dashboard (recorded to `.sleep.json` so the agent consolidates your edits during sleep).
+- **Brain graph** — interactive network of memory/knowledge/features/decisions with explicit + inferred edges.
+- **Council Hall** — every debate as a searchable card grid; detail view with Overview / Agents / Matrix tabs.
+- **"What is this?"** explainer page with live faculty diagrams.
+
+Light/dark with system detection.
+
+---
+
+## Desktop App (macOS beta)
+
+A native **Tauri 2** app that wraps the same dashboard server so you manage every project from one window. Ships via the desktop release + macOS one-line installer (not the npm package). On macOS, `dreamcontext setup` offers to install it, and `dreamcontext upgrade` updates it automatically when installed — so you rarely run these by hand.
+
+```bash
+dreamcontext app install     # install to ~/Applications (no admin, no quarantine prompt)
+dreamcontext app update      # update to the latest release
+dreamcontext app status      # show installed version and state
+#   --from <path>  : install/update from a local .app/.tar.gz/.zip instead of GitHub Releases
+#   --dir <dir>    : install directory (default ~/Applications)
+```
+
+- **Multi-vault launcher** — lists every registered vault; opens each project in its own window (pinned via a request header); per-project status dot (green up-to-date / yellow needs-update / red folder-gone) with an in-UI `update`.
+- **Federation board** — projects rendered as Excalidraw-style cards; click source→target to wire a live "reads" relationship (violet wire = one project reads another's canonical memory live during recall; never a copy), gated by the target being shareable.
+- **In-app onboarding** — quiz-style wizard creates or initializes a project, scaffolds `_dream_context/`, runs `setup`, installs the global CLI; deterministic, LLM-free.
+- **Sleepy — notch quick-capture (beta)** — a global-hotkey transparent notch panel with a mascot whose mood follows sleep debt. Pick a vault, type a thought, choose: **Learn** (save to memory + enrich), **Ask** (one-shot Q&A, nothing saved), **Sleep** (trigger a full consolidation for that vault).
+- Delivery is CLI/curl-driven (no Apple notarization); prefers your auto-upgrading global CLI over its bundled copy. First launch may need right-click → Open.
+
+---
+
+## Federation (cross-project recall)
+
+Most people end up with more than one dreamcontext project. Federation lets projects discover each other and **recall across each other live** — read-only, local-only, no server, and **nothing is ever copied between vaults**. Each vault stays the single source of truth for its own knowledge.
+
+### Vault registry
+```bash
+dreamcontext vaults add <name> <path>            # register a project directory as a vault
+dreamcontext vaults list                         # list registered vaults
+dreamcontext vaults discover [root] [--register] # find every _dream_context/ under a tree (and register)
+dreamcontext vaults remove <name>
+```
+
+### Connections (read edges)
+```bash
+dreamcontext connect <vault> --direction out [--topics a,b]   # out = a read edge (you read the peer)
+dreamcontext connections list                                 # who this vault reads
+dreamcontext disconnect <vault>
+dreamcontext config shareable on|off    # opt THIS project IN/OUT of being recalled by peers (default off/private)
+```
+
+### PULL — recall already spans peers
+Plain `memory recall` automatically searches eligible readable peers alongside the current vault. Hits are namespaced `<vault>::<type>/<slug>` so provenance is always visible.
+```bash
+dreamcontext memory recall "<query>"                 # current vault + eligible readable peers (default)
+dreamcontext memory recall "<query>" --vault <name>  # current + one named peer (repeatable)
+dreamcontext memory recall "<query>" --connected     # current + out/both connections
+dreamcontext memory recall "<query>" --all-vaults    # current + every shareable vault
+```
+Eligible = direction `out`/`both`, not stale, AND the peer is `shareable: true`. Non-shareable peers are silently excluded. If no eligible connections exist, recall is local-only.
+
+### Reading a specific peer (beyond recall)
+
+Recall is the cheap first pass. When you recognize a **specific** connected project actually holds what you need — its code, a decision, a schema — go straight to it instead of guessing or re-deriving:
+
+```bash
+dreamcontext snapshot --vault <name>     # print that peer's full context snapshot (orient fast)
+dreamcontext federation peers            # one-line summary of each readable peer + its active work
+```
+- **Read its files directly.** A peer is a normal directory on disk — resolve its path (from `vaults list` / the snapshot's Connected projects) and `Read`/`Grep` inside its `_dream_context/` or source tree.
+- **Dispatch an explorer scoped to it.** For anything non-trivial, send `dreamcontext-explore` with the peer's path in the prompt ("explore `<peer-path>` for …") so it searches there with context-first discipline.
+- A connection is a standing "may read" agreement — there is no per-situation rule to wait for. If your memory says a sibling project is relevant, read it.
+
+### Ambient awareness
+The session snapshot includes a `## Connected projects` section. For a live summary: `dreamcontext federation peers`. Inspect / clean up: `dreamcontext federation status`.
+
+### Copy-based sync is DISABLED (parked on the roadmap)
+Earlier builds pushed a lossy digest into peers at sleep (`federation sync` / `federation drain`) and ingested `federated: true` copies. That broke single-source-of-truth (stale copies, false conflicts) and is now **inert no-ops**; the `sleep-federation` specialist is **not** dispatched. **Do NOT fire `sleep-federation`** during sleep. To remove leftover copies from the old path:
+```bash
+dreamcontext federation purge --all                # remove every federated:true copy here
+dreamcontext federation purge --vault <name>       # remove only copies from one peer
+dreamcontext federation purge --dry-run            # preview
+```
+
+---
+
+## Council (multi-persona debates)
+
+Structured debates for load-bearing decisions (architecture, migrations, hiring, brand critiques). N personas × N rounds, each persona its own sub-agent with a scoped prompt, model, and aspects; a synthesizer writes the verdict. Also available as the `council` skill pack + `/council` skill.
+
+```bash
+dreamcontext council create "Should we migrate Postgres → Firestore?" --rounds 2
+dreamcontext council agent create migration-risk-auditor --model sonnet --aspects operational-risk,rollback
+dreamcontext council agent create dx-champion --model opus --aspects developer-experience
+dreamcontext council round start 1
+dreamcontext council round end 1        # injects cross-context for round 2+
+dreamcontext council round start 2
+dreamcontext council round end 2
+dreamcontext council synthesize         # prints the manifest the synthesizer reads
+dreamcontext council complete
+dreamcontext council promote <id>       # copy the verdict into knowledge/decision-<slug>.md
+dreamcontext council list [--unpromoted|--all]
+dreamcontext council show <id>
+```
+State lives in `_dream_context/council/<id>/` (`debate.md`, `round-log.md`, `final-report.md`, per-persona folders). During sleep, check `council list --unpromoted` and promote if the user engaged positively. Ships `council-persona` + `council-synthesizer` sub-agents. Rendered in the dashboard's Council Hall.
+
+---
+
+## Marketing (`mk`)
+
+The Meta marketing skill surface (cohorts, campaigns, competitor ingest, learnings), paired with the `meta-marketing` + `growth` skill packs.
+
+```bash
+dreamcontext marketing   # alias: dreamcontext mk
+dreamcontext mk --help   # subcommands (cohort, campaign, competitor, learnings, rem-sleep, …)
+```
+If `_dream_context/marketing/` exists, run `dreamcontext mk rem-sleep` as part of the sleep cycle (see [sleep.md](sleep.md)). PreToolUse gates protect `marketing/.env`.

package/skill/references/knowledge-and-recall.md

@@ -0,0 +1,157 @@
+# Knowledge, Recall & Taxonomy — full reference
+
+## Knowledge files
+
+Deep, durable docs the agent should recall in future sessions (research, design rationale, domain context). The **index is auto-loaded each session** (names, descriptions, tags, staleness) — so you already know what exists.
+
+```bash
+dreamcontext knowledge create <name> -d "description" -t architecture,api -c "body"
+dreamcontext knowledge index [--tag <tag>] [--plain]
+dreamcontext knowledge tags
+dreamcontext knowledge touch <slug>     # record access AFTER reading — powers staleness + warm loading
+```
+
+- **Pin** frequently-needed files so they load in full every session: set `pinned: true` (via `dreamcontext memory update <slug> --pin`). Read non-pinned files on demand, then `knowledge touch`.
+- **Surgical edits mid-session**: `dreamcontext memory update <slug> [--description|--tags|--content|--append <text>|--pin|--unpin]`. Heavy maintenance (merging, deduping, restructuring) belongs to `sleep-product`.
+- **Quick capture**: `dreamcontext memory remember "<text>"` writes a `type=note` CHANGELOG entry; sleep reconciles it into knowledge later.
+
+### Organize knowledge into context folders (the promoted convention)
+
+`knowledge/**/*.md` is indexed **recursively** — a file under `knowledge/<context>/` stays first-class in the index, recall, snapshot, and dashboard (its slug becomes `<context>/<name>`). The promoted layout is **context/topic-grouped folders**, not a flat dump and not a segregated `diagrams/` tree:
+
+```
+knowledge/
+├── recall/                         ← a context folder
+│   ├── recall-engine-v2.md
+│   ├── decision-mem0-vs-bm25.md
+│   └── recall/recall.excalidraw.md ← the context's diagram lives INSIDE the folder
+├── federation/
+│   └── ...
+├── data-structures/{default,<product>}.md
+└── products/<product>.md
+```
+
+**Don't reorganize by hand-moving files + hand-editing links.** To group an existing flat file into a context folder, use the atomic command:
+
+```bash
+dreamcontext knowledge move <slug> <folder>   # knowledge/<slug>.md → knowledge/<folder>/<basename>.md
+```
+
+It moves the file **and** rewrites every inbound `[[wikilink]]` in one atomic step (target token only; `|alias` and `#anchor` are preserved), keeps the file first-class in index/recall/snapshot/dashboard, and migrates its `knowledge_access` decay key. Folder names are free-form — nothing is reserved; nested folders are allowed; path traversal and clobbering an existing destination are rejected. Context grouping is normally done by `sleep-product` during consolidation — its "Organize" pass groups files that share a clear topic and calls this same command. During active work, just create knowledge with `dreamcontext knowledge create` and let sleep organize, or run `knowledge move` yourself — but never `mv` + hand-edit links by hand. When creating a brand-new doc you may place it directly in its context folder.
+
+---
+
+## Memory functions — what they are and how to use them
+
+The `memory` command group is your interface to the curated corpus: `knowledge/*`, `core/features/*`, `state/*.md`, `core/2.memory.md` (Technical Decisions + Known Issues), and every `core/CHANGELOG.json` entry. No setup, no index file, no external service — rebuilt in memory each call (<100ms on ~130 docs).
+
+| Function | Use it to… | Command |
+|---|---|---|
+| **recall** | Find prior decisions/context across the whole corpus | `dreamcontext memory recall <query...>` |
+| **remember** | Capture a one-off fact mid-session before it's lost | `dreamcontext memory remember "<text>"` |
+| **update** | Surgically edit a knowledge file (desc/tags/body/pin) | `dreamcontext memory update <slug> …` |
+| **delete** | Remove a knowledge file (irreversible; recover via git) | `dreamcontext memory delete <slug> -f` |
+| **list** | Enumerate the corpus by type | `dreamcontext memory list [--types …]` |
+| **status** | See corpus size + breakdown by type | `dreamcontext memory status` |
+| **recall mode** | Switch how recall ranks (haiku/raw/off) | `dreamcontext recall on\|raw\|off\|status` |
+
+### recall — your first-line discovery tool
+
+**Run `memory recall` BEFORE grep or blind file reads** whenever the user asks "where did we decide X?", "have we discussed Y?", "what do we know about Z?", or before duplicating work. It ranks across knowledge + features + tasks + memory + changelog in one shot.
+
+```bash
+# Plain discovery — top 10 hits with snippets
+dreamcontext memory recall "how did we decide on the sleep fan-out"
+
+# Narrow to where the answer likely lives (cheaper, sharper)
+dreamcontext memory recall "auth flow" --types knowledge,feature
+dreamcontext memory recall "deprecated" --types changelog        # ship history
+dreamcontext memory recall "rate limit" --types task             # in-flight work
+
+# Tune result count / machine-readable output
+dreamcontext memory recall "rice prioritization" --top 3 --json
+dreamcontext memory recall "vault registry" --plain              # no colors, for piping
+
+# Span federation peers (see integrations.md)
+dreamcontext memory recall "<query>" --connected                 # + out/both peers
+dreamcontext memory recall "<query>" --vault other-project       # + one named peer (repeatable)
+```
+Read the hit's `slug`/path from the output, then `Read` that file for full context. Hits are scored (higher = better); cross-vault hits are namespaced `<vault>::<type>/<slug>`.
+
+### remember — quick capture mid-session
+
+```bash
+dreamcontext memory remember "Chose BM25 over mem0 after a 3-reviewer review"
+dreamcontext memory remember "<text>" --references decision:recall-v2,task:recall-engine
+dreamcontext memory remember "<text>" --person mehmet,ada      # attribute (multi-person)
+```
+Writes a CHANGELOG entry (`type=note`, `scope=quick`); the sleep cycle reconciles it into knowledge later. You do NOT hand-edit `2.memory.md` for these (it no longer carries a LIFO notes section).
+
+### Recall modes
+| Mode | Behavior | Set with |
+|---|---|---|
+| `haiku` (**default**) | A small cloud model picks 0–3 relevant docs per prompt (smarter than keywords; BM25 fallback) | `dreamcontext recall on` |
+| `raw` | BM25 keyword scoring only — no LLM call | `dreamcontext recall raw` |
+| `off` | No recall injection at all | `dreamcontext recall off` |
+| — | Inspect current mode | `dreamcontext recall status` |
+
+- **Auto-injection (ON by default):** the UserPromptSubmit hook surfaces top hits on every non-trivial prompt. Opt out with `DREAMCONTEXT_MEMORY_HOOK=0`; override mode per-session with `DREAMCONTEXT_RECALL_MODE`.
+- **Federation:** plain `recall` automatically spans eligible readable peers; hits are namespaced `<vault>::<type>/<slug>`. Scope with `--vault`/`--connected`/`--all-vaults` (see [integrations.md](integrations.md)).
+
+### What recall is and isn't
+- BM25 is keyword/stemming-based, not semantic — "ML practitioner" won't match "data scientist" (haiku mode mitigates this).
+- Recall does **not** replace the SessionStart snapshot (soul/user/memory/active-tasks/knowledge-index are always pre-loaded). It is not a vector DB or mem0; the corpus is the same set the sleep agents curate.
+
+---
+
+## Root-cause analysis pattern
+
+When debugging (e.g. "notifications are broken"):
+1. `dreamcontext memory recall "notification"` — what's known + what changed?
+2. SEARCH `core/CHANGELOG.json` / `RELEASES.json` for the term — what shipped recently?
+3. READ `core/4.tech_stack.md` — how is the system wired?
+4. SEARCH `knowledge/` for the module — any deep research?
+5. Now diagnose with the full picture.
+
+---
+
+## Taxonomy (tags drive recall precision)
+
+Consistent tags make recall sharp; fragmented near-duplicate tags degrade it. Before tagging anything, consult the vocabulary and reuse canonical faceted tags (`topic:recall`, `domain:security`) before inventing new ones.
+
+```bash
+dreamcontext taxonomy vocab [--facet <facet>] [--json]   # resolved vocabulary (defaults + core/taxonomy.json)
+dreamcontext taxonomy resolve <tag>                       # normalized form, classification, canonical
+dreamcontext taxonomy audit [--json]                      # surface non-canonical / orphan tags (read-only)
+dreamcontext taxonomy init                                # scaffold core/taxonomy.json (idempotent)
+dreamcontext taxonomy add <facet:value>                   # add a new vocabulary tag
+dreamcontext taxonomy alias <alias> <canonical>           # merge a shorthand into a canonical tag
+```
+Standard bare tags: `architecture`, `api`, `frontend`, `backend`, `database`, `devops`, `security`, `testing`, `design`, `decisions`, `onboarding`, `domain`. **Never hand-edit `core/taxonomy.json`** — mutate via the CLI. `sleep-product` runs taxonomy maintenance during consolidation.
+
+---
+
+## Excalidraw boards (diagrams)
+
+Excalidraw boards (`.excalidraw.md`) are first-class knowledge files. **A board belongs INSIDE the context folder it documents**, co-located with that context's `.md` knowledge — not in a separate top-level diagrams dump. A board lives in its own `<title>/` wrapper folder so its tooling siblings stay together:
+
+```
+knowledge/system/architecture/architecture.excalidraw.md   ← board inside its context folder
+knowledge/recall/recall/recall.excalidraw.md
+```
+
+Rules:
+- **REQUIRED frontmatter**: every board must have `name:` and `description:`. Boards with no `## Text Elements` fall back to description-only recall — make the description rich.
+- **Do NOT hand-edit scene JSON.** The `.excalidraw.md` is generated output. Build a spec and run the generator (`.board.cjs`). Edit the spec, not the board. The spec is the source of truth; if they disagree, the spec wins. Commit both. (See the `excalidraw` skill pack for generating boards.)
+- **Dark siblings**: tooling files inside a board's `<title>/` folder — generator scripts (`.board.cjs`), spec `.json`, and frontmatter-less helper `.md` — are excluded from index/recall/snapshot/dashboard. **Exception:** a companion `.md` with `name:` frontmatter is indexed as first-class, so you can co-locate a board with its teardown (`acme/acme.excalidraw.md` + `acme/acme.teardown.md`).
+- **Indexing strips scene JSON/base64/element ids** — only frontmatter + `## Text Elements` are searchable, so a 2 MB board is as searchable as a tiny one. The dashboard renderer still gets the raw scene via the detail API and shows the full nested folder tree.
+
+**Where does a board go?**
+| Nature | Location | Indexed? |
+|---|---|---|
+| Canonical (architecture, flows, roadmaps a future session should recall) | inside its `knowledge/<context>/<title>/` folder | Yes |
+| Temporary / scratch / exploratory | `inbox/` or `workspace/` (dark by location) | No |
+
+Decision rule: *"Will a future session need this? → its context folder under `knowledge/`. Throwaway? → `inbox/` or `workspace/`."*
+
+> **Legacy note:** older projects kept all boards under a single top-level `knowledge/diagrams/` tree, and `dreamcontext migrations apply-diagrams` still maintains flat boards there (folds them into per-title folders + rewrites `[[wikilinks]]` atomically — never hand-edit links). That layout still indexes and renders, but new boards should go in their **context folder**, and `sleep-product` keeps the store organized over time.