Skip to content

docs: correct ARCHITECTURE.md and BUILDING.md against the current tree - #19

Merged
AdamXweb merged 3 commits into
mainfrom
docs/refresh-architecture-and-building
Aug 10, 2026
Merged

docs: correct ARCHITECTURE.md and BUILDING.md against the current tree#19
AdamXweb merged 3 commits into
mainfrom
docs/refresh-architecture-and-building

Conversation

@adamXbot

@adamXbot adamXbot commented Aug 9, 2026

Copy link
Copy Markdown
Collaborator

Both files predate most of the codebase and had drifted far enough to actively mislead.

The one that cost me an hour

ARCHITECTURE.md states that PfctlKillSwitch.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.

Path Contents Built?
privacycommand/privacycommandHelper/ 5 sources incl. PfctlKillSwitch.swift Yes — this is what the Xcode project references
privacycommand/Sources/privacycommandHelper/ 4 sources, 29 lines shorter, no kill switch No — vestigial

ARCHITECTURE.md was describing the stale one. I've corrected the path, the file list, and the diagram, and explicitly flagged that the Sources/ 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

Was Is
Detectors 29 41
Monitoring files 11 12
SwiftUI files 59 63
Total Swift ~100 229
Commits "six commits old" 89

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.

  • Wrong path. cd "MacOS Permissions/privacycommand" — that folder no longer exists.
  • Wrong bundle ID. com.example.privacycommand, in two places. It's org.privacykey.privacycommand, with .HelperTool and .tests.
  • Wrong targets. Claimed two targets and "all 31 Swift sources" in a single app target. There are five Xcode targets; the app alone has 63 sources.
  • Sparkle was missing entirely. A fresh checkout doesn't build without adding the package dependency. The README documents this; BUILDING.md didn't.
  • Added the helper Team ID requirement as failure mode 0. It's the most likely thing to go wrong, it builds cleanly and only fails at runtime, and it takes out file monitoring, the BTM audit and the kill switch simultaneously.
  • Retitled "What I would expect to fail first on a real build" — written before the project had ever been built — to describe what actually trips people.

Scope

Docs only; no code touched. User-facing documentation now lives at privacykey/docs-privacycommand, so these two files are explicitly the internal pair.

Adam 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.
@AdamXweb
AdamXweb merged commit 7f9b355 into main Aug 10, 2026
3 checks passed
@AdamXweb
AdamXweb deleted the docs/refresh-architecture-and-building branch August 10, 2026 16:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants