docs: scrub public wording for v0.8.5 handoff

Author: Paul Kyle

PROGRAM.md

@@ -54,7 +54,7 @@ Extract only things that will be useful **across sessions** — facts that a fut
 
 **Commitments and action items** — things promised to people, deadlines agreed to, follow-ups needed.
 
-- *Example:* "Alice will follow up with legal about copyright clearance." → ActionItem.
+- *Example:* "Alice will follow up with legal about the licensing review." → ActionItem.
 - *Example:* "Q3 Marketing Launch due Week 10 (April 14)." → ActionItem linked to project/marketing-launch.
 
 ### Sometimes extract
@@ -299,7 +299,7 @@ The canonical form of an entity reference is **lowercase, hyphens-not-spaces, `k
 
 - `person/alice-smith` (not `Person/Alice Smith`, not `alice_smith`, not `alice smith`)
 - `project/palinode`
-- `decision/tools-over-pipeline`
+- `decision/reviewability-over-speed`
 - `insight/curation-beats-volume`
 
 The body `[[wikilink]]` may be the human-readable label (`[[Alice Smith]]`) or the slug (`[[alice-smith]]`) — both resolve to the same target file. Whichever you write, the corresponding `entities:` value is always the canonical `kind/slug` form. A body line `Met with [[Alice Smith]] about Q3 planning` requires `entities: [person/alice-smith]` in the frontmatter.

README.md

@@ -42,7 +42,7 @@ Index (SQLite-vec vectors + FTS5 keywords, single .db file)
   ↓ queried by
 Interfaces (MCP server, REST API, CLI, OpenClaw plugin)
   ↓ compacted by
-LLM (proposes ops → deterministic executor applies them → git commits)
+LLM (suggests updates → Palinode validates and writes them → git commits)
 ```
 
 That's the whole architecture. One directory of `.md` files, one SQLite database, one API server. No Postgres, no Redis, no cloud dependency.
@@ -82,7 +82,7 @@ That's the entire client config. Works with Claude Code, Claude Desktop, Cursor,
 
 **Search** — Hybrid BM25 + vector search merged with Reciprocal Rank Fusion. Keyword precision when you need exact terms, semantic recall when you don't. Optional associative entity graph and prospective triggers.
 
-**Compact** — Weekly consolidation where an LLM proposes structured operations (KEEP / UPDATE / MERGE / SUPERSEDE / ARCHIVE) and a deterministic executor applies them. The LLM never touches your files directly. Every compaction is a git commit you can review, blame, or revert.
+**Compact** — Weekly consolidation where an LLM suggests structured memory updates and Palinode applies the validated result to your files. Every compaction is a git commit you can review, blame, or revert.
 
 **Audit** — `git blame` any fact. `git diff` any change. `rollback` any mistake. These aren't just git-compatible files — `palinode_diff`, `palinode_blame`, and `palinode_rollback` are first-class tools your agent can call.
 
@@ -369,7 +369,7 @@ Optional: a chat model for consolidation (any 7B+ works), OpenClaw for agent plu
 - **Your data, your files** — No accounts, no cloud dependency, no vendor lock-in. Your memory is markdown files in a directory you control. Export is `cp`. Backup is `git push`. Whatever happens to any tool in this ecosystem, your data is plain text on your filesystem.
 - **Cross-IDE memory** — Your memory lives in one place. Connect from Claude Code, Cursor, Windsurf, Zed, or any MCP-compatible editor. Switch IDEs without losing context.
 - **Git operations as agent tools** — `diff`, `blame`, `rollback`, `push` exposed via MCP. No other system makes git ops callable by the agent.
-- **Operation-based compaction** — KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE DSL. The LLM proposes structured operations and the deterministic executor applies them. Every compaction is a reviewable git commit.
+- **Reviewable compaction** — The LLM suggests structured memory updates and Palinode applies validated changes with full git history. Every compaction is a reviewable git commit.
 - **Per-fact addressability** — `<!-- fact:slug -->` IDs inline in markdown, invisible in rendering, preserved by git, targetable by compaction.
 - **4-phase injection** — Core (always) + Topic (per-turn search) + Associative (entity graph) + Triggered (prospective recall).
 - **Multi-transport MCP** — stdio for local, Streamable HTTP for remote. One server, any IDE on any machine.

docs/CHANGELOG.md

@@ -118,7 +118,7 @@ Bug-fix release with small UX additions. Brings the public repo up to date with
 
 ## [0.5.0] — 2026-04-10
 
-First tagged release. Persistent memory for AI agents with git-versioned markdown as source of truth, hybrid SQLite-vec + FTS5 search, and LLM-driven consolidation applied by a deterministic executor.
+First tagged release. Persistent memory for AI agents with git-versioned markdown as source of truth, hybrid SQLite-vec + FTS5 search, and LLM-driven consolidation with reviewable git-backed updates.
 
 ### Added
 
@@ -129,7 +129,7 @@ First tagged release. Persistent memory for AI agents with git-versioned markdow
 - File watcher daemon with debounced reindex and fault isolation
 
 **Consolidation and compaction**
-- Deterministic executor applying `KEEP` / `UPDATE` / `MERGE` / `SUPERSEDE` / `ARCHIVE` operations proposed by an LLM
+- Reviewable consolidation engine applying structured memory updates proposed by an LLM
 - Weekly full-corpus consolidation with configurable LLM backend
 - Nightly lightweight consolidation pass (`--nightly` flag) bounded to `UPDATE`/`SUPERSEDE` for safer incremental updates
 - Model fallback chains — primary → fallback → fallback on timeout or HTTP error
