MacMonitor/AGENTS.md

# AGENTS.md: Developer & AI Agent Operating Guide

Welcome to **MacMonitor**. This document serves as the authoritative operating manual for autonomous AI coding agents and human engineers contributing to this repository.

---

## 1. Non-Negotiable Architectural Rules

1. **Architecture & Target OS**:
   - The target architecture is **Intel `x86_64`** exclusively. Do not introduce Apple Silicon ARM64-only assembly, intrinsics, or dependencies.
   - The minimum deployment target is **macOS 14.0 (Sonoma)**. Do not downgrade deployment targets or use deprecated Carbon APIs.
2. **Language Boundaries**:
   - **UI & Presentation**: Modern **SwiftUI** with `@Observable`, `@MainActor`, and **Swift Charts**.
   - **Kernel & Telemetry**: **Objective-C / C** communicating directly with Mach kernel, IOKit, BSD sysctls, and CoreFoundation.
   - **Bridging**: All Objective-C headers exposed to Swift must be declared in `Sources/Bridging/MacMonitor-Bridging-Header.h`.
3. **Gitea MCP Tool Usage**:
   - Whenever performing repository operations, creating branches, reviewing issues, updating comments, or managing pull requests on `git.i3omb.com`, **always** use the available tools on the `gitea` MCP server (`call_mcp_tool` with `ServerName: "gitea"`).
   - Never use raw shell scripts (`curl`, raw tokens) to interact with the Gitea API.

---

## 2. Deterministic Branching Strategy & Workflow

Every feature implementation must follow the branch taxonomy defined in [BUILD-PLAN.md](BUILD-PLAN.md):

```mermaid
gitGraph
   commit id: "Initial commit"
   branch develop
   checkout develop
   commit id: "Docs & Build Plan"
   branch milestone/m1-foundation
   checkout milestone/m1-foundation
   branch feat/1-core-architecture
   checkout feat/1-core-architecture
   commit id: "MMTelemetryCoordinator"
   checkout milestone/m1-foundation
   merge feat/1-core-architecture id: "PR #1 Merged"
   branch feat/2-smc-client
   checkout feat/2-smc-client
   commit id: "AppleSMC IOKit client"
   checkout milestone/m1-foundation
   merge feat/2-smc-client id: "PR #2 Merged"
   checkout develop
   merge milestone/m1-foundation id: "M1 Complete"
```

### 2.1 Branch Naming Directory
When picking up an issue, you must use the exact branch name assigned to that issue:

- Issue #1: `feat/1-core-architecture` (branch from `milestone/m1-foundation`)
- Issue #2: `feat/2-smc-client` (branch from `milestone/m1-foundation`)
- Issue #25: `feat/25-gitea-ci` (branch from `milestone/m1-foundation`)
- Issue #3: `feat/3-cpu-thermals` (branch from `milestone/m2-primary-telemetry`)
- Issue #4: `feat/4-fan-telemetry` (branch from `milestone/m2-primary-telemetry`)
- Issue #5: `feat/5-cpu-load` (branch from `milestone/m2-primary-telemetry`)
- Issue #8: `feat/8-ram-breakdown` (branch from `milestone/m2-primary-telemetry`)
- Issue #9: `feat/9-storage-volumes` (branch from `milestone/m2-primary-telemetry`)
- Issue #18: `feat/18-component-temps` (branch from `milestone/m2-primary-telemetry`)
- Issue #19: `feat/19-power-voltage` (branch from `milestone/m2-primary-telemetry`)
- Issue #6: `feat/6-kernel-counters` (branch from `milestone/m3-advanced-telemetry`)
- Issue #7: `feat/7-load-averages` (branch from `milestone/m3-advanced-telemetry`)
- Issue #10: `feat/10-disk-io` (branch from `milestone/m3-advanced-telemetry`)
- Issue #11: `feat/11-process-explorer` (branch from `milestone/m3-advanced-telemetry`)
- Issue #12: `feat/12-process-threads` (branch from `milestone/m3-advanced-telemetry`)
- Issue #14: `feat/14-gpu-telemetry` (branch from `milestone/m3-advanced-telemetry`)
- Issue #15: `feat/15-network-throughput` (branch from `milestone/m3-advanced-telemetry`)
- Issue #16: `feat/16-network-sockets` (branch from `milestone/m3-advanced-telemetry`)
- Issue #17: `feat/17-battery-telemetry` (branch from `milestone/m3-advanced-telemetry`)
- Issue #20: `feat/20-bus-topology` (branch from `milestone/m3-advanced-telemetry`)
- Issue #21: `feat/21-audio-status` (branch from `milestone/m3-advanced-telemetry`)
- Issue #13: `feat/13-display-brightness` (branch from `milestone/m4-presentation`)
- Issue #22: `feat/22-menubar-popover` (branch from `milestone/m4-presentation`)
- Issue #23: `feat/23-trend-charts` (branch from `milestone/m4-presentation`)
- Issue #24: `feat/24-threshold-alerts` (branch from `milestone/m5-alerts-hardening`)

