Skip to content

Restructure the README to the portfolio standard - #4

Merged
adamXbot merged 1 commit into
mainfrom
docs/readme-standard
Aug 10, 2026
Merged

Restructure the README to the portfolio standard#4
adamXbot merged 1 commit into
mainfrom
docs/readme-standard

Conversation

@adamXbot

@adamXbot adamXbot commented Aug 9, 2026

Copy link
Copy Markdown
Owner

Brings the README into the portfolio-wide layout: hero, badge row, disclosure block, rule, overview, ## What it does, ## Get it, ## Contributing, ## Licence. The existing voice and the accurate prose are kept — this is a restructure plus a correctness pass, not a rewrite.

Wrong facts removed

  • The Install section pointed at a download that does not exist. It said to download the latest ClaudeWatch.zip from the Releases page, unzip, and drag to /Applications. gh release list is empty and there are no tags, so there has never been anything on that page. Replaced with build-from-source instructions and a plain statement that there is no packaged download and no Homebrew formula yet.
  • The release badge could not resolve. https://img.shields.io/github/v/release/adamXbot/ClaudeWatch returns release: no releases or repo not found. Dropped until a non-prerelease release exists.
  • "makes no network connections" — not true. Sources/ClaudeWatch/Updater.swift constructs SPUStandardUpdaterController(startingUpdater: true, …), so Sparkle begins its scheduled-update lifecycle at launch against the SUFeedURL that build.sh writes into Info.plist.
  • "No telemetry, no network, no data leaves your machine" — also not true. NotificationEngine holds a URLSession and posts to user-configured Discord, Slack, Teams and generic-JSON webhooks. The overview now says what is actually true: it never writes to your transcripts and there is no telemetry, and it names both network paths.
  • The signed/notarised release note described a path that has never run. The release job in build.yml only fires on a v* tag, and no tag exists. Only the unsigned first-launch caveat is kept.
  • "Two icons appear in your menu bar" was unconditional. Per SourceAvailability and isVisible(_:), one menu-bar item appears per source that actually has transcripts, with a manual show/hide override in Settings.

No dead relative paths were found in the old README; every path and URL in the new README and CONTRIBUTING.md was checked (test -e for paths, curl for URLs) and returns < 400, with the one exception noted at the bottom.

Real content that was missing

Added from the source, not invented: the Codex event kinds (exec_command, write_stdin, apply_patch), the active-sessions strip and the bell menu-bar icon when a session is waiting, and the notification rules with Keychain-stored webhook URLs. None of these were documented.

Content moved, not deleted

New CONTRIBUTING.md takes the project layout, the --dump and --render-test headless modes, the justfile recipes, what CI genuinely runs, and how the tag-triggered release job degrades when signing secrets are absent.

Badges

Status, CI, licence. The CI badge resolves to passingbuild.yml runs on pushes to main and there are successful runs there. The licence badge resolves to MITLICENSE exists.

Size

README 4624 -> 5060 bytes, under the ~6 KB target. Plus 3378 bytes of moved content in CONTRIBUTING.md.

Known, expected

The status badge renders "resource not found" and its STATUS.md link 404s until the status hub PR merges in adamXbot/.github. The endpoint path is correct and will resolve then.

Separately, and out of scope for this PR: build.sh and build.yml both point maintainers at a RELEASING.md that does not exist in the repo.

Reorders the README into the standard product layout (hero, badges,
disclosure, overview, what it does, get it, contributing, licence) and
corrects several claims that the source contradicts.

Removed or corrected:

- The Install section told readers to download ClaudeWatch.zip from the
  Releases page. No release has ever been published, so there was nothing
  to download. Replaced with build-from-source instructions, stated
  plainly as the only way to get it today.
- The release badge rendered "no releases or repo not found" for the same
  reason; dropped until a release exists.
- "makes no network connections" and "No telemetry, no network, no data
  leaves your machine" were both wrong. Sources/ClaudeWatch/Updater.swift
  starts Sparkle's updater at launch against the SUFeedURL that build.sh
  writes into Info.plist, and NotificationEngine posts to user-configured
  Discord/Slack/Teams/generic webhooks over URLSession. The overview now
  says it never writes to your transcripts and has no telemetry, and names
  the two network paths.
- The signed-and-notarised release note described a path that has never
  run; only the unsigned first-launch caveat remains.
- "Two icons appear in your menu bar" was unconditional. One item appears
  per source that actually has transcripts, per SourceAvailability and
  isVisible(_:).

Added, all verified against the source: the Codex event kinds
(exec_command, write_stdin, apply_patch), the active-sessions strip and
bell icon, and the notification rules and Keychain-backed webhooks, none
of which the README mentioned.

Moved out of the README rather than deleted, into a new CONTRIBUTING.md:
the project layout, the --dump and --render-test headless modes, the
justfile recipes, what CI actually runs, and how the tag-triggered release
job behaves.

Badges are now status, CI and licence. The CI badge resolves ("passing")
because build.yml runs on pushes to main; the licence badge resolves
("MIT") because LICENSE exists.

4624 -> 5060 bytes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@adamXbot
adamXbot merged commit 3d5c22b into main Aug 10, 2026
2 checks passed
@adamXbot
adamXbot deleted the docs/readme-standard branch August 10, 2026 16:21
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.

1 participant