@maccesar/titools 5.1.0 → 5.2.0

package/skills/ti-synthengine/references/sound-design.md

@@ -1,4 +1,4 @@
-> Source snapshot: official TiSynthEngine 1.0.0 documentation at commit `6685b81` (2026-08-29).
+> Source snapshot: official TiSynthEngine 1.0.0 beta documentation from the reviewed working tree based on `95901c98af5353b86d9dc7c60b29ab9186b038cd` (2026-10-14), including uncommitted statistics changes. Upstream `documentation/sound-design.md` SHA-256: `4ccbb55b92879c59d20116aff942e16d431c619341b3d4714da4c50c3c691cf9`.
 
 # Sound design with TiSynthEngine
 
@@ -19,9 +19,14 @@ var WAVE = synth.getDefaults().waveTypes
 
 - [Notes, frequencies and octaves](#notes-frequencies-and-octaves)
 - [Waveform and timbre](#waveform-and-timbre)
+- [Filter, pulse width and quantization](#filter-pulse-width-and-quantization)
 - [Envelope and total duration](#envelope-and-total-duration)
+- [Decay and sustain](#decay-and-sustain)
 - [Pan and movement](#pan-and-movement)
 - [Vibrato and the LFO](#vibrato-and-the-lfo)
+- [Resonant filter](#resonant-filter)
+- [Frequency modulation](#frequency-modulation)
+- [Detune](#detune)
 - [Chords, polyphony and gain](#chords-polyphony-and-gain)
 - [Mixing profiles and limiter](#mixing-profiles-and-limiter)
 - [Speakers, headphones and devices](#speakers-headphones-and-devices)
@@ -105,7 +110,28 @@ melodies, pads and xylophone-like sketches.
 changing that value does not tune the noise. A short envelope turns it into a
 click, hat or impact layer; a long envelope creates wind or static.
 
-Try every waveform at a moderate level before choosing one:
+`noiseRate` changes the source into variable-rate sample-and-hold noise. Zero
+keeps the white-noise default. Lower rates hold each pseudo-random value longer
+and sound grainier. `noiseRateEnd` moves the rate over the event.
+
+### Wavetable
+
+`WAVETABLE` repeats 2 to 64 values supplied in `waveTable`. Values range from
+-1 to 1 and are read as steps, without interpolation. Short asymmetric tables
+are useful for coarse DAC-like voices, buzzy radio tones and original retro
+effects that do not fit the four built-in oscillator shapes.
+
+```javascript
+synth.playTone({
+  note: 'D4',
+  duration: 600,
+  waveType: WAVE.WAVETABLE,
+  waveTable: [-1, -0.8, -0.1, 0.9, 0.45, 0.1, -0.25, -0.6],
+  bitDepth: 8
+})
+```
+
+Try the built-in sources at a moderate level before choosing one:
 
 ```javascript
 ;[WAVE.SINE, WAVE.SQUARE, WAVE.SAWTOOTH, WAVE.TRIANGLE, WAVE.NOISE]
@@ -123,6 +149,34 @@ Try every waveform at a moderate level before choosing one:
   })
 ```
 
+## Filter, pulse width and quantization
+
+`lowPassHz` enables a per-voice one-pole low-pass filter. It is most obvious on
+noise, square and sawtooth sources. Zero bypasses the filter. For resonance,
+high-pass and band-pass shapes or a moving cutoff, use the
+[resonant filter](#resonant-filter) below.
+
+`pulseWidth` controls how much of each square-wave cycle stays high. The 0.5
+default is a normal square. Values closer to 0.05 or 0.95 become thinner and
+brighter. `pulseWidthEnd` creates a linear duty-cycle sweep.
+
+```javascript
+synth.playTone({
+  note: 'A3',
+  duration: 700,
+  release: 180,
+  waveType: WAVE.SQUARE,
+  pulseWidth: 0.1,
+  pulseWidthEnd: 0.86,
+  lowPassHz: 4200
+})
+```
+
+`bitDepth` rounds the oscillator or noise amplitude to a fixed number of
+levels before filtering. Values from 2 to 16 are accepted. Zero preserves the
+floating-point signal. Quantization adds harmonic grit; it does not change the
+audio device's output format.
+
 ## Envelope and total duration
 
 Every event uses an attack, an implicit sustain section and a release:
@@ -153,6 +207,34 @@ release <= duration - attack
 Defaults are adjusted internally if a very short duration leaves no room, but
 values supplied by the caller are never reshaped silently.
 
+## Decay and sustain
+
+Plucked strings, struck keys and mallets start loud and settle. A flat
+envelope cannot do that, so `decay` and `sustain` add a stage after the attack:
+the level falls from full scale to `sustain` over `decay` milliseconds, then
+holds until the release.
+
+```text
+decay: 0                    flat tone, the default
+decay: 260, sustain: 0.18   pluck: loud start, settles low
+decay: 2000, sustain: 0.02  bell or mallet: fades by itself
+```
+
+Practical starting regions:
+
+- plucks and keys: attack 2 to 10 ms, decay 100 to 400 ms, sustain 0.1 to 0.4;
+- struck percussion with a pitch drop: decay about half the duration, sustain
+  near 0.3;
+- bells and mallets: decay over most of the duration, sustain near 0.
+
+`sustain` below 1 needs a nonzero `decay`. Without one the level would jump
+instantly, which clicks, so the call is rejected with `sustain_without_decay`.
+
+The release scales the level the note has reached. If the release begins while
+the decay is still running, the note leaves smoothly from that point. The
+decay still has to fit: `attack` plus `decay` cannot exceed `duration`, and the
+50 ms default attack counts. Set a short `attack` explicitly for a tight pluck.
+
 ## Pan and movement
 
 `pan` ranges from -1 on the left to 1 on the right. Zero is centered. Stereo
@@ -209,12 +291,111 @@ A rate around 4 to 7 Hz with a small depth sounds like musical vibrato. A fast
 rate or large depth becomes an effect. Because depth is measured in hertz, 8 Hz
 is a larger musical interval on a low note than on a high note.
 
+## Resonant filter
+
+`filterType` adds a filter that removes or emphasizes part of the spectrum. It
+has 12 dB per octave of slope, twice as steep as the one-pole `lowPassHz`
+filter, and can be combined with it (`lowPassHz` runs first).
+
+- `lowpass` darkens the sound. A sawtooth through a closing low-pass reads as a
+  zap or a sound moving away; an opening one reads as a swell.
+- `highpass` thins the sound by removing body. It makes hats, hiss and tinny
+  effects out of noise.
+- `bandpass` keeps one band around `filterHz`, which gives vocal, nasal and
+  wah-like colors.
+
+Filters shape harmonics, so give them a source that has some: `SAWTOOTH`,
+`SQUARE` and `NOISE` respond strongly. A sine has only its fundamental, so a
+filter mostly changes its level.
+
+`filterQ` is the resonance. The default 0.7071 is flat. Values from 2 to 4 add
+character, and above about 6 the filter whistles around the cutoff. A low-pass
+or high-pass boosts the cutoff region by about `filterQ`, so Q 10 is roughly
+20 dB. Lower the event `volume` as Q goes up. The limiter catches peaks, but a
+resonance that keeps hitting it makes the whole mix pump. The band-pass keeps
+unity gain at its center for every Q and only narrows.
+
+`filterHzEnd` moves the cutoff over the whole event. The motion is exponential,
+so each second covers the same musical distance. Set it above `filterHz` to
+open the filter and below to close it. Zero disables the sweep.
+
+```javascript
+synth.playTone({
+  note: 'A2',
+  duration: 1000,
+  attack: 10,
+  release: 200,
+  volume: 0.5,
+  waveType: WAVE.SAWTOOTH,
+  filterType: 'bandpass',
+  filterHz: 350,
+  filterHzEnd: 2400,
+  filterQ: 5
+})
+```
+
+## Frequency modulation
+
+FM makes rich, bright and metallic sounds from a plain sine. A second sine, the
+modulator, bends the pitch of the first one, the carrier. Turn it on with
+`fmDepth` or `fmDepthEnd`, on a `SINE` voice.
+
+- `fmRatio` is the modulator frequency as a multiple of the carrier's. Whole
+  numbers (1, 2, 3) keep the added overtones on the harmonic series, so the
+  pitch stays clear and the sound reads as organ- or piano-like. Fractional
+  ratios such as 1.4142 or 3.5 put the overtones between harmonics, which reads
+  as bells, glass and metal.
+- `fmDepth` is the modulation index and works like a brightness control. Around
+  0.5 to 1.5 it warms a sine, 2 to 5 makes it bright and rich, and values near
+  10 get harsh.
+- `fmDepthEnd` moves the index over the event. Starting high and ending low
+  gives a bright attack that mellows, which is the signature of electric pianos,
+  bells and mallets. Pair it with `decay` so the level falls with the brightness.
+
+FM does not change the sine's amplitude, so gain staging is the same as for a
+plain sine. There is no band-limiting: a high carrier with a large index and
+ratio puts sidebands above the Nyquist frequency, where they alias into
+inharmonic noise. Keep bell carriers modest, around 500 Hz, or lower the index.
+
+## Detune
+
+`detune` shifts a pitch by cents, hundredths of a semitone. Two tones a few
+cents apart drift in and out of phase and beat at a rate close to
+`frequency * (2 ^ (cents / 1200) - 1)`. A 12-cent gap at 440 Hz beats about
+3 times a second. Slow beating (0.5 to 4 Hz) sounds warm and wide, like a
+chorus; past about 20 cents it starts to sound out of tune.
+
+On a single tone, `detune` just retunes it, which is handy for small variations
+so a repeated effect does not sound identical. The effect comes from stacking
+detuned copies. In a chord, give `detunes` one entry per pitch and repeat a
+pitch to thicken it:
+
+```javascript
+synth.playChord({
+  frequencies: [440, 440],
+  detunes: [-6, 6],
+  duration: 2000,
+  attack: 200,
+  release: 600,
+  volume: 0.55,
+  waveType: WAVE.SINE
+})
+```
+
+Each repeated pitch is a voice, so size `maxVoices` for the full stack. Protected
+profiles divide per-voice source gain by the square root of the event voice
+count. This reduces buildup; it does not guarantee equal loudness. Correlated
+voices can still reinforce each other, and detuned voices can produce peaks
+as their phases align. `raw` does not apply this event normalization.
+
 ## Chords, polyphony and gain
 
 `playChord` is for notes that should start together. The call is placed in the
 native queue as one event, so the audio callback sees the whole chord or none
-of it. Its source gain is divided by the square root of the chord's voice count
-to keep power stable.
+of it. In protected profiles, per-voice source gain is divided by the square
+root of the chord's voice count. This approximately stabilizes power for
+uncorrelated voices, not coherent copies; it does not guarantee constant peaks
+or perceived loudness. `raw` bypasses this normalization.
 
 ```javascript
 synth.playChord({
@@ -358,16 +539,18 @@ synth.playPattern({
   volume: 0.5,
   waveType: WAVE.SQUARE,
   steps: [
-    { note: 'C5', duration: 80 },
-    { note: 'E5', duration: 80 },
-    { note: 'G5', duration: 80 },
-    { note: 'C6', duration: 160, noteValue: '8n' }
+    { note: 'C5' },
+    { note: 'E5' },
+    { note: 'G5' },
+    { note: 'C6', noteValue: '8n' }
   ]
 })
 ```
 
-The pattern root does not accept `duration`. Put it on each sounding step when
-you want a gate shorter than its rhythmic step.
+The first three steps use sixteenth notes and the last uses an eighth note.
+`release` fades each voice within that rhythmic length. The pattern root does
+not accept `duration`; a step `duration` replaces its rhythmic length as well
+as its voice length. There is no separate gate parameter.
 
 ### Noise percussion
 
@@ -378,17 +561,179 @@ synth.playPattern({
   waveType: WAVE.NOISE,
   volume: 0.34,
   steps: [
-    { frequency: 220, duration: 65, attack: 1, release: 55 },
+    { frequency: 220, attack: 1, decay: 65, sustain: 0, release: 55 },
     { rest: true },
-    { frequency: 220, duration: 35, attack: 1, release: 28 },
-    { frequency: 220, duration: 35, attack: 1, release: 28 }
+    { frequency: 220, attack: 1, decay: 35, sustain: 0, release: 28 },
+    { frequency: 220, attack: 1, decay: 35, sustain: 0, release: 28 }
   ]
 })
 ```
 
+The steps keep the eighth-note grid while short decay and `sustain: 0` let
+each hit settle to silence inside its step.
+
 Noise steps still need `frequency` or `note` because every sounding pattern
 step follows the same shape. The pitch value is not used by the noise source.
 
+### Filtered noise burst
+
+```javascript
+synth.playTone({
+  frequency: 120,
+  duration: 760,
+  attack: 1,
+  release: 580,
+  volume: 0.62,
+  waveType: WAVE.NOISE,
+  noiseRate: 12000,
+  noiseRateEnd: 650,
+  lowPassHz: 2500,
+  bitDepth: 8
+})
+```
+
+The decreasing update rate makes the texture break into slower chunks while
+the envelope removes energy. Reverse the two rates for an effect that becomes
+more frantic.
+
+### Pluck
+
+```javascript
+synth.playTone({
+  note: 'E4',
+  duration: 900,
+  attack: 2,
+  decay: 260,
+  sustain: 0.18,
+  release: 380,
+  volume: 0.6,
+  waveType: WAVE.TRIANGLE
+})
+```
+
+### Electric piano
+
+```javascript
+synth.playTone({
+  note: 'E3',
+  duration: 1800,
+  attack: 3,
+  decay: 700,
+  sustain: 0.3,
+  release: 600,
+  volume: 0.55,
+  waveType: WAVE.SINE,
+  fmRatio: 1,
+  fmDepth: 2.2,
+  fmDepthEnd: 0.25
+})
+```
+
+The index falls from 2.2 to 0.25 while the level settles, so the attack is
+bright and the sustain is mellow.
+
+### Bell
+
+```javascript
+synth.playTone({
+  note: 'C5',
+  duration: 2600,
+  attack: 1,
+  decay: 2000,
+  sustain: 0.02,
+  release: 500,
+  volume: 0.5,
+  waveType: WAVE.SINE,
+  fmRatio: 3.5,
+  fmDepth: 4,
+  fmDepthEnd: 0
+})
+```
+
+The fractional ratio makes the overtones inharmonic. Try 1.4142 or 2.76 for a
+different metal.
+
+### Wah
+
+The wah in [Resonant filter](#resonant-filter) is also a recipe. Reverse the
+two cutoffs for a sound that closes instead of opening.
+
+### Filtered laser
+
+```javascript
+synth.playTone({
+  frequency: 1600,
+  frequencyEnd: 160,
+  duration: 340,
+  attack: 2,
+  release: 90,
+  volume: 0.4,
+  waveType: WAVE.SAWTOOTH,
+  filterType: 'lowpass',
+  filterHz: 7000,
+  filterHzEnd: 500,
+  filterQ: 4
+})
+```
+
+### Hi-hat
+
+```javascript
+synth.playTone({
+  duration: 80,
+  attack: 1,
+  decay: 30,
+  sustain: 0.25,
+  release: 45,
+  volume: 0.45,
+  waveType: WAVE.NOISE,
+  filterType: 'highpass',
+  filterHz: 7000
+})
+```
+
+For an open hat, use `duration: 320`, `decay: 70` and `release: 220`.
+
+### Thick pad
+
+```javascript
+synth.playChord({
+  notes: ['A3', 'E4', 'A3', 'E4', 'A3', 'E4'],
+  detunes: [-9, -9, 0, 0, 9, 9],
+  duration: 3200,
+  attack: 700,
+  release: 1300,
+  volume: 0.5,
+  waveType: WAVE.SAWTOOTH,
+  filterType: 'lowpass',
+  filterHz: 1500,
+  panSpread: 0.8
+})
+```
+
+Six voices play two pitches, each in three slightly different tunings. The
+low-pass takes the harshness off the sawtooth stack. Start the engine with
+`maxVoices` of at least 6.
+
+### Kick
+
+```javascript
+synth.playTone({
+  frequency: 150,
+  frequencyEnd: 42,
+  duration: 320,
+  attack: 1,
+  decay: 150,
+  sustain: 0.3,
+  release: 140,
+  volume: 0.85,
+  waveType: WAVE.SINE
+})
+```
+
+The pitch drop is the punch and the decay is the thump. A phone speaker cannot
+reproduce 42 Hz, so raise `frequencyEnd` toward 70 for speaker playback.
+
 ### Simon-style cues
 
 Use short, distinct square-wave pitches. Play one tone for the sequence and
@@ -424,5 +769,4 @@ function playAllSimonPads () {
 For more complete code, continue with [Examples](examples.md) and
 [Curated sound and interaction recipes](recipes.md). The latter includes retro
 effects, a playable xylophone, memory-pad timbres, layered chords and timer
-ownership. For gain and device-testing advice, see
-[Recommendations](recommendations.md).
+ownership. For gain and device-testing advice, see [Recommendations](recommendations.md).

package/skills/ti-synthengine/references/source-notes.md

@@ -0,0 +1,121 @@
+# Maintaining the synthesis snapshot
+
+The eight official Markdown mirrors and raw statistics comparison are derived
+from the reviewed TiSynthEngine working tree based on the commit in
+[source-snapshot.json](source-snapshot.json). This snapshot includes uncommitted
+native statistics methods, tests and documentation. The commit identifies the
+base; it does not contain all reviewed content. `reviewed_worktree_sha256`
+records the reviewed dirty-state fingerprint, including tracked differences
+and untracked files. The checker verifies that fingerprint in addition to the
+individual source/mirror hashes. A match establishes fidelity to that source
+state; it does not establish that the source is correct, committed, published
+or installed in an app. A different dirty fingerprint requires a fresh review.
+Read the native contracts, command conversion and renderers when auditing
+behavior. The maintainer workflow is `titools-skill-auditor` in this repository.
+
+## Sources and permitted transformations
+
+`api.md`, `audio-engine.md`, `examples.md`, `guide.md`, `recommendations.md`,
+`sound-design.md`, `troubleshooting.md` and `stats-performance.md` mirror the
+corresponding upstream `documentation/` files. `stats-performance.json` preserves
+the complete raw trials without Markdown transformations. These nine assets
+each record a full-source SHA-256 and final mirror SHA-256. Markdown provenance
+headers identify the working tree, base commit and full-source hash.
+
+Only these transformations are currently declared:
+
+- A provenance header and generated `TOC-START`/`TOC-END` navigation.
+- The upstream demo link in `examples.md` is rebased to the last committed
+  `example/app.js` at the base commit. Its label explicitly distinguishes that
+  demo from the pending statistics example in the reviewed working tree; a
+  GitHub commit link cannot expose uncommitted changes. It requires access to
+  the official module repository; the runnable app is not bundled here.
+- `examples.md` and `sound-design.md` retain their TiTools links to
+  [curated recipes](recipes.md). These additions are recorded as reversible
+  `link_fixes`, with the complete original and mirrored Markdown fragments.
+
+For Markdown mirrors, the snapshot test removes the header and generated
+navigation, reverses those fragments, and checks the full original source hash.
+The raw JSON is checked byte for byte. Update the declared
+transformations when an intentional source-derived edit is reviewed; never
+regenerate hashes merely to conceal an unexplained difference.
+
+## Protected curated content
+
+[recipes.md](recipes.md) is a TiTools contribution, not an official mirror.
+Preserve its recipes, lifecycle patterns and navigation during synchronization.
+Check every native option and envelope against the current contract. The
+rhythm tests execute the Markdown examples and assert their intended note
+onsets, lengths and cancellation behavior; they do not render audio.
+
+Do not remove either official mirror's curated recipe link just because the
+upstream source has no equivalent. The snapshot records these intentional
+differences so preservation and source fidelity can both be checked.
+
+## Statistics scope and evidence
+
+The reviewed source adds `getStats()`, `resetStats()` and
+`setStatsEnabled(Boolean)` to the previous eight-method API. Detect support
+before using them with older 1.0.0 beta binaries; the version string alone does
+not identify the feature. Basic counters remain available without enabling
+diagnostics. Monotonic-clock render timing and signal measurements are optional
+and default off; missing/unmeasured fields stay `null`, distinct from measured
+zero. Android backend underrun, buffer and latency fields are independent of
+that diagnostics switch and remain best-effort. Poll at a modest rate and
+cancel polling with the owning screen/service.
+
+[stats-performance.md](stats-performance.md) and its
+[raw trials](stats-performance.json) document an Android native host comparison
+against the base engine, including variability and excluded costs. They do not
+run the iOS callback, JavaScript bridge or real device stream, and do not prove
+device CPU, battery, heat, latency or physical underrun behavior. Review the
+native statistics contract/publication and tests independently of the benchmark
+percentages; no zero-overhead or unchanged device-performance guarantee follows.
+
+## Upstream documents outside the mirror set
+
+The snapshot declares `documentation/index.md` and
+`documentation/third-party-notices.md` in `excluded_documents`, including each
+reviewed hash and reason. SKILL.md supplies the distributed navigation;
+dependency notices accompany the official module and native packages. This
+skill does not distribute Oboe, native binaries or KEMAR impulse responses.
+Changes or deletion of these excluded documents still require review. New
+upstream documents remain visible as new documents until reviewed and mapped
+or explicitly excluded; these records are not a blanket ignore rule.
+
+## Verification after a reviewed update
+
+```bash
+node scripts/verify-module-snapshot.mjs --skill ti-synthengine --source /path/to/TiSynthEngine
+node --test test/ti-synthengine.test.js test/ti-synthengine-recipes.test.js
+```
+
+Run these from TiTools. The checker is read-only: it reports source dirtiness,
+commit drift, source/mirror changes, missing files and new official documents.
+It never fetches, pulls or synchronizes. In the module checkout, also run the
+applicable official documentation, contract and DSP checks described in
+[audio-engine.md](audio-engine.md#regression-coverage).
+
+Regenerate navigation only after inspecting the generator's dry run. Refresh
+the snapshot's mirror hashes after navigation and declared additions are final.
+Before committing, inspect source differences and the distributed package;
+neither an old passing test count nor hash equality substitutes for that review.
+
+## Native findings and acceptance boundaries
+
+At the 2026-10-14 audit, iOS command construction converted zero attack/release
+to at least one sample; Android preserved zero. The shared envelope therefore
+has a one-sample boundary difference. This remains an upstream implementation
+finding: no native changes were made during the documentation correction.
+Recheck command construction or rendered output before calling it resolved.
+
+Java/iOS corpus parity covers validator acceptance/reasons, not rendered
+samples. The shared FIR suite and Android host tests establish narrower DSP
+properties. Inspect their current assertions for rate endpoints and exact
+tail-history coverage rather than assuming every advertised case is tested.
+The JavaScript rhythm checks interpret submitted options; they are not native
+scheduler timing measurements.
+
+Device startup/route behavior, iOS rendering, headphone localization, CPU,
+battery and underruns need their own evidence. Contract-valid recipes are not
+automatically pleasant or perceptually well localized.

package/skills/ti-synthengine/references/source-snapshot.json

@@ -0,0 +1,105 @@
+{
+  "module": "ti.synthengine",
+  "version": "1.0.0 beta",
+  "repository": "https://github.com/macCesar/TiSynthEngine",
+  "commit": "95901c98af5353b86d9dc7c60b29ab9186b038cd",
+  "reviewed_on": "2026-10-14",
+  "files": [
+    {
+      "source": "documentation/api.md",
+      "destination": "references/api.md",
+      "source_sha256": "60f9eda77f327bad6b66b0b6a49089c383a49a211c0691d09a0d715731434b56",
+      "mirrored_sha256": "5c07828516109386224c6380d8e603f6889cb1cbc0f29dd79609db288cabd908",
+      "links": [],
+      "link_fixes": []
+    },
+    {
+      "source": "documentation/audio-engine.md",
+      "destination": "references/audio-engine.md",
+      "source_sha256": "7b5707ee22e01a351af3633be14458726f8956069fb9355d1fb31cc4f7b9438a",
+      "mirrored_sha256": "22b3665068d9507ef7481a606f8949de24e7429e40609b9760164567220dd8fd",
+      "links": [],
+      "link_fixes": []
+    },
+    {
+      "source": "documentation/examples.md",
+      "destination": "references/examples.md",
+      "source_sha256": "53a8bd95215cc24a35776edb8686fa0d60c5399be0b4ff2685eee1563738f6cb",
+      "mirrored_sha256": "6679554e7f1df97d45a1e3c5ea842a0999d713933c677fc1a4678e72ca226f63",
+      "links": [],
+      "link_fixes": [
+        {
+          "original_markdown": "The complete interactive demo is in [`example/app.js`](../example/app.js).",
+          "mirrored_markdown": "The last committed interactive demo is in the upstream [`example/app.js`](https://github.com/macCesar/TiSynthEngine/blob/95901c98af5353b86d9dc7c60b29ab9186b038cd/example/app.js); that commit does not contain the pending statistics example. For additional retro effects, playable xylophone interaction, memory pads, layered polyphony and cancellable repetition, continue with [Curated sound and interaction recipes](recipes.md)."
+        }
+      ]
+    },
+    {
+      "source": "documentation/guide.md",
+      "destination": "references/guide.md",
+      "source_sha256": "c5fb4ff34ec425487221b80d6793bda24aa328281ab9ccb02e65b0065e54842e",
+      "mirrored_sha256": "d8f58c77c4d622e67ae6e2cafee58a2c24c1c8e31bad719a05ec8a5d968b3d04",
+      "links": [],
+      "link_fixes": []
+    },
+    {
+      "source": "documentation/recommendations.md",
+      "destination": "references/recommendations.md",
+      "source_sha256": "0f09ee6ef0876b3a23021fddb509dfd1e1206d08e836acae8f32b58b6481c055",
+      "mirrored_sha256": "f2480f455e55e461c880c8614ac383d60abf0ea8e744e3b99deabea290deb6c6",
+      "links": [],
+      "link_fixes": []
+    },
+    {
+      "source": "documentation/sound-design.md",
+      "destination": "references/sound-design.md",
+      "source_sha256": "4ccbb55b92879c59d20116aff942e16d431c619341b3d4714da4c50c3c691cf9",
+      "mirrored_sha256": "ac716003ff31a9d8dc896faa48ab0a18787a153797b7fa2f77ba0d7a936e8868",
+      "links": [],
+      "link_fixes": [
+        {
+          "original_markdown": "For more complete code, continue with [Examples](examples.md). For gain and\ndevice-testing advice, see [Recommendations](recommendations.md).",
+          "mirrored_markdown": "For more complete code, continue with [Examples](examples.md) and\n[Curated sound and interaction recipes](recipes.md). The latter includes retro\neffects, a playable xylophone, memory-pad timbres, layered chords and timer\nownership. For gain and device-testing advice, see [Recommendations](recommendations.md)."
+        }
+      ]
+    },
+    {
+      "source": "documentation/troubleshooting.md",
+      "destination": "references/troubleshooting.md",
+      "source_sha256": "10949f8f18f9e97933bfb1f025a12217746648c01805ff0fafe2c8e064b1c0cc",
+      "mirrored_sha256": "baaa2e31f1c1e0ab8b3dd9924929ec987caa13962b526af1389bdbfb77f4f9af",
+      "links": [],
+      "link_fixes": []
+    },
+    {
+      "source": "documentation/stats-performance.md",
+      "destination": "references/stats-performance.md",
+      "source_sha256": "798075f7bec08b4dafcaa46f1c43552d90ba23e2c85b49b4ab1d4ddf72c210df",
+      "mirrored_sha256": "40e4dc748379a24a90a812f26177372530a8138324d465a11f75ff7f45c3dc1d",
+      "links": [],
+      "link_fixes": []
+    },
+    {
+      "source": "documentation/stats-performance.json",
+      "destination": "references/stats-performance.json",
+      "source_sha256": "bd0cf07295d0d8f1120e66f527e9ca6d9a014efdc43dff5675716e8e26abe5b3",
+      "mirrored_sha256": "bd0cf07295d0d8f1120e66f527e9ca6d9a014efdc43dff5675716e8e26abe5b3",
+      "links": [],
+      "link_fixes": []
+    }
+  ],
+  "excluded_documents": [
+    {
+      "source": "documentation/index.md",
+      "source_sha256": "a1fee9bfc45e461594b54cc226cf21e9ecbee358400b3414643a199c18b1edb2",
+      "reason": "Upstream documentation index; SKILL.md is the distributed navigation entry point."
+    },
+    {
+      "source": "documentation/third-party-notices.md",
+      "source_sha256": "cff5eb2cb19c9128e33f26d524fac1f7cad43e263693f34413392ead97b0f1c5",
+      "reason": "Dependency and KEMAR notices remain with the official module and its binary packages; this skill redistributes documentation, not the native code or HRTF data. Re-review attribution when the source notice changes."
+    }
+  ],
+  "source_state": "working-tree",
+  "reviewed_worktree_sha256": "5a5085884d65ec92b6281f2c04cf47adaa864d988e3462fca98340d4a9a27ad9"
+}