Move engine README into Sources/BlurtEngine and document evals - #137
Merged
Conversation
Two documentation moves, both about putting the guide next to the thing it documents. `evals/` had no directory-level README — only the harness's own, one level down. Add one that says what the directory is (offline decision support, the repo's only Python, none of it shipped), indexes the harnesses, and records how check.sh gates it: ruff format/check over evals/ and pytest over the one named test file, all three in the --portable subset. That last detail is the trap a second harness would hit — the pytest step names a file rather than globbing, so new tests have to be added to check.sh in the same commit or they never run. `BLURTENGINE.md` becomes `Sources/BlurtEngine/README.md`, so the engine's developer guide sits in the package it describes and renders as the landing page for anyone browsing there. Its two outbound links are repointed at the root, the inbound links in README.md and AGENTS.md follow it, and the repository map in AGENTS.md gains both files. Package.swift excludes the new README from the target: SwiftPM has no rule for a stray .md inside a target directory, so an undeclared one lands in the unhandled-files list. scripts/check.sh --portable is green (prettier, markdownlint, ruff, pytest); the Swift half needs a Mac, so CI is the authority there. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015BBN7mYHeENP9sJc3TNjZW
Contributor
Dev buildDownload Blurt.app — built from Installing itcd ~/Downloads
unzip -o blurt-dev-build-pr-137.zip # GitHub wraps every artifact in a zip
unzip -o Blurt-dev-56481f6.zip
find Blurt.app -exec xattr -c {} + # clear quarantine: xattr lost -r in macOS 12.3
rm -rf /Applications/Blurt.app && cp -R Blurt.app /Applications/
open -a BlurtIt is ad-hoc signed and not notarized: Gatekeeper refuses to open it until Expect that re-grant once per dev build, including a second build of this tccutil reset Accessibility dev.alex.blurt |
alexkroman
pushed a commit
that referenced
this pull request
Aug 13, 2026
Two conflicts of substance, both from main's side moving under this branch. scripts/check.sh: #136 deleted pr-dev-build.yml and corrected the actionlint comment naming it; this branch had restructured that same block into a run_check call. Kept both — main's wording, this branch's structure. check-invariants.sh scoping: #137 moved BLURTENGINE.md to Sources/BlurtEngine/README.md, and the ENGINE scope was the whole Sources directory, which had been all Swift until then. The gate promptly flagged two paragraphs of that document for saying "Do not replace this with a long-lived AVAudioEngine/installTap graph" — prose about a rule read as a violation of it. The whole-line-comment filter cannot help there: a Markdown paragraph is not a comment in any language grep knows. So the scopes now name file types rather than directories, which is what they should have said in the first place: these rules are about code, and a directory holds more than code. It also takes the app scope off the .png and .m4a resources it had been grepping byte by byte. The twelve anchors still resolve against main's rewritten AGENTS.md, so none of the pinned rows moved in #136 or #137. Verified after the merge: --self-test green, the scan clean, and the scan still bites on an injected AVAudioEngine in Swift and an injected LSUIElement in Info.plist. scripts/check.sh --portable is green. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TACi7k2226no2tVcR3YJr1
alexkroman
pushed a commit
that referenced
this pull request
Aug 13, 2026
main moved to e577f19 — #136 removed the per-PR dev builds and split the debug/release bundle IDs, #137 moved BLURTENGINE.md to Sources/BlurtEngine/README.md and added an evals README. Git tracked the rename, so this branch's edits to the engine guide (the `.connecting` phase, the liveness gate, the Bluetooth accommodations, the CoreAudio import line) followed into the new path with no conflict. One conflict, in AGENTS.md's repository map: both sides rewrote the same Audio/ line. Resolved by keeping main's new README.md entry and this branch's expanded Audio/ contents, with MicCapture+Warm added since the line was written. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JU1Ln2MKMsF9PJf1FLMQRX
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
This change reorganizes documentation to better reflect the repository structure:
Moves
BLURTENGINE.md→Sources/BlurtEngine/README.md: The engine's developer guide now lives next to the code it documents, making it easier to discover and maintain alongside the package itself. Updated all cross-references inAGENTS.mdandREADME.mdto point to the new location.Adds
evals/README.md: Documents the Python evaluation harnesses (currently justdictation-prompt/) that are gated by CI but don't ship in the app. Explains the purpose of each harness, how the gate works, and how to run them withuv run.Updates
Package.swift: DeclaresREADME.mdas excluded from the BlurtEngine target so SwiftPM doesn't treat it as an unhandled file.Reorganizes repository map in
AGENTS.md: Reflects the new structure withevals/as a top-level directory containingdictation-prompt/andruff.toml.The changes clarify that evals are a first-class part of the repo's quality gate (linted, formatted, tested by CI) while making it clear they don't ship. Moving the engine README into the package also establishes a pattern for where developer guides live.
How it was tested
scripts/check.shpasses (or CI will, if I'm not on a Mac)No functional changes — this is pure documentation reorganization and cross-reference updates.
https://claude.ai/code/session_015BBN7mYHeENP9sJc3TNjZW