Release next: capture/read hardening and Think Echo backlog

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Report a bug
+---
+
+## Description
+
+<!-- What happened? -->
+
+## Steps to reproduce
+
+1.
+2.
+
+## Expected behavior
+
+<!-- What should have happened? -->
+
+## Environment
+
+- OS:
+- Node version:
+- Think version:

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+## Summary
+
+<!-- What changed and why -->
+
+## Test plan
+
+- [ ] `npm run lint` passes
+- [ ] `npm run test:ports` passes
+- [ ] `npm run test:m1` passes
+- [ ] Docs updated if user-facing

.github/workflows/ci.yml

@@ -20,8 +20,8 @@ jobs:
       matrix:
         node-version: [22]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
         with:
           node-version: ${{ matrix.node-version }}
           cache: npm

.github/workflows/release.yml

@@ -17,8 +17,8 @@ jobs:
   sanity:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
         with:
           node-version: 22
           cache: npm
@@ -49,7 +49,7 @@ jobs:
     needs: sanity
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
 

AGENTS.md

@@ -19,6 +19,7 @@ Do not audit the repository by recursively walking the filesystem. Follow the au
 
 ### 2. The Bedrock
 - **`ARCHITECTURE.md`**: The authoritative structural reference (Git, WARP, Minds).
+- **`docs/INFRASTRUCTURE_DOCTRINE.md`**: The runtime-first engineering standards (MANDATORY).
 - **`docs/VISION.md`**: Core tenets and the capture doctrine.
 - **`docs/method/process.md`**: Repo work doctrine (Backlog lanes, Cycle loop).
 

CHANGELOG.md

@@ -10,6 +10,15 @@ Release discipline:
 - `package.json` version is bumped on the release commit
 - a Git tag is created on the commit that lands on `main` for that release
 
+## Unreleased
+
+- fixed MCP tool result envelopes so structured content matches each registered output schema again
+- fixed checkpoint-backed reads to use public `@git-stunts/git-warp` package exports instead of private `node_modules` internals
+- fixed cached writer retries across raw capture follow-through, annotations, reflect writes, migrations, and enrichment patches
+- fixed enrichment search-index invalidation and per-repo cache scoping, and counted semantic-parse receipts in enrichment results
+- documented `--annotate`, `--enrich`, and `--topics` in CLI help and validated stray positional text for enrichment/topic commands
+- cleaned whitespace in the infrastructure doctrine and reflect command source so diff checks pass
+
 ## [0.7.0] - 2026-04-11
 
 - added `think --doctor` health check command — reports think directory, local repo, graph model version, entry count, and upstream reachability (with `git ls-remote` connectivity test)

CONTRIBUTING.md

@@ -90,7 +90,7 @@ npm run benchmark:browse
 
 ## Coding standard
 
-New JavaScript should follow [System-Style JavaScript](./docs/SYSTEMS_STYLE_JAVASCRIPT.md): runtime-backed domain concepts, boundary validation, explicit ownership of behavior, and narrow seams instead of object-shape soup.
+New JavaScript should follow **[Infrastructure Doctrine](./docs/INFRASTRUCTURE_DOCTRINE.md)** and [System-Style JavaScript](./docs/SYSTEMS_STYLE_JAVASCRIPT.md): runtime-backed domain concepts, boundary validation, explicit ownership of behavior, and narrow seams instead of object-shape soup.
 
 Read [`ARCHITECTURE.md`](./ARCHITECTURE.md) before making structural changes. Do not let storage concerns leak into normal UX, and do not let surface-specific concerns infect the capture core.
 

GUIDE.md

@@ -26,7 +26,7 @@ Return to your archive through high-fidelity browse or context-aware recall.
 
 ### 4. Pressure-Testing (Reflect)
 Move beyond simple capture by challenging your ideas through structured prompt families.
-- **Run**: `think --reflect`
+- **Run**: `think --reflect` (CLI-only; MCP reflect is not yet available)
 - **Modes**: `challenge`, `constraint`, `sharpen`
 
 ## Big Picture: System Orchestration
@@ -40,7 +40,7 @@ Think is a tiered engine designed to keep capture cheap while enabling rich re-e
 ## Orientation Checklist
 
 - [ ] **I am setting up a new machine**: Start with `README.md` Quick Start.
-- [ ] **I want to separate my agent's thoughts**: Use `THINK_REPO_DIR` in an agent wrapper script.
+- [ ] **I want to separate my agent's thoughts**: See [Mind Orchestration](./docs/MIND_ORCHESTRATION.md) for the multi-mind pattern.
 - [ ] **I need to backup my archive**: Configure `THINK_UPSTREAM_URL`.
 - [ ] **I am debugging the TUI**: Start with `ADVANCED_GUIDE.md`.
 - [ ] **I am contributing to Think**: Read `docs/method/process.md` and `docs/BEARING.md`.

README.md

@@ -21,7 +21,7 @@ Unlike traditional note-taking apps that prioritize organization over ingestion,
 ## Quick Start
 
 ### 1. Local Setup
