📝 docs: add agent skills, AGENTS.md, and a doc-sync rule

[nstarman]

Adds the three agent-facing documents, modelled on the quax / quaxed /
quax-blocks set, and wires the skill's examples into CI so they cannot rot.

The layering

Each fact gets one home, and the files cite each other rather than restating:

docs/spec.md               → what is TRUE (normative math + API contract)
skills/coordinax/SKILL.md  → how to USE it from outside, and what bites you
AGENTS.md                  → how to WORK in this repo
.github/skills/code-review → what to CHECK on a diff

skills/coordinax/SKILL.md

The chart / representation / vector / manifold layering, framed around the
one idea that unlocks the library: a chart is not a representation, so
pt_map (dicts, chart-only) and cconvert (vectors, representation-aware)
are not interchangeable. Then the things that cost real time:

• tangents need an anchor, and coord_basis vs phys_basis differ by the
  chart's scale factors — with a worked example showing 1 rad/s become
  2 m/s at r = 2 m
• == is strict on chart and frame; equivalent is the geometric relation
• Distance/Angle degradation to plain Quantity is deliberate
• charts are register_static; close over them, and keep pytrees off the
  jit boundary
• geodesic_distance vs chord_distance, and the lorentzian gate
• a 12-row troubleshooting table, each row keyed to an error string I
  reproduced
• a version-notes rename table (separation → geodesic_distance,
  prolong → act_jet, Parametric → TimeDep,
  materialize_transform → evaluate_at, the groups/builders
  namespaces, quantity_matrix removed)

AGENTS.md

Distilled from .github/copilot-instructions.md rather than copied. Keeps
spec authority, the workspace table, commands, abstract-final, no
from __future__ import annotations, never parametrising a generic in a
dispatched signature, operators via quax.register, scalar-first, and the
new-package versioning template. Adds a Pitfalls section the old file
lacked — batch safety, routes composing instead of failing, eqx.error_if
under jit, plum cache regressions — each citing the PRs it came from.

.github/skills/code-review/SKILL.md

Organised around the two properties that generate most defects here:

1. A missing route composes instead of failing — a wrong route is a wrong
   number, not an exception (🐛 fix(charts): route Cart3D → ProlateSpheroidal3D via Cylindrical3D (stop recursion) #593, 🐛 fix(charts): convert between non-canonical two-sphere charts via canonical #594).
2. Scalar-first code meets batched callers — the largest landed-bug class
   in the log (🐛 fix(charts): read CartND components on the last axis, not the batch axis #590, 🐛 fix(manifolds): make analytic curvilinear metric_matrix batch-safe #591, 🐛 fix(manifolds): make DiagonalMetric.to_dense and the product metric batch-safe #613, 🐛 fix(manifolds): make the hyperspherical round metric batch-safe #618, 🐛 fix(manifolds): batch-safe two-sphere pullback metric; pin the pole behaviour #621, 🐛 fix(vectors): batch indexing crashes on broadcastable-but-unequal shapes #653, 🐛 fix(manifolds): round-metric scale_factors on S¹ and on a batch #751), and one every scalar
   test passes through.

Plus a scope section (leave ruff/ty/prettier to nox -s lint; no generic
security checklist) and a what changed → what to check path table.

Keeping them current

Both AGENTS.md and the review skill carry a doc-sync rule: a change that
alters public semantics, adds a hazard, or invalidates an example is not done
until these files match it, with a table mapping change → file. The review
skill flags the omission from the other side.

#733 is the precedent that motivates it — 17 examples in docs/spec.md had
gone stale purely because nothing forced the update.

The examples are tests

skills/ joins [tool.pytest.ini_options] testpaths and the coordinax
PackageEnum paths in noxfile.py, so Sybil executes all 49 ```pycon blocks
under nox -s test and in CI. Confirmed collected: 10,981 tests total, 49 of
them from the skill.

This earns its keep immediately — three outputs I wrote from memory were
wrong and the first run caught all three.

Two decisions worth a look

• .github/copilot-instructions.md becomes an 8-line pointer (-674).
  Copilot reads AGENTS.md too, and two ~700-line files would diverge within
  a month. Everything load-bearing moved across; I checked specifically for
  the workspace-package versioning template, the scratch-file rule, and the
  agent checklist, which are all now in AGENTS.md.
• /AGENTS.md is dropped from .gitignore, where it sat under
  # Local agents reserving a slot for an untracked local file. The tracked
  file is now canonical, matching quax / quaxed / quax-blocks. Anyone with a
  local untracked AGENTS.md will want to move it aside.

Verification

• pytest skills/ — 49 passed
• pytest --collect-only — 10,981 collected, no collection errors
• prek run --files ... — all hooks pass on every touched file
• Built on fresh upstream/main (c29dad6), and the skill's version notes
  and examples were re-checked against it — separation → geodesic_distance
  (💥 refactor(manifolds): separation becomes geodesic_distance, and a real metric #715) and the lorentzian namespace (♻️ refactor(manifolds): move the causal verbs to a lorentzian sub-namespace #696) are reflected.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds a layered set of agent-facing documentation for the Coordinax workspace (usage skill, in-repo agent instructions, and a code-review skill), and wires the new skills/ docs into the test/lint surface so examples are continuously validated in CI.

Changes:

• Add skills/coordinax/SKILL.md, AGENTS.md, and .github/skills/code-review/SKILL.md, with cross-references to avoid duplicated “source of truth” content.
• Include skills/ in pytest collection and in the coordinax package path set used by nox sessions.
• Replace the large .github/copilot-instructions.md with a short pointer to AGENTS.md, and stop ignoring /AGENTS.md.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
skills/coordinax/SKILL.md	New user-facing “how to use Coordinax” skill with tested pycon examples and troubleshooting/version notes.
AGENTS.md	New canonical in-repo agent instructions (spec authority, commands, conventions, pitfalls, doc-sync rule).
.github/skills/code-review/SKILL.md	New code-review checklist skill focused on coordinax-specific defect patterns and review scope.
pyproject.toml	Add skills/ to testpaths so skill examples are collected under pytest/Sybil.
noxfile.py	Include skills/ in PackageEnum.coordinax paths so package-scoped pytest runs cover the skill docs.
.github/copilot-instructions.md	Reduce to a pointer to AGENTS.md + the review skill to prevent divergence.
.gitignore	Stop ignoring /AGENTS.md so the tracked canonical file is used.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.63%. Comparing base (c29dad6) to head (b75009b).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #758      +/-   ##
==========================================
+ Coverage   96.62%   96.63%   +0.01%     
==========================================
  Files         267      267              
  Lines        9034     9064      +30     
==========================================
+ Hits         8729     8759      +30     
  Misses        305      305              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.