@@ -161,7 +161,7 @@ First tagged release. Persistent memory for AI agents with git-versioned markdow
 - Exclude-paths list prevents search results from surfacing files in `.secrets`, `credentials`, etc.
 
 **Documentation**
-- Architecture decision records covering the deterministic executor design
+- Design and setup docs covering consolidation, provenance, and deployment
 - Remote MCP setup guides for Claude Code, Claude Desktop, Cursor, Zed
 - Example memory files (`examples/people/`, `examples/projects/`, `examples/decisions/`, `examples/insights/`)
 - Compaction walkthrough (`examples/compaction-demo/`) — a memory file across 3 passes with blame + diff output

docs/OBSIDIAN.md

@@ -158,7 +158,7 @@ Given a draft about to be saved, returns the top-K existing files whose embeddin
 
 ### `palinode_orphan_repair`
 
-Given a `[[wikilink]]` whose target file does not exist, returns existing files semantically near the link target text. The LLM proposes a redirect to one of those files, or creates the target with the candidate's content as scaffolding rather than starting cold.
+Given a `[[wikilink]]` whose target file does not exist, returns existing files semantically near the link target text. The agent can redirect to one of those files, or create the target with the candidate's content as scaffolding rather than starting cold.
 
 - **Default threshold:** ≥ 0.65 cosine — more permissive than dedup because a wider candidate slate helps the LLM choose.
 

docs/WHY-LOCAL-MEMORY.md

@@ -18,7 +18,7 @@ Cloud vendors will ship memory. It will live on their servers, be opaque, and be
 | Portability | Locked to one platform | Works across any MCP client |
 | Ownership | Vendor controls retention | You control everything |
 | Offline access | No | `cat` and `grep` always work |
-| Consolidation | Black box | Deterministic executor with reviewable ops |
+| Consolidation | Black box | Reviewable file updates with git provenance |
 
 ## The case for transparency
 

examples/compaction-demo/README.md

@@ -1,6 +1,6 @@
 # Compaction Demo — Watching a Memory File Consolidate
 
-This directory walks through a realistic scenario: a team debating REST vs GraphQL for a new checkout API over several weeks, with the decision recorded as it evolves. You see the raw daily-note accretion, then the deterministic executor applying consolidation operations, and finally the clean state.
+This directory walks through a realistic scenario: a team debating REST vs GraphQL for a new checkout API over several weeks, with the decision recorded as it evolves. You see the raw daily-note accretion, then Palinode applying reviewable consolidation updates, and finally the clean state.
 
 The key thing to notice: **every change is a git commit, and every line can be blamed back to the session where the fact was first recorded.** That's the "git your agent's brain" pitch, made concrete.
 
@@ -22,13 +22,13 @@ Alice and Bob are building a mobile checkout flow (`projects/my-app.md`). Over t
 
 Start with `pass-0-initial.md` and notice the mess — every session-end hook append adds another status line, contradictions don't resolve themselves, and old `[ ]` todos stick around long after they're done.
 
-Then open `pass-1-after-update-supersede.md` side-by-side. The executor preserved every original line's provenance but corrected outdated claims (SUPERSEDE) and tightened wording (UPDATE). Note the `<!-- supersede: ... -->` comments — those aren't just documentation, they're structured metadata the executor writes so that the next pass knows what it's looking at.
+Then open `pass-1-after-update-supersede.md` side-by-side. Palinode preserved every original line's provenance but corrected outdated claims (SUPERSEDE) and tightened wording (UPDATE). Note the `<!-- supersede: ... -->` comments — those aren't just documentation, they're structured metadata the system writes so that the next pass knows what it's looking at.
 
 Then `pass-2-after-merge-archive.md` shows what you'd actually want to read if you opened the file fresh. Related facts have been merged into single lines. Archived entries are gone from this file but preserved in `archive/2026/my-app-status.md` — nothing is deleted, just moved out of the way.
 
 Finally `blame-output.txt` is the demo's money shot: **every line has a commit, and every commit has a session.** You can answer "when did we decide X?" and "which session first mentioned Y?" without remembering — git remembers for you.
 
-## What the executor actually did
+## What the system actually did
 
 Between pass 0 and pass 1 (13 operations):
 - 6 × `UPDATE` — tightened wording on stale-but-still-true status lines
@@ -41,7 +41,7 @@ Between pass 1 and pass 2 (9 operations):
 - 4 × `ARCHIVE` — moved superseded entries to `archive/2026/my-app-status.md`
 - 2 × `UPDATE` — final wording pass on merged lines
 
-All 22 operations were **proposed by an LLM** but **applied by deterministic Python** (`palinode/consolidation/executor.py`). The LLM never touches the file directly — it only emits JSON like `{"op": "SUPERSEDE", "id": "f-0317-1", "superseded_by": "f-0324-2", "reason": "stripe integration actually shipped on the 24th"}` and the executor validates and applies it. That's the core tools-over-pipeline invariant in action.
+All 22 operations were **proposed by an LLM** and then **validated and applied by Palinode's consolidation code** (`palinode/consolidation/executor.py`). The LLM never touches the file directly — it only emits JSON like `{"op": "SUPERSEDE", "id": "f-0317-1", "superseded_by": "f-0324-2", "reason": "stripe integration actually shipped on the 24th"}` and Palinode turns that into reviewable file changes.
 
 ## Why this matters