brainiac-cli 0.16.0__py3-none-any.whl

brain/_assets/scripts/brain-synthesis.sh

@@ -0,0 +1,214 @@
+#!/usr/bin/env bash
+# brain-synthesis — the SECOND sanctioned host scheduled task (weekly).
+#
+# Owner decision 2026-07-11: metadata automation (the nightly maintain folds)
+# closed every organization gap EXCEPT synthesis — state/MOC notes drift
+# behind raw/ because writing prose needs a model, which the engine
+# deliberately does not hold (no API keys in brain). This task closes that
+# gap: once a week it runs a HEADLESS kb-curator session (Claude Code CLI)
+# against EVERY vault registered in ~/.brainiac/workspaces.json — vault-
+# generic by construction, never hardcoded to one vault.
+#
+# Task name:    brain-synthesis (launchd label com.brainiac.synthesis)
+# Schedule:     weekly, Sunday 08:00 local (one hour after the 07:00 nightly,
+#               so the week's promote-scan + digest output is already fresh)
+# Budget:       routines/manifest.json locked_counts.host_os_scheduled == 2
+#               (amended 2026-07-11 for exactly this task — THE LOCK rule
+#               says amend the manifest first; this is that amendment's task)
+# Runtime:      host only. Each session is bounded (--max-turns) and scoped
+#               to the workspace folder; it uses the same `brain` CLI +
+#               skills the interactive sessions use.
+# Logs:         $BRAIN_LOG_DIR/synthesis-YYYY-MM-DD.log (30-day rotation)
+# Skip rules:   no claude CLI -> skip loudly; a workspace without a
+#               kb-curator skill -> skipped and logged, never an error.
+set -u
+
+LOG_DIR="${BRAIN_LOG_DIR:-$HOME/.brain/logs}"
+mkdir -p "$LOG_DIR"
+LOG="$LOG_DIR/synthesis-$(date +%F).log"
+REGISTRY="${BRAIN_WORKSPACES_JSON:-$HOME/.brainiac/workspaces.json}"
+CLAUDE_BIN="${BRAIN_CLAUDE_BIN:-$(command -v claude || echo "$HOME/.local/bin/claude")}"
+MAX_TURNS="${BRAIN_SYNTHESIS_MAX_TURNS:-60}"
+
+log() { printf '%s %s\n' "$(date '+%F %T')" "$*" >> "$LOG"; }
+
+# 30-day log rotation (same posture as brain-brief.sh)
+find "$LOG_DIR" -name 'synthesis-*.log' -mtime +30 -delete 2>/dev/null
+
+if [ ! -x "$CLAUDE_BIN" ]; then
+  log "SKIP-ALL: claude CLI not found ($CLAUDE_BIN) — synthesis needs a model"
+  exit 0
+fi
+if [ ! -f "$REGISTRY" ]; then
+  log "SKIP-ALL: no workspace registry at $REGISTRY"
+  exit 0
+fi
+
+PROMPT="$(cat <<'EOF'
+Run the kb-curator skill for this vault, weekly synthesis pass. FIRST run
+`brain status --json` and `brain doctor`: if the maintain heartbeat is stale
+(daily branch > 48h) or any required surface is flagged, queue a dated entry
+to .brain/memory/hot.md describing what is broken — the scheduled umbrella
+cannot report its own death, so this weekly session is its watchdog. Then
+the synthesis scope:
+(1) refresh any state/MOC note whose content lags this week's raw/ ingests
+(check `brain recent` and the freshness signal on `brain search`); supersede
+rather than edit when the old claim was true-then; (2) review the Sunday
+promote-scan candidates in .brain/memory/hot.md and promote the ones that
+meet the one-idea-per-note bar into typed brain/ notes; (3) update index.md
+zone stamps. Follow AGENTS.md conventions exactly (frontmatter, wikilinks,
+classification explicit on every new note). Finish with `brain sync --publish`
+and a one-paragraph summary of what changed. Stay inside this workspace.
+EOF
+)"
+
+# Iterate REGISTERED host workspaces (dedup by vault_path) — vault-generic:
+# a new `brainiac-install`/`brainiac-cowork-setup` registration is picked up
+# on the next Sunday with zero extra wiring.
+python3 - "$REGISTRY" <<'PY' | while IFS=$'\t' read -r VAULT WS; do
+import json, sys
+seen = set()
+for e in json.load(open(sys.argv[1])).get("entries", []):
+    if e.get("target") != "host":
+        continue
+    v, w = e.get("vault_path", ""), e.get("workspace_path", "")
+    if not v or v in seen:
+        continue
+    seen.add(v)
+    print(f"{v}\t{w or v}")
+PY
+  if [ ! -d "$WS/.claude/skills/kb-curator" ] && [ ! -d "$WS/.agents/skills/kb-curator" ]; then
+    log "SKIP $VAULT: no kb-curator skill in $WS"
+    continue
+  fi
+  log "START synthesis: vault=$VAULT workspace=$WS"
+  # OBS-04: capture the CLI's `--output-format stream-json` NDJSON to OUT_JSON
+  # via a DIRECT redirect — NEVER a `tee` pipe (finding [6]: piping claude's
+  # stdout couples its liveness to the log sink, so a full/unwritable $LOG
+  # would SIGPIPE-kill an otherwise-healthy run and trip a false "synthesis
+  # died" watchdog). The direct-to-file NDJSON is durable and survives a kill
+  # (each line is flushed as emitted); cost/duration/usage are lifted below
+  # from its single `"type":"result"` line — STRUCTURED data only, never
+  # scraped human text (a scraped format drifts silently to a wrong zero —
+  # HARDENED correction 4). The CLI requires --verbose alongside stream-json.
+  # A per-run unique name (date + pid + two $RANDOM draws) avoids the
+  # same-second collision the old date-second+pid name allowed (finding [9]).
+  OUT_JSON="$LOG_DIR/synthesis-out-$(date +%F)-$$-${RANDOM}${RANDOM}.json"
+  ( cd "$WS" && BRAIN_VAULT="$VAULT" "$CLAUDE_BIN" -p "$PROMPT" \
+      --max-turns "$MAX_TURNS" \
+      --permission-mode acceptEdits \
+      --output-format stream-json \
+      --verbose \
+      --allowedTools "Read,Grep,Glob,Edit,Write,Bash(brain *),Bash(python3 tools/*)" \
+  ) > "$OUT_JSON" 2>>"$LOG"
+  RC=$?
+  log "END synthesis: vault=$VAULT rc=$RC"
+  # Render a human-readable transcript from the structured NDJSON into $LOG
+  # (finding [5]): the prior `tee`'d raw NDJSON REPLACED the readable session
+  # transcript the weekly-watchdog prompt tells an operator to open. Structured
+  # fields only (assistant text turns + the final result) — never scraped
+  # prose. A killed run renders whatever streamed before the kill; the full
+  # machine NDJSON stays in $OUT_JSON (30-day retention) regardless.
+  python3 - "$OUT_JSON" >> "$LOG" 2>>"$LOG" <<'PY' || true
+import json, sys
+try:
+    with open(sys.argv[1]) as fh:
+        for raw in fh:
+            raw = raw.strip()
+            if not raw:
+                continue
+            try:
+                obj = json.loads(raw)
+            except Exception:
+                continue
+            if not isinstance(obj, dict):
+                continue
+            if obj.get("type") == "assistant":
+                for b in (obj.get("message") or {}).get("content", []) or []:
+                    if isinstance(b, dict) and b.get("type") == "text":
+                        t = (b.get("text") or "").strip()
+                        if t:
+                            print(t)
+            elif obj.get("type") == "result":
+                r = (obj.get("result") or "").strip()
+                if r:
+                    print("--- result ---")
+                    print(r)
+except Exception:
+    pass
+PY
+  # Heartbeat (WATCHDOG-01): the hourly maintain umbrella reads this file and
+  # raises action_required when the last successful synthesis is > 8 days old
+  # — nobody should have to read synthesis logs to learn the task died.
+  # OBS-04: the same entry is extended with {tokens, duration_s, est_cost_usd}
+  # so src/brain/maintenance.py's collect_health_metrics can lift the latest
+  # metered cost into health-history.jsonl. Honors $BRAIN_SYNTHESIS_STATE (the
+  # SAME override the Python readers consult — finding [3]: the writer used to
+  # hardcode $HOME, so a set env silently split writer and reader and the
+  # watchdog never fired).
+  STATE="${BRAIN_SYNTHESIS_STATE:-$HOME/.brain/synthesis-state.json}"
+  # Finding [3] companion: create the state file's parent dir before writing —
+  # a $BRAIN_SYNTHESIS_STATE override can point at a not-yet-existing dir, and
+  # a silent write failure there would freeze last_success and trip a FALSE
+  # "synthesis stale" watchdog even though synthesis ran fine.
+  mkdir -p "$(dirname "$STATE")" 2>>"$LOG" || true
+  python3 - "$STATE" "$VAULT" "$RC" "$OUT_JSON" <<'PY'
+import json, sys, datetime
+path, vault, rc, out_json = sys.argv[1], sys.argv[2], int(sys.argv[3]), sys.argv[4]
+try:
+    state = json.load(open(path))
+except Exception:
+    state = {}
+entry = state.setdefault(vault, {})
+entry["last_attempt"] = datetime.date.today().isoformat()
+entry["rc"] = rc
+if rc == 0:
+    entry["last_success"] = entry["last_attempt"]
+
+# OBS-04 — meter from the structured --output-format stream-json NDJSON
+# stream ONLY: scan every line, keep the (last) line with "type":"result" —
+# that's the CLI's own final usage/cost summary for the run. Absent/zero/
+# unparseable all record as null (never a scraped guess, never a bare 0
+# masquerading as "measured").
+cost = tokens = duration_s = None
+try:
+    result_obj = None
+    with open(out_json) as fh:
+        for raw_line in fh:
+            raw_line = raw_line.strip()
+            if not raw_line:
+                continue
+            try:
+                obj = json.loads(raw_line)
+            except Exception:
+                continue
+            if isinstance(obj, dict) and obj.get("type") == "result":
+                result_obj = obj
+    if result_obj is not None:
+        c = result_obj.get("total_cost_usd")
+        if isinstance(c, (int, float)) and c > 0:
+            cost = round(c, 4)
+        dm = result_obj.get("duration_ms")
+        if isinstance(dm, (int, float)):
+            duration_s = round(dm / 1000, 1)
+        usage = result_obj.get("usage") or {}
+        parts = [usage.get(k) for k in (
+            "input_tokens", "output_tokens",
+            "cache_creation_input_tokens", "cache_read_input_tokens")]
+        nums = [p for p in parts if isinstance(p, (int, float))]
+        if nums:
+            tokens = int(sum(nums))
+except Exception:
+    pass
+entry["tokens"] = tokens
+entry["duration_s"] = duration_s
+entry["est_cost_usd"] = cost
+json.dump(state, open(path, "w"), indent=1)
+PY
+done
+
+# 30-day rotation for the per-run usage-json captures (same posture as logs).
+find "$LOG_DIR" -name 'synthesis-out-*.json' -mtime +30 -delete 2>/dev/null
+
+log "synthesis run complete"
+exit 0

