docs: make active recovery machine-agnostic

Define the canonical repository by URL and bootstrap a stable local
`githubsucks` alias instead of assigning authority to machine-specific
remote names. Record JSON/YAML checkpoint f99870e and the completed live
YAML provider plus bite evidence, leaving only rebase and full gates.

Keep AGENTS.md and CLAUDE.md synchronized so a fresh agent receives the
same recovery rule on any machine.

Co-Authored-By: OpenAI Codex <noreply@openai.com>

AGENTS.md

@@ -23,9 +23,11 @@ Always true, independent of the handoff:
 - The checkout may be shared with the user: check `git status` for
   foreign uncommitted work before stash, checkout, or branch operations,
   and never delete untracked files you did not create.
-- `githubsucks/main` is the canonical development line. `origin/main`
-  is a release mirror and may lag substantially; never base new work on
-  it without comparing both refs.
+- The canonical development URL is
+  `https://github.com/levineuwirth/pmacs.git`; recovery docs normalize
+  it to the local alias `githubsucks`. Remote names such as `origin` are
+  machine-local and carry no authority by themselves. Bootstrap/verify
+  the alias via `docs/active-work.md` before basing new work.
 - Work is portable only after it is committed and pushed. Uncommitted
   worktree changes, untracked files, and `/tmp` dependencies do not
   travel to another machine.

CLAUDE.md

@@ -23,9 +23,11 @@ Always true, independent of the handoff:
 - The checkout may be shared with the user: check `git status` for
   foreign uncommitted work before stash, checkout, or branch operations,
   and never delete untracked files you did not create.
-- `githubsucks/main` is the canonical development line. `origin/main`
-  is a release mirror and may lag substantially; never base new work on
-  it without comparing both refs.
+- The canonical development URL is
+  `https://github.com/levineuwirth/pmacs.git`; recovery docs normalize
+  it to the local alias `githubsucks`. Remote names such as `origin` are
+  machine-local and carry no authority by themselves. Bootstrap/verify
+  the alias via `docs/active-work.md` before basing new work.
 - Work is portable only after it is committed and pushed. Uncommitted
   worktree changes, untracked files, and `/tmp` dependencies do not
   travel to another machine.

docs/active-work.md

@@ -7,17 +7,39 @@ backlog.
 
 ## Repository authority
 
