diff --git a/.brain/brainstorms/mempalace-inspired-brain-improvements.md b/.brain/brainstorms/mempalace-inspired-brain-improvements.md
new file mode 100644
index 0000000..eea7a2e
--- /dev/null
+++ b/.brain/brainstorms/mempalace-inspired-brain-improvements.md
@@ -0,0 +1,50 @@
+---
+brainstorm_status: active
+created: "2026-04-13T06:23:51Z"
+idea_count: 0
+project: brain
+title: MemPalace-Inspired Brain Improvements
+type: brainstorm
+updated: "2026-04-13T06:23:51Z"
+---
+# Brainstorm: MemPalace-Inspired Brain Improvements
+
+Started: 2026-04-13T06:27:00Z
+
+## Focus Question
+
+Which MemPalace-style ideas are actually worth borrowing for Brain without breaking Brain's explicit, curated-memory philosophy?
+
+## Ideas
+
+- Optional session-aware memory distillation can recover decisions, tradeoffs, bugs, and discoveries that currently disappear when nobody writes them down.
+- Distillation should propose note updates, not silently write them. Brain keeps human or agent approval in the loop.
+- Layered context loading can split startup context into L0 identity/current-state, L1 workflow and architecture summary, L2 full context files, and L3 search-driven deep context.
+- Retrieval ranking should favor what matters now, not just literal query overlap. Recency, note type, and active epic or spec context should affect ordering.
+- Search should bridge directly into usage with an inject mode that returns a preformatted context block an agent can paste into work.
+- Brain needs first-class decision notes so the system keeps why a choice was made, not just the final choice.
+- Session closeout should help the user recover missing memory work by suggesting a session-scoped distill path when repo state changed but durable notes did not.
+- A lightweight session memory cache is interesting only as an optional temporary layer. It should stay clearly separate from durable memory until distilled.
+
+## Related
+
+- [[.brain/planning/epics/planning-and-brainstorming-ux.md]]
+- [[.brain/planning/epics/retrieval-and-index-lifecycle.md]]
+- [[.brain/planning/epics/context-and-session-workflow.md]]
+
+## Raw Notes
+
+High-value changes from the brainstorm:
+
+1. Memory capture: add an optional `brain distill` flow that inspects recent session activity, command runs, and git diff, then proposes durable note updates.
+2. Context efficiency: add layered context loading so agents can start small and pull deeper context only when needed.
+3. Retrieval quality: improve ranking with recency, note-type weighting, and active-work-context bias.
+4. Reasoning preservation: add a first-class decision note type and template.
+5. Workflow smoothing: integrate distillation suggestions into session closeout instead of only blocking on missing memory updates.
+6. Retrieval-to-usage bridge: add `brain search --inject` or equivalent agent-ready context output.
+
+Non-goals from the same brainstorm:
+
+- Do not store everything verbatim.
+- Do not introduce spatial memory abstractions that duplicate the filesystem.
+- Do not lean harder on embeddings at the cost of explicit project structure.
diff --git a/.brain/context/architecture.md b/.brain/context/architecture.md
index 9ccd668..fbc6432 100644
--- a/.brain/context/architecture.md
+++ b/.brain/context/architecture.md
@@ -10,6 +10,7 @@ Use this file for the structural shape of the repository.
 - `internal/brainstorm/`
 - `internal/buildinfo/`
 - `internal/config/`
+- `internal/distill/`
 - `internal/embeddings/`
 - `internal/history/`
 - `internal/index/`
diff --git a/.brain/context/current-state.md b/.brain/context/current-state.md
index 088fc25..681758f 100644
--- a/.brain/context/current-state.md
+++ b/.brain/context/current-state.md
@@ -1,5 +1,5 @@
 ---
-updated: "2026-04-12T05:22:46Z"
+updated: "2026-04-13T15:26:30Z"
 ---
 # Current State
 
@@ -12,9 +12,10 @@ This file is a deterministic snapshot of the repository state at the last refres
 - Root: `.`
 - Runtime: `go`
 - Go module: `brain`
-- Current branch: `docs-pr-workflow-and-windows-ci-fixes`
+- Current branch: `feature/mempalace-planning-roadmap`
+- Default branch: `main`
 - Remote: `https://github.com/JimmyMcBride/brain.git`
-- Go test files: `19`
+- Go test files: `20`
 
 ## Docs
 
@@ -78,3 +79,10 @@ Add repo-specific notes here. `brain context refresh` preserves content outside
 - 2026-04-11: Repositioned the product docs around Brain as durable local operating memory for AI coding agents. The README now leads with the continuity/reliability story, keeps install + skill install + brainstorm-to-execution prominent, treats lower token and tool cost as supporting proof, and replaces the bottom link dump with high-level overview sections that deep-link into usage, architecture, skills, and why.
 - 2026-04-11: Tightened the Windows session-lock fix again after PR feedback. Lock acquisition now treats Windows `os.ErrPermission` during lock-directory races as retryable contention even if a follow-up stat misses the directory, which should stop intermittent `Access is denied` failures in concurrent session tests.
 - 2026-04-11: Tightened the README positioning pass by adding an explicit audience section for heavy AI-agent users, a `Why Brain Exists` founder-pain section, and a cleaner deep-dive section structure so the README sells urgency before dropping into technical overviews.