brain/_assets/scripts/install-brief-mac.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# install-brief-mac.sh — install brain-daily-brief as a macOS launchd LaunchAgent (UX-02)
+#
+# Usage:
+#   BRAIN_VAULT=/path/to/vault bash scripts/install-brief-mac.sh
+#
+# Prerequisites:
+#   - brain binary must be on PATH (test: brain --version)
+#   - BRAIN_AUDIT_KEY_PEM must be set OR the key stored in the macOS Keychain
+#     under service "profile-a-brain-audit-key" (security find-generic-password -s profile-a-brain-audit-key -w)
+#
+# Uninstall (per-vault label — the script prints the exact paths on install):
+#   launchctl unload ~/Library/LaunchAgents/com.brainiac.nightly.<id>.plist
+#   rm ~/Library/LaunchAgents/com.brainiac.nightly.<id>.plist
+set -euo pipefail
+
+VAULT="${BRAIN_VAULT:?BRAIN_VAULT must be set (path to your brain vault)}"
+SCRIPTS="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLIST_SRC="$SCRIPTS/brain-brief-mac.plist"
+
+# Per-vault launchd label (SINGLE SOURCE OF TRUTH: brain.config.nightly_label),
+# so two registered vaults never install to one shared label and clobber each
+# other's nightly job. Prefer the installed package; fall back to a shell
+# reimplementation of vault_slug8 (sha256 of the resolved vault path, first 8).
+LABEL=""
+BRAIN_BIN="$(command -v brain || true)"
+if [ -n "$BRAIN_BIN" ]; then
+    VENV_PY="$(dirname "$BRAIN_BIN")/python3"
+    [ -x "$VENV_PY" ] || VENV_PY="python3"
+    LABEL="$(BRAIN_VAULT="$VAULT" "$VENV_PY" - <<'PY' 2>/dev/null || true
+import os
+from brain.config import nightly_label
+print(nightly_label(os.environ["BRAIN_VAULT"]))
+PY
+)"
+fi
+if [ -z "$LABEL" ]; then
+    _vr="$(python3 -c 'import os,sys; print(os.path.realpath(os.path.expanduser(sys.argv[1])))' "$VAULT" 2>/dev/null || echo "$VAULT")"
+    _h="$(printf '%s' "$_vr" | shasum -a 256 | cut -c1-8)"
+    LABEL="com.brainiac.nightly.$_h"
+fi
+
+LEGACY_LABEL="com.profile-a-brain.daily-brief"
+LEGACY_PLIST="$HOME/Library/LaunchAgents/$LEGACY_LABEL.plist"
+PLIST_DST="$HOME/Library/LaunchAgents/$LABEL.plist"
+LOGDIR="${BRAIN_LOG_DIR:-$HOME/.brain/logs}"
+
+# Audit signing key: the drain resolves it from the macOS Keychain AT RUNTIME
+# (src/brain/audit.py resolve_signing_key(), env -> keychain fallthrough), so
+# the plist does NOT carry the key material. Baking the PEM into the plist
+# (the old behavior) left the private key in a plaintext file under
+# ~/Library/LaunchAgents. We only bake a value when the operator explicitly
+# injected BRAIN_AUDIT_KEY_PEM (custom custody / unattended box) — and the
+# plist is chmod 600 below either way.
+KEYCHAIN_SERVICE="${BRAIN_AUDIT_KEYCHAIN_SERVICE:-profile-a-brain-audit-key}"
+AUDIT_KEY="${BRAIN_AUDIT_KEY_PEM:-}"
+if [ -z "$AUDIT_KEY" ]; then
+    if ! security find-generic-password -s "$KEYCHAIN_SERVICE" -a "$USER" >/dev/null 2>&1; then
+        echo "WARNING: No BRAIN_AUDIT_KEY_PEM and no Keychain entry for '$KEYCHAIN_SERVICE'." >&2
+        echo "         Captures will not be signed (drain fails closed). Run 'brain audit-key'" >&2
+        echo "         (create-if-absent, never rotates) — no reinstall needed after." >&2
+    fi
+fi
+
+mkdir -p "$LOGDIR" "$HOME/Library/LaunchAgents"
+
+# Render the plist to a scratch file first so we can diff against whatever is
+# already installed — the nightly-diff contract (docs/install/plugin-distribution.md
+# §3): reinstall/reload iff the rendered body actually changed, otherwise report
+# unchanged and touch nothing (idempotent re-runs, no needless launchctl churn).
+PLIST_NEW="$(mktemp "${TMPDIR:-/tmp}/brain-brief-mac.plist.XXXXXX")"
+trap 'rm -f "$PLIST_NEW"' EXIT
+
+sed -e "s|LABEL_PLACEHOLDER|$LABEL|g" \
+    -e "s|SCRIPTS_DIR|$SCRIPTS|g" \
+    -e "s|VAULT_PATH|$VAULT|g" \
+    -e "s|HOME_DIR|$HOME|g" \
+    -e "s|AUDIT_KEY_PEM_PLACEHOLDER|$AUDIT_KEY|g" \
+    -e "s|SWEEP_DIRS_PLACEHOLDER|${BRAIN_WORKSPACE_SWEEP_DIRS:-}|g" \
+    "$PLIST_SRC" > "$PLIST_NEW"
+
+# ponytail: real launchctl talks to the login launchd domain by uid, not by
+# $HOME — a sandboxed HOME does NOT sandbox launchctl. BRAIN_LAUNCHD_DRY_RUN=1
+# (or a non-default HOME, detected below) skips the real bootstrap/load calls
+# so test/sandbox runs never touch the real user's launchd domain.
+if [ -z "${BRAIN_LAUNCHD_DRY_RUN:-}" ] && [ "$HOME" != "$(eval echo ~"$USER")" ]; then
+    BRAIN_LAUNCHD_DRY_RUN=1
+fi
+
+# One-time migration off the legacy SHARED label: if the old single-label plist
+# exists (and isn't this vault's per-vault plist), unload + remove it so the two
+# host vaults stop competing for one launchd job. Idempotent — absent after the
+# first migrated install.
+if [ "$LEGACY_PLIST" != "$PLIST_DST" ] && [ -f "$LEGACY_PLIST" ]; then
+    if [ "${BRAIN_LAUNCHD_DRY_RUN:-0}" = "1" ]; then
+        echo "migration DRY-RUN: would retire legacy shared label $LEGACY_LABEL"
+    else
+        launchctl unload "$LEGACY_PLIST" 2>/dev/null || true
+        rm -f "$LEGACY_PLIST"
+        echo "migrated: retired legacy shared nightly label $LEGACY_LABEL (now per-vault)"
+    fi
+fi
+
+if [ -f "$PLIST_DST" ] && cmp -s "$PLIST_NEW" "$PLIST_DST"; then
+    echo "nightly: unchanged (label: $LABEL) — nothing to reload"
+    echo "  Status: launchctl list $LABEL"
+    exit 0
+fi
+
+cp "$PLIST_NEW" "$PLIST_DST"
+chmod 600 "$PLIST_DST"
+
+if [ "${BRAIN_LAUNCHD_DRY_RUN:-0}" = "1" ]; then
+    echo "DRY-RUN (sandboxed HOME or BRAIN_LAUNCHD_DRY_RUN=1) — plist written, launchd NOT reloaded. Would run:"
+    echo "  launchctl unload '$PLIST_DST'"
+    echo "  launchctl load -w '$PLIST_DST'"
+    echo "  To load it for real, re-run this from a normal (non-sandboxed) terminal, or run the two commands above."
+else
+    # (Re)load the agent.
+    launchctl unload "$PLIST_DST" 2>/dev/null || true
+    launchctl load -w "$PLIST_DST"
+fi
+
+echo "✓ Installed: $LABEL (hourly umbrella, vault: $VAULT)"
+
+# --- brain-synthesis (the SECOND sanctioned task; THE LOCK host=2) ---------
+# One per HOST (label has no vault id): the script iterates every registered
+# vault in ~/.brainiac/workspaces.json, so re-running this installer for a
+# second vault just refreshes the same host-level agent. Weekly Sun 08:00.
+SYNTH_SRC="$SCRIPTS/brain-synthesis-mac.plist"
+SYNTH_DST="$HOME/Library/LaunchAgents/com.brainiac.synthesis.plist"
+if [ -f "$SYNTH_SRC" ]; then
+    SYNTH_NEW="$(mktemp "${TMPDIR:-/tmp}/brain-synthesis-mac.plist.XXXXXX")"
+    sed -e "s|SCRIPTS_DIR|$SCRIPTS|g" -e "s|HOME_DIR|$HOME|g" \
+        "$SYNTH_SRC" > "$SYNTH_NEW"
+    if ! cmp -s "$SYNTH_NEW" "$SYNTH_DST" 2>/dev/null; then
+        cp "$SYNTH_NEW" "$SYNTH_DST"
+        chmod 600 "$SYNTH_DST"
+        if [ "${BRAIN_LAUNCHD_DRY_RUN:-0}" = "1" ]; then
+            echo "DRY-RUN — synthesis plist written, launchd NOT reloaded."
+        else
+            launchctl unload "$SYNTH_DST" 2>/dev/null || true
+            launchctl load -w "$SYNTH_DST"
+        fi
+        echo "✓ Installed: com.brainiac.synthesis (weekly Sun 08:00, all registered vaults)"
+    fi
+    rm -f "$SYNTH_NEW"
+fi
+echo "  Logs:      $LOGDIR/brief-YYYY-MM-DD.log"
+echo "  Status:    launchctl list $LABEL"
+echo "  Dry-run:   launchctl start $LABEL"
+echo "  Uninstall: launchctl unload '$PLIST_DST' && rm '$PLIST_DST'"