---

## 3. Telemetry Provider Implementation Invariants

Every low-level telemetry provider created by an agent must conform to the following contract:

### 3.1 Contract Interface
```objc
@protocol MMTelemetryProvider <NSObject>
@property (nonatomic, readonly) MMTelemetryDomain domain;
@property (nonatomic, readonly, copy) NSString *providerIdentifier;
@property (nonatomic, readonly, getter=isAvailable) BOOL available;

- (nullable NSDictionary<NSString *, id> *)sampleTelemetryWithError:(NSError **)error;
@optional
- (void)startMonitoring;
- (void)stopMonitoring;
@end
```

### 3.2 Critical Memory Management Rules
- **Mach Pointer Deallocation:** Any call to `host_processor_info` allocates a Mach virtual memory buffer. Always invoke `vm_deallocate(mach_task_self(), (vm_address_t)ptr, size)` on previous iterations.
- **IOKit Registry Release:** Every `io_registry_entry_t` or `io_iterator_t` returned by `IOServiceGetMatchingServices` or `IOIteratorNext` must be balanced with `IOObjectRelease()`.
- **IOKit Connection Cleanup:** Close user clients using `IOServiceClose()` in `dealloc` or sleep handlers.
- **Autorelease Pool Scoping:** Wrap sampling logic inside `@autoreleasepool { ... }` blocks to reclaim temporary CoreFoundation/Objective-C allocations immediately on each timer tick.

---

## 4. Concurrency & Thread-Safety Invariants

1. **Zero UI Blocking**:
   Under no circumstances may low-level C calls (IOKit, Mach, sysctl) be invoked directly on the main thread (`@MainActor`). All sampling occurs exclusively on `com.i3omb.macmonitor.telemetry` (`QOS_CLASS_UTILITY`).
2. **Value-Type Boundaries**:
   Data passed from Objective-C to Swift view models must be immutable snapshot copies (primitive scalars, strings, or `Sendable` structs). Never pass mutable Objective-C object references into SwiftUI views.
3. **Fast Mutex Synchronization**:
   For shared state (such as SMC key caches or ring buffers), use `os_unfair_lock` or `NSLock`. Do not use `@synchronized(self)`.

---

## 5. Testing & Verification Requirements

### 5.1 Synthetic Hardware Mocking in CI
When writing unit tests for Gitea Actions runners (which may execute in headless virtual machines without physical SMC chips):
- Never assert that physical hardware calls return live metrics in unit tests.
- Structure providers with dependency injection to accept synthetic binary test buffers:
  ```objc
  // Test mock SMC byte decoding
  uint8_t mockTempBytes[2] = { 0x36, 0x80 }; // 54.5°C in sp78 format
  float temp = [MMSMCParser decodeSP78:mockTempBytes];
  XCTAssertEqualWithAccuracy(temp, 54.5, 0.01);
  ```
- Mock Mach host statistics using recorded structs to verify delta load calculation algorithms.

### 5.2 Build Command Verification
Before opening any Pull Request, ensure that the project compiles cleanly for Intel x86_64:
```bash
xcodebuild build test \
  -scheme MacMonitor \
  -destination 'platform=macOS,arch=x86_64' \
  CODE_SIGNING_ALLOWED=NO
```

---

## 6. Label & Issue Conventions on Gitea

- **Tagging**: Every issue, PR, and milestone must carry the `Project/Antigravity` label.
- **Components**: Tag issues with functional area labels:
  - `Feature/Architecture` or `Bug/Architecture`
  - `Feature/Backend` or `Bug/Backend`
  - `Feature/UI` or `Bug/UI`
  - `Feature/DevOps` or `Bug/DevOps`
- **Priorities**: Must accurately reflect system value (`Priority/Critical`, `Priority/High`, `Priority/Medium`, `Priority/Low`).
- **Dependencies**: Keep cross-references updated in the issue body under `### Dependencies`.