@agent-native/core 0.15.13 → 0.16.0

package/docs/content/template-brain.md

@@ -0,0 +1,418 @@
+---
+title: "Brain"
+description: "A public first-party template for cited company memory, reviewable source ingestion, and the path toward universal workspace search."
+---
+
+# Brain
+
+Brain is a public first-party template for Company Brain: cited institutional
+memory that agents and humans can search without pretending raw workplace data
+is already clean, complete, or safe to publish. The first-run surface is a
+full-page company chat with demo and eval controls, source health, review
+counts, and cited answers from approved company knowledge.
+
+Brain ingests approved Slack channels, Clips recordings, Granola Team-space
+notes, GitHub issues/PRs, and generic transcript/webhook payloads. It stores raw
+captures, distills durable facts/decisions/processes, and routes sensitive or
+low-confidence memories through review before they become company knowledge.
+
+Use Brain when your team wants agents to answer questions like "why did we make
+this product decision?", "how does this in-development feature work?", or "what
+changed in this process?" with links back to the source conversation, meeting,
+or issue.
+
+Brain is intentionally on an open-source, Glean-shaped path, but it is not a
+complete Glean replacement today. V1 is cited company memory over reviewed
+knowledge. V1.5 adds universal Brain search across knowledge, captures, and
+sources, plus reusable workspace connections for source credentials. V2 points
+toward federated app/source search, permission-aware result filtering, ranking,
+and an expertise graph as a future platform layer.
+
+## What It Includes
+
+- **Full-page company chat.** The Ask route is the main product surface. It
+  shows a compact demo CTA, source health, review count, and suggested
+  company-memory questions. It uses `AgentChatSurface`, so the Brain composer
+  stays on the same shared chat input stack as the agent sidebar and
+  Agent-Native Code.
+- **Repeatable demo flow.** Load a product-decision corpus, run the demo eval,
+  ask a cited question immediately, then continue into Review or Knowledge so a
+  new workspace can see the trust loop before connecting real sources.
+- **Approved sources.** Configure manual, generic webhook, Clips, Slack,
+  Granola, and GitHub source records. Slack is channel-oriented by design; DMs
+  and MPIMs are not scan targets.
+- **Raw captures.** Store transcripts, channel exports, notes, and webhook imports in portable SQL with dedupe keys and source metadata.
+- **Distilled knowledge.** Write atomic entries with kind, topic, entities, confidence, exact evidence quotes, and supersede links.
+- **Review queue.** Proposed company memories have a first-class Review route
+  where reviewers edit wording, inspect evidence/source links, approve, or
+  reject. Reviewers can also choose whether an approved proposal becomes
+  canonical company context immediately.
+- **Review gating.** High-confidence non-sensitive entries can publish immediately; company-tier or sensitive entries can queue as proposals for approval.
+- **Cited retrieval.** V1 exposes `search-knowledge` and `get-knowledge` for
+  distilled company memory. The V1.5 expansion adds a Search route and
+  `search-everything` action for searching knowledge, raw captures, and source
+  records together, then drilling into `get-knowledge` / `get-capture`.
+- **Pilot and Ops controls.** Slack pilots stay bounded by default, `get-pilot-report` summarizes source quality without raw bodies, and the Ops route tracks stale or failed distillation queue items with safe retry controls.
+- **Shared integrations.** The Sources page shows Brain source records beside
+  reusable workspace connection grants and provider readiness, so Brain can use
+  Dispatch/workspace-managed credentials when a grant exists.
+- **Ambient context.** Canonical approved entries can mirror into workspace
+  resources under `context/company-brain/...` for cross-app context. The Review
+  route exposes this as a per-proposal switch; the Knowledge route can publish
+  or unpublish approved memories later with `set-knowledge-canonical`. Both
+  flows preview the exact Markdown through `preview-canonical-resource` before
+  the resource is written or removed.
+
+Brain intentionally uses SQL text search and agentic query expansion for v1.
+There is no vector database requirement, so the template stays portable across
+SQLite, Postgres, Neon, D1, Turso, and similar hosts. Raw capture content is
+redacted by default in review/search surfaces; editor-authorized distillation
+can request exact raw text for quote validation.
+
+## Search Model
+
+Brain search has three layers:
+
+- **V1 Company Brain search:** answer from reviewed, distilled knowledge first.
+  This is the trust layer for decisions, policies, product facts, processes,
+  and durable summaries.
+- **V1.5 universal Brain search:** use `search-everything` as the broad first
+  pass across knowledge, raw captures, and sources. Then call `get-knowledge`
+  for reviewed entries or `get-capture` for exact source context and links.
+- **V2 federated workspace search:** reuse workspace connections and search
+  across apps/sources with permission-aware result filtering and ranking. The
+  expertise graph belongs to this future/platform layer.
+
+Agents should cite evidence links or source URLs whenever available. If Brain
+does not return support for a question, the agent should report that honestly
+instead of implying the company memory contains an answer.
+
+## Brain vs Dispatch
+
+Brain and Dispatch are complementary, but they do different jobs:
+
+- **Brain owns company memory.** It ingests sources, reviews raw captures,
+  distills durable facts/decisions/processes, answers from cited evidence, and
+  exposes approved knowledge to agents.
+- **Dispatch owns the workspace control plane.** It centralizes messaging,
+  secrets, recurring jobs, approvals, A2A orchestration, and workspace-wide
+  resources.
+
+In a multi-app workspace, Dispatch can route a question to Brain over A2A and
+can grant Brain shared provider credentials. Brain remains the specialist for
+approved source ingestion, review, retrieval, and cited Company Brain answers.
+
+## Scaffolding
+
+```bash
+pnpm dlx @agent-native/core create my-brain --template brain --standalone
+```
+
+Then open the app, add sources, import a transcript, and ask the agent to distill cited memories from the raw capture.
+
+For a public demo, open the Ask page and choose **Start demo**. Brain seeds the
+product-decision corpus, runs the demo eval, asks the cited freemium question,
+then offers Review and Knowledge follow-ups. The seeded corpus demonstrates
+product-decision recall, citation links, supersede behavior, review gating,
+redaction, personal-content exclusion, and honest not-found behavior without
+connecting a real workspace.
+
+## Generic Ingest
+
+Brain exposes a signed webhook for Clips and generic transcript/capture imports
+at:
+
+```txt
+/api/_agent-native/brain/ingest
+```
+
+Create a source with a `sourceKey` to receive a bearer token, then send a `RawCapturePayload`:
+
+```json
+{
+  "sourceKey": "clips",
+  "externalId": "meeting-123",
+  "title": "Pricing decision review",
+  "participants": ["Ada", "Grace"],
+  "occurredAt": "2026-05-15T15:00:00.000Z",
+  "transcript": "We decided to keep annual pricing because...",
+  "sourceUrl": "https://example.com/share/meeting-123",
+  "tags": ["pricing", "product"],
+  "raw": {}
+}
+```
+
+Set `Authorization: Bearer <ingestToken>` on the request. Clips can export to
+that endpoint without Brain reading the Clips database directly. Generic sources
+use the same payload shape for call transcripts, customer research, imported
+notes, or any other source that can produce a bounded capture.
+
+## Slack Backfill
+
+Brain resolves `SLACK_BOT_TOKEN` from a granted Slack workspace connection
+first, then from backward-compatible Brain-local or registered vault
+credentials. It scans only channels that an admin configures on the source:
+
+```bash
+pnpm --filter brain action create-source \
+  --title "Slack product channels" \
+  --provider slack \
+  --visibility org \
+  --config '{"channelIds":["C0123456789"],"historyLimit":15}'
+```
+
+The connector verifies each configured conversation before reading history and
+rejects DMs and MPIMs. Cursor state is stored on the source so each sync can pick
+up where the last one stopped, including after Slack rate limiting.
+
+Use `test-slack-connection` before a production backfill. It validates the
+Slack bot token with `auth.test` and, when channel refs are provided, checks
+channel metadata without reading message history.
+
+For Slack, grant the bot the smallest scopes needed for the source:
+
+- `auth.test` for credential validation.
+- `conversations.info` for allow-list verification and DM/MPIM rejection.
+- `conversations.history` for allow-listed channel history.
+- `chat.getPermalink` for durable citations.
+- `conversations.list` only when setup resolves channel names instead of IDs.
+
+Private channels require inviting the bot to the channel. Public channels may
+also require joining or inviting the bot depending on the Slack app posture.
+
+For local CLI/action-runner QA, put `SLACK_BOT_TOKEN` in a workspace connection,
+registered vault secret, or Brain-local app credential before running source
+actions. Brain source connectors intentionally do not read process environment
+variables directly, so `.env.local` alone is not a credential source.
+
+Use `run-slack-pilot` for a safer first-pass rollout report. The default action
+validates the Slack credential and allow-listed channels, reports guardrails,
+privacy exclusions, current knowledge/proposal counts, and next steps, and does
+not call `conversations.history`. Only pass `readHistory: true` when the user
+explicitly wants a tiny sample sync; the pilot caps the read to two validated
+channels, one page per channel, ten messages per page, ten permalinks,
+`autoSync: false`, and a recent default history window.
+
+After a sample sync succeeds, list the imported inventory before opening raw
+message bodies:
+
+```bash
+pnpm --filter brain action list-captures \
+  --sourceId <source-id> \
+  --status queued
+```
+
+The listing omits raw capture content by default and includes each capture's
+latest distillation queue state. Use `get-capture` for one specific record when
+a reviewer or agent needs exact source context, then write only durable, cited
+knowledge. Keep `autoSync` disabled until the channel allow-list, review gate,
+and first distilled entries are validated.
+
+The Sources UI has the same flow: open **Captures** on a source card to review
+queued records, opt into short previews only when needed, queue distillation,
+see whether a capture is waiting on the distillation worker, or mark non-company
+material ignored.
+
+Slack source cards expose this as a clean rollout flow: **Test** checks the
+credential and allow-list without history reads, **Safe pilot** imports only a
+tiny capped sample, **Review captures** opens the capture inventory, and
+**Review queue** sends reviewers to approve proposals before they become
+queryable company memory.
+
+Use `get-pilot-report` after a sample sync to inspect sync health, capture
+counts, queue state, published knowledge, pending proposals, privacy notes, and
+recommended rollout steps without returning raw capture bodies.
+
+Recommended production rollout:
+
+1. Start with one or two high-signal channels and channel IDs.
+2. Keep `autoSync: false` until review quality is proven.
+3. Run `test-slack-connection`, then `run-slack-pilot` without history.
+4. Run one explicit `run-slack-pilot --readHistory true` sample when the report
+   is clean.
+5. Review captures with previews only when needed; ignore social, personal, or
+   thin records.
+6. Distill durable company context, approve proposal-gated memories, and verify
+   `ask-brain` returns cited Slack permalinks.
+7. Expand with bounded manual `sync-source` runs before enabling background
+   polling.
+
+When approving a proposal, keep the company-context switch off unless the
+memory should be ambient context for Dispatch and other apps. Turn it on for
+canonical decisions, policies, product facts, or durable process notes that are
+safe to place under `context/company-brain/...`; Brain shows the exact Markdown
+preview before approval publishes it. Use the Knowledge route or
+`set-knowledge-canonical --published=false` to remove a mirrored resource after
+previewing what will be removed, without deleting the underlying Brain
+knowledge.
+
+Distillation has two worker paths. When a Brain tab is open, the app shell
+claims queued items with `claim-distillation` and delegates them to the app
+agent in the background. When no tab is open, the `brain-distillation` server
+sweep runs with `RUN_BACKGROUND_JOBS`, claims due queued rows, reclaims stale
+`processing` rows, and invokes the same agent loop headlessly. Re-running
+`enqueue-distillation` for an active queue item refreshes the handoff instead
+of duplicating queue rows. The agent reads the capture, writes cited knowledge
+or review proposals, then calls `mark-capture-distilled`, which marks the
+active queue row done. If the agent does not close the queue, the worker
+requeues the item with a short delay and eventually fails it after repeated
+attempts.
+
+The Ops route is the operator view for distillation. It lists queued,
+processing, failed, done, stale, and retryable handoffs, backed by
+`list-distillation-queue` and `retry-distillation`.
+
+## Granola Polling
+
+Brain resolves `GRANOLA_API_KEY` from a granted Granola workspace connection
+first, then from backward-compatible Brain-local or registered vault
+credentials. It polls Granola's public API for notes, then fetches each note
+with its transcript:
+
+```bash
+pnpm --filter brain action create-source \
+  --title "Granola team notes" \
+  --provider granola \
+  --visibility org \
+  --config '{"pageSize":10,"updatedAfter":"2026-05-01T00:00:00.000Z"}'
+```
+
+Granola Enterprise API keys expose Team-space notes, not private notes or
+private folders. Brain stores the note summary, transcript, attendees, calendar
+metadata, and source URL as a raw capture before distillation.
+
+## GitHub Connector
+
+GitHub is Brain's first reusable connector proof. It resolves `GITHUB_TOKEN`
+from a granted GitHub workspace connection first, then from backward-compatible
+Brain-local or registered vault credentials, and imports bounded issue and pull
+request context from approved repositories:
+
+```bash
+pnpm --filter brain action create-source \
+  --title "GitHub product repos" \
+  --provider github \
+  --visibility org \
+  --config '{"repositories":["owner/repo"],"state":"all","limit":25}'
+```
+
+The connector accepts `repositories` or `repos`, optional `state`, `limit`,
+`includeIssues`, and `includePullRequests`. Imported items become raw captures
+with stable source URLs and can be distilled like Slack or meeting context. This
+is intentionally Brain context ingestion, not a replacement for Analytics-style
+GitHub reporting.
+
+## Shared Workspace Connections
+
+Brain sources can reuse shared workspace connections when Dispatch or another
+workspace setup has already connected a provider and granted `appId=brain`
+access. The source record still belongs to Brain: it stores channel ids,
+repositories, sync cursors, review settings, and other source-specific choices,
+while the provider credential stays in the workspace vault behind a connection
+or grant credential ref.
+
+The `list-connection-providers` action returns each Brain provider with
+connection counts, grant state, credential reference names, credential health,
+and whether Brain has access. It never returns credential values. Source sync
+resolves credentials in this order:
+
+1. Granted `workspace_connections` / `workspace_connection_grants` credential
+   refs for `appId=brain`.
+2. Backward-compatible Brain-local SQL credentials.
+3. Registered vault secrets for the same user/org/workspace scope.
+
+Brain source credentials do not fall back to deploy-level environment
+variables. If a shared provider exists but has not been granted to Brain, grant
+Brain access instead of copying the same secret into a Brain-specific setting.
+
+Keep the ownership model simple:
+
+- Dispatch or the workspace layer owns provider account metadata, credential
+  ref names, and app grants.
+- The vault owns the secret values.
+- Brain owns source-local choices such as Slack channels, GitHub repositories,
+  Granola polling windows, cursors, review posture, and distillation status.
+- Agents should inspect connection readiness first, then request a grant or
+  source configuration instead of asking the user for another provider token.
+
+The Sources page surfaces the same provider catalog. A provider can be:
+
+- `connected` when an active workspace connection is already granted to Brain.
+- `granted` when Brain can access the connection but it is not currently active.
+- `needs_grant` when the workspace has a connection that has not been granted to
+  Brain.
+- `not_connected` when Brain is using scoped credentials or has no connection
+  yet.
+
+The page also shows provider readiness: ready, grant needed, needs repair,
+missing keys, or metadata only. Agents should inspect this same readiness via
+`list-connection-providers` before asking users for duplicate Slack, Granola,
+GitHub, or future provider credentials.
+
+## Scheduled Sync
+
+The Sources page includes a setup sheet for Slack, Granola, GitHub, Clips,
+generic webhooks, and manual imports. Slack, Granola, and GitHub sources can
+opt into `autoSync` with a `pollMinutes` cadence. Use `sync-source` for a
+single source, `sync-due-sources` for all due accessible sources, or enable
+`RUN_BACKGROUND_JOBS=1` locally to let the Brain background job poll due sources
+from the Nitro process.
+
+## Demo and Eval
+
+Brain ships with a repeatable product-decision demo corpus. `seed-demo-data`
+loads Slack, Clips, Granola, and webhook-style captures; creates cited knowledge
+about retiring freemium, how Decision Digest works, and why product decisions
+are the lead demo; queues a policy-sensitive proposal; redacts an email; and
+keeps a personal aside out of queryable knowledge.
+
+`run-demo-eval` checks the behavior that matters most for trust: recall,
+citations, supersede links, proposal gating, redaction, and personal-content
+exclusion. The Ask page includes a compact **Start demo** CTA for empty
+workspaces and reveals Review, Knowledge, and **Run eval** follow-ups once the
+demo is ready.
+
+`run-retrieval-eval` checks an offline real-channel-style retrieval set. It
+uses existing workspace Brain data when #dev-fusion stale Fusion branch answers
+already have citation-backed support; otherwise, with `seedIfMissing` enabled,
+it seeds a small Slack-style fallback corpus and re-runs the same checks. The
+result covers Slack-style citations, branch-safety terms, and an unsupported
+cleanup-cron not-found case. The same mode is available through `run-demo-eval`
+with `mode: "retrieval"`.
+
+The repository-level `pnpm test` command includes `pnpm test:brain-evals`, which
+runs Brain's product-demo and retrieval action evals against a disposable local
+SQLite database. The CI/prep eval path is fully seeded and offline; it does not
+require production Slack, Granola, Clips, or any external workspace data.
+
+## Privacy And Gating
+
+Brain is designed for company memory, not personal surveillance:
+
+- Slack sync only reads explicitly configured channels and rejects DMs/MPIMs.
+- Granola sync reads Team-space notes exposed by Granola's API, not private
+  notes or private folders.
+- Raw captures are redacted from listing/search surfaces by default; reviewers
+  and distillation flows request previews or raw content only when needed.
+- Source configs can require review before distilled knowledge becomes durable
+  company memory.
+- Settings control default publish tier, whether company-tier knowledge requires
+  approval, citation requirements, email redaction, and connector error
+  notifications.
+- Demo/eval coverage checks proposal gating, PII redaction, personal-content
+  exclusion, citations, real-channel-style retrieval, and honest not-found
+  behavior.
+
+## Developer Notes
+
+The template follows the agent-native four-area contract:
+
+- **UI:** Ask, Search, Knowledge, Review, Sources, Ops, and Settings routes.
+- **Actions:** imports, source management, pilot reports, distillation queueing/claiming/retry, proposal review, cited search, and navigation/context actions.
+- **Skills/instructions:** Brain-specific guidance for distillation and retrieval.
+- **Application state:** route, filters, and selected IDs mirror into `application_state` for agent context.
+
+See [Dispatch](/docs/dispatch) for the workspace control plane, the
+[Dispatch template](/templates/dispatch) for the scaffolded app,
+[Workspace](/docs/workspace) for shared resources, and
+[A2A Protocol](/docs/a2a-protocol) for cross-app delegation.

