docs: reposition around agents + OKF + freshness, strip em dashes

AGENTS.md

@@ -15,24 +15,24 @@ Guidance for AI coding agents working in this repo. (Humans: see
 [`CONTRIBUTING.md`](./CONTRIBUTING.md) and [`docs/`](./docs/index.md).)
 
 > This file is itself a hub (see `surf.toml`): the one sealed claim below anchors to the lint rule
-> that polices this very file — a small bit of dogfooding. Everything else here is plain
+> that polices this very file - a small bit of dogfooding. Everything else here is plain
 > instruction, deliberately not anchored.
 
 Surface is a deterministic gate that surfaces divergence between docs and code: you anchor a
 sentence to the code it describes, and `surf check` blocks when that code's logic changes out
-from under the prose. **This repo dogfoods Surface on its own source** — the gate runs on
+from under the prose. **This repo dogfoods Surface on its own source** - the gate runs on
 `surf-core`/`surf-cli`.
 
 ## Where the context lives: `hubs/`
 
 <!-- surf:hubs -->
 [`hubs/`](./hubs/) is the governed context for this codebase. Each hub is markdown prose
 describing an invariant, with frontmatter anchoring the claim to a specific symbol. Unlike code
-comments, **hub prose is sealed by `surf check`** — if the anchored code changed since a human
+comments, **hub prose is sealed by `surf check`** - if the anchored code changed since a human
 last confirmed the prose, the gate fails. So the hubs are trustworthy and current in a way
 comments are not, and they are the fastest accurate way to understand a part of the system.
 
-**Read only the hubs you need — not the whole directory.** The hubs together describe the entire
+**Read only the hubs you need - not the whole directory.** The hubs together describe the entire
 codebase; reading all of them is wasteful context. They are split per module
 (`hubs/cli-check.md`, `hubs/hash.md`, `hubs/resolve.md`, …), and each starts with a one-line
 `summary:` in its frontmatter. Scan the filenames and summaries, then open only the hub(s)