brain/_assets/scripts/install-brief-windows.ps1

@@ -0,0 +1,97 @@
+# install-brief-windows.ps1 — install brain-daily-brief as a Windows Scheduled Task (UX-02)
+#
+# Usage (run as the same user who will run brain, NOT as Administrator):
+#   .\scripts\install-brief-windows.ps1 -VaultPath C:\Users\you\brain\vault
+#
+# Prerequisites:
+#   - brain.exe must be on PATH (test: brain --version)
+#
+# Uninstall:
+#   Unregister-ScheduledTask -TaskName "brain-daily-brief" -Confirm:$false
+#
+# Threat model: the signing key lives in Windows Credential Manager (service
+# profile-a-brain-audit-key) and is resolved AT RUNTIME by the brain process
+# itself (audit.py resolve_signing_key(), env -> keyring fallthrough). It is
+# NEVER embedded in this script, the task action, or the task XML. See
+# docs/operations/s09-evidence.md § Scheduled-task threat model.
+param(
+    [Parameter(Mandatory=$true)]
+    [string]$VaultPath,
+
+    [string]$BrainExe   = "brain",
+    [string]$TaskName   = "",
+    [string]$LogDir     = "$env:USERPROFILE\.brain\logs"
+)
+$ErrorActionPreference = "Stop"
+
+# Per-vault task name (mirrors brain.config.nightly_label's sha256(resolved-vault)[:8]
+# slug) so two registered vaults don't install to one shared Scheduled Task and
+# clobber each other's job. Pass -TaskName explicitly to override.
+$LegacyTask = "brain-daily-brief"
+if ([string]::IsNullOrEmpty($TaskName)) {
+    $resolved = Resolve-Path -LiteralPath $VaultPath -ErrorAction SilentlyContinue
+    $vpath = if ($resolved) { $resolved.Path } else { $VaultPath }
+    $bytes = [System.Text.Encoding]::UTF8.GetBytes($vpath)
+    $hash  = ([System.Security.Cryptography.SHA256]::Create().ComputeHash($bytes) |
+              ForEach-Object { $_.ToString('x2') }) -join ''
+    $TaskName = "brain-daily-brief-" + $hash.Substring(0, 8)
+}
+
+# One-time migration off the legacy SHARED task name.
+if ($TaskName -ne $LegacyTask) {
+    $existing = Get-ScheduledTask -TaskName $LegacyTask -ErrorAction SilentlyContinue
+    if ($existing) {
+        Unregister-ScheduledTask -TaskName $LegacyTask -Confirm:$false
+        Write-Host "migrated: retired legacy shared task $LegacyTask (now per-vault)"
+    }
+}
+
+New-Item -ItemType Directory -Force -Path $LogDir | Out-Null
+
+# Audit signing key: provision create-if-absent (never rotates) into the
+# Credential Manager via the engine; the drain resolves it at runtime, so
+# nothing key-shaped goes into the task action below.
+try {
+    & $BrainExe audit-key
+} catch {
+    Write-Warning "audit-key provisioning failed: $_"
+    Write-Warning "Captures will not be drained (drain fails closed, unsigned)."
+    Write-Warning "Run '$BrainExe audit-key' manually later — no reinstall needed."
+}
+
+$logFile = "$LogDir\brief-$(Get-Date -Format 'yyyy-MM-dd').log"
+
+# Task action: the `maintain` umbrella -- sync --publish + brief, PLUS the
+# date-gated branches (Mon=health, Tue=integrity, Sun=digest,
+# 1st=graphify-documented-only). This is THE single sanctioned OS task
+# (`brain-nightly`, persistence-budget.md THE LOCK) -- see
+# src/brain/core.py BrainCore.maintain. routines/manifest.json id "brain-nightly".
+$scriptBlock = @"
+`$env:BRAIN_VAULT = '$VaultPath'
+`$log = '$LogDir\brief-' + (Get-Date -Format 'yyyy-MM-dd') + '.log'
+'=== brain-daily-brief / brain-nightly ' + (Get-Date -Format 'yyyy-MM-ddTHH:mm:ssZ') + ' ===' | Out-File -Append -FilePath `$log
+& '$BrainExe' maintain --json 2>&1 | Out-File -Append -FilePath `$log
+# Rotate logs older than 30 days
+Get-ChildItem '$LogDir\brief-*.log' | Where-Object { `$_.LastWriteTime -lt (Get-Date).AddDays(-30) } | Remove-Item -Force
+"@
+
+$action   = New-ScheduledTaskAction -Execute "powershell.exe" `
+              -Argument "-NonInteractive -WindowStyle Hidden -Command `"$scriptBlock`""
+# HOURLY (owner decision 2026-07-11, parity with the macOS installer):
+# ingestion is frequent — every firing runs the incremental/idempotent work;
+# weekly/monthly branches stay date-gated inside `brain maintain`.
+$trigger  = New-ScheduledTaskTrigger -Once -At (Get-Date).Date `
+              -RepetitionInterval (New-TimeSpan -Hours 1)
+$settings = New-ScheduledTaskSettingsSet `
+              -RunOnlyIfNetworkAvailable:$false `
+              -StartWhenAvailable `
+              -ExecutionTimeLimit (New-TimeSpan -Minutes 10)
+
+Register-ScheduledTask -TaskName $TaskName -Action $action -Trigger $trigger `
+    -Settings $settings -RunLevel Limited -Force | Out-Null
+
+Write-Host "Installed: $TaskName (hourly umbrella)"
+Write-Host "  Logs:      $LogDir\brief-YYYY-MM-DD.log"
+Write-Host "  Status:    Get-ScheduledTask -TaskName '$TaskName'"
+Write-Host "  Dry-run:   Start-ScheduledTask -TaskName '$TaskName'"
+Write-Host "  Uninstall: Unregister-ScheduledTask -TaskName '$TaskName' -Confirm:`$false"