diff --git a/AGENTS.md b/AGENTS.md
index 5ca1ae1..36a084b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,7 +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.
+- 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 fab78c8..3b54554 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.40] - 2026-09-29
 
 ### Added
diff --git a/docs/KB.md b/docs/KB.md
index dd853ef..d30c89a 100644
--- a/docs/KB.md
+++ b/docs/KB.md
@@ -11,7 +11,7 @@ Last verified: 2026-09-29
 ## 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.