From 6c6d4c13ae23418b2419e643ad2434da184d22fc Mon Sep 17 00:00:00 2001
From: pekth <5535435+pekth@users.noreply.github.com>
Date: Tue, 29 Sep 2026 10:59:21 -0400
Subject: [PATCH 1/2] docs(agents): note Swift tooling is macOS-only over SSH

---
 AGENTS.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 5ca1ae1..4c7af7a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,7 +6,9 @@ public repository.
 ## Project rules
 
 - Keep changes focused and explain user-visible behavior in the pull request.
-- Run `swift build` and `swift test` before submitting code changes.
+- Run `swift build` and `swift test` before submitting code changes. Swift is
+  macOS-only; when the current host is not macOS, run these on the Mac over SSH
+  (`ssh fleet-mac`, `zsh`). Do not claim Swift verification from a non-macOS host.
 - During release work, verify each requested state separately: tested source,
   built and signed bundle, installed and running app, Git tag, published GitHub
   Release, uploaded asset, and manual runtime checks. Do not infer one state

From 1795077ed0c5841abf1ae4a4f0abf40407a02f6b Mon Sep 17 00:00:00 2001
From: pekth <5535435+pekth@users.noreply.github.com>
Date: Wed, 30 Sep 2026 22:26:30 -0400
Subject: [PATCH 2/2] docs(agents): clarify macOS package validation

---
 AGENTS.md    | 7 ++++---
 CHANGELOG.md | 7 +++++++
 docs/KB.md   | 2 +-
 3 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 4c7af7a..36a084b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,9 +6,10 @@ public repository.
 ## Project rules
 
 - Keep changes focused and explain user-visible behavior in the pull request.
-- Run `swift build` and `swift test` before submitting code changes. Swift is
-  macOS-only; when the current host is not macOS, run these on the Mac over SSH
-  (`ssh fleet-mac`, `zsh`). Do not claim Swift verification from a non-macOS host.
+- Run `swift build` and `swift test` before submitting code changes. This
+  package uses macOS frameworks and requires macOS 13 or later. When developing
+  on Linux, run these checks on macOS over SSH. Report the actual validation
+  host; Swift itself also supports other platforms.
 - During release work, verify each requested state separately: tested source,
   built and signed bundle, installed and running app, Git tag, published GitHub
   Release, uploaded asset, and manual runtime checks. Do not infer one state
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d96c6dc..05e3ec9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,13 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 follows [Semantic Versioning](https://semver.org/).
 
+## Unreleased
+
+### Changed
+
+- Clarify that this package requires macOS for build and test checks. Replace
+  the private SSH alias in public agent guidance with a generic macOS SSH route.
+
 ## [0.2.39] - 2026-09-27
 
 ### Fixed
diff --git a/docs/KB.md b/docs/KB.md
index 6558202..f2b660c 100644
--- a/docs/KB.md
+++ b/docs/KB.md
@@ -11,7 +11,7 @@ Last verified: 2026-09-27
 ## Product and source facts
 
 - meterusage is a macOS menu-bar app that displays AI coding-assistant quota and usage signals. `README.md` describes provider clusters, quota cards, heatmaps, sparklines, alerts, diagnostics, and a scriptable JSON CLI.
-- The app is Swift Package Manager based, targets macOS 13 or later, and includes an executable target and a test target. `Package.swift` is the source for this package structure.
+- The app is Swift Package Manager based, targets macOS 13 or later, and includes an executable target and a test target. `Package.swift` is the source for this package structure. Its AppKit and SwiftUI imports require macOS for package build and test checks; Swift itself supports other platforms. `AGENTS.md` describes a generic macOS SSH route for Linux development without private host aliases.
 - Provider data sources are implemented under `Sources/MeterUsage/Services/`. `docs/PRIVACY.md` describes the boundary for local files, provider CLIs, documented network endpoints, and data reduction before display.
 - Antigravity quota and usage share a bounded Docker/Podman runtime resolver. It prefers a healthy runtime and can start only an already-existing `podman-machine-default` after an inspect check; it never creates a machine or pulls an image. Concurrent recovery calls are serialized; failed starts have a 60-second cooldown. Internet or authentication failures are not repaired by restarting a healthy runtime.
 - Demo mode uses synthetic data. `README.md` and `docs/DEMO.md` describe it as the path for screenshots and local UI inspection without provider accounts.