docs: correct ARCHITECTURE.md and BUILDING.md against the current tree - #19
Merged
Conversation
added 2 commits
August 9, 2026 19:52
Both files predate most of the codebase and had drifted far enough to mislead. ARCHITECTURE.md - The helper row said PfctlKillSwitch.swift "isn't committed yet", and the audit-flow diagram called the kill switch "planned". It ships. The file was reading Sources/privacycommandHelper/, a stale duplicate; Xcode builds the top-level privacycommandHelper/ directory, which has all 5 sources. Both the correct path and the existence of the stale copy are now called out, because anyone editing the wrong one will wonder why nothing changes. - Counts refreshed: 41 detectors (was 29), 12 monitoring files (was 11), 63 SwiftUI files (was 59), 229 Swift files total. Dropped "six commits old" — it is 89. - "The four targets" listed seven. - Finished the truncated sentence in the intro and pointed it at the sibling design docs. BUILDING.md - Wrong path: cd "MacOS Permissions/privacycommand" — that folder is long gone. - Wrong bundle ID: com.example.privacycommand. It is org.privacykey.privacycommand, with .HelperTool and .tests alongside. - Wrong target list: claimed two targets and "all 31 Swift sources" in one app target. There are five Xcode targets; the app alone has 63 sources. - The Sparkle package dependency was missing entirely — a fresh checkout does not build without it, and the README documented it while BUILDING.md didn't. - Added the helper Team ID requirement as failure mode 0. It is the most likely thing to go wrong, it builds cleanly and only fails at runtime, and it takes out every privileged feature at once. - Retitled the speculative "What I would expect to fail first on a real build" section, written before the project had been built, to describe what actually trips people. User-facing documentation now lives at privacykey/docs-privacycommand; these two files stay internal.
… at it Sources/privacycommandHelper/ was a dead copy of the helper target. Verified before removing: - Package.swift declares no helper target at all — it is Xcode-only, and the Xcode project references the top-level privacycommandHelper/ directory. - Diffing the two trees: CodeSignValidator, FsUsageRunner and main were byte identical; HelperToolService was 29 lines behind; PfctlKillSwitch.swift existed only in the live tree. Nothing unique was lost. - The only remaining references were prose, all corrected here. It had already caused real confusion: ARCHITECTURE.md described the dead tree and concluded the network kill switch was unimplemented. README.md, while here: - The privileged-helper row pointed at the deleted path. - [`architecture.md`](ARCHITECTURE.md) was a broken link — the file is at .github/ARCHITECTURE.md. - docs/RELEASES.md does not exist and never has. Both the README and ARCHITECTURE.md linked it twice. Pointed at the real release pipeline instead: privacykey/gh-workflows, with .github/workflows/release.yml as the thin caller that documents the secret layout. - "Related products" listed only privacycommand itself. It now names the siblings it was presumably meant to. - Added a Documentation section pointing at the new docs site. HELPER.md said the target builds from Sources/privacycommandHelper/*.swift. Corrected to the directory beside Sources/, which is what Xcode actually compiles.
README.md conflicted: PR #18 restructured it to the portfolio standard, which supersedes every README edit this branch made. Took main's version wholesale — the helper-path table, the Updates section and the Related products list that this branch was correcting no longer exist there, and the ARCHITECTURE.md link it fixed is already correct on main. Two corrections to keep the merged tree self-consistent: - ARCHITECTURE.md claimed user-facing docs live at docs-privacycommand. That repo is private and docs.privacycommand.privacykey.org does not resolve, so main's "there is no docs site yet" is the accurate line. Pointed the scale note at README.md instead. - Swift file count 229 -> 225. Counted before this branch's own second commit deleted the four stale helper sources.
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
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.
Both files predate most of the codebase and had drifted far enough to actively mislead.
The one that cost me an hour
ARCHITECTURE.mdstates thatPfctlKillSwitch.swift"isn't committed yet", and the audit-flow diagram labels the network kill switch "planned". It ships and works.The cause is worth fixing properly: there are two helper source trees.
privacycommand/privacycommandHelper/PfctlKillSwitch.swiftprivacycommand/Sources/privacycommandHelper/ARCHITECTURE.mdwas describing the stale one. I've corrected the path, the file list, and the diagram, and explicitly flagged that theSources/copy exists and should be deleted — anyone who edits the wrong tree will spend a while wondering why nothing changes. I haven't deleted it in this PR, since that's a code change rather than a docs fix; happy to follow up.ARCHITECTURE.md — counts
Also: "The four targets" heads a table listing seven, and the intro sentence was truncated mid-clause — now completed and pointed at the sibling design docs.
BUILDING.md
This one was worse — following it verbatim does not produce a build.
cd "MacOS Permissions/privacycommand"— that folder no longer exists.com.example.privacycommand, in two places. It'sorg.privacykey.privacycommand, with.HelperTooland.tests.Scope
Docs only; no code touched. User-facing documentation now lives at privacykey/docs-privacycommand, so these two files are explicitly the internal pair.