package/docs/content/template-dispatch.md

@@ -26,8 +26,10 @@ If you're running an [multi-app workspace](/docs/multi-app-workspace) with many
 - **Central inbox.** Slack DMs, Telegram messages, email notifications, A2A requests from other agents — all land in one place. The Dispatch agent triages and either handles them itself or delegates. See [Messaging](/docs/messaging) for how to wire Slack, email, and Telegram into your workspace.
 - **Orchestrator, not specialist.** Dispatch does _not_ try to be the email app or the analytics app. When someone asks "summarize last week's signups," Dispatch calls the analytics agent over A2A and returns the answer. When someone asks "draft a reply to Alice," Dispatch calls the mail agent.
 - **Secrets vault.** A central store for API keys, OAuth tokens, and shared credentials. Apps in the workspace resolve secrets from Dispatch instead of duplicating them in every `.env`. Requests + approvals for sensitive access.
+- **Workspace resources.** Global skills, guardrail instructions, custom agent profiles, and reference resources can be created once in Dispatch. All-app resources are inherited at runtime by every app with no copy or manual sync step; selected grants are for app-specific exceptions.
 - **Integrations catalog.** One page showing every third-party integration — Slack, Telegram, SendGrid, Apollo, etc. — with a "configured / not configured / pending approval" status per app.
 - **Scheduled jobs hub.** Cross-app [recurring jobs](/docs/recurring-jobs) live here: "every weekday at 7, pull yesterday's key metrics from analytics and draft a morning summary email."