@@ -44,41 +44,41 @@ directory exists; by convention it points at the directory rather than duplicati
 individual hubs (so agents search, not read everything).
 
 Caveat (the tool's own honest limit): a green gate means *the anchored code hasn't changed
-since last verified* — not that every sentence is true, and nothing about code no hub anchored.
+since last verified* - not that every sentence is true, and nothing about code no hub anchored.
 If you read a hub claim, sanity-check it against the code it points at before relying on it.
 
-## When you add or change a feature — keep the hubs honest
+## When you add or change a feature - keep the hubs honest
 
 Run the loop (binary builds to `target/debug/surf`; see `CONTRIBUTING.md` for build commands):
 
 1. Make the change.
-2. `surf lint` — every anchor must resolve. Consider the advisory granularity warnings
+2. `surf lint` - every anchor must resolve. Consider the advisory granularity warnings
    (over/under-anchoring); they are nudges, not blocks.
-3. `surf check` — if you touched code a hub anchors, it will report `DIVERGED`. Re-read the
+3. `surf check` - if you touched code a hub anchors, it will report `DIVERGED`. Re-read the
    claim. If the prose **still holds**, `surf verify` re-seals it (writes the new hash); if the
    prose is **now false**, fix the prose first, then verify.
 4. Added public behavior? First reach for an *existing* system claim: extend its prose, or add
    the new symbol as another site under its multi-site `at:` list. Write a brand-new claim only
-   when the behavior is genuinely its own. A hub is an onboarding doc, not a per-function log —
+   when the behavior is genuinely its own. A hub is an onboarding doc, not a per-function log -
    the under-coverage warning lists undocumented symbols, but consolidating them into one coarse,
    multi-anchor claim beats one claim per function (`surf lint` will nudge a claim-log the other
    way). When you update a hub, update its *prose* to stay accurate, not just the hash.
 5. Record user-facing changes in [`CHANGELOG.md`](./CHANGELOG.md) under `[Unreleased]`.
 6. Hit a *notable* dogfooding moment? Log it in [`docs/dogfood-log.md`](./docs/dogfood-log.md).
-   This is the repo eating its own dogfood, so it produces good material — capture it while it's
+   This is the repo eating its own dogfood, so it produces good material - capture it while it's
    fresh. The bar is "a reader would find this interesting," **not** every change: the gate
    catching a real contract drift, a lint false-positive, surprising friction, an invariant that
    was hard to express. Add a dated entry (newest first, template at the bottom of the file);
    skip routine changes that worked as expected.
 
-Do not blindly `surf verify` to make the gate green — that is the rubber-stamping failure the
+Do not blindly `surf verify` to make the gate green - that is the rubber-stamping failure the
 tool exists to prevent. Verify means "I read the prose and it is still true."
 
 ## Pointers
 
-- [`hubs/`](./hubs/) — governed context, split per module; read only the hub(s) you need.
-- [`CHANGELOG.md`](./CHANGELOG.md) — what changed; update `[Unreleased]`.
-- [`docs/dogfood-log.md`](./docs/dogfood-log.md) — dated notes from using Surface on itself; add notable moments.
-- [`docs/index.md`](./docs/index.md) — documentation map (guides, reference, concepts).
-- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — build, test, format, lint commands and layout.
-- [`docs/surface-proposal.md`](./docs/surface-proposal.md) — the product spec (the `§` references in hubs).
+- [`hubs/`](./hubs/) - governed context, split per module; read only the hub(s) you need.
+- [`CHANGELOG.md`](./CHANGELOG.md) - what changed; update `[Unreleased]`.
+- [`docs/dogfood-log.md`](./docs/dogfood-log.md) - dated notes from using Surface on itself; add notable moments.
+- [`docs/index.md`](./docs/index.md) - documentation map (guides, reference, concepts).
+- [`CONTRIBUTING.md`](./CONTRIBUTING.md) - build, test, format, lint commands and layout.
+- [`docs/surface-proposal.md`](./docs/surface-proposal.md) - the product spec (the `§` references in hubs).

CONTRIBUTING.md

@@ -28,29 +28,29 @@ cargo run -q -p surf-cli -- check   # anchored spans match their stored hashes
 ```
 
 If you change a symbol that a hub anchors (see `hubs/`), `check` will block until you either
-revert or — if the change is intended and the prose still holds — re-stamp it:
+revert or - if the change is intended and the prose still holds - re-stamp it:
 
 ```sh
 cargo run -q -p surf-cli -- verify "surf-core/src/hash.rs > emit"
 ```
 
 ## Layout
 
-- `surf-core/` — pure parse/resolve/hash logic, no I/O (also the future WASM target).
-- `surf-cli/` — the `surf` binary: workspace discovery, the commands, all I/O.
-- `docs/phases/` — how the MVP was built, one self-contained file per phase. Start with
+- `surf-core/` - pure parse/resolve/hash logic, no I/O (also the future WASM target).
+- `surf-cli/` - the `surf` binary: workspace discovery, the commands, all I/O.
+- `docs/phases/` - how the MVP was built, one self-contained file per phase. Start with
   `docs/phases/OVERVIEW.md`. The product spec is `docs/surface-proposal.md`.
-- `docs/index.md` — the documentation overview; `docs/getting-started/`, `docs/guides/`, and
+- `docs/index.md` - the documentation overview; `docs/getting-started/`, `docs/guides/`, and
   `docs/reference/` hold the user-facing pages. `AGENTS.md` is the on-ramp for AI coding agents.
 
 Keep `surf-core` free of I/O so it stays reusable; put filesystem/git work in `surf-cli`.
 
 **Docs source of truth.** This repo's `docs/` is canonical. The Starlight docs site
 ([`Connorrmcd6/surface-site`](https://github.com/Connorrmcd6/surface-site),
-surface.gradientdev.xyz) is generated *from* these pages — edit docs here, never only on the site.
+surface.gradientdev.xyz) is generated *from* these pages - edit docs here, never only on the site.
 On every `v*` release tag, the release workflow dispatches to surface-site, which regenerates its
 docs from `docs/` and `CHANGELOG.md` and opens a sync PR (a human merges it to deploy). So a
-release ships the docs that were merged before the tag — land doc edits with the code.
+release ships the docs that were merged before the tag - land doc edits with the code.
 
 `docs/reference/commands.md` is governed by `hubs/cli-reference.md`, anchored to the clap
 `Command` enum in `surf-cli/src/main.rs`: change a command or flag and `surf check` blocks until