Skills: teach API-first authoring (guarded construction + Piccolissimo operator inventory)

[aarontrowbridge]

Important

Problem

The platform skills teach hand-rolled Hamiltonian construction. In the cx-cat-cat-cavity campaign a sanity script bypassed the QuantumSystem Hermitian guard and shipped a typo'd pump to runtime — the exact failure the guard exists for, invisible because the skill never said "construct through the API." The Piccolissimo operator/system inventory (cat system, Kerr-star system, beamsplitter operators, matrix-free solver paths) is invisible to authoring agents.

Approach

Upstream the already-hot staging patch to the extension's bosonic skill: a core-API bullet (guarded construction always, including sanity scripts; inventory before hand-rolling; structural-type discipline) and two gotchas (the Stage-0 incident as the cautionary tale; the missing-cat-pair-constructor note with the inline-authoring fallback). Add short cross-references in the setup and problem-types skills pointing at the same rules.

Approaches Considered

• Patch the bosonic skill + cross-refs (CHOSEN) — the incident was bosonic, but the rule is general; cross-refs catch other platforms.
• Rewrite all platform skills (rejected — no evidence yet from other platforms; let the pattern prove out).
• Memory cards only (rejected — cards are per-user; skills are the shared, VSIX-shipped surface).

Scope

In: bosonic SKILL + gotchas upstreaming; setup/problem-types cross-references. Out: new skills; VSIX release mechanics.

---

Acceptance Criteria

• Extension skills dir carries the patched files; staging copy and repo copy are identical after the next wrapper rsync (no drift flag).
• A fresh authoring session on a bosonic target cites the constructor inventory before writing any kron (spot-check).

Key Decisions

• Staging copy already patched (hot) — this issue makes it durable and reviewable.

Source

• Session cx-cat-cat-cavity (2026-08-18); memory cards reference_api_first_authoring, project_autoresearch_meta.