+- **Dreams.** Dispatch can review recent agent runs, failures, feedback, and successful patterns to propose memory, skill, job, and instruction improvements before anything durable is applied.
 - **Approval flow.** Destructive or external actions (sending money, shipping an outbound email, posting to Slack at scale) can require an admin OK before they fire. Dispatch owns the queue.
 
 ## When to use it {#when-to-use}
@@ -47,7 +49,9 @@ Day-to-day, Dispatch is the place admins and ops folks open to keep the workspac
 
 - **Connect Slack, email, and Telegram** so people can message your agent from wherever they already work. See [Messaging](/docs/messaging) for the wiring steps.
 - **Save shared secrets once.** API keys, OAuth tokens, and service credentials live in the vault and the other apps in your workspace pull from there instead of every team member juggling their own `.env`.
+- **Keep company context global.** Put personas, positioning, messaging, company facts, brand guidelines, and guardrails in Dispatch Resources once, then preview the effective workspace -> app/org -> personal stack for any app/user or inspect the stack from an app card's Context view.
 - **Set up recurring jobs.** "Every Monday at 7am, ask the analytics agent for last week's signups and email me a summary." See [Recurring Jobs](/docs/recurring-jobs).
+- **Review dream proposals.** Dispatch Dreams inspect prior agent runs and create source-backed proposals for what the workspace should remember, which stale notes should be cleaned up, and which repeated lessons should become skills or jobs.
 - **Approve outbound actions before they fire.** Sending money, mass-emailing customers, or posting to a public Slack channel can be gated behind an admin OK.
 - **See who has access to what.** Per-app grants, request queue, and an audit log of who used which secret when.
 - **Route messages to the right specialist.** A Slack DM about analytics goes to the analytics agent; one about email goes to the mail agent — Dispatch picks.
