CLAUDE.md: move the merged history to docs/HISTORY.md

Scripts/encoder-check/hbparse.py

@@ -4,7 +4,7 @@
 # (C/F is what the 2026-09-25 investigation read as the time per frame on the encoder: 9.0 ms in
 # the fast state, 14.0 in the slow one, alone on the engine at 3024×1964; the counters are the
 # engine's, so C/F is only a session's own when it is alone on the engine). A/s: the first
-# counter's growth a second. CLAUDE.md, "The 33 fps plateau".
+# counter's growth a second. docs/HISTORY.md, "The 33 fps plateau".
 # usage: hbparse.py FILE      (the output of the log show above)
 import re, sys
 res, prev = {}, None

Scripts/encoder-check/no-device.sh

@@ -9,7 +9,7 @@
 # "[1s] … · N client(s)" line in the last 60 s blocks, not only the newest stats line.
 # With --since 'YYYY-MM-DD HH:MM:SS': also fail if any connect line is at or after that time.
 # Why: a hardware encoder run beside a stream shares the Mac's one encoder engine with it (CLAUDE.md,
-# "Busy, not stuck": the operational rule). SILL_LOG_DIR overrides ~/Library/Logs/Sill.
+# Working rules). SILL_LOG_DIR overrides ~/Library/Logs/Sill.
 L=${SILL_LOG_DIR:-$HOME/Library/Logs/Sill}
 cat $L/Sill.1.log $L/Sill.log 2>/dev/null | python3 -c '
 import re, sys, datetime

Scripts/encoder-check/verify-hardware.sh

@@ -7,7 +7,7 @@
 # also says whether another process is encoding (engine-free.sh, the kernel's AppleAVE2 HeartBeat
 # of the last 12 s): a shared engine is a different experiment (the Claude app's iOS Simulator panel
 # encodes its screen at priority 60), and the Retina Desktop's slow state needs the engine to
-# itself (CLAUDE.md, "The 33 fps plateau").
+# itself (docs/HISTORY.md, "The 33 fps plateau").
 #
 # usage: Scripts/encoder-check/verify-hardware.sh [parity] [stream] [harness] [probe] [keyframe]   (none: all five)
 #   parity   SillHost --synthetic idle 35 s, base then new: new's stdout masked and sorted must

Sources/SillHost/EncoderMailbox.swift

@@ -9,7 +9,7 @@ import CoreMedia
 ///
 /// One frame inside at a time, on the hardware and the software encoder alike: the next goes in
 /// when the last came back. Two at once was measured against the hardware's slow state and
-/// dropped (CLAUDE.md, "The 33 fps plateau").
+/// dropped (docs/HISTORY.md, "The 33 fps plateau").
 ///
 /// Foundation and CoreMedia only, so it is checked on its own with swiftc against a stand-in for
 /// VideoToolbox that returns frames after programmable delays, in virtual time

Sources/SillHost/EncoderSlowState.swift

@@ -7,7 +7,7 @@ import Foundation
 /// took over; it is checked on its own with swiftc against scripted streams in virtual time
 /// (`Tests/checks/encoder-slowstate`, which CI runs).
 ///
-/// The slow state (CLAUDE.md, "The 33 fps plateau"), measured alone on the engine at 3024×1964:
+/// The slow state (docs/HISTORY.md, "The 33 fps plateau"), measured alone on the engine at 3024×1964:
 /// every fresh session started fast (9 ms a frame, then ~16 ms paced to 57 fps); about a second
 /// into a quiet spell an isolated frame took 29 ms, and once motion resumed every frame did for as
 /// long as it lasted (90 s of 90): 34 fps out of 57 captured, one frame inside at a time.

Sources/SillHost/HEVCEncoder.swift

@@ -18,7 +18,7 @@ import StreamProtocol
 ///   finds the place taken waits in the mailbox, where a newer one replaces it (`EncoderMailbox`,
 ///   which keeps this bookkeeping and is checked on its own). Latency beats quality: a frame the
 ///   encoder has no room for waits in the mailbox, never inside VT behind another. Two inside at
-///   once was measured against the hardware's slow state and dropped (CLAUDE.md, "The 33 fps
+///   once was measured against the hardware's slow state and dropped (docs/HISTORY.md, "The 33 fps
 ///   plateau").
 /// - A watchdog on its own queue declares the session dead when a frame has been inside VT
 ///   `hangAfter` seconds without an output. The owner is told (`onHung`) and starts over on the
@@ -31,10 +31,10 @@ import StreamProtocol
 ///     the encoder firmware's priority 80, a real-time session like this one at 0, and the one
 ///     encoder engine served the recorder while this session's frame waited 1.8 s and 8.6 s. Both
 ///     frames came back, and fresh sessions answered at once. The kernel's AppleAVE2 log showed it
-///     (CLAUDE.md, "Frozen stream").
+///     (docs/HISTORY.md, "Frozen stream").
 ///   A session given up on reports on its way out whether its stalled frame ever came back
 ///   (`deinit`): a busy encoder hands it back, a stuck one never does.
-/// - The hardware's slow state (CLAUDE.md, "The 33 fps plateau"): a session fed sparse frames for
+/// - The hardware's slow state (docs/HISTORY.md, "The 33 fps plateau"): a session fed sparse frames for
 ///   about a second can settle at ~29 ms a frame instead of 9–16 and stay there through any motion
 ///   that follows (34 fps out of 57 captured at 3024×1964). When a stream's session does
 ///   (`EncoderSlowState`), the stream gets a new one in place (`replacesSlowSessions`): made on a
