substrate-ai 0.20.103 → 0.20.105

package/dist/cli/index.js

@@ -2089,6 +2089,10 @@ async function runInitAction(options) {
 			".substrate/current-run-id",
 			".substrate/scenarios/",
 			".substrate/state/",
+			".substrate/runs/",
+			".substrate/notifications/",
+			".substrate/kv-metrics.json",
+			".substrate/latest-heartbeat-per-story-state.json",
 			".substrate/substrate.db",
 			".substrate/substrate.db-journal",
 			".codex/prompts/",

package/dist/cli/templates/agents-md-substrate-section.md

@@ -93,4 +93,16 @@ Each dispatched story runs in `.substrate-worktrees/story-<key>` on its own bran
 - `.substrate/runs/<run-id>.json` — per-run manifest (one file per run; not an aggregate)
 - `.substrate/current-run-id` — plain text file with the latest run ID
 - `.substrate/notifications/<run-id>-<timestamp>.json` — operator halt notifications (deleted by `substrate report` after read)
+
+### Recommended `.gitignore` entries
+
+Substrate writes per-project state under `.substrate/` in a few flavors: per-process scratch (`.pid`, `current-run-id`, `latest-heartbeat-per-story-state.json` — regenerated each run); per-run artifacts (`runs/<run-id>.json`, `notifications/`); local telemetry (`kv-metrics.json` — per-run phase token breakdown, accumulates into a local corpus used by `substrate metrics` and optional auto-tuner); the Dolt repository (`state/`); and the operator config (`config.yaml`, the only file intended for cross-machine sharing).
+
+Defensible default: ignore everything under `.substrate/` except the operator config. Local telemetry stays per-developer; operators see their own corpus locally regardless of git.
+
+```gitignore
+# Substrate state — track only the operator config
+.substrate/*
+!.substrate/config.yaml
+```
 <!-- substrate:end -->

package/dist/cli/templates/claude-md-substrate-section.md

@@ -109,6 +109,40 @@ Each dispatched story runs in `.substrate-worktrees/story-<key>` on its own bran
 - `.substrate/current-run-id` — plain text file with the latest run ID; consulted by canonical run-discovery
 - `.substrate/notifications/<run-id>-<timestamp>.json` — operator halt notifications written by the Recovery Engine; deleted by `substrate report` after read
 
+### Recommended `.gitignore` entries
+
+Substrate writes per-project state under `.substrate/` in a few flavors:
+- **Per-process scratch** (`.pid`, `current-run-id`, `latest-heartbeat-per-story-state.json`) — regenerated each run.
+- **Per-run artifacts** (`runs/<run-id>.json`, `notifications/<run-id>-*.json`) — accumulate across runs; substrate report consumes and cleans notifications.
+- **Local telemetry** (`kv-metrics.json` — per-run phase token breakdown used by `substrate metrics --output-format json` and, when enabled, the routing auto-tuner) — accumulates across runs into a local corpus.
+- **The Dolt repository** (`state/`) — versioned pipeline state, large + binary.
+- **Operator config** (`config.yaml`) — the only file intended for cross-machine sharing.
+
+The defensible default for most projects is to ignore everything under `.substrate/` except the operator config. Local telemetry stays on each developer's machine — operators see their own corpus locally via `substrate metrics`; cross-machine sharing of routing telemetry is a future feature, not currently supported.
+
+```gitignore
+# Substrate state — track only the operator config; everything else is
+# per-process, per-run, or local-machine accumulation
+.substrate/*
+!.substrate/config.yaml
+```
+
+This is future-proof against new files substrate may introduce. If you want to enumerate explicitly instead:
+
+```gitignore
+.substrate/state/
+.substrate/runs/
+.substrate/notifications/
+.substrate/kv-metrics.json
+.substrate/current-run-id
+.substrate/latest-heartbeat-per-story-state.json
+.substrate/*.db
+.substrate/*.pid
+.substrate/routing-policy.yaml
+```
+
+**Tradeoff to consider:** if your team wants to share a routing auto-tune corpus across machines (e.g., to seed `config.auto_tune` decisions with combined data), you could remove `kv-metrics.json` from the ignore set — at the cost of one git-mutation per substrate run. Most teams don't need this; the file is operator-visible locally regardless of git.
+
 ### State Backend
 
 Substrate uses Dolt for versioned pipeline state by default. Run `substrate init` to set it up automatically if Dolt is on PATH. Features that require Dolt: `substrate history`, OTEL observability persistence, and context engineering repo-map storage.

package/dist/cli/templates/gemini-md-substrate-section.md

@@ -93,4 +93,16 @@ Each dispatched story runs in `.substrate-worktrees/story-<key>` on its own bran
 - `.substrate/runs/<run-id>.json` — per-run manifest (one file per run; not an aggregate)
 - `.substrate/current-run-id` — plain text file with the latest run ID
 - `.substrate/notifications/<run-id>-<timestamp>.json` — operator halt notifications (deleted by `substrate report` after read)
+
+### Recommended `.gitignore` entries
+
+Substrate writes per-project state under `.substrate/` in a few flavors: per-process scratch (`.pid`, `current-run-id`, `latest-heartbeat-per-story-state.json` — regenerated each run); per-run artifacts (`runs/<run-id>.json`, `notifications/`); local telemetry (`kv-metrics.json` — per-run phase token breakdown, accumulates into a local corpus used by `substrate metrics` and optional auto-tuner); the Dolt repository (`state/`); and the operator config (`config.yaml`, the only file intended for cross-machine sharing).
+
+Defensible default: ignore everything under `.substrate/` except the operator config. Local telemetry stays per-developer; operators see their own corpus locally regardless of git.
+
+```gitignore
+# Substrate state — track only the operator config
+.substrate/*
+!.substrate/config.yaml
+```
 <!-- substrate:end -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "substrate-ai",
-  "version": "0.20.103",
+  "version": "0.20.105",
   "description": "Substrate — multi-agent orchestration daemon for AI coding agents",
   "type": "module",
   "license": "MIT",