Fix API signature drift in user-guide skill + README (closes #11)

[Arcadia-1]

Summary

PR #13 (the user-guide-skill-revamp) and the long-standing README both shipped Python code examples that don't match the actual package API. The eval used in PR #13 was text-similarity only — subagents simulated responses but never imported or ran the code, so drift went undetected. Issue #11 named the README cases. This PR fixes the same class of bug everywhere it appears in the bundled skill, fixes the README per the issue, and adds an executable smoke test so this can't silently regress again.

Concrete corrections

All verified against python/src/adctoolbox/:

• analyze_spectrum takes (data, fs, ...) — does not take Fin or n_bits. Plot kwarg is create_plot=, not show_plot=. Returns a dict with lowercase _dbc keys (sndr_dbc, sfdr_dbc, enob, snr_dbc, thd_dbc, …) — not the uppercase SNDR / SFDR / ENOB previously shown. (Issue README API examples use wrong parameter names #11 case 1.)
• find_coherent_frequency is positional: (fs, fin_target, n_fft). The old fs=, n=, fin_target= form passes wrong values.
• calibrate_weight_sine first arg is bits (N×B {0,1} matrix), not integer codes. No n_bits= kw. Returns a dict with weight, offset, calibrated_signal, ideal, error, refined_frequency — not just a weights array.
• calibrate_weight_sine_lite(bits, freq) is positional and returns an ndarray.
• analyze_overflow(bits, weight) needs a calibrated weights array as its 2nd arg and returns a 4-tuple (range_min, range_max, ovf_pct_zero, ovf_pct_one).
• analyze_bit_activity / analyze_enob_sweep take bits (matrix), no n_bits=; analyze_enob_sweep requires normalized freq=Fin/Fs.
• analyze_phase_plane / analyze_error_phase_plane do not take Fin (they self-fit the fundamental).
• generate_aout_dashboard takes freq in Hz and writes to output_path= (not savepath=). generate_dout_dashboard takes freq normalized (Fin/Fs).
• fit_static_nonlin(sig_distorted, order) returns (k2, k3, fitted_sine, fitted_transfer). Input is a distorted signal — not INL/DNL data — so the previous example was wrong on both signature and intent.
• convert_cap_to_weight takes three same-length arrays (caps_bit, caps_bridge, caps_parasitic), not one.

api-quickref.md's Key Conventions section is rewritten to capture all of the above. decompose_harmonic_error is added to the advanced-tier submodule import list (it lives in adctoolbox.aout, not flat). SKILL.md §2 now leads with the bits vs aout naming convention.

Why this kept happening

PR #13's eval workflow scored text similarity from subagents — they could mention analyze_spectrum and reference real-sounding return keys without ever executing the code, so signatures drifted unchecked. The README has the same root cause: hand-written examples never wired to a runnable test.

How this prevents recurrence

python/tests/integration/test_user_guide_skill_examples.py actually imports each named API and runs the documented call pattern with a small synthetic fixture (ADC_Signal_Generator + a coherent capture). 9 tests, one per SKILL.md / advanced-debug.md / api-quickref.md section. If a future edit drifts again, the test fails before merge.

Test plan

• pytest tests/integration/test_user_guide_skill_examples.py -v → 9 passed
• Repo-wide grep for show_plot, Fin=, uppercase metric keys, n_bits=N) in skill files + README → 0 hits
• CI green

Closes #11.

🤖 Generated with Claude Code