Merge branch 'dev'

# Conflicts:
#	almanac/README.md
#	almanac/architecture/providers.md
#	almanac/getting-started.md

Author: kushagrchitkar

almanac/README.md

@@ -32,7 +32,7 @@ Begin with [Getting started](getting-started). It gives the shortest reading pat
 
 The core idea is the [local repo wiki](concepts/local-repo-wiki): a browseable Markdown wiki committed with the code, plus derived local state for search and runs. That concept explains why page identity comes from paths, why `README.md` files are landing pages, and why file evidence belongs in `sources:`.
 
-For implementation work, read [Service boundaries](architecture/service-boundaries). It explains how the CLI, app composition root, workflows, services, stores, ports, and integrations divide responsibility. For command behavior, use [CLI public command surface](reference/cli/public-command-surface).
+For implementation work, read [Service boundaries](architecture/service-boundaries). It explains how the CLI, app composition root, workflows, services, stores, ports, and integrations divide responsibility. For command behavior, use [CLI public command surface](reference/cli/public-command-surface). For config defaults and precedence, use [Config keys](reference/config-keys).
 
 ## Main Clusters
 

almanac/getting-started.md

@@ -54,6 +54,7 @@ Before editing pages, read the relevant manual files under `src/codealmanac/manu
 Use these routes when you already know the kind of work:
 
 - For command behavior, read [CLI public command surface](reference/cli/public-command-surface).
+- For config defaults, model choices, and precedence, read [Config keys](reference/config-keys).
 - For page identity, routes, and `README.md` landing pages, read [Page identity](architecture/wiki/page-identity).
 - For page evidence and frontmatter, read [Frontmatter and sources](reference/page-format/frontmatter-and-sources).
 - For lifecycle run state, logs, and attach behavior, read [Run states and events](reference/runs/run-states-and-events).

docs/plans/2026-07-07-hide-provider-text-deltas.md

@@ -0,0 +1,152 @@
+# Hide Future Provider Text Deltas Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Stop future CodeAlmanac jobs from persisting token-by-token assistant text deltas in run logs.
+
+**Architecture:** Codex and Claude may continue to emit `TEXT_DELTA` harness events because those are real provider stream events. The operation runner decides which harness events become durable product history. `TEXT_DELTA` is live-only stream material, so the operation runner skips it when recording run events.
+
+**Tech Stack:** Python 3.12, Pydantic models, SQLite run event store, pytest, Ruff.
+
+---
+
+## Product Decision
+
+`TEXT_DELTA` is not durable product history.
+
+Persist:
+
+- `TEXT`
+- `TOOL_USE`
+- `TOOL_RESULT`
+- `TOOL_SUMMARY`
+- `PROVIDER_SESSION`
+- `CONTEXT_USAGE`
+- `WARNING`
+- `ERROR`
+- `DONE`
+- agent trace events
+- run status events
+
+Do not persist:
+
+- `TEXT_DELTA`
+
+This is provider-neutral. It applies to Codex and Claude.
+
+## Scope
+
+This affects future jobs created by:
+
+- `codealmanac init`
+- `codealmanac ingest`
+- `codealmanac garden`
+- ingest jobs created by `codealmanac sync`
+- scheduled sync ingest jobs
+- scheduled garden jobs
+
+This does not affect:
+
+- old jobs already stored in the database
+- provider transcripts
+- Codex/Claude adapters
+- viewer/server read paths
+- read-only commands such as `search`, `show`, `topics`, `health`, `validate`,
+  `serve`, `config`, `automation`, `update`, `doctor`, and `list`
+
+## Out Of Scope
+
+- No old-log filtering.
+- No database migration.
+- No live typing renderer.
+- No `--raw` mode.
+- No delta coalescing.
+- No provider adapter changes.
+
+Old jobs that already persisted `TEXT_DELTA` rows can remain noisy because the
+product is not in public use yet.
+
+## Implementation
+
+### Step 1: Add A Predicate
+
+Modify:
+
+```text
+src/codealmanac/workflows/operations/harness.py
+```
+
+Add:
+
+```python
+def should_record_harness_event(event: HarnessEvent) -> bool:
+    return event.kind != HarnessEventKind.TEXT_DELTA
+```
+
+This function answers:
+
+```text
+Should this provider event become durable job history?
+```
+
+### Step 2: Use It At The Operation Boundary
+
+Modify:
+
+```text
+src/codealmanac/workflows/operations/service.py
+```
+
+Change:
+
+```python
+for event in harness_events(harness):
+    self.record(...)
+```
+
+to:
+
+```python
+for event in harness_events(harness):
+    if not should_record_harness_event(event):
+        continue
+    self.record(...)
+```
+
+### Step 3: Add Regression Coverage
+
+Modify:
+
+```text
+tests/test_ingest_workflow.py
+```
+
+Add `TEXT_DELTA` events before the existing completed `TEXT` event in
+`EventfulHarnessAdapter`.
+
+Assert the run log still contains the completed assistant message and no
+`TEXT_DELTA` harness events.
+
+## Verification
+
+Targeted:
+
+```bash
+uv run pytest tests/test_ingest_workflow.py::test_ingest_workflow_records_normalized_harness_events -q
+uv run pytest tests/test_ingest_workflow.py tests/test_codex_app_server_adapter.py tests/test_claude_adapter.py -q
+```
+
+Full:
+
+```bash
+uv run ruff check .
+uv run pytest -q
+uv run codealmanac validate
+```
+
+Expected:
+
+- Future runs no longer persist `TEXT_DELTA`.
+- Full assistant `TEXT` messages still persist.
+- Tool/status/error/usage events still persist.
+- Existing noisy jobs remain unchanged.

src/codealmanac/workflows/operations/harness.py

@@ -25,6 +25,10 @@ def harness_events(result: HarnessRunResult) -> tuple[HarnessEvent, ...]:
     return (terminal_harness_event(result.kind, result.status, result.output_text),)
 
 
+def should_record_harness_event(event: HarnessEvent) -> bool:
+    return event.kind != HarnessEventKind.TEXT_DELTA
+
+
 def harness_run_event_kind(event: HarnessEvent) -> RunEventKind:
     if event.kind == HarnessEventKind.ERROR:
         return RunEventKind.ERROR

src/codealmanac/workflows/operations/service.py

@@ -21,6 +21,7 @@
     first_line,
     harness_events,
     harness_run_event_kind,
+    should_record_harness_event,
     validate_harness_result,
 )
 from codealmanac.workflows.operations.models import OperationContext, OperationResult
@@ -169,6 +170,8 @@ def record_harness_events(
         harness: HarnessRunResult,
     ) -> None:
         for event in harness_events(harness):
+            if not should_record_harness_event(event):
+                continue
             self.record(
                 RecordOperationEventRequest(
                     context=context,

tests/test_ingest_workflow.py

@@ -104,6 +104,26 @@ def run(self, request: RunHarnessRequest) -> HarnessRunResult:
         return result.model_copy(
             update={
                 "events": (
+                    HarnessEvent(
+                        kind=HarnessEventKind.TEXT_DELTA,
+                        message="agent ",
+                        actor=HarnessRunActor(
+                            thread_id="root-thread",
+                            role=HarnessActorRole.ROOT,
+                            confidence=HarnessActorConfidence.PROVIDER,
+                            label="Main",
+                        ),
+                    ),
+                    HarnessEvent(
+                        kind=HarnessEventKind.TEXT_DELTA,
+                        message="read ",
+                        actor=HarnessRunActor(
+                            thread_id="root-thread",
+                            role=HarnessActorRole.ROOT,
+                            confidence=HarnessActorConfidence.PROVIDER,
+                            label="Main",
+                        ),
+                    ),
                     HarnessEvent(
                         kind=HarnessEventKind.TEXT,
                         message="agent read source note",
@@ -423,6 +443,11 @@ def test_ingest_workflow_records_normalized_harness_events(
     assert log[-3].harness_event.agent_trace.child_thread_id == "helper-thread"
     assert log[-2].harness_event is not None
     assert log[-2].harness_event.provider_session_id == "root-thread"
+    assert all(
+        entry.harness_event is None
+        or entry.harness_event.kind != HarnessEventKind.TEXT_DELTA
+        for entry in log
+    )
 
 
 def test_ingest_prompt_includes_git_source_runtime(