docs: add .agent playbook and converge docs to single sources

[HynLcc]

TL;DR

Docs + dead-code cleanup only — no application or runtime logic changes. This PR:

1. adds a .agent/ playbook that walks an agent (or a newcomer) through adding a perf case;
2. converges the docs so every fact about the project lives in exactly one place;
3. deletes leftover scripts from the old matrix CI model.

pnpm check passes. Two commits, split by intent (docs: then chore:).

Why

The docs had drifted into several copies of the same facts, and some copies were already wrong:

• docs/operations/teable-ee-e2e.md listed 3 runners and 4 cases. The repo actually has 8 runners and 11 cases — so anyone trusting that file got stale information.
• The CI trigger command (gh workflow run ...) was copy-pasted across three files.
• scripts/resolve-case-matrix.mjs kept its own hardcoded copy of the case list from registry.ts (also drifted: 4 vs 11), even though nothing calls it anymore — the workflow moved from a parallel matrix to a single serial job a while ago and left the scaffolding behind.

The risk this creates: an agent or a reviewer reads one of the stale copies and acts on the wrong version. The goal of this PR is one home per fact.

What changed

1. New .agent/ playbook (the main addition)

A small folder an agent reads to author a perf case. .agent/README.md is the entry point and is the workflow; the other files are pulled in only when a step needs them.

File	Purpose
README.md	Orchestration loop: intake → draft spec → confirm → pick runner → write → register → check
runners.md	Runner catalog, config shapes, and the reuse → extend → new decision
case-spec.md	The spec template to draft and confirm with the user before coding
checklist.md	Hard rules: metric excludes seed, deterministic data, stream-completion handling, two-level verification
seed-execute.md	The seed-vs-execute boundary, seed hash, and cache contract
examples.md	Points at a real case (record-delete/delete-10k) as the worked example

Why a hidden .agent/ folder: it keeps the repo root uncluttered while staying fully readable to tools/agents. (Folder name and location were chosen deliberately for this.)

2. Docs converged to single sources

• README.md slimmed to a human-facing overview (~810 lines moved into .agent/ or dropped). Case authoring now links to .agent/.
• docs/operations/teable-ee-e2e.md — removed the stale runner list, stale case list, and the "add a case" block; these now link to the authoritative sources. Jaeger endpoint URLs now point to trace-viewer.md instead of being restated.
• docs/plan.md — added a header note marking it a design snapshot (the repo is authoritative where they differ); §11 now points to the real workflow file.
• tasks/todo.md — trimmed; removed the open-decisions block that duplicated plan.md §15.

3. Removed matrix-era dead code

All confirmed unreferenced (grepped across workflows, scripts, and package.json):

• scripts/resolve-case-matrix.mjs and scripts/resolve-case-max-parallel.mjs
• docs/examples/perf-regression.workflow.yml (stale, still in the old matrix shape)
• the max_parallel workflow input (deprecated, never consumed) — the only behavior change in this PR
• scripts/check-yaml.mjs repointed from the deleted draft to the real sync-perf-cases.yml, so both runnable workflows are now validated (previously only one was)

Single-source map (after this PR)

Topic	Single home
Runnable case ids + aliases	registry.ts
Case list (human-readable)	README.md
Runner catalog	.agent/runners.md
Case authoring flow	.agent/
CI trigger command + inputs	docs/operations/teable-ee-e2e.md
seed/execute contract	.agent/seed-execute.md
Observability / Jaeger	docs/operations/trace-viewer.md
Design vision (snapshot)	docs/plan.md

A few facts intentionally still repeat where collapsing them would hurt more than help: necessary code literals (env defaults, workflow-injected values), self-contained case .md descriptions, and the pnpm check instruction. These are stable and not drift-prone.

How to review

• Read per commit. Commit 1 (docs:) is the playbook + convergence; commit 2 (chore:) is the dead-code removal. Each stands on its own.
• Start at .agent/README.md. If the authoring flow there reads clearly to you, the core goal of this PR is met.
• Deletions are safe: the removed scripts have no references anywhere; pnpm check still passes and now additionally validates sync-perf-cases.yml.
• Nothing runtime changed: cases/, framework/, and registry.ts are untouched. The only workflow-interface change is dropping the unused max_parallel input.

Verification

pnpm check   # format + YAML + TS syntax + case registry — all green

🤖 Generated with Claude Code