-- Canonical development remote: `githubsucks`
-  (`https://github.com/levineuwirth/pmacs.git`).
+- Canonical development URL:
+  `https://github.com/levineuwirth/pmacs.git`. This ledger uses the
+  normalized local alias `githubsucks` so its refs and recovery commands
+  are identical on every machine. Remote names are otherwise
+  machine-local: `origin` may name this canonical URL, a release mirror,
+  or something else, and therefore has no authority by name alone.
 - Canonical base at this snapshot:
   `githubsucks/main` @ `f8096ff` (#124 merged, protocol v17).
-- `origin/main` @ `d3fa632` is the release mirror and was 400 commits
-  behind `githubsucks/main` at the snapshot. Do not base new work on it.
+- On the transfer source, `origin/main` named a release mirror at
+  `d3fa632` and lagged badly. On the current destination, `origin` names
+  the canonical URL. This difference is why all recovery begins by
+  verifying URLs and normalizing `githubsucks` rather than trusting
+  `origin/main`.
 - The shared desktop checkout contained unrelated uncommitted work. The
   branches below were prepared in isolated worktrees; never clean or
   overwrite the shared checkout to recover them.
 
-Start on another machine with:
+Start on another machine by inspecting its remotes:
+
+```sh
+git remote -v
+git remote get-url githubsucks
+```
+
+If the second command says the alias is absent, add it; if it prints a
+different URL, stop and resolve that collision rather than overwriting an
+unknown remote:
+
+```sh
+git remote add githubsucks https://github.com/levineuwirth/pmacs.git
+```
+
+Then recover current refs:
 
 ```sh
 git fetch githubsucks --prune
@@ -37,13 +59,13 @@ If it does not, stop and repair the remote/fetch configuration.
 - Original merge base: `56eb67e`; current main is nine commits ahead.
 - Portable checkpoint branch:
   `githubsucks/json-yaml-handoff-2026-07-20`
-- Checkpoint head: `a8b7195`
+- Checkpoint head: `f99870e`
 - The checkpoint is a continuation branch for recovery, not a second
   feature and not a merge target. Finish there, then push its completed
   head to `githubsucks/json-yaml-grammar`.
 
-The checkpoint carries the unpushed review-fix set that previously lived
-only in `../pmacs-jsonyaml`:
+The checkpoint carries the transferred review-fix set plus the completed
+destination-machine continuation:
 
 - push configured settings via
   `workspace/didChangeConfiguration` immediately after `initialized`;
@@ -55,8 +77,12 @@ only in `../pmacs-jsonyaml`:
   `yaml`, `http`, `[yaml]`, `editor`, `files`;
 - corrected telemetry, schema-network, and schema-association claims;
 - PATH-gated real JSON provider integration test.
+- PATH-gated real YAML 1.24.0 integration test with SchemaStore and the
+  Kubernetes CRD catalog disabled for network-free determinism. It pins
+  YAML-specific auto-attach/initialization, a real syntax diagnostic,
+  no crash, and continued initialized state after the diagnostic.
 
-Verification already completed before transfer:
+Verification completed across the source and destination machines:
 
 - JSON provider standalone protocol smoke passed.
 - JSON provider through pmacs passed
@@ -70,19 +96,19 @@ Verification already completed before transfer:
   `yaml`, `http`, `[yaml]`, `editor`, `files`; opening the document
   caused a second scoped `[yaml]` request; invalid YAML produced a real
   parser diagnostic; shutdown exited 0 with empty stderr.
+- `m4_real_yaml_provider_pulls_config_and_reports_diagnostics` passed
+  against `/tmp/pmacs-yamlls` on the destination machine (0.36s).
+- Bite verification passed: with `builtin/runtime/lsp.lua` swapped to
+  pre-JSON/YAML `56eb67e`, the real YAML test failed at the absent YAML
+  config rather than skipping.
 
-Still required on the destination machine:
+Still required:
 
-1. Add the PATH-gated real-YAML pmacs acceptance test, mirroring the
-   JSON test. Disable SchemaStore and Kubernetes CRD catalog access in
-   the test for deterministic, network-free operation.
-2. Run it against the exact Red Hat provider and require:
-   auto-attach, initialized state, a non-empty diagnostic, and no crash.
-3. Update `docs/json-yaml-framing.md` if the live pmacs path reveals any
-   difference from the standalone evidence.
-4. Rebase the checkpoint onto current `githubsucks/main`.
-5. Run the full repository gate suite from `AGENTS.md`.
-6. Push the completed head to `githubsucks/json-yaml-grammar`; confirm
+1. Rebase the checkpoint onto current `githubsucks/main`.
+2. Run the full repository gate suite from `AGENTS.md`, putting both
+   pinned temporary provider prefixes on PATH so neither live smoke can
+   skip.
+3. Push the completed head to `githubsucks/json-yaml-grammar`; confirm
    new PR checks belong to that head. Never merge without the user's
    instruction.
 

docs/agent-handoff.md

@@ -141,11 +141,12 @@ commands, read `docs/active-work.md` immediately after this file.
   Completing stage 3 completes Arc 4.
 - **OPEN: JSON + YAML PR #123.** The public PR branch still points to
   the original two-commit implementation (`4be2a65`). Review fixes and
-  live-provider evidence are preserved on checkpoint branch
-  `json-yaml-handoff-2026-07-20`; the real YAML-through-pmacs smoke,
-  rebase, and full gates remain. Do not mistake the PR's old green CI
-  for validation of the checkpoint. Exact recovery is in
-  `docs/active-work.md`.
+  both live-provider paths are preserved on checkpoint branch
+  `json-yaml-handoff-2026-07-20`; the real YAML-through-pmacs smoke now
+  proves auto-attach, network-free configuration, diagnostics, and
+  continued liveness against Red Hat 1.24.0. Rebase and full gates
+  remain. Do not mistake the PR's old green CI for validation of the
+  checkpoint. Exact recovery is in `docs/active-work.md`.
 - **PARKED: kill-ring browser + persistence.** Revision 2 framing is
   preserved on branch `kill-ring-browser`, but its `0efb5cd` scout is
   stale and must be repeated before implementation. No PR or