Polish docs and arbiter language

Author: trilltino

JUDGE_FIX_PLAN.md

@@ -14,7 +14,7 @@ The remaining items are external setup (fund a live LLM provider) or larger foll
 | P0 | LLM is currently fallback | The thesis is "AI agents buying/selling reads"; deterministic fallback weakens the product story on video. | External: top up Anthropic or set `LLM_PROVIDER=openai` with a funded OpenAI key. | S |
 | P1 | Market is effectively 1:1 | One buyer plus one seller is coordination, not a market. | Done: `round.ts` launches three TxODDS seller personas; specialist is priced to win. | S |
 | P1 | Seller agent has legacy generic services | CoinGecko/Jupiter/news code distracts from the TxODDS story. | Done: `service.ts` is TxODDS-only and seller docs describe legacy helpers as outside the loop. | S |
-| P1 | Arbiter is centralized | One proxy-controlled arbiter key makes "trustless" easy to challenge. | Done in docs: described as arbiter-gated with a trusted neutral arbiter, not decentralized arbitration. | S |
+| P1 | Arbiter is centralized | One proxy-controlled arbiter key makes overbroad settlement claims easy to challenge. | Done in docs: described as arbiter-gated with a trusted neutral arbiter. | S |
 | P2 | Product value is thin | The read restates de-margined odds; there is not yet a real betting edge. | Be honest now; stretch goal is bookmaker comparison for true edge. | L |
 | P2 | No Rust CI | Devnet tests cannot run in Actions, so contract regressions are not caught in CI. | Add LiteSVM/Mollusk contract tests. | M |
 | P2 | Free TxLINE tier is brittle | Intermittent feed/tokens can undermine demos. | Keep fallback data, document the dependency, and prefer a warmed token/session before recording. | S |
@@ -97,13 +97,12 @@ base escrow path. That means the best innovations are absent from the multi-agen
 
 ## P1: Tighten Arbiter Language
 
-**Problem:** a single arbiter key controlled by the proxy is not decentralized.
+**Problem:** a single arbiter key controlled by the proxy is a trusted neutral party.
 
 **Fix:**
 
-- Avoid saying simply "trustless" without qualification.
-- Prefer "arbiter-gated", "buyer cannot unilaterally claw back", and "trustless between buyer and seller, with a trusted neutral arbiter".
-- Document production upgrades: staked arbiters, multisig arbiters, decentralized oracle set.
+- Avoid wording that implies the arbiter has no trusted keypair.
+- Prefer "arbiter-gated", "buyer cannot unilaterally claw back", and "trusted neutral arbiter".
 
 ## P2: Product Depth
 

LLM.md

@@ -1,58 +1,58 @@
-# LLMs — what they do, and how to switch provider / keys
+# LLMs - what they do, and how to switch provider / keys
 
-The kit is **provider-agnostic**. One shim — [`packages/agent-runtime/src/llm/complete.ts`](packages/agent-runtime/src/llm/complete.ts)
-— makes a single `fetch` call (no vendor SDK) and supports **Anthropic** (default) and **OpenAI**. You
-flip the whole demo between them with **env vars only — no code change**.
+The kit is **provider-agnostic**. One shim - [`packages/agent-runtime/src/llm/complete.ts`](packages/agent-runtime/src/llm/complete.ts)
+- makes a single `fetch` call (no vendor SDK) and supports **Anthropic** (default) and **OpenAI**. You
+flip the whole demo between them with **env vars only - no code change**.
 
 ## Where the LLM is used
 
 | Where | What it does | Falls back to |
 |-------|--------------|---------------|
