fix: dreamer.inject_docs=false now actually omits project docs

When the <project-docs> block moved from the system prompt into the m[0]
baseline, the dreamer.inject_docs gate stayed behind on the retired
system-prompt path: the flag was still computed and passed to the
system-prompt handler, which never used it, while the m[0] compose read
ARCHITECTURE.md and STRUCTURE.md unconditionally on both harnesses. The
flag silently did nothing.

Thread the flag through OpenCode and Pi m[0] injection instead, with
flag-only semantics independent of dreamer runnable state (docs exist on
disk and are hand-authored regardless of whether the dreamer maintains
them). Every docs read site routes through one gated helper per harness
that returns the rendered block and the docs hash together as the stable
empty pair when disabled, so execute, defer, fallback, and snapshot-marker
paths all agree byte-for-byte. Flipping the flag mid-session does not
force a materialization on its own; like docs content edits, it folds in
on the next natural hard bust. The dead system-prompt plumbing is removed
and the schema description now says what the flag actually gates.

Fixes #210

Author: ualtinok

assets/magic-context.schema.json

@@ -969,7 +969,7 @@
         },
         "inject_docs": {
           "default": true,
-          "description": "Inject ARCHITECTURE.md and STRUCTURE.md into system prompt",
+          "description": "Inject ARCHITECTURE.md and STRUCTURE.md into the m[0] `<project-docs>` block (default true)",
           "type": "boolean"
         },
         "thinking_level": {

packages/docs/src/content/docs/reference/configuration.md

@@ -199,7 +199,7 @@ Off-hours maintenance (Dreamer) and on-demand prompt augmentation (Sidekick).
 | `dreamer.tasks.refresh-primers.fallback_models` | string \\| string[] | — | Per-task fallback chain (inherits dreamer.fallback_models) |
 | `dreamer.tasks.refresh-primers.thinking_level` | `"off"` \\| `"minimal"` \\| `"low"` \\| `"medium"` \\| `"high"` \\| `"xhigh"` | — | Pi only: per-task thinking level |
 | `dreamer.tasks.refresh-primers.timeout_minutes` | number (5–) | `20` | Minutes allowed for this task before it is aborted |
-| `dreamer.inject_docs` | boolean | `true` | Inject ARCHITECTURE.md and STRUCTURE.md into system prompt |
+| `dreamer.inject_docs` | boolean | `true` | Inject ARCHITECTURE.md and STRUCTURE.md into the m[0] `<project-docs>` block (default true) |
 | `dreamer.thinking_level` | `"off"` \\| `"minimal"` \\| `"low"` \\| `"medium"` \\| `"high"` \\| `"xhigh"` | — | Pi only: default thinking level for dreamer subagent invocations. See historian.thinking_level. |
 | `sidekick` | object | — | Optional sidekick agent configuration for session-start memory retrieval |
 | `sidekick.model` | string | — | Primary model ID (e.g. 'claude-sonnet-4-6') |

packages/pi-plugin/src/context-handler.ts

@@ -682,8 +682,10 @@ export interface PiHeuristicsOptions {
 /** <session-history> injection config — writes compartments+facts+memories into message[0]. */
 export interface PiInjectionOptions {
 	/** When false (config `memory.enabled=false`), project memories are NOT read
-	 *  or rendered into m[0]/m[1]. Docs still render. */
+	 *  or rendered into m[0]/m[1]. Docs are controlled by injectDocs. */
 	memoryEnabled?: boolean;
+	/** Defaults true. When false, m[0] omits the <project-docs> block and docs hash. */
+	injectDocs?: boolean;
 	injectionBudgetTokens: number;
 	temporalAwareness?: boolean;
 }
@@ -3297,8 +3299,10 @@ interface RunPipelineArgs {
 	/** Memory-injection config — when omitted, no <session-history> injection runs. */
 	injection?: {
 		/** When false (config `memory.enabled=false`), project memories are NOT
-		 *  read or rendered into m[0]/m[1]. Docs still render. */
+		 *  read or rendered into m[0]/m[1]. Docs are controlled by injectDocs. */
 		memoryEnabled?: boolean;
+		/** Defaults true. When false, m[0] omits the <project-docs> block and docs hash. */
+		injectDocs?: boolean;
 		injectionBudgetTokens: number;
 		/** v2 decay-render history budget (~60K), distinct from the memory
 		 *  injection budget. Drives compartment tier demotion in renderM0Pi. */
@@ -4257,17 +4261,18 @@ async function runPipeline(args: RunPipelineArgs): Promise<RunPipelineResult> {
 			// NOTE: do NOT clear the m[0]/m[1] cache on a cache-busting pass. A new
 			// compartment is an m[1] DELTA (SOFT), not an m[0] re-materialization
 			// (HARD) — clearing forced mustMaterializePi to first_render and folded
-			// m[0] every history-refresh pass, defeating the whole m[0]/m[1] split
-			// (parity with the OpenCode max_compartment_seq removal). injectM0M1Pi
-			// now keeps cached m[0] and soft-refreshes m[1] with the new compartment;
-			// HARD triggers (model/system/ttl/epoch/docs/upgrade/mutation) still
+			// m[0] every history-refresh pass, defeating the whole m[0]/m[1] split.
+			// This matches OpenCode's rule that a new compartment sequence alone is not
+			// a HARD trigger. injectM0M1Pi now keeps cached m[0] and soft-refreshes m[1];
+			// HARD triggers (model/system/ttl/epoch/upgrade/mutation) still
 			// re-materialize inside mustMaterializePi when genuinely needed.
 			injectionResult = injectM0M1Pi(
 				{
 					sessionId: args.sessionId,
 					projectIdentity: args.projectIdentity,
 					projectDirectory: args.projectDirectory,
 					memoryEnabled: args.injection.memoryEnabled,
+					injectDocs: args.injection.injectDocs,
 					injectionBudgetTokens: args.injection.injectionBudgetTokens,
 					historyBudgetTokens: args.injection.historyBudgetTokens,
 					hardSignals: piHardSignals,

packages/pi-plugin/src/index.ts

@@ -657,6 +657,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		},
 		injection: {
 			memoryEnabled: cfg.memory.enabled,
+			injectDocs: cfg.dreamer?.inject_docs !== false,
 			injectionBudgetTokens: cfg.memory.injection_budget_tokens,
 			temporalAwareness: cfg.temporal_awareness === true,
 		},
@@ -1092,16 +1093,11 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			const effectiveDreamerRunnable = switchedProject
 				? isDreamerRunnable(effectiveConfig)
 				: isDreamerRunnable(config);
-			const injectDocs = switchedProject
-				? effectiveDreamerRunnable &&
-					(effectiveConfig.dreamer?.inject_docs ?? true)
-				: isDreamerRunnable(config) && (config.dreamer?.inject_docs ?? true);
 			const block = buildMagicContextBlock({
 				db,
 				cwd: currentProject.projectDir,
 				sessionId,
 				memoryEnabled: effectiveConfig.memory.enabled,
-				injectDocs,
 				includeGuidance: true,
 				protectedTags: effectiveConfig.protected_tags,
 				ctxReduceEnabled: effectiveConfig.ctx_reduce_enabled,

packages/pi-plugin/src/inject-compartments-pi.test.ts

@@ -11,6 +11,7 @@ import {
 } from "@magic-context/core/features/magic-context/memory/storage-memory";
 import {
 	getCompartments,
+	getOrCreateSessionMeta,
 	queueMemoryMutation,
 	setProjectState,
 } from "@magic-context/core/features/magic-context/storage";
@@ -385,6 +386,70 @@ describe("injectM0M1Pi", () => {
 		}
 	});
 
+	it("gates project docs block and hash with injectDocs=false", () => {
+		const db = createTestDb();
+		const cwd = mkdtempSync(join(tmpdir(), "pi-m0m1-docs-gate-"));
+		try {
+			writeFileSync(
+				join(cwd, "ARCHITECTURE.md"),
+				"# PI_FLAG_OFF_ARCH_DOCS\nArchitecture bytes must stay out.\n",
+			);
+			writeFileSync(
+				join(cwd, "STRUCTURE.md"),
+				"# PI_FLAG_OFF_STRUCTURE_DOCS\nStructure bytes must stay out.\n",
+			);
+			const state = { ...piState("ses-pi-docs-off", cwd), injectDocs: false };
+
+			const first = [userMessage("hello", 10)];
+			const firstResult = injectM0M1Pi(state, db, first as never);
+			const firstM0 = textOf(first[0] as never);
+			const firstM1 = textOf(first[1] as never);
+
+			expect(firstResult.m0Materialized).toBe(true);
+			expect(firstM0).not.toContain("<project-docs>");
+			expect(firstM0).not.toContain("PI_FLAG_OFF_ARCH_DOCS");
+			expect(firstM0).not.toContain("PI_FLAG_OFF_STRUCTURE_DOCS");
+			expect(
+				getOrCreateSessionMeta(db, state.sessionId).cachedM0ProjectDocsHash,
+			).toBe("");
+			expect(mustMaterializePi(state, db)).toEqual({
+				value: false,
+				reason: null,
+			});
+
+			const second = [userMessage("hello again", 11)];
+			const secondResult = injectM0M1Pi(
+				state,
+				db,
+				second as never,
+				undefined,
+				false,
+			);
+
+			expect(secondResult.m0Materialized).toBe(false);
+			expect(textOf(second[0] as never)).toBe(firstM0);
+			expect(textOf(second[1] as never)).toBe(firstM1);
+
+			const enabledState = piState("ses-pi-docs-on", cwd);
+			const enabled = [userMessage("hello docs", 12)];
+			injectM0M1Pi(enabledState, db, enabled as never);
+			expect(textOf(enabled[0] as never)).toContain("<project-docs>");
+			expect(textOf(enabled[0] as never)).toContain("PI_FLAG_OFF_ARCH_DOCS");
+			expect(textOf(enabled[0] as never)).toContain(
+				"PI_FLAG_OFF_STRUCTURE_DOCS",
+			);
+			expect(
+				mustMaterializePi({ ...enabledState, injectDocs: false }, db),
+			).toEqual({
+				value: false,
+				reason: null,
+			});
+		} finally {
+			rmSync(cwd, { recursive: true, force: true });
+			closeQuietly(db);
+		}
+	});
+
 	it("replays byte-stable cached m[0]/m[1] for identical state", () => {
 		const db = createTestDb();
 		const cwd = mkdtempSync(join(tmpdir(), "pi-m0m1-stable-"));

packages/pi-plugin/src/inject-compartments-pi.ts

@@ -452,8 +452,10 @@ const EMPTY_MAX_COMPARTMENT_SEQ = -1;
 
 type PiCompartment = ReturnType<typeof getCompartments>[number];
 
+type PiProjectDocsRender = ReturnType<typeof readProjectDocsCanonical>;
+
 interface FrozenM0Inputs {
-	docs: ReturnType<typeof readProjectDocsCanonical>;
+	docs: PiProjectDocsRender;
 	markers: PiM0SnapshotMarkers;
 	compartments: PiCompartment[];
 	memories: Memory[];
@@ -497,9 +499,10 @@ export interface PiM0M1State {
 	/** When false, project memories are NOT read or rendered into m[0]/m[1]
 	 *  (config `memory.enabled=false`). Mirrors OpenCode, which passes
 	 *  `projectPath: undefined` in that case so every memory read short-circuits.
-	 *  Docs still render (they key off projectDirectory, not memory).
-	 *  Unset/true keeps memory on. */
+	 *  Docs are controlled independently by injectDocs. Unset/true keeps memory on. */
 	memoryEnabled?: boolean;
+	/** Defaults true. When false, m[0] omits the <project-docs> block and docs hash. */
+	injectDocs?: boolean;
 	/** Memory-block trim budget (~4K). Bounds the <project-memory> block. */
 	injectionBudgetTokens?: number;
 	/** v2 decay-render history budget (~60K). Drives compartment tier demotion.
@@ -513,11 +516,22 @@ export interface PiM0M1State {
 	hardSignals?: PiM0HardSignals;
 }
 
+const EMPTY_PI_PROJECT_DOCS: PiProjectDocsRender = {
+	renderedBlock: "",
+	canonicalHash: "",
+};
+
+function readProjectDocsForPiM0(state: PiM0M1State): PiProjectDocsRender {
+	return state.injectDocs !== false
+		? readProjectDocsCanonical(state.projectDirectory)
+		: EMPTY_PI_PROJECT_DOCS;
+}
+
 /**
  * The project path used for MEMORY reads only. Returns undefined when
  * `memory.enabled=false`, so every memory read short-circuits to its empty
- * value (mirrors OpenCode passing `projectPath: undefined`). Docs + key-files
- * use `projectDirectory` directly and are unaffected.
+ * value (mirrors OpenCode passing `projectPath: undefined`). Project docs use
+ * the independent injectDocs flag.
  */
 function memoryProjectPath(state: PiM0M1State): string | undefined {
 	return state.memoryEnabled === false ? undefined : state.projectIdentity;
@@ -846,8 +860,7 @@ function readCurrentMarkersFromCompartments(
 			: null,
 		projectUserProfileVersion: globalState?.projectUserProfileVersion ?? 0,
 		projectDocsHash:
-			projectDocsHash ??
-			readProjectDocsCanonical(state.projectDirectory).canonicalHash,
+			projectDocsHash ?? readProjectDocsForPiM0(state).canonicalHash,
 		sessionFactsVersion: getSessionFactsVersion(db, state.sessionId),
 		materializedAt: Date.now(),
 		// Dynamic upgrade state (parity with OpenCode getUpgradeState): suffix
@@ -992,7 +1005,7 @@ function renderUserProfileBlock(
 export function renderM0Pi(
 	state: PiM0M1State,
 	db: ContextDatabase,
-	projectDocs = readProjectDocsCanonical(state.projectDirectory).renderedBlock,
+	projectDocs = readProjectDocsForPiM0(state).renderedBlock,
 	decayPressureMultiplier = 1,
 	// Atomic-snapshot override: when materializeM0Pi reads markers + memories in
 	// one transaction, it passes the SAME memory set here so the rendered m[0]
@@ -1169,7 +1182,7 @@ export class PiMaterializeContentionError extends Error {
 function readFrozenM0InputsPi(
 	state: PiM0M1State,
 	db: ContextDatabase,
-	docs = readProjectDocsCanonical(state.projectDirectory),
+	docs = readProjectDocsForPiM0(state),
 	memoryCutoff?: number,
 ): FrozenM0Inputs {
 	// Read every render source and its corresponding watermark as one short DB
@@ -1254,7 +1267,7 @@ function renderFreshM0PiNonPersisted(
 	snapshotMarkers: PiM0SnapshotMarkers;
 	renderedMemoryIds: number[];
 } {
-	const docs = readProjectDocsCanonical(state.projectDirectory);
+	const docs = readProjectDocsForPiM0(state);
 	const cachedMaterializedAt =
 		getOrCreateSessionMeta(db, state.sessionId).cachedM0MaterializedAt ?? 0;
 	const frozen = readFrozenM0InputsPi(state, db, docs, cachedMaterializedAt);
@@ -1317,7 +1330,7 @@ export function materializeM0Pi(
 } {
 	// Phase 1 (no lock): read markers + render. Rendering can be slow, so we do
 	// it OUTSIDE the write lock to keep the BEGIN IMMEDIATE critical section tiny.
-	const docs = readProjectDocsCanonical(state.projectDirectory);
+	const docs = readProjectDocsForPiM0(state);
 	const foldMaterializedAt = Date.now();
 	const frozen = readFrozenM0InputsPi(state, db, docs, foldMaterializedAt);
 	const snapshotMarkers = frozen.markers;
@@ -1368,9 +1381,7 @@ export function materializeM0Pi(
 		attempts += 1;
 	}
 	const m0Bytes = Buffer.from(m0, "utf8");
-	const phase3ProjectDocsHash = readProjectDocsCanonical(
-		state.projectDirectory,
-	).canonicalHash;
+	const phase3ProjectDocsHash = readProjectDocsForPiM0(state).canonicalHash;
 
 	// Phase 2 + 3 (locked): re-read markers under BEGIN IMMEDIATE; if anything
 	// changed since Phase 1, the rendered bytes are stale — roll back and let the

packages/pi-plugin/src/signal-peek-drain.test.ts

@@ -327,9 +327,11 @@ describe("source contract: peek-then-drain in before_agent_start (system prompt)
 		expect(code).not.toContain("^todo.*write");
 	});
 
-	test("project-docs injection is gated on dreamer.disable", () => {
-		expect(code).toContain("isDreamerRunnable(config) &&");
-		expect(code).toContain("(config.dreamer?.inject_docs ?? true)");
+	test("project-docs m0 injection uses the flag independent of dreamer.disable", () => {
+		expect(code).toContain("injectDocs: cfg.dreamer?.inject_docs !== false");
+		expect(code).not.toContain(
+			"isDreamerRunnable(config) && (config.dreamer?.inject_docs",
+		);
 	});
 
 	test("hash-change path remains eager for all three refresh sets", () => {

packages/pi-plugin/src/system-prompt.test.ts

@@ -24,7 +24,6 @@ describe("buildMagicContextBlock v2 system-prompt parity", () => {
 				cwd: tempDir("pi-guidance-"),
 				sessionId: "ses-guidance",
 				memoryEnabled: true,
-				injectDocs: true,
 				includeGuidance: true,
 			});
 
@@ -51,7 +50,6 @@ describe("buildMagicContextBlock v2 system-prompt parity", () => {
 				cwd,
 				sessionId: "ses-v2-system",
 				memoryEnabled: true,
-				injectDocs: true,
 				includeGuidance: true,
 				userMemoriesEnabled: true,
 			});
@@ -75,7 +73,6 @@ describe("buildMagicContextBlock v2 system-prompt parity", () => {
 				cwd,
 				sessionId: "ses-no-guidance",
 				memoryEnabled: true,
-				injectDocs: true,
 				includeGuidance: false,
 				userMemoriesEnabled: true,
 				pinKeyFilesEnabled: true,
@@ -95,7 +92,6 @@ describe("buildMagicContextBlock v2 system-prompt parity", () => {
 				cwd: tempDir("pi-guidance-dedup-"),
 				sessionId: "ses-guidance-dedup",
 				memoryEnabled: false,
-				injectDocs: false,
 				includeGuidance: true,
 				existingSystemPrompt: "base\n## Magic Context\nalready present",
 			});
@@ -114,7 +110,6 @@ describe("buildMagicContextBlock v2 system-prompt parity", () => {
 				cwd: tempDir("pi-noreduce-"),
 				sessionId: "ses-noreduce",
 				memoryEnabled: false,
-				injectDocs: false,
 				includeGuidance: true,
 				ctxReduceEnabled: false,
 			});
@@ -135,15 +130,13 @@ describe("buildMagicContextBlock v2 system-prompt parity", () => {
 				cwd: tempDir("pi-language-baseline-"),
 				sessionId: "ses-language-baseline",
 				memoryEnabled: true,
-				injectDocs: false,
 				includeGuidance: true,
 			});
 			const unset = buildMagicContextBlock({
 				db,
 				cwd: tempDir("pi-language-unset-"),
 				sessionId: "ses-language-unset",
 				memoryEnabled: true,
-				injectDocs: false,
 				includeGuidance: true,
 				language: " ",
 			});
@@ -152,7 +145,6 @@ describe("buildMagicContextBlock v2 system-prompt parity", () => {
 				cwd: tempDir("pi-language-set-"),
 				sessionId: "ses-language-set",
 				memoryEnabled: true,
-				injectDocs: false,
 				includeGuidance: true,
 				language: "es",
 			});

packages/pi-plugin/src/system-prompt.ts

@@ -35,8 +35,6 @@ export interface BuildMagicContextBlockOptions {
 	sessionId?: string;
 	/** Reserved for compatibility; project memories now live in m[0]/m[1]. */
 	memoryEnabled: boolean;
-	/** Reserved for compatibility; project docs now live in m[0]. */
-	injectDocs: boolean;
 	memoryBudgetChars?: number;
 	/** When true (default), emit the `## Magic Context` guidance section. */
 	includeGuidance?: boolean;

packages/plugin/src/config/schema/magic-context.ts

@@ -171,7 +171,9 @@ export const DreamerConfigSchema = AgentOverrideConfigSchema.merge(
         inject_docs: z
             .boolean()
             .default(true)
-            .describe("Inject ARCHITECTURE.md and STRUCTURE.md into system prompt"),
+            .describe(
+                "Inject ARCHITECTURE.md and STRUCTURE.md into the m[0] `<project-docs>` block (default true)",
+            ),
         thinking_level: PiThinkingLevelSchema.describe(
             "Pi only: default thinking level for dreamer subagent invocations. See historian.thinking_level.",
         ),