@@ -109,7 +109,7 @@ final class HEVCEncoder {
     private var watchdog: DispatchSourceTimer?
     static let hangAfter: CFTimeInterval = 1.5
     /// A hardware stream session that settles in the slow state is replaced (`EncoderSlowState`).
-    /// Measured alone on the engine (CLAUDE.md, "The 33 fps plateau"): the resumed motion ran at
+    /// Measured alone on the engine (docs/HISTORY.md, "The 33 fps plateau"): the resumed motion ran at
     /// 57 fps against 34 without it. False keeps each session for the stream's life.
     static let replacesSlowSessions = true
     /// `replacesSlowSessions`, unless TEST ONLY `SILL_TEST_ENCODER_RECYCLE=1` or `0` says otherwise for

Sources/SillHost/HostConfig.swift

@@ -27,7 +27,7 @@ package struct HostConfig: Equatable, Sendable {
     /// Direct Wireless Connection: peer-to-peer Wi-Fi (AWDL) on the listener and its Bonjour
     /// registration, so a device with no network in common can find and reach the Mac. Off by
     /// default: while it is on the kernel keeps AWDL up and the Mac's one radio leaves its Wi-Fi
-    /// channel up to ~97 ms every 524 ms (CLAUDE.md, trackpad stutter). The listener's, not the
+    /// channel up to ~97 ms every 524 ms (docs/HISTORY.md, trackpad stutter). The listener's, not the
     /// pipeline's: a change replaces the listener (StreamServer.setPeerToPeer) and never restarts
     /// the stream.
     package var directWireless: Bool

Sources/SillHost/VirtualStage.swift

@@ -192,7 +192,7 @@ final class VirtualStage {
         return Self.fraction(of: live, inside: CGDisplayBounds(d.displayID)) < 0.9
     }
 
-    // MARK: Geometry (pure; the numbers in CLAUDE.md come from these)
+    // MARK: Geometry (pure; the numbers in docs/HISTORY.md come from these)
 
     /// The size the window should have on the virtual display, in Mac points: the client's panel
     /// divided by its text scale (Aa Off or a bad scale count as 1.0), or the window's own size

Sources/SillHostCLI/main.swift

@@ -31,7 +31,7 @@ config.virtualDisplay = virtualDisplay
 // `SillHost --direct-wireless`: also advertise over, and accept connections from, peer-to-peer
 // Wi-Fi (AWDL), so a device with no network in common can connect. Off by default: while it is on
 // the Mac's radio leaves its Wi-Fi channel up to ~97 ms every 524 ms, which is the stutter in
-// CLAUDE.md. A device can still turn it on or off; that lasts until SillHost quits.
+// docs/HISTORY.md. A device can still turn it on or off; that lasts until SillHost quits.
 config.directWireless = CommandLine.arguments.contains("--direct-wireless")
 
 // `SillHost --no-clipboard`: share nothing of the clipboard with devices for this run (kind 32,

Tests/checks/README.md

@@ -101,7 +101,7 @@ with it, in the same commit.
 
 ## Where they came from
 
-Each check was written beside the change it verifies (the plans in `docs/` and CLAUDE.md's entries
+Each check was written beside the change it verifies (the plans in `docs/` and the entries in docs/HISTORY.md
 name them: H2, H3, H13 and so on) and moved here unchanged except for paths: the compile line in a
 `main.swift`'s header comment, and the `policy`, `fence` and `clientlink` mutants scripts, which
 named absolute paths and wrote beside themselves; they now read the repository and write to

Tests/checks/key-strokes/main.swift

@@ -1,6 +1,6 @@
 import Foundation
 
-// The Mac's modifier keys after a device's keys (CLAUDE.md, "The stuck command after Spotlight"):
+// The Mac's modifier keys after a device's keys (docs/HISTORY.md, "The stuck command after Spotlight"):
 // KeyStrokes (Sources/SillHost), the keyboard events InputInjector posts for a device's keys, put
 // through a model of InputInjector's glue and of the Mac's HID state table.
 //

Tests/checks/key-strokes/run.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # KeyStrokes (Sources/SillHost): the keyboard events the Mac is sent for a device's keys, and what
-# they leave in its HID state table, which every click and scroll after them starts from (CLAUDE.md,
+# they leave in its HID state table, which every click and scroll after them starts from (docs/HISTORY.md,
 # "The stuck command after Spotlight"): a key's up leaves only the modifiers still held down, a
 # modifier's own key goes up without its flag, a device's own word on its modifiers lets go of the
 # keys it no longer holds, and a device that leaves, or the host that goes, lets go of its keys; the

docs/DEVELOPMENT.md

@@ -6,7 +6,8 @@ Sill, see the [Support](https://getsill.app/support) page on
 
 Until 2026-09-25 this was the README, so where a plan in `docs/` mentions "the
 README", it means a section here. `CLAUDE.md` has the rest: the work in
-progress, the decisions already made, and every test hook.
+progress, the decisions already made, and every test hook. `docs/HISTORY.md`
+has what each merged step did and what is left to test on a device.
 
 ## Overview