docs(skills): Measurement index semantics on the QICK seam — intonatissimo + intonatoqick

packages/extension/skills/intonatissimo/SKILL.md

@@ -3,6 +3,7 @@ name: intonatissimo
 description: Intonatissimo.jl usage — the entitled calibration tier. Measurement-matching objectives, NLP subproblem construction/updates, and the public-API ILC loop over Intonato's PulseTuningProblem chassis. Use when authoring a closed-loop pulse-tuning solve.jl in an Intonatissimo-enabled environment.
 surface: entitled
 entitlement: issimo
+revision: 1
 ---
 
 # Intonatissimo — usage guide
@@ -38,8 +39,11 @@ kpo, params = MeasurementMatchingObjective(model, y_target, traj; weights = w_ve
   point's target and weights. Mutate through the references between outer
   iterations; rebuilding the objective allocates and loses warm-start structure.
 - `update_targets!(params, y_target)` — retarget in place. `y_target` is a
-  `Vector{Measurement}` (a `Measurement` wraps one measurement vector plus its
-  knot index).
+  `Vector{Measurement}` (a `Measurement` wraps one measurement vector plus an
+  integer `index`). Here, as in `MeasurementModel` and `SimulatedExperiment`, the
+  index is a **knot index** π_j ∈ 1:N of the pulse — the state is read at
+  `get_knot_times(pulse)[index]`. See the hardware-path caveat below before
+  mixing these with measurements from a soc.
 - `update_weights!(params, w_flat)` — write the flattened per-element effective
   weights in model element order (measurement-major), in place.
 - `weights` are per-measurement task-importance vectors. The legacy `Q` /
@@ -89,6 +93,19 @@ solve!(ptp; max_iter = 5, tol = 1e-3, γ = 0.8, min_nominal_fidelity = 0.8)
 # ptp.qcp is updated in place with the tuned result
 ```
 
+- **Hardware-path index caveat (Intonato's QICK seam).** Through
+  `StrumentoExperiment` → `StrumentoBackend` → a soc (`MockSoc`, `TwinSoc`,
+  `StrumentoSoc`), the backend's `indices` are documented as knot indices, but
+  every soc resamples the pulse onto its DAC grid
+  (`floor(Int, T*dac_rate) + 1` points) and uses the integers as **DAC-sample**
+  indices of that grid — while the returned `Measurement`s still carry the knot
+  label. With N = 11, T = 5, `dac_rate = 20`, "index 11" is measured at t = 0.5,
+  not t = 5, so `y_exp` and the model targets disagree for a reason that is not
+  model error and ILC will "correct" it. Until Intonato measures at
+  `t = knot_times[k]` on the soc path: pass each knot's sample index
+  (`round(Int, t_k * dac_rate) + 1`) to the backend, or put the pulse's knots on
+  the DAC grid, and check one evaluation against `SimulatedExperiment` before a
+  loop. `SimulatedExperiment` itself is unaffected.
 - **Plain ILC** is the bare `ILCStrategy()` — no parameter calibration.
 - `solve!` kwargs: `max_iter` (outer iterations, default 5), `tol` (measurement
   error convergence, default 1e-3), `γ` (trust-region schedule factor, default

packages/extension/skills/intonatoqick/SKILL.md

@@ -3,10 +3,19 @@ name: intonatoqick
 description: Drive the public IntonatoQICK.jl QICK/RFSoC hardware backend — mock loop, channel map, measurement model, and composing a QickExperiment into Intonato's closed-loop chassis. Use when running or testing quantum optimal control on QICK hardware (or its pure-Julia mock).
 agents: [experimenter, engineer]
 surface: public
+revision: 1
 ---
 
 # IntonatoQICK — the public QICK hardware backend
 
+> **Status: archived.** `harmoniqs/IntonatoQICK.jl` is archived and was renamed
+> Strumento.jl (`QickBackend` → `StrumentoBackend`, `MockQickSoc` → `MockSoc`,
+> `PyQickSoc` → `StrumentoSoc`); the closed-loop seam (`StrumentoBackend` /
+> `StrumentoExperiment`) now lives in Intonato itself (`src/hardware/`), and
+> Intonato 0.5 absorbs the socs too (Strumento.jl retiring). New work targets
+> `using Intonato`; the recipe below is kept for pinned IntonatoQICK 0.1.0
+> environments. The index caveat applies to both lines.
+
 > **Provenance:** salvaged from `harmoniqs/amico-plugin` PR #42 (repo archived
 > 2026-08-26) — ruled SALVAGE in amicode#850, ported in amicode#851.
 
@@ -58,8 +67,13 @@ ptp = PulseTuningProblem(qcp, qexp, model)
 solve!(ptp; max_iter = 10)
 ```
 
-- `dac_rate` is the mock DAC grid; readout converges to the continuum as it rises (translation
-  is faithful, not lossy) — it is not bit-identical to a coarse-knot direct sim.
+- `dac_rate` is the mock DAC grid. **Measurement indices are DAC-sample indices on this
+  path**, not knot indices: the mock resamples onto `floor(Int, T*dac_rate)+1` points and
+  measures at the reconstruction's `knot_times[k]`, so `[N]` means t = (N−1)/`dac_rate`, not
+  t = T, unless the knot grid equals the DAC grid. The "readout converges as `dac_rate`
+  rises" check therefore converges toward the *initial* state and does not show translation
+  is faithful. Pass each knot's sample index (`round(Int, t_k*dac_rate)+1`) or put the
+  knots on the DAC grid.
 - Swap `MockQickSoc` → `PyQickSoc` for a real board; nothing else in the loop changes.
 - **Intonato ≥ v0.4:** the `R_tr` / `Q_meas` constructor kwargs are **removed** — trust-region
   weighting belongs to the strategy (Intonatissimo's subproblem constructors take `R_tr`) and
@@ -81,6 +95,7 @@ drive the backend, roll the mock, validate the seam.
 ## Verification contract
 
 A script authored on this skill must emit: the backend/experiment constructed, the measurement
-model, and — for the mock — evidence the loop ran (per-iteration measurement + a convergence or
-faithfulness check as `dac_rate` rises). Keep the script self-contained (inline the constants;
+model, and — for the mock — evidence the loop ran (per-iteration measurement + a faithfulness
+check that compares the mock at the knot's time against a direct `SimulatedExperiment` — not
+a readout-vs-`dac_rate` trend at a fixed index). Keep the script self-contained (inline the constants;
 no `include` of demo-repo files).