-| **The read** — `analyzeEdge()` ([`agent/edge.ts`](examples/txodds/agent/edge.ts)) → `complete()` | turns the verified fair line into a one-line read + confidence | a **deterministic** read (favourite by probability) — so the demo never breaks |
-| **The CoralOS round** — the seller's `edge` delivery ([`coral-agents/seller-agent`](coral-agents/seller-agent)) | the seller runs the same edge over MCP | a deterministic delivery |
+| **The read** - `analyzeEdge()` ([`agent/edge.ts`](examples/txodds/agent/edge.ts)) -> `complete()` | turns the verified fair line into a one-line read + confidence | a **deterministic** read (favourite by probability) - so the demo never breaks |
+| **The CoralOS round** - the seller's `edge` delivery ([`coral-agents/seller-agent`](coral-agents/seller-agent)) | the seller runs the same edge over MCP | a deterministic delivery |
 
 If there's **no key (or the account is out of credits)**, the call throws and the code uses the
 deterministic fallback. The web UI shows a **`deterministic`** badge instead of `LLM` so you can tell.
 
 ## The env vars
 
-All live in the repo-root **`.env`** (gitignored — never committed). `.env.example` shows the empty fields.
+All live in the repo-root **`.env`** (gitignored - never committed). `.env.example` shows the empty fields.
 
 | Var | Meaning |
 |-----|---------|
-| `ANTHROPIC_API_KEY` | Anthropic key (`sk-ant-…`). The default provider. |
-| `OPENAI_API_KEY` | OpenAI key (`sk-…`). |
+| `ANTHROPIC_API_KEY` | Anthropic key (`sk-ant-...`). The default provider. |
+| `OPENAI_API_KEY` | OpenAI key (`sk-...`). |
 | `LLM_PROVIDER` | Force the provider: `anthropic` or `openai`. Optional. |
 | `LLM_MODEL` | Override the model id. Optional (sensible per-provider default otherwise). |
-| `TRACE` | `1` → log the chosen provider/model + the raw reply. |
+| `TRACE` | `1` -> log the chosen provider/model + the raw reply. |
 
 ## How the provider is chosen
 
 [`pickProvider()`](packages/agent-runtime/src/llm/complete.ts) resolves it in this order:
 
-1. **Explicit** — if `LLM_PROVIDER=openai` (or `anthropic`), use that.
-2. **Auto-detect** — else if `OPENAI_API_KEY` is set, use **OpenAI**.
-3. **Default** — else **Anthropic**.
+1. **Explicit** - if `LLM_PROVIDER=openai` (or `anthropic`), use that.
+2. **Auto-detect** - else if `OPENAI_API_KEY` is set, use **OpenAI**.
+3. **Default** - else **Anthropic**.
 
-Default models (override with `LLM_MODEL`): Anthropic `claude-haiku-4-5-20251001` · OpenAI `gpt-4o-mini`.
+Default models (override with `LLM_MODEL`): Anthropic `claude-haiku-4-5-20251001` - OpenAI `gpt-4o-mini`.
 
-## Switch it — copy/paste
+## Switch it - copy/paste
 
 **Anthropic (default):**
 ```ini
-ANTHROPIC_API_KEY=sk-ant-…
+ANTHROPIC_API_KEY=sk-ant-...
 # LLM_PROVIDER / OPENAI_API_KEY unset
 ```
 
 **OpenAI:**
 ```ini
 LLM_PROVIDER=openai
-OPENAI_API_KEY=sk-…
+OPENAI_API_KEY=sk-...
 ```
 
 **Pin a specific model:**
 ```ini
-ANTHROPIC_API_KEY=sk-ant-…
+ANTHROPIC_API_KEY=sk-ant-...
 LLM_MODEL=claude-opus-4-8
 ```
 
@@ -61,15 +61,15 @@ LLM_MODEL=claude-opus-4-8
 Edit `.env`, then **restart** so it's re-read:
 
 - **Web demo:** restart `npm run dev` (the proxy reads `.env` at startup).
-- **CoralOS round:** just re-run `npm run coral` — `coral/round.ts` reads `.env` and passes the keys to
+- **CoralOS round:** just re-run `npm run coral` - `coral/round.ts` reads `.env` and passes the keys to
   the agents in the session request, so coral-server launches them with the new provider/key.
 
 ## "It says `deterministic`, not `LLM`"
 
 The model didn't return. Almost always the key:
 
 - not set / wrong key, or