+- 2026-04-12: Returned the local checkout to `main` after PR #5 merged and fast-forwarded the repo to `v0.1.7`, which includes the README urgency follow-up and aligned supporting docs.
+
+- 2026-04-13: Updated `skills/brain/SKILL.md` and refreshed the global Codex `brain` skill so it now teaches `brain distill`, `brain search --inject`, `brain context load --level`, and the session-finish distill recovery flow.
+
+- 2026-04-13: Fixed the CLI test output normalizer so Windows no longer corrupts JSON escape sequences while replacing temp-root paths, which restores `TestCLIContextLoadLevels` and other JSON-based CLI tests on the Windows pipeline.
+
+- 2026-04-13: Fixed the remaining Windows CLI skill-target assertions to use OS-native path joins in tests, so `TestCLISkillsCommands` now accepts Windows `\` paths without regressing Unix output expectations.
diff --git a/.brain/context/workflows.md b/.brain/context/workflows.md
index c43c8b7..592f283 100644
--- a/.brain/context/workflows.md
+++ b/.brain/context/workflows.md
@@ -15,11 +15,24 @@ Use this file for agent operating workflow inside the repo.
 - Keep durable discoveries, decisions, and risks in AGENTS.md, /docs, or .brain notes.
 - Update existing durable notes instead of duplicating context.
 - Run required verification commands through `brain session run -- <command>`.
+- If you change Brain command behavior or agent-facing workflow guidance, update `skills/brain/SKILL.md` in the same branch.
 - Re-read context before large changes if the task shifts.
 
+## Ticket Loop
+
+1. Start one story or ticket at a time and keep the scope narrow.
+2. Implement the story, then run focused tests for the touched packages.
+3. Run the required full checks through `brain session run -- go test ./...` and `brain session run -- go build ./...`.
+4. Review the diff against the story acceptance criteria and user-facing behavior.
+5. If review finds issues, patch the work and repeat the test and review steps.
+6. When the story is clean, commit it, push it, and only then move to the next story.
+
 ## Close-Out
 
 - Refresh or update durable notes for meaningful behavior, config, or architecture changes.
+- If `skills/brain/` changed, reinstall the local Brain skill for Codex and OpenClaw with `brain skills install --scope local --agent codex --agent openclaw --project .`.
+- When opening a PR, make the title and body release-note friendly because GitHub release notes are generated from merged PR metadata.
+- Summarize shipped behavior in the PR, not just implementation steps, so future changelogs stay human-readable.
 - Finish with `brain session finish`.
 - If you must bypass enforcement, use `brain session finish --force --reason "..."` so the override is recorded.
 <!-- brain:end context-workflows -->
diff --git a/.brain/planning/epics/context-and-session-workflow.md b/.brain/planning/epics/context-and-session-workflow.md
index 6e14e31..2530187 100644
--- a/.brain/planning/epics/context-and-session-workflow.md
+++ b/.brain/planning/epics/context-and-session-workflow.md
@@ -4,7 +4,7 @@ project: brain
 spec: context-and-session-workflow
 title: Context And Session Workflow
 type: epic
-updated: "2026-04-11T21:53:09Z"
+updated: "2026-04-13T06:23:51Z"
 ---
 # Context And Session Workflow
 
@@ -12,10 +12,18 @@ Created: 2026-04-11T05:10:54Z
 
 ## Description
 
+Make Brain's context loading and session closeout flow more graduated and more helpful. Agents should be able to start with less context, pull more intentionally, and recover from missing memory work without leaving the session workflow.
+
 ## Work Items
 
+- [[.brain/planning/stories/context-and-session-workflow-current-state-and-next-actions.md]]
+- [[.brain/planning/stories/add-layered-context-loading-levels.md]]
+- [[.brain/planning/stories/suggest-distillation-during-session-closeout.md]]
+
 ## Notes
 
+This epic is the workflow glue around context tiers and session-to-memory recovery. Temporary session cache work stays optional until the core path exists.
+
 ## Spec
 
 - [[.brain/planning/specs/context-and-session-workflow.md]]
diff --git a/.brain/planning/epics/planning-and-brainstorming-ux.md b/.brain/planning/epics/planning-and-brainstorming-ux.md
index 9b4f1e4..3b27db6 100644
--- a/.brain/planning/epics/planning-and-brainstorming-ux.md
+++ b/.brain/planning/epics/planning-and-brainstorming-ux.md
@@ -4,7 +4,7 @@ project: brain
 spec: planning-and-brainstorming-ux
 title: Planning And Brainstorming UX
 type: epic
-updated: "2026-04-11T21:53:09Z"
+updated: "2026-04-13T06:23:51Z"
 ---
 # Planning And Brainstorming UX
 
@@ -12,10 +12,18 @@ Created: 2026-04-11T05:10:54Z
 
 ## Description
 
+Close the gap between useful work happening in sessions and the durable project memory Brain relies on. Add optional distillation and reasoning capture without abandoning explicit, reviewed markdown as the source of truth.
+
 ## Work Items
 
+- [[.brain/planning/stories/planning-and-brainstorming-ux-current-state-and-next-actions.md]]
+- [[.brain/planning/stories/add-session-aware-memory-distillation.md]]
+- [[.brain/planning/stories/capture-decision-rationale-as-first-class-notes.md]]
+
 ## Notes
 
+This epic is about memory capture quality, not transcript storage. The approval loop stays intact.
+
 ## Spec
 
 - [[.brain/planning/specs/planning-and-brainstorming-ux.md]]
diff --git a/.brain/planning/epics/retrieval-and-index-lifecycle.md b/.brain/planning/epics/retrieval-and-index-lifecycle.md
index c9add1c..c65f206 100644
--- a/.brain/planning/epics/retrieval-and-index-lifecycle.md
+++ b/.brain/planning/epics/retrieval-and-index-lifecycle.md
@@ -4,7 +4,7 @@ project: brain
 spec: retrieval-and-index-lifecycle
 title: Retrieval And Index Lifecycle
 type: epic
-updated: "2026-04-11T21:53:09Z"
+updated: "2026-04-13T06:23:51Z"
 ---
 # Retrieval And Index Lifecycle
 
@@ -12,10 +12,18 @@ Created: 2026-04-11T05:10:54Z
 
 ## Description
 
+Improve retrieval so Brain ranks and packages context around the work that matters now. Focus on better ranking signals and an agent-ready search handoff while keeping the local markdown-first index model intact.
+
 ## Work Items
 
+- [[.brain/planning/stories/retrieval-and-index-lifecycle-current-state-and-next-actions.md]]
+- [[.brain/planning/stories/improve-retrieval-ranking-with-recency-and-active-context.md]]
+- [[.brain/planning/stories/turn-search-results-into-agent-ready-context-blocks.md]]
+
 ## Notes
 
+The point is to improve retrieval quality and usability, not to add a more magical storage model.
+
 ## Spec
 
 - [[.brain/planning/specs/retrieval-and-index-lifecycle.md]]
diff --git a/.brain/planning/specs/context-and-session-workflow.md b/.brain/planning/specs/context-and-session-workflow.md
index ab95a34..e13398a 100644
--- a/.brain/planning/specs/context-and-session-workflow.md
+++ b/.brain/planning/specs/context-and-session-workflow.md
@@ -2,10 +2,10 @@
 created: "2026-04-11T21:53:09Z"
 epic: context-and-session-workflow
 project: brain
-status: draft
+status: approved
 title: Context And Session Workflow Spec
 type: spec
-updated: "2026-04-11T21:53:09Z"
+updated: "2026-04-13T06:23:52Z"
 ---
 # Context And Session Workflow Spec
 
@@ -13,24 +13,74 @@ Created: 2026-04-11T21:53:09Z
 
 ## Why
 
+Context and session enforcement should help an agent stay focused and leave the repo in a better state. Right now the repo contract is strong, but context loading is heavier than it needs to be and session closeout is stricter than it is helpful when memory updates are missing.
+
 ## Problem
 
+Brain's current context model is effectively all-or-nothing: agents either read a broad set of files or risk missing something important. Session finish can also detect missing durable memory work without giving the user a first-class recovery path. The result is friction where Brain should be guiding the next step.
+
 ## Goals
 
+- Introduce layered context loading so agents can start from a minimal contract and pull deeper context on demand.
+- Make session closeout point users toward the right recovery action when durable memory updates are missing.
+- Keep enforcement explicit and deterministic while reducing avoidable workflow friction.
+
 ## Non-Goals
 
+- Background automatic context loading with opaque heuristics.
+- Silent memory writes at session finish.
+- A durable long-term store for temporary scratch memory.
+
 ## Requirements
 
+- Add a context-loading interface that supports at least four levels: always-on identity/current-state, lightweight summaries, full context files, and deep search-driven context.
+- Make the active context tiering obvious enough that agents can request more depth intentionally.
+- When session finish sees meaningful repo change without memory updates, suggest `brain distill --session` or equivalent as the first recovery path.
+- Reuse the same distillation primitives as the planning-memory workflow instead of inventing a separate closeout-only mechanism.
+- Treat any session memory cache as optional, temporary, and explicitly non-durable until distilled.
+
 ## UX / Flows
 
+Layered context flow:
+1. Agent loads minimal startup context.
+2. Agent requests the next level only when the task needs more detail.
+3. Brain makes the transition from static context to search-driven deep context explicit.
+
+Session closeout recovery flow:
+1. User runs `brain session finish`.
+2. Brain detects repo changes without acceptable memory updates.
+3. Brain suggests a session-scoped distill flow instead of only returning a hard stop.
+4. User reviews the proposed memory updates, accepts what matters, and retries closeout.
+
 ## Data / Interfaces
 
+- Define context tiers in Brain-managed docs or config in a way that remains deterministic.
+- Thread active session information into distill so closeout can scope the candidate updates.
+- Keep any temporary session cache out of the accepted durable-memory globs unless explicitly promoted.
+
 ## Risks / Open Questions
 
+- How much of layered context belongs in generated docs versus command output?
+- Should session closeout suggest distill unconditionally, or only when certain note classes are missing?
+- Does a temporary session cache help enough to justify another concept in the workflow?
+
 ## Rollout
 
+1. Add layered context-loading primitives and documentation.
+2. Add session closeout suggestions that reuse distill once manual distill exists.
+3. Evaluate whether a temporary session cache is needed after those two steps land.
+
 ## Story Breakdown
 
+- [ ] Add Layered Context Loading Levels
+- [ ] Suggest Distillation During Session Closeout
+
 ## Resources
 
+- [[.brain/brainstorms/mempalace-inspired-brain-improvements.md]]
+- [[.brain/planning/stories/context-and-session-workflow-current-state-and-next-actions.md]]
+- [[.brain/resources/references/agent-workflow.md]]
+
 ## Notes
+
+The optional session-memory-cache idea stays out of the initial execution set until the lower-friction closeout path is proven useful.
diff --git a/.brain/planning/specs/planning-and-brainstorming-ux.md b/.brain/planning/specs/planning-and-brainstorming-ux.md
index b88af53..7bd777d 100644
--- a/.brain/planning/specs/planning-and-brainstorming-ux.md
+++ b/.brain/planning/specs/planning-and-brainstorming-ux.md
@@ -2,10 +2,10 @@
 created: "2026-04-11T21:53:09Z"
 epic: planning-and-brainstorming-ux
 project: brain
-status: draft
+status: approved
 title: Planning And Brainstorming UX Spec
 type: spec
-updated: "2026-04-11T21:53:09Z"
+updated: "2026-04-13T06:23:52Z"
 ---
 # Planning And Brainstorming UX Spec
 
@@ -13,24 +13,74 @@ Created: 2026-04-11T21:53:09Z
 
 ## Why
 
+Brain is strongest when durable project memory stays explicit, local, and reviewable. The main weakness in that model is that valuable reasoning often never becomes durable memory at all. This planning pass focuses on closing that gap without sliding into transcript hoarding.
+
 ## Problem
 
+Today Brain depends on explicit `brain edit` discipline and manual note updates. That preserves correctness, but it also means decisions, tradeoffs, bugs, and discoveries from active sessions can disappear unless someone remembers to capture them. The planning and brainstorming flow does not yet provide a first-class bridge from session work to curated project memory.
+
 ## Goals
 
+- Add an optional memory distillation workflow that turns session activity into proposed durable-note updates.
+- Preserve decision rationale as a first-class artifact instead of only capturing final outcomes.
+- Keep Brain's explicit approval model intact so distillation never becomes silent background storage.
+- Make the new memory-capture path feel native to the existing brainstorm -> epic -> spec -> story workflow.
+
 ## Non-Goals
 
+- Storing full conversations or command transcripts as durable memory by default.
+- Auto-writing AGENTS, context, or resource notes without review.
+- Replacing existing explicit note-edit workflows for users who prefer manual capture.
+
 ## Requirements
 
+- Add a `brain distill` workflow that can inspect recent session history, command runs, and git diff.
+- Distillation must output candidate updates for Brain-managed targets such as `AGENTS.md`, `.brain/context/*`, `.brain/resources/changes/*`, and decision notes.
+- Introduce a first-class decision note shape under `.brain/resources/decisions/` with enough structure to preserve context, options, decision, and tradeoffs.
+- Keep approval in the loop so users or agents can accept, reject, or edit generated updates before they become durable memory.
+- Record enough provenance that a later reader can tell which session or source material drove the distilled update.
+
 ## UX / Flows
 
+Manual distillation flow:
+1. User or agent runs `brain distill`.
+2. Brain gathers recent session history, command runs, and git diff context.
+3. Brain proposes note updates grouped by destination and reason.
+4. User or agent reviews, edits, and accepts the proposed updates.
+
+Decision-note flow:
+1. User or distill flow creates a decision note.
+2. The note captures context, options considered, final choice, and tradeoffs.
+3. The note is linked from specs, stories, or change notes where relevant.
+
 ## Data / Interfaces
 
+- Add a decision-note template and note-type conventions under `.brain/resources/decisions/`.
+- Define a distillation payload shape that can represent proposed file targets, generated body changes, and source provenance.
+- Keep generated output text-first and markdown-native so it fits the rest of Brain's note model.
+
 ## Risks / Open Questions
 
+- How much source material should distill inspect by default before the output becomes noisy?
+- Should approval happen inline in the terminal, through note creation, or via staged patch-like files?
+- How deterministic does the distilled proposal need to be for tests and history expectations?
+
 ## Rollout
 
+1. Add note templates and data structures for decision notes and distillation proposals.
+2. Ship a manual `brain distill` path first.
+3. Reuse the same primitives from session closeout once the manual workflow feels stable.
+
 ## Story Breakdown
 
+- [ ] Add Session-Aware Memory Distillation
+- [ ] Capture Decision Rationale As First-Class Notes
+
 ## Resources
 
+- [[.brain/brainstorms/mempalace-inspired-brain-improvements.md]]
+- [[.brain/planning/stories/planning-and-brainstorming-ux-current-state-and-next-actions.md]]
+
 ## Notes
+
+The guiding constraint is simple: recover missing insight without turning Brain into a raw transcript archive.
diff --git a/.brain/planning/specs/retrieval-and-index-lifecycle.md b/.brain/planning/specs/retrieval-and-index-lifecycle.md
index 26cb971..b7e7cb9 100644
--- a/.brain/planning/specs/retrieval-and-index-lifecycle.md
+++ b/.brain/planning/specs/retrieval-and-index-lifecycle.md
@@ -2,10 +2,10 @@
 created: "2026-04-11T21:53:09Z"
 epic: retrieval-and-index-lifecycle
 project: brain
-status: draft
+status: approved
 title: Retrieval And Index Lifecycle Spec
 type: spec
-updated: "2026-04-11T21:53:09Z"
+updated: "2026-04-13T06:23:52Z"
 ---
 # Retrieval And Index Lifecycle Spec
 
@@ -13,24 +13,73 @@ Created: 2026-04-11T21:53:09Z
 
 ## Why
 
+Brain's retrieval layer is already useful, but the next gain is not more storage. It is better ranking and better handoff into agent work. Search should answer what matters right now and make the answer easier to use.
+
 ## Problem
 
+Current hybrid search is query-matching oriented. It does not yet strongly account for recency, note importance, or the active work context from the current session, epic, or spec. Search results also stop at retrieval, forcing the agent to manually convert ranked matches into a usable context block.
+
 ## Goals
 
+- Improve ranking quality with recency, note-type weighting, and active-work-context signals.
+- Add a search-to-context bridge that returns agent-ready injected context, not just ranked hits.
+- Keep retrieval project-local and markdown-backed while improving the quality of what is returned.
+
 ## Non-Goals
 
+- Turning Brain into a hosted semantic retrieval system.
+- Replacing explicit note structure with opaque embedding-only ranking.
+- Introducing filesystem-like room or wing abstractions on top of the repo.
+
 ## Requirements
 
+- Add recency-sensitive ranking so recently updated notes can receive a measured boost.
+- Weight note types so durable decisions, specs, and change notes can outrank brainstorm noise when relevance is otherwise close.
+- Use active session context, current epic or spec, or nearby planning metadata to bias results toward the work in front of the agent.
+- Add `brain search --inject` or equivalent output that includes both ranked results and a preformatted relevant-context block.
+- Keep ranking explainability good enough that `brain search --explain` can still make the score story understandable.
+
 ## UX / Flows
 
+Search with injection:
+1. Agent runs `brain search --inject "query"`.
+2. Brain ranks results with lexical, semantic, recency, type, and active-context signals.
+3. Output includes both the normal ranked matches and a compact `Relevant Context` block ready to reuse.
+
+Search during active work:
+1. User starts or validates a session.
+2. Brain knows the active project task and nearby planning notes.
+3. Retrieval quietly boosts the notes tied to the active work while keeping the result explainable.
+
 ## Data / Interfaces
 
+- Extend ranking inputs to include note timestamps, note types, and active planning context.
+- Define an injected-context output format that stays markdown-native and easy to paste into agent prompts.
+- Preserve explain output so retrieval tuning remains debuggable.
+
 ## Risks / Open Questions
 
+- How aggressive should recency and type weighting be before search starts hiding older but critical notes?
+- Which active-context signals are reliable enough to boost by default?
+- Should injected context be a new flag, a new format mode, or part of broader context loading?
+
 ## Rollout
 
+1. Add ranking features behind explainable scoring changes.
+2. Land injected-context output once the ranking results are trustworthy.
+3. Tune weights against real project notes and session flows.
+
 ## Story Breakdown
 
+- [ ] Improve Retrieval Ranking With Recency And Active Context
+- [ ] Turn Search Results Into Agent-Ready Context Blocks
+
 ## Resources
 
+- [[.brain/brainstorms/mempalace-inspired-brain-improvements.md]]
+- [[.brain/resources/references/retrieval-and-indexing.md]]
+- [[.brain/planning/stories/retrieval-and-index-lifecycle-current-state-and-next-actions.md]]
+
 ## Notes
+
+This spec improves how Brain chooses and packages context. It does not change the core local-first storage model.
diff --git a/.brain/planning/stories/add-layered-context-loading-levels.md b/.brain/planning/stories/add-layered-context-loading-levels.md
new file mode 100644
index 0000000..365072b
--- /dev/null
+++ b/.brain/planning/stories/add-layered-context-loading-levels.md
@@ -0,0 +1,36 @@
+---
+created: "2026-04-13T06:23:52Z"
+epic: context-and-session-workflow
+project: brain
+spec: context-and-session-workflow
+status: done
+title: Add Layered Context Loading Levels
+type: story
+updated: "2026-04-13T07:36:47Z"
+---
+# Add Layered Context Loading Levels
+
+Created: 2026-04-13T06:23:52Z
+
+## Description
+
+Introduce explicit context tiers so agents can load minimal startup context first and request progressively deeper repo context only when needed.
+
+
+## Acceptance Criteria
+
+- [ ] Brain exposes at least four context levels from core identity through deep search-driven context
+- [ ] Agents can intentionally request the next context level instead of always reading everything
+- [ ] Context-tier behavior is documented and deterministic
+
+
+
+
+## Resources
+
+- [[.brain/planning/specs/context-and-session-workflow.md]]
+- [[.brain/brainstorms/mempalace-inspired-brain-improvements.md]]
+
+
+
+## Notes
diff --git a/.brain/planning/stories/add-session-aware-memory-distillation.md b/.brain/planning/stories/add-session-aware-memory-distillation.md
new file mode 100644
index 0000000..fb8ef33
--- /dev/null
+++ b/.brain/planning/stories/add-session-aware-memory-distillation.md
@@ -0,0 +1,30 @@
+---
+created: "2026-04-13T06:23:52Z"
+epic: planning-and-brainstorming-ux
+project: brain
+spec: planning-and-brainstorming-ux
+status: done
+title: Add Session-Aware Memory Distillation
+type: story
+updated: "2026-04-13T07:30:14Z"
+---
+# Add Session-Aware Memory Distillation
+
+Created: 2026-04-13T06:23:52Z
+
+## Description
+
+Add a first-class `brain distill` workflow that inspects recent session history, command runs, and git diff, then proposes durable note updates without silently writing them.
+
+## Acceptance Criteria
+
+- [ ] Manual distill can scope to the active session and gather recent command, diff, and note context
+- [ ] Distill output proposes updates for Brain-managed note targets instead of auto-applying them
+- [ ] Users or agents can review and edit candidate updates before accepting them
+
+## Resources
+
+- [[.brain/planning/specs/planning-and-brainstorming-ux.md]]
+- [[.brain/brainstorms/mempalace-inspired-brain-improvements.md]]
+
+## Notes
diff --git a/.brain/planning/stories/capture-decision-rationale-as-first-class-notes.md b/.brain/planning/stories/capture-decision-rationale-as-first-class-notes.md
new file mode 100644
index 0000000..8104744
--- /dev/null
+++ b/.brain/planning/stories/capture-decision-rationale-as-first-class-notes.md
@@ -0,0 +1,36 @@
+---
+created: "2026-04-13T06:23:52Z"
+epic: planning-and-brainstorming-ux
+project: brain
+spec: planning-and-brainstorming-ux
+status: done
+title: Capture Decision Rationale As First-Class Notes
+type: story
+updated: "2026-04-13T07:12:12Z"
+---
+# Capture Decision Rationale As First-Class Notes
+
+Created: 2026-04-13T06:23:52Z
+
+## Description
+
+Add a decision-note template and note conventions so Brain can preserve why a choice was made, what options were considered, and which tradeoffs were accepted.
+
+
+## Acceptance Criteria
+
+- [ ] Decision notes live in a dedicated durable-memory location with a stable template
+- [ ] Decision notes capture context, options, decision, and tradeoffs
+- [ ] Specs, stories, or distill output can link to decision notes
+
+
+
+
+## Resources
+
+- [[.brain/planning/specs/planning-and-brainstorming-ux.md]]
+- [[.brain/brainstorms/mempalace-inspired-brain-improvements.md]]
+
+
+
+## Notes
diff --git a/.brain/planning/stories/improve-retrieval-ranking-with-recency-and-active-context.md b/.brain/planning/stories/improve-retrieval-ranking-with-recency-and-active-context.md
new file mode 100644
index 0000000..2a83be6
--- /dev/null
+++ b/.brain/planning/stories/improve-retrieval-ranking-with-recency-and-active-context.md
@@ -0,0 +1,36 @@
+---
+created: "2026-04-13T06:23:52Z"
+epic: retrieval-and-index-lifecycle
+project: brain
+spec: retrieval-and-index-lifecycle
+status: done
+title: Improve Retrieval Ranking With Recency And Active Context
+type: story
+updated: "2026-04-13T07:17:02Z"
+---
+# Improve Retrieval Ranking With Recency And Active Context
+
+Created: 2026-04-13T06:23:52Z
+
+## Description
+
+Tune retrieval ranking so recent notes, more durable note types, and the active work context influence what appears first without making the score story opaque.
+
+
+## Acceptance Criteria
+
+- [ ] Ranking includes a measured recency boost
+- [ ] Ranking can weight note types such as specs, decisions, and change notes above lower-signal notes when relevance is close
+- [ ] Active session or planning context can bias results toward the work in front of the agent
+
+
+
+
+## Resources
+
+- [[.brain/planning/specs/retrieval-and-index-lifecycle.md]]
+- [[.brain/brainstorms/mempalace-inspired-brain-improvements.md]]
+
+
+
+## Notes
diff --git a/.brain/planning/stories/suggest-distillation-during-session-closeout.md b/.brain/planning/stories/suggest-distillation-during-session-closeout.md
new file mode 100644
index 0000000..44c36bf
--- /dev/null
+++ b/.brain/planning/stories/suggest-distillation-during-session-closeout.md
@@ -0,0 +1,36 @@
+---
+created: "2026-04-13T06:23:52Z"
+epic: context-and-session-workflow
+project: brain
+spec: context-and-session-workflow
+status: done
+title: Suggest Distillation During Session Closeout
+type: story
+updated: "2026-04-13T07:38:30Z"
+---
+# Suggest Distillation During Session Closeout
+
+Created: 2026-04-13T06:23:52Z
+
+## Description
+
+When session finish detects repo change without acceptable memory updates, guide the user into a session-scoped distill flow instead of only blocking them.
+
+
+## Acceptance Criteria
+
+- [ ] Session finish detects the missing-memory case and suggests a distill recovery path
+- [ ] The recovery path scopes candidate updates to the active session
+- [ ] Closeout can succeed after reviewed memory updates are accepted
+
+
+
+
+## Resources
+
+- [[.brain/planning/specs/context-and-session-workflow.md]]
+- [[.brain/brainstorms/mempalace-inspired-brain-improvements.md]]
+
+
+
+## Notes
diff --git a/.brain/planning/stories/turn-search-results-into-agent-ready-context-blocks.md b/.brain/planning/stories/turn-search-results-into-agent-ready-context-blocks.md
new file mode 100644
index 0000000..66cdc61
--- /dev/null
+++ b/.brain/planning/stories/turn-search-results-into-agent-ready-context-blocks.md
@@ -0,0 +1,36 @@
+---
+created: "2026-04-13T06:23:52Z"
+epic: retrieval-and-index-lifecycle
+project: brain
+spec: retrieval-and-index-lifecycle
+status: done
+title: Turn Search Results Into Agent-Ready Context Blocks
+type: story
+updated: "2026-04-13T07:20:03Z"
+---
+# Turn Search Results Into Agent-Ready Context Blocks
+
+Created: 2026-04-13T06:23:52Z
+
+## Description
+
+Extend search output with an inject mode that returns ranked results plus a compact markdown context block the agent can reuse immediately.
+
+
+## Acceptance Criteria
+
+- [ ] Search can emit a preformatted relevant-context block
+- [ ] Injected context cites the source notes it was built from
+- [ ] Injected output stays markdown-native and compact enough for prompt reuse
+
+
+
+
+## Resources
+
+- [[.brain/planning/specs/retrieval-and-index-lifecycle.md]]
+- [[.brain/brainstorms/mempalace-inspired-brain-improvements.md]]
+
+
+
+## Notes
diff --git a/.brain/resources/references/maintainer-global-refresh.md b/.brain/resources/references/maintainer-global-refresh.md
index 684586e..b0c69e2 100644
--- a/.brain/resources/references/maintainer-global-refresh.md
+++ b/.brain/resources/references/maintainer-global-refresh.md
@@ -18,6 +18,8 @@ Default maintainer flow: work on a feature branch, open a PR, merge to `main`, w
 4. Run required verification through `brain session run -- <command>`.
 5. Commit the branch changes.
 6. Open a PR into `main`.
+   - Write the PR title and body in release-note language because GitHub release notes are generated from merged PR metadata.
+   - Summarize shipped behavior in human-readable bullets, not just implementation steps or internal refactors.
 7. Review and merge the PR.
 8. Wait for the automatic stable release workflow to tag and publish the new version from that merge commit on `main`.
 9. Refresh the installed binary and global Codex skill:
@@ -44,4 +46,5 @@ Windows PowerShell:
 - This flow refreshes only the global Codex `brain` skill.
 - It does not commit, push, or edit repo-tracked files.
 - Treat direct pushes to `main` as the exception, not the default. PR merge is the normal release boundary.
+- Treat release-note-friendly PR copy as part of the definition of done for every PR.
 - Do not create a follow-up repo-memory commit just because you refreshed the global binary or skill. Otherwise the installed binary immediately lags `HEAD` again.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..700c458
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,17 @@
+## Summary
+- describe the user-facing change in release-note language
+- keep this focused on shipped behavior, not implementation mechanics
+
+## Release Notes
+- list the 1-5 highest-signal user-visible changes
+- write these as human-readable bullets that can survive into GitHub-generated release notes
+- if the PR is mainly a fix, say what was broken and what is now correct
+
+## Verification
+- go test ./...
+- go build ./...
+
+## Maintainer Notes
+- if this PR changes Brain commands or agent-facing workflow guidance, update `skills/brain/SKILL.md`
+- if `skills/brain/` changed, reinstall the local Brain skill for Codex and OpenClaw before closeout:
+  - `brain skills install --scope local --agent codex --agent openclaw --project .`
diff --git a/.gitignore b/.gitignore
index 31f39a5..2a38499 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,4 +7,6 @@
 .brain/sessions/
 .brain/policy.override.yaml
 .brain/state/
+.codex/skills/
+.openclaw/skills/
 # brain:end gitignore-session
diff --git a/cmd/brainstorm.go b/cmd/brainstorm.go
index 9c5e170..1cfe772 100644
--- a/cmd/brainstorm.go
+++ b/cmd/brainstorm.go
@@ -114,7 +114,7 @@ func addBrainstormCommand(root *cobra.Command, flags *rootFlagsState, loadApp ap
 	var distillLimit int
 	distillCmd := &cobra.Command{
 		Use:   "distill <path>",
-		Short: "Create a distillation note from a brainstorm",
+		Short: "Create a distillation proposal from a brainstorm",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			appCtx, err := loadApp()
@@ -125,12 +125,12 @@ func addBrainstormCommand(root *cobra.Command, flags *rootFlagsState, loadApp ap
 			if err := appCtx.SyncIndex(cmd.Context()); err != nil {
 				return err
 			}
-			note, err := appCtx.Brainstorm.Distill(cmd.Context(), args[0], distillLimit)
+			note, err := appCtx.Distill.FromBrainstorm(cmd.Context(), args[0], distillLimit)
 			if err != nil {
 				return err
 			}
 			return appCtx.Output.Print(note, func(w io.Writer) error {
-				_, err := fmt.Fprintf(w, "Created distillation %s\n", note.Path)
+				_, err := fmt.Fprintf(w, "Created distill proposal %s\n", note.Path)
 				return err
 			})
 		},
diff --git a/cmd/cli_test.go b/cmd/cli_test.go
index 2009757..5ca608d 100644
--- a/cmd/cli_test.go
+++ b/cmd/cli_test.go
@@ -3,6 +3,7 @@ package cmd
 import (
 	"bytes"
 	"context"
+	"encoding/json"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -92,9 +93,15 @@ func (e *cliEnv) run(t *testing.T, stdin string, args ...string) cliResult {
 }
 
 func normalizeCLIOutput(s, root string) string {
+	s = strings.ReplaceAll(s, "\r\n", "\n")
 	s = strings.ReplaceAll(s, root, "<ROOT>")
+	s = strings.ReplaceAll(s, filepath.ToSlash(root), "<ROOT>")
 	s = rfc3339Pattern.ReplaceAllString(s, "<TIME>")
-	return filepath.ToSlash(s)
+	return s
+}
+
+func cliPath(parts ...string) string {
+	return filepath.Join(parts...)
 }
 
 func requireOK(t *testing.T, result cliResult) string {
@@ -233,7 +240,7 @@ func TestCLISearchStatusAndExplain(t *testing.T) {
 
 	requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "edit", "docs/project-overview.md", "-b", "# Project Overview\n\nRetrieval status should become observable."))
 	searchOutput := requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "search", "--explain", "retrieval observable"))
-	if !strings.Contains(searchOutput, "[") || !strings.Contains(searchOutput, "lex=") || !strings.Contains(searchOutput, "sem=") {
+	if !strings.Contains(searchOutput, "[") || !strings.Contains(searchOutput, "lex=") || !strings.Contains(searchOutput, "sem=") || !strings.Contains(searchOutput, "rec=") || !strings.Contains(searchOutput, "type=") || !strings.Contains(searchOutput, "ctx=") {
 		t.Fatalf("expected explain output:\n%s", searchOutput)
 	}
 
@@ -249,6 +256,100 @@ func TestCLISearchStatusAndExplain(t *testing.T) {
 	}
 }
 
+func TestCLISearchInjectIncludesContextBlockInHumanAndJSONModes(t *testing.T) {
+	env := newCLIEnv(t)
+	requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "init"))
+	requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "edit", "docs/project-overview.md", "-b", "# Project Overview\n\nInjectable context should cite the project overview note."))
+
+	human := requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "search", "--inject", "injectable context"))
+	if !strings.Contains(human, "## Relevant Context") || !strings.Contains(human, "docs/project-overview.md") {
+		t.Fatalf("expected injected context in human output:\n%s", human)
+	}
+
+	jsonOut := requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "--json", "search", "--inject", "injectable context"))
+	var payload map[string]any
+	if err := json.Unmarshal([]byte(jsonOut), &payload); err != nil {
+		t.Fatalf("parse json output: %v\n%s", err, jsonOut)
+	}
+	results, ok := payload["results"].([]any)
+	if !ok || len(results) == 0 {
+		t.Fatalf("expected results in json payload: %#v", payload)
+	}
+	contextBlock, ok := payload["context_block"].(string)
+	if !ok || !strings.Contains(contextBlock, "## Relevant Context") || !strings.Contains(contextBlock, "docs/project-overview.md") {
+		t.Fatalf("expected context block in json payload: %#v", payload)
+	}
+}
+
+func TestCLIDistillSessionCreatesProposal(t *testing.T) {
+	env := newCLIEnv(t)
+	requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "init"))
+	initGitProject(t, env.project)
+
+	requireOK(t, env.run(t, "", "--config", env.config, "session", "start", "--project", env.project, "--task", "tighten session distill"))
+	requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "edit", ".brain/context/current-state.md", "-b", "# Current State\n\nSession context was updated.\n"))
+	if err := os.WriteFile(filepath.Join(env.project, "main.go"), []byte("package main\nfunc main() { println(\"changed\") }\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	requireOK(t, env.run(t, "", "--config", env.config, "session", "run", "--project", env.project, "--", "go", "version"))
+
+	agentsBefore, err := os.ReadFile(filepath.Join(env.project, "AGENTS.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	output := requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "distill", "--session"))
+	if !strings.Contains(output, "Created distill proposal .brain/resources/changes/tighten-session-distill-distill-proposal.md") {
+		t.Fatalf("unexpected distill output:\n%s", output)
+	}
+
+	noteRaw, err := os.ReadFile(filepath.Join(env.project, ".brain", "resources", "changes", "tighten-session-distill-distill-proposal.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	note := string(noteRaw)
+	if !strings.Contains(note, "## Source Provenance") || !strings.Contains(note, "go version") || !strings.Contains(note, "main.go") {
+		t.Fatalf("expected session-derived provenance in proposal:\n%s", note)
+	}
+	if !strings.Contains(note, "## Proposed Updates") || !strings.Contains(note, "### AGENTS.md") || !strings.Contains(note, "### .brain/context/current-state.md") {
+		t.Fatalf("expected target sections in proposal:\n%s", note)
+	}
+
+	agentsAfter, err := os.ReadFile(filepath.Join(env.project, "AGENTS.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(agentsBefore) != string(agentsAfter) {
+		t.Fatalf("expected distill not to modify AGENTS.md directly")
+	}
+}
+
+func TestCLIDistillBrainstormModeMatchesLegacyWrapper(t *testing.T) {
+	env := newCLIEnv(t)
+	requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "init"))
+
+	requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "brainstorm", "start", "Auth Ideas"))
+	requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "brainstorm", "idea", ".brain/brainstorms/auth-ideas.md", "-b", "Favor explicit durable memory over transcript storage."))
+
+	topLevel := requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "distill", "--brainstorm", ".brain/brainstorms/auth-ideas.md"))
+	legacy := requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "brainstorm", "distill", ".brain/brainstorms/auth-ideas.md"))
+	if topLevel != legacy {
+		t.Fatalf("expected equivalent command output\nnew:\n%s\nlegacy:\n%s", topLevel, legacy)
+	}
+
+	noteRaw, err := os.ReadFile(filepath.Join(env.project, ".brain", "resources", "changes", "auth-ideas-distill-proposal.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	note := string(noteRaw)
+	if !strings.Contains(note, "Mode: `brainstorm`") || !strings.Contains(note, "[[.brain/brainstorms/auth-ideas.md]]") {
+		t.Fatalf("expected brainstorm provenance in proposal:\n%s", note)
+	}
+	if !strings.Contains(note, "### .brain/resources/decisions/auth-ideas.md") {
+		t.Fatalf("expected proposed decision target in proposal:\n%s", note)
+	}
+}
+
 func TestCLIProjectPlanningWorkflow(t *testing.T) {
 	env := newCLIEnv(t)
 	requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "init"))
@@ -286,22 +387,22 @@ func TestCLIProjectPlanningWorkflow(t *testing.T) {
 func TestCLISkillsCommands(t *testing.T) {
 	env := newCLIEnv(t)
 	targets := requireOK(t, env.run(t, "", "skills", "targets", "--scope", "both", "-a", "codex", "-a", "copilot", "-a", "pi.dev", "-a", "zed", "--project", env.project))
-	if !strings.Contains(targets, "codex [global] brain <ROOT>/home/.codex/skills/brain") {
+	if !strings.Contains(targets, "codex [global] brain "+cliPath("<ROOT>", "home", ".codex", "skills", "brain")) {
 		t.Fatalf("missing global codex target:\n%s", targets)
 	}
-	if !strings.Contains(targets, "copilot [global] brain <ROOT>/home/.copilot/skills/brain") {
+	if !strings.Contains(targets, "copilot [global] brain "+cliPath("<ROOT>", "home", ".copilot", "skills", "brain")) {
 		t.Fatalf("missing global copilot target:\n%s", targets)
 	}
-	if !strings.Contains(targets, "copilot [local] brain <ROOT>/project/.github/skills/brain") {
+	if !strings.Contains(targets, "copilot [local] brain "+cliPath("<ROOT>", "project", ".github", "skills", "brain")) {
 		t.Fatalf("missing local copilot target:\n%s", targets)
 	}
-	if !strings.Contains(targets, "pi [global] brain <ROOT>/home/.pi/agent/skills/brain") {
+	if !strings.Contains(targets, "pi [global] brain "+cliPath("<ROOT>", "home", ".pi", "agent", "skills", "brain")) {
 		t.Fatalf("missing global pi target:\n%s", targets)
 	}
-	if !strings.Contains(targets, "pi [local] brain <ROOT>/project/.pi/skills/brain") {
+	if !strings.Contains(targets, "pi [local] brain "+cliPath("<ROOT>", "project", ".pi", "skills", "brain")) {
 		t.Fatalf("missing local pi target:\n%s", targets)
 	}
-	if !strings.Contains(targets, "zed [local] brain <ROOT>/project/.zed/skills/brain") {
+	if !strings.Contains(targets, "zed [local] brain "+cliPath("<ROOT>", "project", ".zed", "skills", "brain")) {
 		t.Fatalf("missing local zed target:\n%s", targets)
 	}
 	requireOK(t, env.run(t, "", "skills", "install", "--scope", "local", "-a", "codex", "--project", env.project, "--mode", "copy"))
@@ -385,6 +486,55 @@ func TestCLIContextCommands(t *testing.T) {
 	}
 }
 
+func TestCLIContextLoadLevels(t *testing.T) {
+	env := newCLIEnv(t)
+	requireOK(t, env.run(t, "", "--config", env.config, "context", "install", "--project", env.project))
+	requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "edit", "docs/project-overview.md", "-b", "# Project Overview\n\nLayered context helps agents stay fast."))
+
+	level0 := requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "context", "load", "--level", "0"))
+	if !strings.Contains(level0, "## Source: AGENTS.md (summary)") || !strings.Contains(level0, "## Source: .brain/context/current-state.md") {
+		t.Fatalf("unexpected level 0 output:\n%s", level0)
+	}
+	if strings.Contains(level0, ".brain/context/overview.md") {
+		t.Fatalf("expected level 0 to omit overview:\n%s", level0)
+	}
+
+	level2JSON := requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "--json", "context", "load", "--level", "2"))
+	var payload map[string]any
+	if err := json.Unmarshal([]byte(level2JSON), &payload); err != nil {
+		t.Fatalf("parse json output: %v\n%s", err, level2JSON)
+	}
+	if payload["level"].(float64) != 2 {
+		t.Fatalf("expected level 2 payload: %#v", payload)
+	}
+	sources, ok := payload["sources"].([]any)
+	if !ok || len(sources) != 7 {
+		t.Fatalf("expected 7 static sources in level 2 payload: %#v", payload)
+	}
+	content, ok := payload["content"].(string)
+	if !ok || !strings.Contains(content, "## Source: .brain/context/architecture.md") || !strings.Contains(content, "## Source: .brain/context/memory-policy.md") {
+		t.Fatalf("unexpected level 2 content: %#v", payload)
+	}
+}
+
+func TestCLIContextLoadLevelThreeUsesQueryOrActiveSession(t *testing.T) {
+	env := newCLIEnv(t)
+	requireOK(t, env.run(t, "", "--config", env.config, "context", "install", "--project", env.project))
+	requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "edit", "docs/project-overview.md", "-b", "# Project Overview\n\nLayered context query should retrieve this overview."))
+
+	missing := env.run(t, "", "--config", env.config, "--project", env.project, "context", "load", "--level", "3")
+	if missing.err == nil || !strings.Contains(missing.err.Error(), "requires --query or an active session task") {
+		t.Fatalf("expected missing-query error, got err=%v stdout=%s stderr=%s", missing.err, missing.stdout, missing.stderr)
+	}
+
+	initGitProject(t, env.project)
+	requireOK(t, env.run(t, "", "--config", env.config, "session", "start", "--project", env.project, "--task", "layered context query"))
+	level3 := requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "context", "load", "--level", "3"))
+	if !strings.Contains(level3, "## Source: search:layered context query") || !strings.Contains(level3, "## Relevant Context") || !strings.Contains(level3, "docs/project-overview.md") {
+		t.Fatalf("unexpected level 3 output:\n%s", level3)
+	}
+}
+
 func TestCLISessionWorkflow(t *testing.T) {
 	env := newCLIEnv(t)
 	requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "init"))
@@ -399,11 +549,12 @@ func TestCLISessionWorkflow(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	validateBlocked := env.run(t, "", "--config", env.config, "session", "validate", "--project", env.project, "--stage", "finish")
-	if validateBlocked.err == nil || !strings.Contains(validateBlocked.stdout, "durable note update required for repo changes") {
-		t.Fatalf("expected finish validation to block before note update:\nstdout=%s\nstderr=%s", validateBlocked.stdout, validateBlocked.stderr)
+	finishBlocked := env.run(t, "", "--config", env.config, "session", "finish", "--project", env.project, "--summary", "premature closeout")
+	if finishBlocked.err == nil || !strings.Contains(finishBlocked.stdout, "durable note update required for repo changes") || !strings.Contains(finishBlocked.stdout, "brain distill --session") {
+		t.Fatalf("expected finish to block and suggest distill:\nstdout=%s\nstderr=%s", finishBlocked.stdout, finishBlocked.stderr)
 	}
 
+	requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "distill", "--session"))
 	requireOK(t, env.run(t, "", "--config", env.config, "--project", env.project, "edit", "AGENTS.md", "-b", "# Project Agent Contract\n\nRecorded durable note for project changes.\n"))
 	requireOK(t, env.run(t, "", "--config", env.config, "session", "run", "--project", env.project, "--", "go", "test", "./..."))
 	requireOK(t, env.run(t, "", "--config", env.config, "session", "run", "--project", env.project, "--", "go", "build", "./..."))
diff --git a/cmd/context.go b/cmd/context.go
index 66e3172..23e142b 100644
--- a/cmd/context.go
+++ b/cmd/context.go
@@ -1,11 +1,13 @@
 package cmd
 
 import (
+	"errors"
 	"fmt"
 	"io"
 	"strings"
 
 	"brain/internal/projectcontext"
+	"brain/internal/search"
 
 	"github.com/spf13/cobra"
 )
@@ -15,6 +17,8 @@ func addContextCommand(root *cobra.Command, flags *rootFlagsState, loadApp appLo
 	var agents []string
 	var dryRun bool
 	var force bool
+	var level int
+	var query string
 
 	contextCmd := &cobra.Command{
 		Use:   "context",
@@ -31,8 +35,9 @@ This creates a minimal root AGENTS/CLAUDE contract plus a modular
 		Use:   "install",
 		Short: "Create or update the project context bundle",
 		RunE: func(cmd *cobra.Command, args []string) error {
+			projectRoot := contextProjectPath(project, flags.projectPath)
 			return runContextCommand(cmd, loadApp, projectcontext.Request{
-				ProjectDir: project,
+				ProjectDir: projectRoot,
 				Agents:     agents,
 				DryRun:     dryRun,
 				Force:      force,
@@ -44,8 +49,9 @@ This creates a minimal root AGENTS/CLAUDE contract plus a modular
 		Use:   "refresh",
 		Short: "Refresh brain-managed project context files",
 		RunE: func(cmd *cobra.Command, args []string) error {
+			projectRoot := contextProjectPath(project, flags.projectPath)
 			return runContextCommand(cmd, loadApp, projectcontext.Request{
-				ProjectDir: project,
+				ProjectDir: projectRoot,
 				Agents:     agents,
 				DryRun:     dryRun,
 				Force:      force,
@@ -53,14 +59,67 @@ This creates a minimal root AGENTS/CLAUDE contract plus a modular
 		},
 	}
 
+	loadCmd := &cobra.Command{
+		Use:   "load",
+		Short: "Load a deterministic context bundle by level",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			projectRoot := contextProjectPath(project, flags.projectPath)
+			appCtx, err := loadApp(projectRoot)
+			if err != nil {
+				return err
+			}
+			defer appCtx.Close()
+
+			bundle, err := appCtx.Context.Load(projectcontext.LoadRequest{
+				ProjectDir: projectRoot,
+				Level:      level,
+			})
+			if err != nil {
+				return err
+			}
+
+			if level == 3 {
+				activeTask := ""
+				active, err := appCtx.Session.Active(projectRoot)
+				if err == nil && active != nil {
+					activeTask = active.Task
+				}
+				resolvedQuery := strings.TrimSpace(query)
+				if resolvedQuery == "" {
+					resolvedQuery = strings.TrimSpace(activeTask)
+				}
+				if resolvedQuery == "" {
+					return errors.New("context load --level 3 requires --query or an active session task")
+				}
+				if err := appCtx.SyncIndex(cmd.Context()); err != nil {
+					return err
+				}
+				results, err := appCtx.Search.SearchWithOptions(cmd.Context(), resolvedQuery, 5, search.Options{ActiveTask: activeTask})
+				if err != nil {
+					return err
+				}
+				bundle.Sources = append(bundle.Sources, fmt.Sprintf("search:%s", resolvedQuery))
+				bundle.Content = strings.TrimRight(bundle.Content, "\n") + "\n\n## Source: search:" + resolvedQuery + "\n\n" + strings.TrimSpace(search.BuildContextBlock(results)) + "\n"
+			}
+
+			return appCtx.Output.Print(bundle, func(w io.Writer) error {
+				_, err := io.WriteString(w, bundle.Content)
+				return err
+			})
+		},
+	}
+
 	for _, sub := range []*cobra.Command{installCmd, refreshCmd} {
-		sub.Flags().StringVar(&project, "project", ".", "project root to scan and update")
+		sub.Flags().StringVar(&project, "project", "", "project root to scan and update")
 		sub.Flags().StringArrayVarP(&agents, "agent", "a", nil, "agent wrapper to generate; repeatable")
 		sub.Flags().BoolVar(&dryRun, "dry-run", false, "show planned changes without writing files")
 		sub.Flags().BoolVar(&force, "force", false, "adopt unmanaged files by preserving existing content under Local Notes")
 	}
+	loadCmd.Flags().StringVar(&project, "project", "", "project root to load context from")
+	loadCmd.Flags().IntVar(&level, "level", 0, "context depth to load: 0, 1, 2, or 3")
+	loadCmd.Flags().StringVar(&query, "query", "", "search query for level 3 context")
 
-	contextCmd.AddCommand(installCmd, refreshCmd)
+	contextCmd.AddCommand(installCmd, refreshCmd, loadCmd)
 	root.AddCommand(contextCmd)
 }
 
@@ -93,3 +152,10 @@ func runContextCommand(cmd *cobra.Command, loadApp appLoader, req projectcontext
 		return nil
 	})
 }
+
+func contextProjectPath(localProject, rootProject string) string {
+	if strings.TrimSpace(localProject) != "" {
+		return localProject
+	}
+	return rootProject
+}
diff --git a/cmd/distill.go b/cmd/distill.go
new file mode 100644
index 0000000..608a81c
--- /dev/null
+++ b/cmd/distill.go
@@ -0,0 +1,57 @@
+package cmd
+
+import (
+	"errors"
+	"fmt"
+	"io"
+
+	"brain/internal/notes"
+
+	"github.com/spf13/cobra"
+)
+
+func addDistillCommand(root *cobra.Command, flags *rootFlagsState, loadApp appLoader) {
+	var sessionScope bool
+	var brainstormPath string
+	var limit int
+
+	distillCmd := &cobra.Command{
+		Use:   "distill",
+		Short: "Create a reviewed distillation proposal from a session or brainstorm",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if sessionScope == (brainstormPath != "") {
+				return errors.New("choose exactly one distill scope: --session or --brainstorm <path>")
+			}
+
+			appCtx, err := loadApp()
+			if err != nil {
+				return err
+			}
+			defer appCtx.Close()
+
+			var note *notes.Note
+			if sessionScope {
+				note, err = appCtx.Distill.FromSession(cmd.Context(), limit)
+			} else {
+				if err := appCtx.SyncIndex(cmd.Context()); err != nil {
+					return err
+				}
+				note, err = appCtx.Distill.FromBrainstorm(cmd.Context(), brainstormPath, limit)
+			}
+			if err != nil {
+				return err
+			}
+
+			return appCtx.Output.Print(note, func(w io.Writer) error {
+				_, err := fmt.Fprintf(w, "Created distill proposal %s\n", note.Path)
+				return err
+			})
+		},
+	}
+
+	distillCmd.Flags().BoolVar(&sessionScope, "session", false, "distill from the active session")
+	distillCmd.Flags().StringVar(&brainstormPath, "brainstorm", "", "distill from a brainstorm note path")
+	distillCmd.Flags().IntVarP(&limit, "limit", "n", 6, "maximum related notes or recent history entries")
+
+	root.AddCommand(distillCmd)
+}
diff --git a/cmd/root.go b/cmd/root.go
index 79e956f..0bf7458 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -25,7 +25,7 @@ type rootFlagsState struct {
 	jsonOutput  bool
 }
 
-type appLoader func() (*app.App, error)
+type appLoader func(projectPath ...string) (*app.App, error)
 
 var rootCmd = newRootCommand(rootOptions{})
 
@@ -66,8 +66,12 @@ func newRootCommand(opts rootOptions) *cobra.Command {
 	cmd.PersistentFlags().StringVar(&flags.projectPath, "project", ".", "project root path")
 	cmd.PersistentFlags().BoolVar(&flags.jsonOutput, "json", false, "render output as JSON")
 
-	loadApp := func() (*app.App, error) {
-		return opts.appLoad(flags.configPath, flags.projectPath, flags.jsonOutput, cmd.OutOrStdout(), cmd.ErrOrStderr())
+	loadApp := func(projectPath ...string) (*app.App, error) {
+		resolvedProject := flags.projectPath
+		if len(projectPath) != 0 && strings.TrimSpace(projectPath[0]) != "" {
+			resolvedProject = projectPath[0]
+		}
+		return opts.appLoad(flags.configPath, resolvedProject, flags.jsonOutput, cmd.OutOrStdout(), cmd.ErrOrStderr())
 	}
 
 	addCommands(cmd, flags, loadApp)
@@ -84,6 +88,7 @@ func addCommands(root *cobra.Command, flags *rootFlagsState, loadApp appLoader)
 	addEditCommand(root, flags, loadApp)
 	addFindCommand(root, flags, loadApp)
 	addSearchCommand(root, flags, loadApp)
+	addDistillCommand(root, flags, loadApp)
 	addBrainstormCommand(root, flags, loadApp)
 	addPlanCommand(root, flags, loadApp)
 	addHistoryCommand(root, flags, loadApp)
@@ -169,6 +174,8 @@ func chooseTemplate(noteType, templateName string) string {
 	switch noteType {
 	case "brainstorm", "brainstorm_distill":
 		return "brainstorm.md"
+	case "decision":
+		return "decision.md"
 	case "epic":
 		return "epic.md"
 	case "spec":
diff --git a/cmd/search.go b/cmd/search.go
index 1e9d5c4..5a900ec 100644
--- a/cmd/search.go
+++ b/cmd/search.go
@@ -4,12 +4,15 @@ import (
 	"fmt"
 	"io"
 
+	"brain/internal/search"
+
 	"github.com/spf13/cobra"
 )
 
 func addSearchCommand(root *cobra.Command, flags *rootFlagsState, loadApp appLoader) {
 	var limit int
 	var explain bool
+	var inject bool
 
 	searchCmd := &cobra.Command{
 		Use:   "search <query>",
@@ -24,19 +27,54 @@ func addSearchCommand(root *cobra.Command, flags *rootFlagsState, loadApp appLoa
 			if _, err := appCtx.EnsureFreshIndex(cmd.Context()); err != nil {
 				return err
 			}
+			searchOpts := search.Options{}
+			active, err := appCtx.Session.Active(flags.projectPath)
+			if err != nil {
+				return err
+			}
+			if active != nil {
+				searchOpts.ActiveTask = active.Task
+			}
 
 			if explain {
-				results, err := appCtx.Search.SearchWithExplain(cmd.Context(), args[0], limit)
+				results, err := appCtx.Search.SearchWithExplainOptions(cmd.Context(), args[0], limit, searchOpts)
 				if err != nil {
 					return err
 				}
+				if inject {
+					payload := map[string]any{
+						"results":       results,
+						"context_block": search.BuildContextBlock(results),
+					}
+					return appCtx.Output.Print(payload, func(w io.Writer) error {
+						if len(results) == 0 {
+							_, err := io.WriteString(w, "No results.\n")
+							return err
+						}
+						for _, result := range results {
+							if _, err := fmt.Fprintf(w, "%.3f  [%s lex=%.3f sem=%.3f rec=%.3f type=%.3f ctx=%.3f] %s", result.Score, result.Source, result.LexicalScore, result.SemanticScore, result.RecencyBoost, result.TypeBoost, result.ContextBoost, result.NotePath); err != nil {
+								return err
+							}
+							if result.Heading != "" {
+								if _, err := fmt.Fprintf(w, " -> %s", result.Heading); err != nil {
+									return err
+								}
+							}
+							if _, err := fmt.Fprintf(w, "\n  %s\n", result.Snippet); err != nil {
+								return err
+							}
+						}
+						_, err := fmt.Fprintf(w, "\n%s", search.BuildContextBlock(results))
+						return err
+					})
+				}
 				return appCtx.Output.Print(results, func(w io.Writer) error {
 					if len(results) == 0 {
 						_, err := io.WriteString(w, "No results.\n")
 						return err
 					}
 					for _, result := range results {
-						if _, err := fmt.Fprintf(w, "%.3f  [%s lex=%.3f sem=%.3f] %s", result.Score, result.Source, result.LexicalScore, result.SemanticScore, result.NotePath); err != nil {
+						if _, err := fmt.Fprintf(w, "%.3f  [%s lex=%.3f sem=%.3f rec=%.3f type=%.3f ctx=%.3f] %s", result.Score, result.Source, result.LexicalScore, result.SemanticScore, result.RecencyBoost, result.TypeBoost, result.ContextBoost, result.NotePath); err != nil {
 							return err
 						}
 						if result.Heading != "" {
@@ -52,10 +90,37 @@ func addSearchCommand(root *cobra.Command, flags *rootFlagsState, loadApp appLoa
 				})
 			}
 
-			results, err := appCtx.Search.Search(cmd.Context(), args[0], limit)
+			results, err := appCtx.Search.SearchWithOptions(cmd.Context(), args[0], limit, searchOpts)
 			if err != nil {
 				return err
 			}
+			if inject {
+				payload := map[string]any{
+					"results":       results,
+					"context_block": search.BuildContextBlock(results),
+				}
+				return appCtx.Output.Print(payload, func(w io.Writer) error {
+					if len(results) == 0 {
+						_, err := io.WriteString(w, "No results.\n")
+						return err
+					}
+					for _, result := range results {
+						if _, err := fmt.Fprintf(w, "%.3f  %s", result.Score, result.NotePath); err != nil {
+							return err
+						}
+						if result.Heading != "" {
+							if _, err := fmt.Fprintf(w, " -> %s", result.Heading); err != nil {
+								return err
+							}
+						}
+						if _, err := fmt.Fprintf(w, "\n  %s\n", result.Snippet); err != nil {
+							return err
+						}
+					}
+					_, err := fmt.Fprintf(w, "\n%s", search.BuildContextBlock(results))
+					return err
+				})
+			}
 			return appCtx.Output.Print(results, func(w io.Writer) error {
 				if len(results) == 0 {
 					_, err := io.WriteString(w, "No results.\n")
@@ -80,6 +145,7 @@ func addSearchCommand(root *cobra.Command, flags *rootFlagsState, loadApp appLoa
 	}
 	searchCmd.Flags().IntVarP(&limit, "limit", "n", 10, "maximum results")
 	searchCmd.Flags().BoolVar(&explain, "explain", false, "show lexical and semantic ranking contributions")
+	searchCmd.Flags().BoolVar(&inject, "inject", false, "include an agent-ready relevant-context block")
 
 	statusCmd := &cobra.Command{
 		Use:   "status",
diff --git a/docs/project-architecture.md b/docs/project-architecture.md
index 46bd326..094780d 100644
--- a/docs/project-architecture.md
+++ b/docs/project-architecture.md
@@ -10,6 +10,7 @@ Use this file for the structural shape of the repository.
 - `internal/brainstorm/`
 - `internal/buildinfo/`
 - `internal/config/`
+- `internal/distill/`
 - `internal/embeddings/`
 - `internal/history/`
 - `internal/index/`
diff --git a/docs/project-workflows.md b/docs/project-workflows.md
index fe96e71..6ca271c 100644
--- a/docs/project-workflows.md
+++ b/docs/project-workflows.md
@@ -15,11 +15,24 @@ Use this file for agent operating workflow inside the repo.
 - Keep durable discoveries, decisions, and risks in AGENTS.md, /docs, or .brain notes.
 - Update existing durable notes instead of duplicating context.
 - Run required verification commands through `brain session run -- <command>`.
+- If you change Brain command behavior or agent-facing workflow guidance, update `skills/brain/SKILL.md` in the same branch.
 - Re-read context before large changes if the task shifts.
 
+## Ticket Loop
+
+1. Start one story or ticket at a time and keep the scope narrow.
+2. Implement the story, then run focused tests for the touched packages.
+3. Run the required full checks through `brain session run -- go test ./...` and `brain session run -- go build ./...`.
+4. Review the diff against the story acceptance criteria and user-facing behavior.
+5. If review finds issues, patch the work and repeat the test and review steps.
+6. When the story is clean, commit it, push it, and only then move to the next story.
+
 ## Close-Out
 
 - Refresh or update durable notes for meaningful behavior, config, or architecture changes.
+- If `skills/brain/` changed, reinstall the local Brain skill for Codex and OpenClaw with `brain skills install --scope local --agent codex --agent openclaw --project .`.
+- When opening a PR, make the title and body release-note friendly because GitHub release notes are generated from merged PR metadata.
+- Summarize shipped behavior in the PR, not just implementation steps, so future changelogs stay human-readable.
 - Finish with `brain session finish`.
 - If you must bypass enforcement, use `brain session finish --force --reason "..."` so the override is recorded.
 <!-- brain:end project-doc-workflows -->
diff --git a/docs/skills.md b/docs/skills.md
index f934ff8..2637381 100644
--- a/docs/skills.md
+++ b/docs/skills.md
@@ -33,6 +33,7 @@ Install into a project:
 
 ```bash
 brain skills install --scope local --agent codex --project .
+brain skills install --scope local --agent openclaw --project .
 brain skills install --scope local --agent copilot --project .
 brain skills install --scope local --agent pi --project .
 ```
@@ -42,12 +43,23 @@ Use `--mode copy` when the target runtime does not support symlinked skill direc
 Default roots:
 
 - Codex global: `~/.codex/skills/`
+- Codex local: `.codex/skills/`
 - Claude global: `~/.claude/skills/`
 - Copilot global: `~/.copilot/skills/`
 - Pi global: `~/.pi/agent/skills/`
+- OpenClaw global: `~/.openclaw/skills/`
+- OpenClaw local: `.openclaw/skills/`
 - Copilot local: `.github/skills/`
 - Pi local: `.pi/skills/`
 
+## Repo Maintenance
+
+When a repo change updates Brain's command surface or agent-facing workflow guidance, update `skills/brain/SKILL.md` in the same branch and reinstall the local Brain skill for Codex and OpenClaw before closing the work:
+
+```bash
+brain skills install --scope local --agent codex --agent openclaw --project .
+```
+
 ## Relationship To Project Context
 
 The skill is the generic fallback.  
diff --git a/docs/usage.md b/docs/usage.md
index 7c8953c..691c23a 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -97,6 +97,20 @@ brain search --project . "follow-up"
 
 Brainstorms live in `.brain/brainstorms/`.
 
+## Distillation
+
+Use distillation when session work or a brainstorm should become proposed durable memory without mutating the destination notes directly.
+
+```bash
+brain distill --project . --session
+brain distill --project . --brainstorm .brain/brainstorms/event-follow-up-ideas.md
+brain brainstorm distill --project . .brain/brainstorms/event-follow-up-ideas.md
+```
+
+`brain distill --session` requires an active session and creates a proposal note under `.brain/resources/changes/` with source provenance, proposed target notes, and suggested markdown updates for review.
+
+`brain distill --brainstorm ...` uses the same proposal flow for brainstorms. `brain brainstorm distill ...` remains supported as a compatibility wrapper.
+
 ## Planning
 
 Initialize once:
@@ -136,10 +150,21 @@ brain context install --project .
 brain context install --project . --agent codex
 brain context refresh --project .
 brain context refresh --project . --dry-run
+brain context load --project . --level 0
+brain context load --project . --level 1
+brain context load --project . --level 2
+brain context load --project . --level 3 --query "auth flow"
 ```
 
 Use `--force` when adopting an existing unmanaged `AGENTS.md` or docs file into the managed-block model.
 
+`context load` is read-only and deterministic:
+
+- level 0 loads the AGENTS summary plus current state
+- level 1 adds overview and workflows
+- level 2 loads the full static context bundle
+- level 3 adds search-injected relevant context, using `--query` or the active session task
+
 Wrappers are opt-in. Brain always installs the root contract and `.brain/context/*`; agent-specific wrapper files are only created when you pass one or more `--agent` flags.
 
 If you want the full existing-repo bootstrap instead of just context takeover, use:
@@ -160,6 +185,8 @@ brain session run --project . -- go build ./...
 brain session finish --project . --summary "auth flow tightened"
 ```
 
+If finish blocks because repo changes need durable memory updates, run `brain distill --project . --session`, review the proposal, apply the note updates that matter, and retry `brain session finish`.
+
 ## Skills
 
 Install the Brain skill when you want the agent runtime itself to understand how to use the repo brain correctly from the start.
@@ -174,10 +201,17 @@ brain skills install --scope local --agent copilot --project .
 brain skills install --scope global --agent pi
 brain skills install --scope local --agent pi --project .
 brain skills install --scope global --agent openclaw --mode copy
+brain skills install --scope local --agent openclaw --project .
 ```
 
 `brain skills install` always installs the Brain skill. Use `--scope global` to add it to your machine and `--scope local --project .` to add it to the current project.
 
+When a branch changes Brain's command surface or agent-facing workflow guidance, update `skills/brain/SKILL.md` in that same branch and reinstall the local Brain skill for Codex and OpenClaw before closing the work:
+
+```bash
+brain skills install --scope local --agent codex --agent openclaw --project .
+```
+
 ## History And Undo
 
 ```bash
diff --git a/internal/app/app.go b/internal/app/app.go
index 7276794..af616a1 100644
--- a/internal/app/app.go
+++ b/internal/app/app.go
@@ -10,6 +10,7 @@ import (
 	"brain/internal/backup"
 	"brain/internal/brainstorm"
 	"brain/internal/config"
+	"brain/internal/distill"
 	"brain/internal/embeddings"
 	"brain/internal/history"
 	"brain/internal/index"
@@ -39,6 +40,7 @@ type App struct {
 	Search     *search.Engine
 	Project    *project.Manager
 	Brainstorm *brainstorm.Manager
+	Distill    *distill.Manager
 	Plan       *plan.Manager
 	Skills     *skills.Installer
 	Context    *projectcontext.Manager
@@ -90,7 +92,9 @@ func New(configPath, projectPath string, jsonOutput bool, opts Options) (*App, e
 	searchEngine := search.New(store, embedder)
 	notesManager := notes.New(workspaceSvc, tpl, backups, historyLog)
 	projectManager := project.New(notesManager, workspaceSvc)
+	sessionManager := session.New(historyLog)
 	brainstormManager := brainstorm.New(notesManager, searchEngine, projectManager)
+	distillManager := distill.New(notesManager, searchEngine, projectManager, historyLog, sessionManager)
 	planManager := plan.New(notesManager, projectManager)
 	userHome, _ := os.UserHomeDir()
 
@@ -108,10 +112,11 @@ func New(configPath, projectPath string, jsonOutput bool, opts Options) (*App, e
 		Search:     searchEngine,
 		Project:    projectManager,
 		Brainstorm: brainstormManager,
+		Distill:    distillManager,
 		Plan:       planManager,
 		Skills:     skills.NewInstaller(userHome),
 		Context:    projectcontext.New(userHome),
-		Session:    session.New(historyLog),
+		Session:    sessionManager,
 		Output:     output.New(cfg.OutputMode, opts.Stdout),
 	}, nil
 }
diff --git a/internal/distill/manager.go b/internal/distill/manager.go
new file mode 100644
index 0000000..d5810e2
--- /dev/null
+++ b/internal/distill/manager.go
@@ -0,0 +1,514 @@
+package distill
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+
+	"brain/internal/history"
+	"brain/internal/notes"
+	"brain/internal/project"
+	"brain/internal/search"
+	"brain/internal/session"
+)
+
+var slugPattern = regexp.MustCompile(`[^a-z0-9]+`)
+
+type Manager struct {
+	notes   *notes.Manager
+	search  *search.Engine
+	project *project.Manager
+	history *history.Logger
+	session *session.Manager
+}
+
+func New(notesManager *notes.Manager, searchEngine *search.Engine, projectManager *project.Manager, historyLog *history.Logger, sessionManager *session.Manager) *Manager {
+	return &Manager{
+		notes:   notesManager,
+		search:  searchEngine,
+		project: projectManager,
+		history: historyLog,
+		session: sessionManager,
+	}
+}
+
+func (m *Manager) FromSession(ctx context.Context, limit int) (*notes.Note, error) {
+	projectDir := m.notes.WorkspaceAbs(".")
+	active, err := m.session.Active(projectDir)
+	if err != nil {
+		return nil, err
+	}
+	if active == nil || active.Status != "active" {
+		return nil, errors.New("distill --session requires an active session")
+	}
+	if limit <= 0 {
+		limit = 6
+	}
+
+	changedFiles, diffSummary := gitDiffSummary(ctx, projectDir, active.GitBaseline.Head)
+	recentNotes, err := m.historyAfterBaseline(active.HistoryBaseline, limit)
+	if err != nil {
+		return nil, err
+	}
+
+	title := strings.TrimSpace(active.Task)
+	if title == "" {
+		title = "Session"
+	}
+	title += " Distill Proposal"
+	changeSlug := slugify(active.Task)
+	if changeSlug == "" {
+		changeSlug = "session"
+	}
+	decisionSlug := changeSlug
+	body := renderSessionProposal(sessionProposal{
+		Title:       title,
+		SessionID:   active.ID,
+		Task:        active.Task,
+		GitHead:     active.GitBaseline.Head,
+		Commands:    active.CommandRuns,
+		Changed:     changedFiles,
+		DiffSummary: diffSummary,
+		RecentNotes: recentNotes,
+		Targets: []proposalTarget{
+			{
+				Path:   "AGENTS.md",
+				Reason: "capture new workflow guidance, decisions, or constraints that should become part of the repo contract",
+				Body: []string{
+					fmt.Sprintf("- Add the durable guidance learned while working on %q.", active.Task),
+					"- Keep the note concise and operational so future agents can reuse it.",
+				},
+			},
+			{
+				Path:   ".brain/context/current-state.md",
+				Reason: "record what changed, what remains active, and any follow-up state that should persist beyond the session",
+				Body: []string{
+					fmt.Sprintf("- Summarize the current state of %q.", active.Task),
+					"- Note the highest-signal changed files and any remaining follow-up.",
+				},
+			},
+			{
+				Path:   filepath.ToSlash(filepath.Join(".brain/resources/changes", changeSlug+".md")),
+				Reason: "capture the implementation outcome, changed files, and verification trail as a durable change note",
+				Body: []string{
+					fmt.Sprintf("# %s", strings.TrimSpace(active.Task)),
+					"",
+					"## Outcome",
+					"- Summarize the shipped behavior from this session.",
+					"",
+					"## Verification",
+					"- Copy the passing session commands after review.",
+					"",
+					"## Changed Files",
+					"- List the durable files that materially changed.",
+				},
+			},
+			{
+				Path:   filepath.ToSlash(filepath.Join(".brain/resources/decisions", decisionSlug+".md")),
+				Reason: "preserve rationale if this session changed a technical or workflow decision instead of only changing code",
+				Body: []string{
+					fmt.Sprintf("# Why we chose %s", strings.TrimSpace(active.Task)),
+					"",
+					"## Context",
+					"",
+					"## Options Considered",
+					"",
+					"## Decision",
+					"",
+					"## Tradeoffs",
+				},
+			},
+		},
+	})
+
+	return m.createProposal(title, map[string]any{
+		"type":              "distill_proposal",
+		"distill_scope":     "session",
+		"source_session_id": active.ID,
+		"source_task":       active.Task,
+		"proposed_targets": proposalPaths([]proposalTarget{
+			{Path: "AGENTS.md"},
+			{Path: ".brain/context/current-state.md"},
+			{Path: filepath.ToSlash(filepath.Join(".brain/resources/changes", changeSlug+".md"))},
+			{Path: filepath.ToSlash(filepath.Join(".brain/resources/decisions", decisionSlug+".md"))},
+		}),
+	}, body)
+}
+
+func (m *Manager) FromBrainstorm(ctx context.Context, path string, limit int) (*notes.Note, error) {
+	note, err := m.notes.Read(path)
+	if err != nil {
+		return nil, err
+	}
+	if note.Type != "brainstorm" {
+		return nil, fmt.Errorf("note %s is type %q, not brainstorm", path, note.Type)
+	}
+	if limit <= 0 {
+		limit = 6
+	}
+
+	query := strings.TrimSpace(note.Title + " " + note.Content)
+	results, err := m.search.Search(ctx, query, limit+1)
+	if err != nil {
+		return nil, err
+	}
+	related := make([]search.Result, 0, len(results))
+	for _, result := range results {
+		if result.NotePath == note.Path {
+			continue
+		}
+		related = append(related, result)
+		if len(related) >= limit {
+			break
+		}
+	}
+
+	sourceSlug := strings.TrimSuffix(filepath.Base(note.Path), filepath.Ext(note.Path))
+	title := strings.TrimSpace(note.Title)
+	if title == "" {
+		title = sourceSlug
+	}
+	title += " Distill Proposal"
+	body := renderBrainstormProposal(brainstormProposal{
+		Title:      title,
+		SourcePath: note.Path,
+		KeyIdeas:   extractSection(note.Content, "Ideas"),
+		Related:    related,
+		Targets: []proposalTarget{
+			{
+				Path:   "AGENTS.md",
+				Reason: "carry forward any durable workflow or policy guidance that emerged from the brainstorm",
+				Body: []string{
+					fmt.Sprintf("- Promote the durable guidance from %q only if it should become repo contract.", note.Title),
+				},
+			},
+			{
+				Path:   ".brain/context/current-state.md",
+				Reason: "capture the active problem framing if the brainstorm changes what the project is currently pursuing",
+				Body: []string{
+					fmt.Sprintf("- Note how %q changes the current focus or next actions.", note.Title),
+				},
+			},
+			{
+				Path:   filepath.ToSlash(filepath.Join(".brain/resources/changes", sourceSlug+".md")),
+				Reason: "turn the brainstorm into a durable change note once the ideas collapse into an execution path",
+				Body: []string{
+					fmt.Sprintf("# %s", note.Title),
+					"",
+					"## Summary",
+					"- Distill the strongest ideas that should survive beyond the brainstorm.",
+					"",
+					"## References",
+					fmt.Sprintf("- [[%s]]", note.Path),
+				},
+			},
+			{
+				Path:   filepath.ToSlash(filepath.Join(".brain/resources/decisions", sourceSlug+".md")),
+				Reason: "preserve the why if the brainstorm already surfaces a clear choice or tradeoff",
+				Body: []string{
+					fmt.Sprintf("# Why we chose %s", note.Title),
+					"",
+					"## Context",
+					"",
+					"## Options Considered",
+					"",
+					"## Decision",
+					"",
+					"## Tradeoffs",
+				},
+			},
+		},
+	})
+
+	return m.createProposal(title, map[string]any{
+		"type":              "distill_proposal",
+		"distill_scope":     "brainstorm",
+		"source_brainstorm": note.Path,
+		"proposed_targets": proposalPaths([]proposalTarget{
+			{Path: "AGENTS.md"},
+			{Path: ".brain/context/current-state.md"},
+			{Path: filepath.ToSlash(filepath.Join(".brain/resources/changes", sourceSlug+".md"))},
+			{Path: filepath.ToSlash(filepath.Join(".brain/resources/decisions", sourceSlug+".md"))},
+		}),
+	}, body)
+}
+
+type sessionProposal struct {
+	Title       string
+	SessionID   string
+	Task        string
+	GitHead     string
+	Commands    []session.CommandRun
+	Changed     []string
+	DiffSummary string
+	RecentNotes []history.Entry
+	Targets     []proposalTarget
+}
+
+type brainstormProposal struct {
+	Title      string
+	SourcePath string
+	KeyIdeas   string
+	Related    []search.Result
+	Targets    []proposalTarget
+}
+
+type proposalTarget struct {
+	Path   string
+	Reason string
+	Body   []string
+}
+
+func renderSessionProposal(proposal sessionProposal) string {
+	var b strings.Builder
+	b.WriteString("# " + proposal.Title + "\n\n")
+	b.WriteString("## Source Provenance\n\n")
+	b.WriteString("- Mode: `session`\n")
+	b.WriteString("- Session: `" + proposal.SessionID + "`\n")
+	if strings.TrimSpace(proposal.Task) != "" {
+		b.WriteString("- Task: " + proposal.Task + "\n")
+	}
+	if strings.TrimSpace(proposal.GitHead) != "" {
+		b.WriteString("- Git baseline: `" + proposal.GitHead + "`\n")
+	}
+	b.WriteString("\n### Commands Run\n\n")
+	if len(proposal.Commands) == 0 {
+		b.WriteString("- No recorded session commands yet.\n")
+	} else {
+		for _, command := range proposal.Commands {
+			b.WriteString(fmt.Sprintf("- `%s` (exit %d)\n", command.Command, command.ExitCode))
+		}
+	}
+	b.WriteString("\n### Git Diff\n\n")
+	if len(proposal.Changed) == 0 && strings.TrimSpace(proposal.DiffSummary) == "" {
+		b.WriteString("- No changed files detected from the session baseline.\n")
+	} else {
+		for _, path := range proposal.Changed {
+			b.WriteString("- `" + path + "`\n")
+		}
+		if strings.TrimSpace(proposal.DiffSummary) != "" {
+			b.WriteString("\n```text\n" + strings.TrimSpace(proposal.DiffSummary) + "\n```\n")
+		}
+	}
+	b.WriteString("\n### Recent Durable Notes\n\n")
+	if len(proposal.RecentNotes) == 0 {
+		b.WriteString("- No durable note edits were recorded after the session baseline.\n")
+	} else {
+		for _, entry := range proposal.RecentNotes {
+			b.WriteString(fmt.Sprintf("- `%s` (%s: %s)\n", entry.File, entry.Operation, entry.Summary))
+		}
+	}
+	appendTargets(&b, proposal.Targets)
+	return b.String()
+}
+
+func renderBrainstormProposal(proposal brainstormProposal) string {
+	var b strings.Builder
+	b.WriteString("# " + proposal.Title + "\n\n")
+	b.WriteString("## Source Provenance\n\n")
+	b.WriteString("- Mode: `brainstorm`\n")
+	b.WriteString("- Source: `[[" + proposal.SourcePath + "]]`\n")
+	b.WriteString("\n### Key Ideas\n\n")
+	if strings.TrimSpace(proposal.KeyIdeas) == "" {
+		b.WriteString("- No brainstorm ideas were captured yet.\n")
+	} else {
+		b.WriteString(strings.TrimSpace(proposal.KeyIdeas) + "\n")
+	}
+	b.WriteString("\n\n### Related Notes\n\n")
+	if len(proposal.Related) == 0 {
+		b.WriteString("- No related notes found.\n")
+	} else {
+		for _, result := range proposal.Related {
+			line := "- `[[" + result.NotePath + "]]`"
+			if result.Heading != "" {
+				line += " -> `" + result.Heading + "`"
+			}
+			if strings.TrimSpace(result.Snippet) != "" {
+				line += ": " + strings.TrimSpace(result.Snippet)
+			}
+			b.WriteString(line + "\n")
+		}
+	}
+	appendTargets(&b, proposal.Targets)
+	return b.String()
+}
+
+func appendTargets(b *strings.Builder, targets []proposalTarget) {
+	b.WriteString("\n## Proposed Updates\n")
+	for _, target := range targets {
+		b.WriteString("\n### " + target.Path + "\n\n")
+		b.WriteString("Reason: " + target.Reason + "\n\n")
+		b.WriteString("Suggested update:\n\n")
+		b.WriteString("```md\n")
+		b.WriteString(strings.TrimRight(strings.Join(target.Body, "\n"), "\n"))
+		b.WriteString("\n```\n")
+	}
+}
+
+func (m *Manager) createProposal(title string, metadata map[string]any, body string) (*notes.Note, error) {
+	return m.notes.Create(notes.CreateInput{
+		Title:     title,
+		NoteType:  "distill_proposal",
+		Section:   ".brain",
+		Subdir:    "resources/changes",
+		Body:      body,
+		Metadata:  metadata,
+		Overwrite: true,
+	})
+}
+
+func (m *Manager) historyAfterBaseline(baseline session.HistoryBaseline, limit int) ([]history.Entry, error) {
+	if m.history == nil {
+		return nil, nil
+	}
+	entries, err := m.history.All()
+	if err != nil {
+		return nil, err
+	}
+	var recent []history.Entry
+	for _, entry := range entries {
+		if baseline.LastID != "" {
+			if entry.ID == baseline.LastID {
+				recent = recent[:0]
+				continue
+			}
+		}
+		if baseline.LastID == "" && !baseline.LastTimestamp.IsZero() && !entry.Timestamp.After(baseline.LastTimestamp) {
+			continue
+		}
+		if isDurableNotePath(entry.File) {
+			recent = append(recent, entry)
+		}
+	}
+	if limit > 0 && len(recent) > limit {
+		recent = recent[len(recent)-limit:]
+	}
+	return recent, nil
+}
+
+func gitDiffSummary(ctx context.Context, projectDir, baseHead string) ([]string, string) {
+	changedSet := map[string]struct{}{}
+	if strings.TrimSpace(baseHead) != "" {
+		for _, path := range runGitLines(ctx, "-C", projectDir, "diff", "--name-only", baseHead, "--") {
+			changedSet[path] = struct{}{}
+		}
+	}
+	for _, path := range normalizeStatusLines(runGitLines(ctx, "-C", projectDir, "status", "--short")) {
+		changedSet[path] = struct{}{}
+	}
+	changed := make([]string, 0, len(changedSet))
+	for path := range changedSet {
+		if path == "" {
+			continue
+		}
+		changed = append(changed, path)
+	}
+	sort.Strings(changed)
+	diffSummary := strings.TrimSpace(runGitText(ctx, "-C", projectDir, "diff", "--stat", baseHead, "--"))
+	if baseHead == "" {
+		diffSummary = strings.TrimSpace(runGitText(ctx, "-C", projectDir, "diff", "--stat", "--"))
+	}
+	return changed, diffSummary
+}
+
+func runGitLines(ctx context.Context, args ...string) []string {
+	text := runGitText(ctx, args...)
+	if strings.TrimSpace(text) == "" {
+		return nil
+	}
+	lines := strings.Split(text, "\n")
+	out := make([]string, 0, len(lines))
+	for _, line := range lines {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		out = append(out, filepath.ToSlash(line))
+	}
+	return out
+}
+
+func runGitText(ctx context.Context, args ...string) string {
+	cmd := exec.CommandContext(ctx, "git", args...)
+	out, err := cmd.Output()
+	if err != nil {
+		return ""
+	}
+	return string(out)
+}
+
+func normalizeStatusLines(lines []string) []string {
+	out := make([]string, 0, len(lines))
+	for _, line := range lines {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		fields := strings.Fields(line)
+		if len(fields) == 0 {
+			continue
+		}
+		out = append(out, filepath.ToSlash(fields[len(fields)-1]))
+	}
+	return out
+}
+
+func proposalPaths(targets []proposalTarget) []string {
+	out := make([]string, 0, len(targets))
+	for _, target := range targets {
+		out = append(out, target.Path)
+	}
+	return out
+}
+
+func isDurableNotePath(path string) bool {
+	path = filepath.ToSlash(strings.TrimSpace(path))
+	if path == "" {
+		return false
+	}
+	return path == "AGENTS.md" || strings.HasPrefix(path, "docs/") || strings.HasPrefix(path, ".brain/")
+}
+
+func slugify(value string) string {
+	value = strings.ToLower(strings.TrimSpace(value))
+	value = slugPattern.ReplaceAllString(value, "-")
+	return strings.Trim(value, "-")
+}
+
+func extractSection(content, heading string) string {
+	lines := strings.Split(content, "\n")
+	inSection := false
+	sectionLevel := 0
+	var out []string
+
+	for _, line := range lines {
+		if strings.HasPrefix(line, "#") {
+			level := 0
+			for _, ch := range line {
+				if ch == '#' {
+					level++
+				} else {
+					break
+				}
+			}
+			title := strings.TrimSpace(strings.TrimLeft(line, "#"))
+			if strings.EqualFold(title, heading) {
+				inSection = true
+				sectionLevel = level
+				continue
+			}
+			if inSection && level <= sectionLevel {
+				break
+			}
+		}
+		if inSection {
+			out = append(out, line)
+		}
+	}
+	return strings.TrimSpace(strings.Join(out, "\n"))
+}
diff --git a/internal/distill/manager_test.go b/internal/distill/manager_test.go
new file mode 100644
index 0000000..a7ce02b
--- /dev/null
+++ b/internal/distill/manager_test.go
@@ -0,0 +1,203 @@
+package distill
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"brain/internal/backup"
+	"brain/internal/config"
+	"brain/internal/embeddings"
+	"brain/internal/history"
+	"brain/internal/index"
+	"brain/internal/notes"
+	"brain/internal/project"
+	"brain/internal/search"
+	"brain/internal/session"
+	"brain/internal/templates"
+	"brain/internal/workspace"
+)
+
+func TestFromSessionRequiresActiveSession(t *testing.T) {
+	manager, _ := newTestManager(t)
+	if _, err := manager.FromSession(context.Background(), 6); err == nil || !strings.Contains(err.Error(), "requires an active session") {
+		t.Fatalf("expected active session error, got %v", err)
+	}
+}
+
+func TestFromSessionCreatesProposalWithoutEditingTargets(t *testing.T) {
+	manager, harness := newTestManager(t)
+	mustInitGitRepo(t, harness.root)
+
+	if _, err := harness.session.Start(context.Background(), session.StartRequest{
+		ProjectDir: harness.root,
+		Task:       "tighten session distill",
+	}); err != nil {
+		t.Fatalf("start session: %v", err)
+	}
+
+	if err := os.WriteFile(filepath.Join(harness.root, "main.go"), []byte("package main\nfunc main() { println(\"updated\") }\n"), 0o644); err != nil {
+		t.Fatalf("write code change: %v", err)
+	}
+	if _, err := harness.notes.Update(".brain/context/current-state.md", notes.UpdateInput{
+		Body:    stringPtr("# Current State\n\nRecorded durable context.\n"),
+		Summary: "recorded durable context",
+	}); err != nil {
+		t.Fatalf("update durable note: %v", err)
+	}
+	if _, err := harness.session.RunCommand(context.Background(), session.RunRequest{
+		ProjectDir:    harness.root,
+		Argv:          []string{"go", "version"},
+		CaptureOutput: true,
+	}, nil, nil); err != nil {
+		t.Fatalf("record command: %v", err)
+	}
+
+	agentsBefore, err := os.ReadFile(filepath.Join(harness.root, "AGENTS.md"))
+	if err != nil {
+		t.Fatalf("read agents before: %v", err)
+	}
+
+	note, err := manager.FromSession(context.Background(), 6)
+	if err != nil {
+		t.Fatalf("distill session: %v", err)
+	}
+	if note.Type != "distill_proposal" {
+		t.Fatalf("expected distill proposal note, got %q", note.Type)
+	}
+	if !strings.Contains(note.Content, "## Source Provenance") || !strings.Contains(note.Content, "## Proposed Updates") {
+		t.Fatalf("expected provenance and targets in proposal:\n%s", note.Content)
+	}
+	if !strings.Contains(note.Content, "go version") || !strings.Contains(note.Content, "main.go") || !strings.Contains(note.Content, ".brain/context/current-state.md") {
+		t.Fatalf("expected session-derived material in proposal:\n%s", note.Content)
+	}
+	if !strings.Contains(note.Content, "### AGENTS.md") || !strings.Contains(note.Content, "### .brain/context/current-state.md") {
+		t.Fatalf("expected target sections in proposal:\n%s", note.Content)
+	}
+
+	agentsAfter, err := os.ReadFile(filepath.Join(harness.root, "AGENTS.md"))
+	if err != nil {
+		t.Fatalf("read agents after: %v", err)
+	}
+	if string(agentsBefore) != string(agentsAfter) {
+		t.Fatalf("expected distill not to modify AGENTS.md directly")
+	}
+}
+
+type testHarness struct {
+	root    string
+	notes   *notes.Manager
+	session *session.Manager
+}
+
+func newTestManager(t *testing.T) (*Manager, testHarness) {
+	t.Helper()
+	root := t.TempDir()
+	workspaceSvc := workspace.New(root)
+	if err := workspaceSvc.Initialize(); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "AGENTS.md"), []byte("# Project Agent Contract\n\nLocal notes.\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, ".brain", "context", "current-state.md"), []byte("---\ntitle: Current State\ntype: resource\n---\n# Current State\n\nBaseline state.\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	for rel, content := range map[string]string{
+		".brain/context/overview.md":      "# Overview\n\nTest overview.\n",
+		".brain/context/workflows.md":     "# Workflows\n\nTest workflows.\n",
+		".brain/context/memory-policy.md": "# Memory Policy\n\nTest memory rules.\n",
+		".brain/policy.yaml": `version: 1
+project:
+  name: brain
+  slug: brain
+  runtime: go
+  memory:
+    accepted_note_globs:
+      - AGENTS.md
+      - docs/**
+      - .brain/context/**
+      - .brain/planning/**
+      - .brain/brainstorms/**
+      - .brain/resources/**
+session:
+  require_task: true
+  single_active: true
+  active_file: .brain/session.json
+  ledger_dir: .brain/sessions
+preflight:
+  require_brain_doctor: true
+  required_docs:
+    - AGENTS.md
+    - .brain/context/overview.md
+    - .brain/context/workflows.md
+    - .brain/context/memory-policy.md
+closeout:
+  acceptable_history_operations:
+    - update
+  require_memory_update_on_repo_change: true
+  verification_profiles:
+    - name: tests
+      commands:
+        - "go test ./..."
+`,
+	} {
+		if err := os.WriteFile(filepath.Join(root, filepath.FromSlash(rel)), []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	historyLog := history.New(filepath.Join(root, ".brain", "state", "history.jsonl"))
+	notesManager := notes.New(workspaceSvc, templates.New(), backup.New(filepath.Join(root, ".brain", "state", "backups")), historyLog)
+	projectManager := project.New(notesManager, workspaceSvc)
+	store, err := index.New(filepath.Join(root, ".brain", "state", "brain.sqlite3"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = store.Close() })
+	provider, err := embeddings.New(&config.Config{
+		EmbeddingProvider: "localhash",
+		EmbeddingModel:    "hash-v1",
+		OutputMode:        "json",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := store.Reindex(context.Background(), workspaceSvc, provider); err != nil {
+		t.Fatal(err)
+	}
+	searchEngine := search.New(store, provider)
+	sessionManager := session.New(historyLog)
+	manager := New(notesManager, searchEngine, projectManager, historyLog, sessionManager)
+	return manager, testHarness{
+		root:    root,
+		notes:   notesManager,
+		session: sessionManager,
+	}
+}
+
+func mustInitGitRepo(t *testing.T, root string) {
+	t.Helper()
+	runGit(t, root, "init", "-q")
+	runGit(t, root, "config", "user.email", "tester@example.com")
+	runGit(t, root, "config", "user.name", "tester")
+	runGit(t, root, "add", ".")
+	runGit(t, root, "commit", "-q", "-m", "init")
+}
+
+func runGit(t *testing.T, dir string, args ...string) {
+	t.Helper()
+	cmd := exec.Command("git", args...)
+	cmd.Dir = dir
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("git %s failed: %v\n%s", strings.Join(args, " "), err, string(out))
+	}
+}
+
+func stringPtr(value string) *string {
+	return &value
+}
diff --git a/internal/index/sqlite.go b/internal/index/sqlite.go
index 7317fa1..df9a497 100644
--- a/internal/index/sqlite.go
+++ b/internal/index/sqlite.go
@@ -29,12 +29,15 @@ type Store struct {
 }
 
 type ChunkRecord struct {
-	ChunkID  int64   `json:"chunk_id"`
-	NotePath string  `json:"note_path"`
-	Heading  string  `json:"heading"`
-	Content  string  `json:"content"`
-	Snippet  string  `json:"snippet"`
-	Score    float64 `json:"score"`
+	ChunkID    int64   `json:"chunk_id"`
+	NotePath   string  `json:"note_path"`
+	NoteTitle  string  `json:"note_title,omitempty"`
+	NoteType   string  `json:"note_type,omitempty"`
+	ModifiedAt string  `json:"modified_at,omitempty"`
+	Heading    string  `json:"heading"`
+	Content    string  `json:"content"`
+	Snippet    string  `json:"snippet"`
+	Score      float64 `json:"score"`
 }
 
 type Stats struct {
@@ -251,7 +254,8 @@ func (s *Store) Reindex(ctx context.Context, workspaceSvc *workspace.Service, pr
 		if err != nil {
 			return Stats{}, fmt.Errorf("marshal note metadata: %w", err)
 		}
-		if _, err := insertNote.ExecContext(ctx, rel, title, noteType, string(metaJSON), body, time.Now().UTC().Format(time.RFC3339)); err != nil {
+		modifiedAt := noteModifiedAt(meta, file)
+		if _, err := insertNote.ExecContext(ctx, rel, title, noteType, string(metaJSON), body, modifiedAt); err != nil {
 			return Stats{}, fmt.Errorf("insert note: %w", err)
 		}
 		stats.Notes++
@@ -397,10 +401,11 @@ func (s *Store) SearchFTS(ctx context.Context, query string, limit int) ([]Chunk
 		return nil, nil
 	}
 	rows, err := s.DB.QueryContext(ctx, `
-		SELECT rowid, note_path, heading,
+		SELECT c.rowid, c.note_path, n.title, n.type, n.modified_at, c.heading,
 		       snippet(chunk_fts, 2, '[', ']', ' … ', 18) AS snippet,
 		       bm25(chunk_fts) AS rank
-		FROM chunk_fts
+		FROM chunk_fts c
+		JOIN notes n ON n.path = c.note_path
 		WHERE chunk_fts MATCH ?
 		ORDER BY rank
 		LIMIT ?`, query, limit)
@@ -413,7 +418,7 @@ func (s *Store) SearchFTS(ctx context.Context, query string, limit int) ([]Chunk
 	for rows.Next() {
 		var rec ChunkRecord
 		var rank float64
-		if err := rows.Scan(&rec.ChunkID, &rec.NotePath, &rec.Heading, &rec.Snippet, &rank); err != nil {
+		if err := rows.Scan(&rec.ChunkID, &rec.NotePath, &rec.NoteTitle, &rec.NoteType, &rec.ModifiedAt, &rec.Heading, &rec.Snippet, &rank); err != nil {
 			return nil, err
 		}
 		rec.Score = rank
@@ -424,8 +429,9 @@ func (s *Store) SearchFTS(ctx context.Context, query string, limit int) ([]Chunk
 
 func (s *Store) EmbeddingCandidates(ctx context.Context, provider, model string) ([]ChunkRecord, [][]float32, error) {
 	rows, err := s.DB.QueryContext(ctx, `
-		SELECT c.id, c.note_path, c.heading, c.content, e.vector
+		SELECT c.id, c.note_path, n.title, n.type, n.modified_at, c.heading, c.content, e.vector
 		FROM chunks c
+		JOIN notes n ON n.path = c.note_path
 		JOIN embeddings e ON e.chunk_id = c.id
 		WHERE e.provider = ? AND e.model = ?`, provider, model)
 	if err != nil {
@@ -438,7 +444,7 @@ func (s *Store) EmbeddingCandidates(ctx context.Context, provider, model string)
 	for rows.Next() {
 		var rec ChunkRecord
 		var blob []byte
-		if err := rows.Scan(&rec.ChunkID, &rec.NotePath, &rec.Heading, &rec.Content, &blob); err != nil {
+		if err := rows.Scan(&rec.ChunkID, &rec.NotePath, &rec.NoteTitle, &rec.NoteType, &rec.ModifiedAt, &rec.Heading, &rec.Content, &blob); err != nil {
 			return nil, nil, err
 		}
 		rec.Snippet = snippet(rec.Content)
@@ -548,6 +554,23 @@ func typeFromMeta(path string, meta map[string]any) string {
 	}
 }
 
+func noteModifiedAt(meta map[string]any, path string) string {
+	for _, key := range []string{"updated", "created"} {
+		switch raw := meta[key].(type) {
+		case string:
+			if ts, err := time.Parse(time.RFC3339, raw); err == nil {
+				return ts.UTC().Format(time.RFC3339)
+			}
+		case time.Time:
+			return raw.UTC().Format(time.RFC3339)
+		}
+	}
+	if info, err := os.Stat(path); err == nil {
+		return info.ModTime().UTC().Format(time.RFC3339)
+	}
+	return time.Now().UTC().Format(time.RFC3339)
+}
+
 func snippet(content string) string {
 	content = strings.TrimSpace(strings.ReplaceAll(content, "\n", " "))
 	if len(content) <= 180 {
diff --git a/internal/notes/manager.go b/internal/notes/manager.go
index 217abce..76a7445 100644
--- a/internal/notes/manager.go
+++ b/internal/notes/manager.go
@@ -75,7 +75,15 @@ func (m *Manager) Create(input CreateInput) (*Note, error) {
 		input.Template = "resource.md"
 	}
 	if input.Subdir == "" && input.Section == ".brain" {
-		input.Subdir = "resources/references"
+		switch input.NoteType {
+		case "decision":
+			input.Subdir = "resources/decisions"
+		default:
+			input.Subdir = "resources/references"
+		}
+	}
+	if input.Template == "resource.md" && input.NoteType == "decision" {
+		input.Template = "decision.md"
 	}
 	now := time.Now().UTC().Format(time.RFC3339)
 	relDir := filepath.ToSlash(filepath.Join(input.Section, input.Subdir))
@@ -400,6 +408,9 @@ func inferTypeFromPath(path string) string {
 	if len(parts) == 0 {
 		return "note"
 	}
+	if strings.HasPrefix(filepath.ToSlash(path), ".brain/resources/decisions/") {
+		return "decision"
+	}
 	switch parts[0] {
 	case ".brain":
 		return "resource"
diff --git a/internal/notes/manager_test.go b/internal/notes/manager_test.go
index 5050541..60b6669 100644
--- a/internal/notes/manager_test.go
+++ b/internal/notes/manager_test.go
@@ -193,3 +193,64 @@ func TestUpdateRejectsInvalidFrontmatter(t *testing.T) {
 		t.Fatalf("note was modified unexpectedly:\n%s", reloaded.Content)
 	}
 }
+
+func TestCreateDecisionNoteUsesDecisionDefaults(t *testing.T) {
+	manager := newTestManager(t)
+
+	note, err := manager.Create(CreateInput{
+		Title:    "Why We Chose SQLite",
+		NoteType: "decision",
+		Section:  ".brain",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if note.Path != ".brain/resources/decisions/why-we-chose-sqlite.md" {
+		t.Fatalf("unexpected decision note path: %s", note.Path)
+	}
+	if note.Type != "decision" {
+		t.Fatalf("unexpected decision note type: %s", note.Type)
+	}
+	for _, heading := range []string{"## Context", "## Options Considered", "## Decision", "## Tradeoffs"} {
+		if !strings.Contains(note.Content, heading) {
+			t.Fatalf("expected decision template heading %q in note:\n%s", heading, note.Content)
+		}
+	}
+}
+
+func TestInferDecisionTypeFromPath(t *testing.T) {
+	manager := newTestManager(t)
+
+	if _, err := manager.Create(CreateInput{
+		Title:    "Keep Search Local",
+		NoteType: "decision",
+		Section:  ".brain",
+	}); err != nil {
+		t.Fatal(err)
+	}
+	path := manager.WorkspaceAbs(".brain/resources/decisions/keep-search-local.md")
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	meta, body, err := ParseFrontmatter(string(raw))
+	if err != nil {
+		t.Fatal(err)
+	}
+	delete(meta, "type")
+	normalized, err := ComposeFrontmatter(meta, body)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(normalized), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	note, err := manager.Read(".brain/resources/decisions/keep-search-local.md")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if note.Type != "decision" {
+		t.Fatalf("expected decision type inferred from path, got %q", note.Type)
+	}
+}
diff --git a/internal/projectcontext/manager.go b/internal/projectcontext/manager.go
index cb528c6..4b78dc4 100644
--- a/internal/projectcontext/manager.go
+++ b/internal/projectcontext/manager.go
@@ -61,6 +61,17 @@ type fileSpec struct {
 	CommentPrefix string
 }
 
+type LoadRequest struct {
+	ProjectDir string
+	Level      int
+}
+
+type LoadedContext struct {
+	Level   int      `json:"level"`
+	Sources []string `json:"sources"`
+	Content string   `json:"content"`
+}
+
 func New(home string) *Manager {
 	if home == "" {
 		home, _ = os.UserHomeDir()
@@ -82,6 +93,175 @@ func (m *Manager) Refresh(ctx context.Context, req Request) ([]Result, error) {
 	return m.apply(ctx, req)
 }
 
+func (m *Manager) Load(req LoadRequest) (*LoadedContext, error) {
+	projectDir, err := filepath.Abs(defaultProjectDir(req.ProjectDir))
+	if err != nil {
+		return nil, err
+	}
+	sources, err := staticLoadSources(req.Level)
+	if err != nil {
+		return nil, err
+	}
+
+	out := &LoadedContext{
+		Level:   req.Level,
+		Sources: make([]string, 0, len(sources)),
+	}
+	var content strings.Builder
+	for i, source := range sources {
+		body, err := renderLoadSource(projectDir, source)
+		if err != nil {
+			return nil, err
+		}
+		if i > 0 {
+			content.WriteString("\n\n")
+		}
+		content.WriteString("## Source: " + source.label() + "\n\n")
+		content.WriteString(body)
+		out.Sources = append(out.Sources, source.label())
+	}
+	out.Content = strings.TrimSpace(content.String()) + "\n"
+	return out, nil
+}
+
+type loadSource struct {
+	Path    string
+	Summary bool
+}
+
+func staticLoadSources(level int) ([]loadSource, error) {
+	switch level {
+	case 0:
+		return []loadSource{
+			{Path: "AGENTS.md", Summary: true},
+			{Path: ".brain/context/current-state.md"},
+		}, nil
+	case 1:
+		return []loadSource{
+			{Path: "AGENTS.md", Summary: true},
+			{Path: ".brain/context/current-state.md"},
+			{Path: ".brain/context/overview.md"},
+			{Path: ".brain/context/workflows.md"},
+		}, nil
+	case 2, 3:
+		return []loadSource{
+			{Path: "AGENTS.md"},
+			{Path: ".brain/context/overview.md"},
+			{Path: ".brain/context/architecture.md"},
+			{Path: ".brain/context/standards.md"},
+			{Path: ".brain/context/workflows.md"},
+			{Path: ".brain/context/memory-policy.md"},
+			{Path: ".brain/context/current-state.md"},
+		}, nil
+	default:
+		return nil, fmt.Errorf("unsupported context level %d (expected 0, 1, 2, or 3)", level)
+	}
+}
+
+func renderLoadSource(projectDir string, source loadSource) (string, error) {
+	raw, err := os.ReadFile(filepath.Join(projectDir, filepath.FromSlash(source.Path)))
+	if err != nil {
+		return "", fmt.Errorf("read context source %s: %w", source.Path, err)
+	}
+	content := strings.ReplaceAll(string(raw), "\r\n", "\n")
+	if source.Path == "AGENTS.md" && source.Summary {
+		return summarizeAgents(content), nil
+	}
+	return stripLocalNotes(strings.TrimSpace(content)), nil
+}
+
+func (s loadSource) label() string {
+	if s.Summary {
+		return s.Path + " (summary)"
+	}
+	return s.Path
+}
+
+func summarizeAgents(content string) string {
+	intro := firstParagraph(content)
+	workflow := extractMarkdownSection(content, "Required Workflow")
+	var b strings.Builder
+	if intro != "" {
+		b.WriteString(intro)
+	}
+	if workflow != "" {
+		if b.Len() > 0 {
+			b.WriteString("\n\n")
+		}
+		b.WriteString("## Required Workflow\n\n")
+		b.WriteString(workflow)
+	}
+	summary := strings.TrimSpace(b.String())
+	if summary == "" {
+		return stripLocalNotes(strings.TrimSpace(content))
+	}
+	return summary
+}
+
+func firstParagraph(content string) string {
+	lines := strings.Split(content, "\n")
+	var paragraph []string
+	for _, line := range lines {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			if len(paragraph) != 0 {
+				break
+			}
+			continue
+		}
+		if strings.HasPrefix(line, "#") || strings.HasPrefix(line, "<!--") || strings.HasPrefix(line, "- [") || strings.HasPrefix(line, "- ") {
+			if len(paragraph) != 0 {
+				break
+			}
+			continue
+		}
+		paragraph = append(paragraph, line)
+	}
+	return strings.TrimSpace(strings.Join(paragraph, " "))
+}
+
+func extractMarkdownSection(content, heading string) string {
+	lines := strings.Split(content, "\n")
+	inSection := false
+	sectionLevel := 0
+	var out []string
+
+	for _, line := range lines {
+		if strings.HasPrefix(line, "#") {
+			level := 0
+			for _, ch := range line {
+				if ch == '#' {
+					level++
+				} else {
+					break
+				}
+			}
+			title := strings.TrimSpace(strings.TrimLeft(line, "#"))
+			if strings.EqualFold(title, heading) {
+				inSection = true
+				sectionLevel = level
+				continue
+			}
+			if inSection && level <= sectionLevel {
+				break
+			}
+		}
+		if inSection {
+			out = append(out, line)
+		}
+	}
+	return strings.TrimSpace(strings.Join(out, "\n"))
+}
+
+func stripLocalNotes(content string) string {
+	content = strings.TrimSpace(content)
+	marker := "\n## Local Notes\n"
+	if idx := strings.Index(content, marker); idx >= 0 {
+		return strings.TrimSpace(content[:idx])
+	}
+	return content
+}
+
 func (m *Manager) apply(ctx context.Context, req Request) ([]Result, error) {
 	projectDir, err := filepath.Abs(defaultProjectDir(req.ProjectDir))
 	if err != nil {
@@ -835,9 +1015,20 @@ func renderWorkflows(snapshot Snapshot) string {
 	b.WriteString("- Keep durable discoveries, decisions, and risks in AGENTS.md, /docs, or .brain notes.\n")
 	b.WriteString("- Update existing durable notes instead of duplicating context.\n")
 	b.WriteString("- Run required verification commands through `brain session run -- <command>`.\n")
+	b.WriteString("- If you change Brain command behavior or agent-facing workflow guidance, update `skills/brain/SKILL.md` in the same branch.\n")
 	b.WriteString("- Re-read context before large changes if the task shifts.\n\n")
+	b.WriteString("## Ticket Loop\n\n")
+	b.WriteString("1. Start one story or ticket at a time and keep the scope narrow.\n")
+	b.WriteString("2. Implement the story, then run focused tests for the touched packages.\n")
+	b.WriteString("3. Run the required full checks through `brain session run -- go test ./...` and `brain session run -- go build ./...`.\n")
+	b.WriteString("4. Review the diff against the story acceptance criteria and user-facing behavior.\n")
+	b.WriteString("5. If review finds issues, patch the work and repeat the test and review steps.\n")
+	b.WriteString("6. When the story is clean, commit it, push it, and only then move to the next story.\n\n")
 	b.WriteString("## Close-Out\n\n")
 	b.WriteString("- Refresh or update durable notes for meaningful behavior, config, or architecture changes.\n")
+	b.WriteString("- If `skills/brain/` changed, reinstall the local Brain skill for Codex and OpenClaw with `brain skills install --scope local --agent codex --agent openclaw --project .`.\n")
+	b.WriteString("- When opening a PR, make the title and body release-note friendly because GitHub release notes are generated from merged PR metadata.\n")
+	b.WriteString("- Summarize shipped behavior in the PR, not just implementation steps, so future changelogs stay human-readable.\n")
 	b.WriteString("- Finish with `brain session finish`.\n")
 	b.WriteString("- If you must bypass enforcement, use `brain session finish --force --reason \"...\"` so the override is recorded.\n")
 	return b.String()
@@ -918,5 +1109,7 @@ func renderGitIgnore() string {
 .brain/sessions/
 .brain/policy.override.yaml
 .brain/state/
+.codex/skills/
+.openclaw/skills/
 `) + "\n"
 }
diff --git a/internal/projectcontext/manager_test.go b/internal/projectcontext/manager_test.go
index 19228c4..7408ce7 100644
--- a/internal/projectcontext/manager_test.go
+++ b/internal/projectcontext/manager_test.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"os"
 	"path/filepath"
+	"reflect"
 	"strings"
 	"testing"
 )
@@ -161,6 +162,52 @@ func TestInstallDryRunDoesNotWrite(t *testing.T) {
 	}
 }
 
+func TestLoadReturnsDeterministicSourcesByLevel(t *testing.T) {
+	project := t.TempDir()
+	mustWriteFile(t, filepath.Join(project, "go.mod"), "module example.com/test\n\ngo 1.26\n")
+	manager := New(t.TempDir())
+	if _, err := manager.Install(context.Background(), Request{ProjectDir: project}); err != nil {
+		t.Fatal(err)
+	}
+
+	level0, err := manager.Load(LoadRequest{ProjectDir: project, Level: 0})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := []string{"AGENTS.md (summary)", ".brain/context/current-state.md"}; !reflect.DeepEqual(level0.Sources, want) {
+		t.Fatalf("unexpected level 0 sources: got=%v want=%v", level0.Sources, want)
+	}
+	if strings.Contains(level0.Content, ".brain/context/overview.md") {
+		t.Fatalf("expected level 0 to omit overview:\n%s", level0.Content)
+	}
+
+	level1, err := manager.Load(LoadRequest{ProjectDir: project, Level: 1})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := []string{"AGENTS.md (summary)", ".brain/context/current-state.md", ".brain/context/overview.md", ".brain/context/workflows.md"}; !reflect.DeepEqual(level1.Sources, want) {
+		t.Fatalf("unexpected level 1 sources: got=%v want=%v", level1.Sources, want)
+	}
+
+	level2, err := manager.Load(LoadRequest{ProjectDir: project, Level: 2})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := []string{"AGENTS.md", ".brain/context/overview.md", ".brain/context/architecture.md", ".brain/context/standards.md", ".brain/context/workflows.md", ".brain/context/memory-policy.md", ".brain/context/current-state.md"}; !reflect.DeepEqual(level2.Sources, want) {
+		t.Fatalf("unexpected level 2 sources: got=%v want=%v", level2.Sources, want)
+	}
+	if !strings.Contains(level2.Content, "## Source: .brain/context/architecture.md") || !strings.Contains(level2.Content, "## Source: .brain/context/memory-policy.md") {
+		t.Fatalf("expected full static bundle in level 2:\n%s", level2.Content)
+	}
+}
+
+func TestLoadRejectsUnsupportedLevel(t *testing.T) {
+	manager := New(t.TempDir())
+	if _, err := manager.Load(LoadRequest{ProjectDir: t.TempDir(), Level: 9}); err == nil {
+		t.Fatal("expected unsupported level error")
+	}
+}
+
 func TestAdoptMarksUnmanagedFilesAsAdopted(t *testing.T) {
 	project := t.TempDir()
 	mustWriteFile(t, filepath.Join(project, "AGENTS.md"), "manual contract\n")
diff --git a/internal/projectcontext/testdata/gitignore.golden b/internal/projectcontext/testdata/gitignore.golden
index f57dcb7..8feaaff 100644
--- a/internal/projectcontext/testdata/gitignore.golden
+++ b/internal/projectcontext/testdata/gitignore.golden
@@ -3,4 +3,6 @@
 .brain/sessions/
 .brain/policy.override.yaml
 .brain/state/
+.codex/skills/
+.openclaw/skills/
 # brain:end gitignore-session
diff --git a/internal/search/search.go b/internal/search/search.go
index 52a2b6a..907b8ac 100644
--- a/internal/search/search.go
+++ b/internal/search/search.go
@@ -2,8 +2,12 @@ package search
 
 import (
 	"context"
+	"fmt"
 	"math"
+	"regexp"
 	"sort"
+	"strings"
+	"time"
 
 	"brain/internal/embeddings"
 	"brain/internal/index"
@@ -11,32 +15,52 @@ import (
 
 type Result struct {
 	NotePath      string  `json:"note_path"`
+	NoteTitle     string  `json:"note_title,omitempty"`
+	NoteType      string  `json:"note_type,omitempty"`
+	ModifiedAt    string  `json:"modified_at,omitempty"`
 	Heading       string  `json:"heading"`
 	Snippet       string  `json:"snippet"`
 	Score         float64 `json:"score"`
 	LexicalScore  float64 `json:"lexical_score,omitempty"`
 	SemanticScore float64 `json:"semantic_score,omitempty"`
+	RecencyBoost  float64 `json:"recency_boost,omitempty"`
+	TypeBoost     float64 `json:"type_boost,omitempty"`
+	ContextBoost  float64 `json:"context_boost,omitempty"`
 	Source        string  `json:"source,omitempty"`
 }
 
+type Options struct {
+	ActiveTask string
+}
+
 type Engine struct {
 	store    *index.Store
 	embedder embeddings.Provider
 }
 
+var tokenPattern = regexp.MustCompile(`[[:alnum:]_]+`)
+
 func New(store *index.Store, embedder embeddings.Provider) *Engine {
 	return &Engine{store: store, embedder: embedder}
 }
 
 func (e *Engine) Search(ctx context.Context, query string, limit int) ([]Result, error) {
-	return e.search(ctx, query, limit, false)
+	return e.SearchWithOptions(ctx, query, limit, Options{})
 }
 
 func (e *Engine) SearchWithExplain(ctx context.Context, query string, limit int) ([]Result, error) {
-	return e.search(ctx, query, limit, true)
+	return e.SearchWithExplainOptions(ctx, query, limit, Options{})
+}
+
+func (e *Engine) SearchWithOptions(ctx context.Context, query string, limit int, opts Options) ([]Result, error) {
+	return e.search(ctx, query, limit, false, opts)
+}
+
+func (e *Engine) SearchWithExplainOptions(ctx context.Context, query string, limit int, opts Options) ([]Result, error) {
+	return e.search(ctx, query, limit, true, opts)
 }
 
-func (e *Engine) search(ctx context.Context, query string, limit int, explain bool) ([]Result, error) {
+func (e *Engine) search(ctx context.Context, query string, limit int, explain bool, opts Options) ([]Result, error) {
 	fts, err := e.store.SearchFTS(ctx, query, max(limit*3, 15))
 	if err != nil {
 		return nil, err
@@ -47,10 +71,13 @@ func (e *Engine) search(ctx context.Context, query string, limit int, explain bo
 	for i, rec := range fts {
 		lexicalScore := ftsScores[i] * 0.45
 		combined[rec.ChunkID] = &Result{
-			NotePath: rec.NotePath,
-			Heading:  rec.Heading,
-			Snippet:  rec.Snippet,
-			Score:    lexicalScore,
+			NotePath:   rec.NotePath,
+			NoteTitle:  rec.NoteTitle,
+			NoteType:   rec.NoteType,
+			ModifiedAt: rec.ModifiedAt,
+			Heading:    rec.Heading,
+			Snippet:    rec.Snippet,
+			Score:      lexicalScore,
 		}
 		if explain {
 			combined[rec.ChunkID].LexicalScore = lexicalScore
@@ -83,10 +110,13 @@ func (e *Engine) search(ctx context.Context, query string, limit int, explain bo
 						continue
 					}
 					combined[rec.ChunkID] = &Result{
-						NotePath: rec.NotePath,
-						Heading:  rec.Heading,
-						Snippet:  rec.Snippet,
-						Score:    semanticScore,
+						NotePath:   rec.NotePath,
+						NoteTitle:  rec.NoteTitle,
+						NoteType:   rec.NoteType,
+						ModifiedAt: rec.ModifiedAt,
+						Heading:    rec.Heading,
+						Snippet:    rec.Snippet,
+						Score:      semanticScore,
 					}
 					if explain {
 						combined[rec.ChunkID].SemanticScore = semanticScore
@@ -96,6 +126,10 @@ func (e *Engine) search(ctx context.Context, query string, limit int, explain bo
 		}
 	}
 
+	applyRecencyBoosts(combined, explain)
+	applyTypeBoosts(combined, explain)
+	applyContextBoosts(combined, opts.ActiveTask, explain)
+
 	results := make([]Result, 0, len(combined))
 	for _, result := range combined {
 		if explain {
@@ -125,6 +159,142 @@ func (e *Engine) search(ctx context.Context, query string, limit int, explain bo
 	return results, nil
 }
 
+func applyRecencyBoosts(combined map[int64]*Result, explain bool) {
+	if len(combined) == 0 {
+		return
+	}
+	type stampEntry struct {
+		id   int64
+		unix float64
+	}
+	var stamps []float64
+	var parsed []stampEntry
+	for id, result := range combined {
+		if ts, err := time.Parse(time.RFC3339, result.ModifiedAt); err == nil {
+			unix := float64(ts.UTC().Unix())
+			parsed = append(parsed, stampEntry{id: id, unix: unix})
+			stamps = append(stamps, unix)
+		}
+	}
+	norm := normalizeDense(stamps)
+	if len(norm) == 0 {
+		return
+	}
+	for i, entry := range parsed {
+		boost := norm[i] * 0.08
+		combined[entry.id].Score += boost
+		if explain {
+			combined[entry.id].RecencyBoost = boost
+		}
+	}
+}
+
+func applyTypeBoosts(combined map[int64]*Result, explain bool) {
+	for _, result := range combined {
+		boost := noteTypeBoost(result.NoteType)
+		if boost <= 0 {
+			continue
+		}
+		result.Score += boost
+		if explain {
+			result.TypeBoost = boost
+		}
+	}
+}
+
+func applyContextBoosts(combined map[int64]*Result, activeTask string, explain bool) {
+	activeTask = strings.TrimSpace(activeTask)
+	if activeTask == "" {
+		return
+	}
+	taskTokens := tokenize(activeTask)
+	if len(taskTokens) == 0 {
+		return
+	}
+	for _, result := range combined {
+		candidateTokens := tokenize(strings.Join([]string{
+			result.NotePath,
+			result.NoteTitle,
+			result.NoteType,
+			result.Heading,
+			result.Snippet,
+		}, " "))
+		if len(candidateTokens) == 0 {
+			continue
+		}
+		matches := 0
+		for token := range taskTokens {
+			if _, ok := candidateTokens[token]; ok {
+				matches++
+			}
+		}
+		if matches == 0 {
+			continue
+		}
+		boost := (float64(matches) / float64(len(taskTokens))) * 0.07
+		result.Score += boost
+		if explain {
+			result.ContextBoost = boost
+		}
+	}
+}
+
+func noteTypeBoost(noteType string) float64 {
+	switch strings.ToLower(strings.TrimSpace(noteType)) {
+	case "decision":
+		return 0.08
+	case "spec":
+		return 0.07
+	case "change":
+		return 0.06
+	case "epic", "story":
+		return 0.04
+	case "reference", "resource":
+		return 0.02
+	default:
+		return 0
+	}
+}
+
+func tokenize(text string) map[string]struct{} {
+	tokens := tokenPattern.FindAllString(strings.ToLower(text), -1)
+	if len(tokens) == 0 {
+		return nil
+	}
+	out := make(map[string]struct{}, len(tokens))
+	for _, token := range tokens {
+		out[token] = struct{}{}
+	}
+	return out
+}
+
+func BuildContextBlock(results []Result) string {
+	if len(results) == 0 {
+		return "## Relevant Context\n\n- No relevant context found.\n"
+	}
+	seen := map[string]struct{}{}
+	lines := []string{"## Relevant Context", ""}
+	for _, result := range results {
+		if _, ok := seen[result.NotePath]; ok {
+			continue
+		}
+		seen[result.NotePath] = struct{}{}
+		source := fmt.Sprintf("- Source: `%s`", result.NotePath)
+		if result.Heading != "" {
+			source += fmt.Sprintf(" -> `%s`", result.Heading)
+		}
+		snippet := strings.TrimSpace(result.Snippet)
+		if snippet != "" {
+			source += fmt.Sprintf(": %s", snippet)
+		}
+		lines = append(lines, source)
+		if len(seen) >= 5 {
+			break
+		}
+	}
+	return strings.Join(lines, "\n") + "\n"
+}
+
 func cosine(a, b []float32) float64 {
 	if len(a) == 0 || len(a) != len(b) {
 		return 0
diff --git a/internal/search/search_test.go b/internal/search/search_test.go
index 4afd020..9126c5b 100644
--- a/internal/search/search_test.go
+++ b/internal/search/search_test.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"brain/internal/config"
@@ -124,3 +125,236 @@ Basil grows well in warm sunlight with consistent watering.
 		t.Fatalf("expected both score contributions, got %+v", first)
 	}
 }
+
+func TestSearchRecencyBoostPrefersNewerNotes(t *testing.T) {
+	ctx := context.Background()
+	root := t.TempDir()
+	cfg := &config.Config{
+		EmbeddingProvider: "localhash",
+		EmbeddingModel:    "hash-v1",
+		OutputMode:        "human",
+	}
+	workspaceSvc := workspace.New(root)
+	if err := workspaceSvc.Initialize(); err != nil {
+		t.Fatal(err)
+	}
+
+	files := map[string]string{
+		filepath.Join(root, "docs", "older.md"): `---
+title: Older Retrieval Note
+type: resource
+updated: 2026-04-10T00:00:00Z
+---
+# Retrieval
+
+Local retrieval needs observability and ranking.
+`,
+		filepath.Join(root, "docs", "newer.md"): `---
+title: Newer Retrieval Note
+type: resource
+updated: 2026-04-12T00:00:00Z
+---
+# Retrieval
+
+Local retrieval needs observability and ranking.
+`,
+	}
+	for path, content := range files {
+		if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	store, err := index.New(filepath.Join(root, ".brain", "state", "brain.sqlite3"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer store.Close()
+	provider, err := embeddings.New(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := store.Reindex(ctx, workspaceSvc, provider); err != nil {
+		t.Fatal(err)
+	}
+
+	engine := New(store, provider)
+	results, err := engine.SearchWithExplain(ctx, "retrieval observability ranking", 5)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(results) < 2 {
+		t.Fatalf("expected at least 2 results, got %+v", results)
+	}
+	if results[0].NotePath != "docs/newer.md" {
+		t.Fatalf("expected newer note first, got %+v", results)
+	}
+	if results[0].RecencyBoost <= results[1].RecencyBoost {
+		t.Fatalf("expected newer note to get higher recency boost, got %+v", results[:2])
+	}
+}
+
+func TestSearchTypeBoostPrefersDecisionNotes(t *testing.T) {
+	ctx := context.Background()
+	root := t.TempDir()
+	cfg := &config.Config{
+		EmbeddingProvider: "localhash",
+		EmbeddingModel:    "hash-v1",
+		OutputMode:        "human",
+	}
+	workspaceSvc := workspace.New(root)
+	if err := workspaceSvc.Initialize(); err != nil {
+		t.Fatal(err)
+	}
+
+	files := map[string]string{
+		filepath.Join(root, ".brain", "resources", "decisions", "search-strategy.md"): `---
+title: Search Strategy
+type: decision
+updated: 2026-04-12T00:00:00Z
+---
+# Search Strategy
+
+Retrieval ranking should prefer stable project memory.
+`,
+		filepath.Join(root, ".brain", "brainstorms", "search-strategy.md"): `---
+title: Search Strategy Brainstorm
+type: brainstorm
+updated: 2026-04-12T00:00:00Z
+---
+# Search Strategy
+
+Retrieval ranking should prefer stable project memory.
+`,
+	}
+	for path, content := range files {
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	store, err := index.New(filepath.Join(root, ".brain", "state", "brain.sqlite3"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer store.Close()
+	provider, err := embeddings.New(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := store.Reindex(ctx, workspaceSvc, provider); err != nil {
+		t.Fatal(err)
+	}
+
+	engine := New(store, provider)
+	results, err := engine.SearchWithExplain(ctx, "retrieval ranking stable memory", 5)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(results) < 2 {
+		t.Fatalf("expected at least 2 results, got %+v", results)
+	}
+	if results[0].NoteType != "decision" {
+		t.Fatalf("expected decision note first, got %+v", results)
+	}
+	if results[0].TypeBoost <= results[1].TypeBoost {
+		t.Fatalf("expected decision note to get higher type boost, got %+v", results[:2])
+	}
+}
+
+func TestSearchActiveTaskBoostPrefersMatchingWorkContext(t *testing.T) {
+	ctx := context.Background()
+	root := t.TempDir()
+	cfg := &config.Config{
+		EmbeddingProvider: "localhash",
+		EmbeddingModel:    "hash-v1",
+		OutputMode:        "human",
+	}
+	workspaceSvc := workspace.New(root)
+	if err := workspaceSvc.Initialize(); err != nil {
+		t.Fatal(err)
+	}
+
+	files := map[string]string{
+		filepath.Join(root, "docs", "session-distill.md"): `---
+title: Workflow Notes
+type: doc
+updated: 2026-04-12T00:00:00Z
+---
+# Workflow
+
+The workflow should stay explicit and deterministic.
+`,
+		filepath.Join(root, "docs", "release-workflow.md"): `---
+title: Workflow Notes
+type: doc
+updated: 2026-04-12T00:00:00Z
+---
+# Workflow
+
+The workflow should stay explicit and deterministic.
+`,
+	}
+	for path, content := range files {
+		if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	store, err := index.New(filepath.Join(root, ".brain", "state", "brain.sqlite3"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer store.Close()
+	provider, err := embeddings.New(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := store.Reindex(ctx, workspaceSvc, provider); err != nil {
+		t.Fatal(err)
+	}
+
+	engine := New(store, provider)
+	withContext, err := engine.SearchWithExplainOptions(ctx, "workflow explicit deterministic", 5, Options{ActiveTask: "implement session distill memory updates"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(withContext) < 2 {
+		t.Fatalf("expected at least 2 results, got %+v", withContext)
+	}
+	if withContext[0].NotePath != "docs/session-distill.md" {
+		t.Fatalf("expected active-task-matching note first, got %+v", withContext)
+	}
+	if withContext[0].ContextBoost <= 0 {
+		t.Fatalf("expected context boost on matching note, got %+v", withContext[0])
+	}
+
+	withoutContext, err := engine.Search(ctx, "workflow", 5)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(withoutContext) < 2 {
+		t.Fatalf("expected at least 2 baseline results, got %+v", withoutContext)
+	}
+	if strings.TrimSpace(withoutContext[0].NotePath) == "" {
+		t.Fatalf("expected note path in baseline results, got %+v", withoutContext)
+	}
+}
+
+func TestBuildContextBlockDedupesNotes(t *testing.T) {
+	block := BuildContextBlock([]Result{
+		{NotePath: "docs/session.md", Heading: "Overview", Snippet: "Session guidance."},
+		{NotePath: "docs/session.md", Heading: "Details", Snippet: "More details."},
+		{NotePath: "AGENTS.md", Heading: "", Snippet: "Project contract."},
+	})
+
+	if strings.Count(block, "docs/session.md") != 1 {
+		t.Fatalf("expected deduped session note in context block:\n%s", block)
+	}
+	if !strings.Contains(block, "## Relevant Context") || !strings.Contains(block, "AGENTS.md") {
+		t.Fatalf("unexpected context block contents:\n%s", block)
+	}
+}
diff --git a/internal/session/manager.go b/internal/session/manager.go
index 41f364b..72a80b8 100644
--- a/internal/session/manager.go
+++ b/internal/session/manager.go
@@ -219,6 +219,18 @@ func defaultProjectDir(dir string) string {
 	return dir
 }
 
+func (m *Manager) Active(projectDir string) (*ActiveSession, error) {
+	projectDir, err := filepath.Abs(defaultProjectDir(projectDir))
+	if err != nil {
+		return nil, err
+	}
+	policy, _, _, err := projectcontext.LoadPolicy(projectDir)
+	if err != nil {
+		return nil, err
+	}
+	return loadActiveSessionIfExists(filepath.Join(projectDir, filepath.FromSlash(policy.Session.ActiveFile)))
+}
+
 func (m *Manager) Validate(ctx context.Context, req ValidateRequest) (*ValidationResult, error) {
 	projectDir, err := filepath.Abs(defaultProjectDir(req.ProjectDir))
 	if err != nil {
@@ -495,7 +507,8 @@ func (m *Manager) evaluateFinish(ctx context.Context, policy *projectcontext.Pol
 	if result.RepoChanged && policy.Closeout.RequireMemoryUpdateOnRepoChange && result.MemorySatisfiedBy == "" {
 		result.OK = false
 		result.Obligations = append(result.Obligations, "durable note update required for repo changes")
-		result.Remediation = append(result.Remediation, fmt.Sprintf("run `brain edit AGENTS.md ...` or update docs/.brain notes for %s", policy.Project.Name))
+		result.Remediation = append(result.Remediation, "run `brain distill --session` to generate a session-scoped memory proposal")
+		result.Remediation = append(result.Remediation, fmt.Sprintf("review the proposal, apply the durable note updates for %s, then retry `brain session finish`", policy.Project.Name))
 	} else if result.MemorySatisfiedBy == "git_committed_notes" {
 		result.Remediation = append(result.Remediation, "durable notes were already committed in the session commit range")
 	}
diff --git a/internal/session/manager_test.go b/internal/session/manager_test.go
index 50d3688..f64e54c 100644
--- a/internal/session/manager_test.go
+++ b/internal/session/manager_test.go
@@ -293,6 +293,9 @@ func TestValidateFinishStillBlocksCommittedCodeOnlyPublishSession(t *testing.T)
 	if result.MemorySatisfiedBy != "" {
 		t.Fatalf("expected no memory satisfaction source, got %q", result.MemorySatisfiedBy)
 	}
+	if !containsString(result.Remediation, "run `brain distill --session` to generate a session-scoped memory proposal") {
+		t.Fatalf("expected distill remediation, got %v", result.Remediation)
+	}
 }
 
 func TestValidateFinishDoesNotUseCommittedDurableNotesWhenWorktreeDirty(t *testing.T) {
@@ -338,6 +341,15 @@ func TestValidateFinishDoesNotUseCommittedDurableNotesWhenWorktreeDirty(t *testi
 	}
 }
 
+func containsString(values []string, want string) bool {
+	for _, value := range values {
+		if value == want {
+			return true
+		}
+	}
+	return false
+}
+
 func TestSessionCommandHelper(t *testing.T) {
 	idx := -1
 	for i, arg := range os.Args {
diff --git a/internal/templates/templates.go b/internal/templates/templates.go
index 9180800..c38298f 100644
--- a/internal/templates/templates.go
+++ b/internal/templates/templates.go
@@ -145,6 +145,22 @@ Created: {{ .Now }}
 
 ## Resources
 
+## Notes
+`,
+	"decision.md": `# {{ .Title }}
+
+Created: {{ .Now }}
+
+## Context
+
+## Options Considered
+
+## Decision
+
+## Tradeoffs
+
+## Related
+
 ## Notes
 `,
 }
diff --git a/skills/brain/SKILL.md b/skills/brain/SKILL.md
index 6c48936..6c52fd2 100644
--- a/skills/brain/SKILL.md
+++ b/skills/brain/SKILL.md
@@ -62,10 +62,24 @@ Use these commands by default:
   - Inspect index freshness, indexed counts, and the local sqlite path without mutating the index.
 - `brain search --explain "query"`
   - Show lexical and semantic score contributions plus the retrieval source classification for each result.
+- `brain search --inject "query"`
+  - Return ranked results plus an agent-ready `## Relevant Context` block that can be reused directly.
+- `brain distill --session`
+  - Create a session-scoped distill proposal note with source provenance and suggested durable note updates.
+- `brain distill --brainstorm <path>`
+  - Create the same style of proposal note from a brainstorm source.
 - `brain brainstorm ...`
   - Manage project-local brainstorming notes.
 - `brain plan ...`
   - Manage project-local epics, specs, and stories with a spec-driven workflow.
+- `brain context load --level 0`
+  - Load the minimal AGENTS summary plus current state.
+- `brain context load --level 1`
+  - Add overview and workflows to the minimal context bundle.
+- `brain context load --level 2`
+  - Load the full static context bundle.
+- `brain context load --level 3 --query "..."`
+  - Load the full static bundle plus search-injected relevant context. If a session is active, the task can stand in for `--query`.
 - `brain context install --project .`
   - Create or adopt the root contract plus `.brain/context`.
 - `brain context refresh --project .`
@@ -95,9 +109,32 @@ Use these commands by default:
 2. `brain search "<task or concept>"` for ranked results.
 3. `brain search status` when results look stale, missing, or surprising.
 4. `brain search --explain "<task or concept>"` when you need to inspect ranking behavior.
-5. `brain read <path>` for the winning notes.
-6. Re-run search after meaningful note updates when you need the latest local state reflected. Brain will rebuild the local index automatically only when it is stale or missing.
-7. If retrieval quality matters, check which provider is active in `brain doctor` or `brain search status` before assuming the project is using a strong hosted semantic model.
+5. `brain search --inject "<task or concept>"` when you need a compact context block to pass straight into the next step.
+6. `brain read <path>` for the winning notes when the injected block is not enough.
+7. Re-run search after meaningful note updates when you need the latest local state reflected. Brain will rebuild the local index automatically only when it is stale or missing.
+8. If retrieval quality matters, check which provider is active in `brain doctor` or `brain search status` before assuming the project is using a strong hosted semantic model.
+
+## Context Workflow
+
+1. `brain context load --level 0` for minimal startup context.
+2. `brain context load --level 1` when you need summaries and workflows.
+3. `brain context load --level 2` when the task needs the full static context bundle.
+4. `brain context load --level 3 --query "<task or concept>"` when you need search-driven deep context.
+5. Prefer requesting the next level explicitly instead of loading everything up front.
+
+## Distillation Workflow
+
+1. Run `brain distill --session` when a working session surfaced decisions, tradeoffs, bugs, or discoveries that should become durable memory.
+2. Run `brain distill --brainstorm <path>` when a brainstorm should collapse into proposed durable note updates.
+3. Review the proposal note under `.brain/resources/changes/`.
+4. Apply the durable note updates with `brain edit` or by updating the target notes directly after review.
+5. Treat distill as a proposal generator, not as an auto-write path.
+
+## Session Recovery
+
+- If `brain session finish` blocks on missing durable memory updates, run `brain distill --session`.
+- Review the proposal, update the durable notes that matter, then retry `brain session finish`.
+- Keep using `brain session run -- <command>` for required verification commands before closeout.
 
 ## When Not To Use This Skill