docs: add AGENTS.md at repo root + pin tests

[dreamrec]

Summary

Adds AGENTS.md at the repo root — the development-time operating-rules doc that AI coding agents (Claude, Codex, Copilot, Cursor) and human contributors share. Reviewer on PR #30 specifically requested this: their local copy had "important release and DeepSeek-specific operating rules that future agents won't see from the public repo." AGENTS.md is exactly that doc, now public.

What's covered

• TL;DR fresh-agent kit — the things every new agent should internalize in the first 30 seconds.
• Critical naming pins — tdpilot-dpsk4 (NOT tdpilot), dreamrec/TDPilot_deepseekv4, dreamrec-TDPilot_deepseekv4, etc. Cross-linked to the test pins from PR ci: fix post-v2.1.5 package-name drift caught by Codex review on PR #30 #31.
• Repository layout — src/td_mcp/ (MCP-server Python) vs td_component/ (TD-bound code that gets baked into the .tox files).
• The two .tox files — what's baked into each, the source-hash freshness gates, when you must rebuild, and the canonical paste-verbatim Textport recipe with the four-footgun explanation (ASCII open default, Textport multi-line bug, TD_MCP_REPO_ROOT requirement, marker-file path drift).
• Eight version manifests in lockstep + the API_VERSION → .tox rebuild chain.
• The 12-step release ritual that's settled across v2.1.3/4/5 and PR ci: fix post-v2.1.5 package-name drift caught by Codex review on PR #30 #31, including the load-bearing gh release create step (because git push origin <tag> alone never fires release-assets.yml).
• DeepSeek-specific operating rules — thinking blocks must be echoed back, reasoning_content sub-keys must be stripped (opposite handling), prefix-cache byte-stability requirement, model-tier override regex.
• Security model — origin allowlist always enforced, per-launch session token, Sec-Fetch-Site rejection, TDPILOT_API_INSECURE escape hatch, EXEC_MODE clamp under insecure mode, MCP shared-secret auth.
• TouchDesigner gotchas — Textport rules, cook thread vs worker thread, comp.storage for reload-safe state, sys.modules overwrite (not setdefault), executeDAT force-cook, op.run unreliability, webRenderTOP http:// requirement, webserverDAT.onServerStart hook, geometryCOMP POP-family default, reference-style params need real OP refs, viewer=True on test COMPs, td_get_errors is not a render-success signal, the canonical feedbackTOP wiring, expression relative-vs-absolute paths.
• PR conventions — branch naming, HEREDOC commit messages, always-squash-merge, gh CLI usage, the Codex review cadence.
• Meta — how to keep AGENTS.md living (add a rule when you find a non-obvious gotcha; pin it in test_release_critical_names.py if mechanically checkable).

Test plan

• 3 new pin tests in tests/test_release_critical_names.py:
  • test_agents_md_exists_at_repo_root
  • test_agents_md_pins_all_critical_names (every canonical name from the naming-pins table)
  • test_agents_md_covers_release_critical_topics (substring match on every load-bearing topic — release flow gates, DeepSeek rules, security model, TD gotchas, .tox dance)
• pytest tests/ — 1695 → 1698 passed, 0 failed.
• ruff format --check + ruff check — clean.
• check_versions.py — sync at v2.1.5 (no bump; pure docs+tests).
• Both .tox freshness gates — pass (no rebuild needed).

No version bump. Style and convention follow agents.md (~60K-project standard, no required schema, repo-root markdown).

🤖 Generated with Claude Code