-- **out of credits** — Anthropic returns `400 … credit balance is too low`. Top up, swap the key, or
+- **out of credits** - Anthropic returns `400 ... credit balance is too low`. Top up, swap the key, or
   switch to OpenAI (above). Then restart.
 
 Run with `TRACE=1` in `.env` to see exactly which provider/model was used and the raw reply.

POLISH_AND_ARBITER_DECENTRALIZATION_PLAN.md

@@ -0,0 +1,97 @@
+# Polish And Arbiter Language Plan
+
+This tracks the two remaining judge-facing weaknesses after the CoralOS arbiter alignment work:
+
+1. Some older docs/comments contain mojibake, mostly from copied arrows/dashes.
+2. The arbiter is a single trusted keypair, so the repo language must not overclaim.
+
+## Priority
+
+| Priority | Issue | Why It Matters | Fix |
+|---|---|---|---|
+| P0 | Mojibake in docs/comments | It makes the repo look rushed even when the system is strong. | Normalize docs and comments to clean ASCII or valid UTF-8. |
+| P1 | Centralized arbiter language | A sharp judge can challenge overbroad settlement claims. | Make language precise and consistent. |
+
+## P0: Mojibake Cleanup
+
+**Goal:** the repo should read cleanly in GitHub, terminals, and IDEs.
+
+**Scope:**
+
+- Markdown docs
+- `coral-agent.toml` descriptions
+- Source comments and log strings
+- README snippets and diagrams
+
+**Likely search patterns:**
+
+```sh
+rg -n "[^\\x00-\\x7F]" README.md LLM.md coral-agents examples/txodds packages scripts
+```
+
+**Rules:**
+
+- Prefer ASCII in docs and comments unless a file is already intentionally Unicode-clean.
+- Replace mojibake arrows with `->`.
+- Replace mojibake em dashes with `-`.
+- Replace curly quotes with straight quotes.
+- Replace box drawing diagrams with fenced ASCII diagrams.
+- Do not touch generated lockfiles or binary assets.
+
+**Acceptance Criteria:**
+
+- `rg -n "[^\\x00-\\x7F]" ...` returns no meaningful repo-authored docs/comments.
+- Main READMEs render cleanly on GitHub.
+- No behavior changes.
+- Typechecks still pass.
+
+## P1: Arbiter Language Tightening
+
+**Current truth:** the arbiter makes settlement fairer between buyer and seller, but it is still a trusted
+neutral keypair. The repo should say that directly.
+
+**Approved language:**
+
+- "arbiter-gated escrow"
+- "buyer cannot unilaterally claw back after delivery"
+- "trusted neutral arbiter"
+- "trusted neutral arbiter"
+
+**Avoid:**
+
+- Any wording that implies arbitration has no trusted keypair.
+- Any wording that implies the system has no trusted neutral party.
+- Any wording that says both sides are fully protected without naming the arbiter trust assumption.
+
+**Files to audit:**
+
+- `README.md`
+- `examples/txodds/README.md`
+- `examples/txodds/coral/README.md`
+- `examples/txodds/escrow/README.md`
+- `examples/txodds/web/app.js`
+- `coral-agents/**/*.md`
+- `coral-agents/**/*.toml`
+
+**Acceptance Criteria:**
+
+- Every settlement claim is qualified.
+- The trusted-arbiter assumption is visible before any judge reaches the contract section.
+- README clearly says the arbiter is trusted/centralized in this demo.
+
+## Recommended Path
+
+1. Do P0 mojibake cleanup immediately.
+2. Do P1 language tightening immediately.
+
+## Verification Checklist
+
+```sh
+rg -n "[^\\x00-\\x7F]" README.md LLM.md coral-agents examples/txodds packages scripts
+npm run typecheck --prefix packages/agent-runtime
+npm run typecheck --prefix coral-agents/buyer-agent
+npm run typecheck --prefix coral-agents/seller-agent
+npm run typecheck --prefix examples/txodds
+```
+
+If only docs/comments change, tests are optional but typechecks should remain green.