fix(beads): silence bd --json deprecation, opt projects into v2.0 envelope

commands/flow-setup.md

@@ -378,9 +378,14 @@ bd init --non-interactive --stealth --prefix <project_name_slug> --skip-agents
 bd config set no-git-ops true
 bd config set export.auto false
 bd config set export.git-add false
+
+mkdir -p .beads
+if [ ! -f .beads/config.yaml ] || ! grep -q '^json-envelope:' .beads/config.yaml; then
+  printf 'json-envelope: true\n' >> .beads/config.yaml
+fi
 ```
 
-These defaults keep Beads local-only: no automatic export, no auto-staging, and no git operations in `bd prime` output. `bd dolt push` remains explicit opt-in only.
+These defaults keep Beads local-only: no automatic export, no auto-staging, and no git operations in `bd prime` output. `bd dolt push` remains explicit opt-in only. The `json-envelope: true` Viper key opts the project into the bd v2.0 JSON envelope so `bd --json` stops emitting the deprecation notice; flow's hooks export `BD_JSON_ENVELOPE=1` until beads wires this through Viper.
 
 If no-Beads mode was selected:
 

commands/flow/setup.toml

@@ -57,7 +57,7 @@ Use `${FLOW_INSTALL_ROOT}` in every command below that references shipped templa
    If B selected, continue in no-Beads mode. Do NOT halt.
 
 3. **Default initialization rules:**
-   - Official Beads MUST use `bd init --non-interactive --stealth --prefix "$repo_slug" --skip-agents`, then set `bd config set no-git-ops true`, `bd config set export.auto false`, and `bd config set export.git-add false`.
+   - Official Beads MUST use `bd init --non-interactive --stealth --prefix "$repo_slug" --skip-agents`, then set `bd config set no-git-ops true`, `bd config set export.auto false`, and `bd config set export.git-add false`. Append `json-envelope: true` to `.beads/config.yaml` (idempotent) to opt into the bd v2.0 envelope.
    - Prefer `.git/info/exclude` for local-only ignores instead of editing repo `.gitignore`.
 
 4. **Continue:** Once the backend choice is clear, proceed to 1.1.
@@ -641,6 +641,11 @@ Use `${FLOW_INSTALL_ROOT}` in every command below that references shipped templa
     bd config set no-git-ops true
     bd config set export.auto false
     bd config set export.git-add false
+
+    mkdir -p .beads
+    if [ ! -f .beads/config.yaml ] || ! grep -q '^json-envelope:' .beads/config.yaml; then
+      printf 'json-envelope: true\n' >> .beads/config.yaml
+    fi
     ```
 
     If B selected, skip backend initialization and continue in no-Beads mode.

hooks/detect-env.ps1

@@ -9,6 +9,12 @@ $ErrorActionPreference = 'Stop'
 $script:DEFAULT_ROOT_DIR = if ($env:CLAUDE_PLUGIN_OPTION_AGENTSDIR) { $env:CLAUDE_PLUGIN_OPTION_AGENTSDIR } else { '.agents' }
 $script:USE_BEADS = if ($env:CLAUDE_PLUGIN_OPTION_USEBEADS) { $env:CLAUDE_PLUGIN_OPTION_USEBEADS } else { 'true' }
 