@@ -62,6 +66,32 @@ _How it works under the hood (for developers)._
 - **Slack / Telegram plugins.** Server plugins that register webhooks and forward incoming messages to the orchestrator agent.
 - **MCP hub mode.** Dispatch can act as the workspace's [MCP hub](/docs/mcp-clients#hub) so every other app in the workspace pulls the same org-scope MCP server list.
 
+## Dreams {#dreams}
+
+Dreams are Dispatch's review loop for agent memory. A dream pass looks over existing agent runs, thread debug data, feedback, evals, and repeated tool failures, then writes a report with proposed changes. The proposals can target personal memory, shared `LEARNINGS.md`, workspace instructions, workspace skills, workspace knowledge, workspace agents, or recurring jobs, but shared and workspace-level changes stay reviewable rather than being applied silently.
+
+Dream proposals are checked against the personal memory index, existing `memory/*.md` files, and shared `LEARNINGS.md` before they are saved. Duplicate lessons are skipped in the report, while likely stale personal memories are updated in place instead of producing parallel notes. Within a report, Dreams also deduplicate repeated evidence by thread, signal type, and normalized quote, strip injected context from user-correction detection, and summarize raw eval/tool rows into human-readable bullets before they appear in proposal text. When a pass finds signals but intentionally creates no proposals, the report includes guardrail notes explaining which evidence was suppressed.
+
+When Dispatch approval policy is enabled, applying a shared or team-wide dream proposal creates a pending approval request instead of writing immediately. Creating, updating, or deleting an All-app workspace resource also queues an approval request. Personal memory proposals and selected-only resource edits can still be applied directly after review.
+
+Use Dreams when you want to answer questions like "what did agents keep getting wrong this week?", "what should we remember?", or "which repeated lesson deserves a skill?" Inbound Slack, email, Telegram, WhatsApp, and web-derived evidence is treated as untrusted input, so proposals from those sources require review and provenance before they affect shared memory. Workspace-instruction proposals require durable evidence spanning at least two threads or two source apps; eval-only noise, account setup issues, quota limits, and single-app UI wording corrections stay out of global instructions.
+
+In the Dispatch UI, open **Dreams** to run a manual pass, review candidate threads, inspect the report, and open each proposal's review sheet before applying or rejecting it. Use **Settings** to edit the recurring cron schedule, source scope, timeout/concurrency limits, candidate limit, and minimum candidate threshold; use **Ensure schedule** after saving when you want the `jobs/dispatch-dream.md` recurring job materialized from those settings. The review sheet shows approval behavior, the current target content, proposed content, and source evidence. Agents use the same workflow through actions:
+
+- `list-dream-candidates` finds recent threads with grounded signals such as explicit user corrections, failed runs, tool errors, feedback, eval failures, and successful checkpointed workflows. Pass `sourceId: "all"` or `sourceIds` to scan multiple thread-debug sources; `sourceTimeoutMs`, `sourceConcurrency`, `sourceStartStaggerMs`, `threadConcurrency`, and `threadTimeoutMs` keep production scans partial and bounded, and the response includes per-source health.
+- `create-dream-report` creates the report and pending proposals. Multi-source reports include a Source Health section so partial scans are visible during review. Repeated corrections and recurring failures can become workspace-resource proposals such as `workspace-instruction`; repeated successful checkpointed workflows can become `workspace-skill` proposals.
+- `get-dream-settings` and `set-dream-settings` read and update the recurring dream schedule, source scope, timeout/concurrency controls, limit, and minimum candidate threshold.
+- `get-dream`, `preview-dream-proposal`, `apply-dream-proposal`, and `reject-dream-proposal` handle review.
+- `ensure-dream-job` creates the safe recurring dream job once manual reports are useful.
+
+The Dispatch template's local action runner also exposes packaged Dispatch actions, so in development you can run the same workflow from `apps/dispatch`:
+
+```bash
+pnpm action get-dream-settings
+pnpm action set-dream-settings --enabled true --schedule "0 9 * * 1" --allSources true --limit 8
+pnpm action create-dream-report --allSources true --sourceTimeoutMs 30000 --limit 8
+```
+
 ## Scaffolding {#scaffolding}
 
 ```bash