-Clone, install dependencies, and capture your first thought.
+Requires **Node.js >= 22** and **Git**. Clone, install, capture.
 ```bash
 npm install
 node ./bin/think.js "first captured thought"

docs/AMBIENT_CONTEXT.md

@@ -0,0 +1,121 @@
+# Ambient Context and Recall
+
+How Think collects, persists, and uses project context for capture
+provenance and recall matching.
+
+## Overview
+
+When a thought is captured, Think records the ambient project context
+— the working directory, git remote, branch, and derived project
+tokens — alongside the raw text. This context powers `--remember`,
+which matches prior thoughts by project affinity rather than requiring
+explicit search terms.
+
+## Collection
+
+Two levels of context are collected at different points in the capture
+flow:
+
+### Capture ambient context (`getCaptureAmbientContext`)
+
+Collected synchronously during `saveRawCapture`. Cheap — no git
+probes.
+
+| Field | Source | Notes |
+|-------|--------|-------|
+| `cwd` | `path.resolve(cwd)` | Resolved working directory |
+| `projectName` | Derived from cwd basename | Fallback when no git |
+| `projectTokens` | Derived from projectName | Lowercased, split on non-alphanumeric |
+
+### Full ambient context (`getAmbientProjectContext`)
+
+Collected during `finalizeCapturedThought` follow-through. Runs three
+`git` probes via `spawnSync`:
+
+| Field | Git command | Notes |
+|-------|-------------|-------|
+| `gitRoot` | `rev-parse --show-toplevel` | Absolute path to repo root |
+| `gitRemote` | `config --get remote.origin.url` | Origin remote URL |
+| `gitBranch` | `branch --show-current` | Current branch name |
+| `projectName` | Derived from gitRemote → gitRoot → cwd | Priority order |
+| `projectTokens` | All candidates, lowercased, split | Used for recall matching |
+
+### Resolution priority
+
+The `projectName` is derived in priority order:
+1. Last segment of `gitRemote` URL (sans `.git`)
+2. Basename of `gitRoot`
+3. Basename of `cwd`
+
+### Where resolution happens
+
+The CLI and MCP layers resolve ambient context at the boundary
+(`process.cwd()`) and pass it into the store functions. The store
+layer does not read `process.cwd()` or shell out to git directly.
+
+## Persistence
+
+Context fields are stored as WARP node properties on the entry:
+
+| Property | Source |
+|----------|--------|
+| `ambientCwd` | `cwd` |
+| `ambientGitRoot` | `gitRoot` (follow-through only) |
+| `ambientGitRemote` | `gitRemote` (follow-through only) |
+| `ambientGitBranch` | `gitBranch` (follow-through only) |
+
+The two-phase write means `ambientCwd` is available immediately after
+capture, while git fields are backfilled during follow-through. This
+preserves capture latency.
+
+## Recall matching (`--remember`)
+
+### Ambient recall (no query)
+
+`buildAmbientRememberScope(cwd)` resolves the current project context
+and matches stored entries by affinity:
+
+| Match kind | Condition | Score | Tier |
+|------------|-----------|-------|------|
+| `ambient_git_remote` | Entry's `ambientGitRemote` matches current | 100 | 3 |
+| `ambient_git_root` | Entry's `ambientGitRoot` matches current | 50 | 3 |
+| `ambient_cwd` | Entry's `ambientCwd` matches current | 25 | 3 |
+| `ambient_git_branch` | Entry's `ambientGitBranch` matches current | 15 | 3 |
+| `project_tokens_text` | Entry text contains any current project token | 5 per token | 3 |
+
+Results are sorted by score (highest first), then by recency.
+
+### Explicit recall (with query)
+
+`buildExplicitRememberScope(query)` splits the query into terms and
+matches against entry text. Terms are lowercased and split on
+non-alphanumeric boundaries.
+
+| Match kind | Condition | Score |
+|------------|-----------|-------|
+| `query_terms` | Entry text contains query terms | 1 per term |
+
+### Provenance
+
+Capture provenance (`CaptureProvenance`) is separate from ambient
+context. It records how the thought entered the system:
+
+| Field | Source | Values |
+|-------|--------|--------|
+| `ingress` | Capture surface | `url`, `shortcut`, `selected_text`, `share` |
+| `sourceApp` | Originating application | Free text (trimmed) |
+| `sourceURL` | Source URL | `http:` or `https:` only |
+
+Provenance is normalized at the boundary via
+`normalizeCaptureProvenance` and persisted as entry properties
+(`captureIngress`, `captureSourceApp`, `captureSourceURL`).
+
+## Files
+
+| File | Role |
+|------|------|
+| `src/project-context.js` | Collection and token generation |
+| `src/capture-provenance.js` | Provenance normalization |
+| `src/store/capture.js` | Persistence (saveRawCapture, finalize) |
+| `src/store/remember.js` | Recall scope and matching |
+| `src/store/queries.js` | Query execution (rememberThoughts) |