+# Opt into the bd v2.0 JSON envelope so `bd --json` stops emitting the
+# deprecation notice into the SessionStart context block. Bridges until
+# beads wires this through Viper config; flow's parsers below are
+# envelope-aware either way.
+$env:BD_JSON_ENVELOPE = '1'
+
 function Get-BeadsBackend {
     Write-Host "## Flow Environment Context"
     if ($script:USE_BEADS -ne 'true') {
@@ -122,8 +128,13 @@ function Get-ActiveWork($backend) {
     }
     if ($backend -eq "bd") {
         try {
-            # ConvertFrom-Json may return a single object; wrap in @(...) so Select-Object sees an array
-            $ready = @(bd ready --json | ConvertFrom-Json) | Select-Object -First 3
+            # ConvertFrom-Json may return a single object; wrap in @(...) so Select-Object sees an array.
+            # Unwrap the v2.0 envelope ({schema_version, data: [...]}) when present so legacy and envelope outputs both flow through.
+            $parsed = bd ready --json | ConvertFrom-Json
+            if ($parsed -is [PSCustomObject] -and $parsed.PSObject.Properties.Name -contains 'data') {
+                $parsed = $parsed.data
+            }
+            $ready = @($parsed) | Select-Object -First 3
             if ($ready) {
                 $readyJson = $ready | ConvertTo-Json -Compress
                 Write-Host "- **Ready Tasks (Top 3)**: $readyJson"

hooks/detect-env.sh

@@ -17,6 +17,12 @@ IFS=$'\n\t'
 readonly DEFAULT_ROOT_DIR="${CLAUDE_PLUGIN_OPTION_AGENTSDIR:-.agents}"
 readonly USE_BEADS="${CLAUDE_PLUGIN_OPTION_USEBEADS:-true}"
 
+# Opt into the bd v2.0 JSON envelope so `bd --json` stops emitting the
+# deprecation notice into the SessionStart context block. Bridges until
+# beads wires this through Viper config; flow's parsers below are
+# envelope-aware either way.
+export BD_JSON_ENVELOPE=1
+
 # --- Functions ---
 
 # Helper to safely run a command with timeout and return its output
@@ -161,7 +167,11 @@ active_work() {
             # Attempt to parse and truncate with python if available
             if command -v python3 >/dev/null 2>&1; then
                 local truncated
-                truncated=$(echo "${ready}" | python3 -c 'import json, sys; d=json.load(sys.stdin); print(json.dumps(d[:3]))' 2>/dev/null || true)
+                truncated=$(echo "${ready}" | python3 -c 'import json, sys
+d = json.load(sys.stdin)
+if isinstance(d, dict) and "data" in d:
+    d = d["data"]
+print(json.dumps(d[:3]))' 2>/dev/null || true)
                 if [[ -n "${truncated}" ]]; then
                     echo "- **Ready Tasks (Top 3)**: ${truncated}"
                     return

skills/flow/references/setup.md

@@ -261,6 +261,17 @@ bd config set export.git-add false
 Flow owns the host instruction files, so Beads setup must skip its generated agent files.
 The config commands keep Beads local-only by default: no automatic export, no auto-staging, and no git operations in `bd prime` output.
 
+Opt the project into the bd v2.0 JSON envelope so `bd --json` stops printing the deprecation notice on every command. Append the Viper key idempotently to `.beads/config.yaml`:
+
+```bash
+mkdir -p .beads
+if [ ! -f .beads/config.yaml ] || ! grep -q '^json-envelope:' .beads/config.yaml; then
+  printf 'json-envelope: true\n' >> .beads/config.yaml
+fi
+```
+
+bd 1.x reads the toggle only from `BD_JSON_ENVELOPE`; flow's hooks export that during sessions. Writing the YAML key now records the intent in version-controllable form so the project is ready when beads wires the toggle through Viper.
+
 Or prompt user:
 
 > **Beads mode:**

templates/agent/workflow.md

@@ -39,7 +39,7 @@ Flow supports two modes:
 
 Configured for local-only use during setup unless the user explicitly asks for shared repo state.
 
-Default setup writes `.agents/beads.json` with `syncPolicy.autoExport: false`, `syncPolicy.autoGitAdd: false`, and `syncPolicy.allowDoltPush: false`. It also applies `bd config set no-git-ops true`, `bd config set export.auto false`, and `bd config set export.git-add false`.
+Default setup writes `.agents/beads.json` with `syncPolicy.autoExport: false`, `syncPolicy.autoGitAdd: false`, and `syncPolicy.allowDoltPush: false`. It also applies `bd config set no-git-ops true`, `bd config set export.auto false`, and `bd config set export.git-add false`, and appends `json-envelope: true` to `.beads/config.yaml` to opt into the bd v2.0 JSON envelope.
 
 ### Session Protocol
 

templates/opencode/agents/flow.md

@@ -36,6 +36,7 @@ bd init --non-interactive --stealth --prefix <project_name_slug> --skip-agents #
 bd config set no-git-ops true
 bd config set export.auto false
 bd config set export.git-add false
+mkdir -p .beads && grep -q '^json-envelope:' .beads/config.yaml 2>/dev/null || printf 'json-envelope: true\n' >> .beads/config.yaml  # Opt into bd v2.0 envelope
 bd status                  # Workspace overview
 bd ready                   # Ready queue
 ```

templates/opencode/commands/flow-setup.md

@@ -261,9 +261,14 @@ bd init --non-interactive --stealth --prefix <project_name_slug> --skip-agents
 bd config set no-git-ops true
 bd config set export.auto false
 bd config set export.git-add false
+
+mkdir -p .beads
+if [ ! -f .beads/config.yaml ] || ! grep -q '^json-envelope:' .beads/config.yaml; then
+  printf 'json-envelope: true\n' >> .beads/config.yaml
+fi
 ```
 
-These defaults keep Beads local-only: no automatic export, no auto-staging, and no git operations in `bd prime` output. `bd dolt push` remains explicit opt-in only.
+These defaults keep Beads local-only: no automatic export, no auto-staging, and no git operations in `bd prime` output. `bd dolt push` remains explicit opt-in only. The `json-envelope: true` Viper key opts the project into the bd v2.0 JSON envelope so `bd --json` stops emitting the deprecation notice; flow's hooks export `BD_JSON_ENVELOPE=1` until beads wires this through Viper.
 
 If no-Beads mode was selected: