diff --git a/.github/ISSUE_TEMPLATE/pcp_bug_report.yml b/.github/ISSUE_TEMPLATE/pcp_bug_report.yml
new file mode 100644
index 0000000000..39f723c80b
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/pcp_bug_report.yml
@@ -0,0 +1,61 @@
+name: Performance Co-Pilot Issue Report
+description: Create a report for a PCP related bug
+title: "[Bug] "
+labels: ["bug"]
+body:
+ - type: markdown
+ attributes:
+ value: Thank you for taking the time to fill out this bug report!
+ - type: textarea
+ id: issue-description
+ attributes:
+ label: Issue Description
+ description: What is the issue that you are encountering?
+ validations:
+ required: True
+ - type: input
+ id: operating-system
+ attributes:
+ label: Operating System
+ description: What is your machines operating system? Include name and version number.
(`cat /etc/os-release | grep -E "^(NAME=|VERSION=)"`)
+ placeholder: e.g. Rocky Linux Version 9.5
+ validations:
+ required: True
+ - type: input
+ id: architecture
+ attributes:
+ label: Architecture
+ description: What is your machines architecture?
(`uname -m`)
+ placeholder: e.g. x86_64
+ validations:
+ required: True
+ - type: input
+ id: pcp-version
+ attributes:
+ label: PCP Version
+ description: What version of PCP are you using (optional)?
(`(cd path_to_your_pcp_install/bin && ./pcp)`)
+ placeholder: e.g. main or PCP 7.1.2
+ validations:
+ required: False
+ - type: input
+ id: component
+ attributes:
+ label: Component
+ description: What PCP component does this issue pertain to (optional)?
+ placeholder: e.g. pmlogger
+ validations:
+ required: False
+ - type: textarea
+ id: steps-to-reproduce
+ attributes:
+ label: Steps to Reproduce
+ description: Provide steps to reproduce this issue (optional).
+ validations:
+ required: False
+ - type: textarea
+ id: additional-information
+ attributes:
+ label: Additional Information
+ description: Is there any additional information that is relevant to your issue? Are there known machine configurations or versions of PCP where this issue does not occur?
+ validations:
+ required: False
diff --git a/.github/ISSUE_TEMPLATE/pcp_feature_request.yml b/.github/ISSUE_TEMPLATE/pcp_feature_request.yml
new file mode 100644
index 0000000000..18c92a2ced
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/pcp_feature_request.yml
@@ -0,0 +1,23 @@
+name: Performance Co-Pilot Feature Request
+description: Request additional functionality or suggest a new approach to existing functionality
+title: "[RFE] "
+labels: ["feature"]
+body:
+ - type: markdown
+ attributes:
+ value: Thank you for taking the time to make a feature request!
+ - type: textarea
+ id: feature-request
+ attributes:
+ label: Description of Request for Enhancement
+ description: Describe the feature that you would like to see in PCP.
+ validations:
+ required: True
+ - type: input
+ id: component
+ attributes:
+ label: Component
+ description: If this is for a specific PCP component, please mention it here (optional).
+ placeholder: e.g. pmlogger
+ validations:
+ required: False
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000000..945f25553b
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,14 @@
+## Pull Request Description
+
+## Related Issues
+Fixes #
+
+## Checklist
+- [ ] ** Description **
+_Why_ this PR exists. Reference all relevant information, including _background_, _issues_, _test failures_, etc
+- [ ] ** Commmits **
+_Commits_ are self contained and only do one thing
+_Commits_ have a header of the form: `module: short description`
+_Commits_ have a body (whenever relevant) containing a detailed description of the addressed problem and its solution
+- [ ] Documentation updated
+- [ ] Tests added/updated
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..c4054d4d96
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,194 @@
+# AGENTS.md
+
+This file provides guidance to AI Agents (for example claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Performance Co-Pilot (PCP) is a mature, extensible, cross-platform toolkit for system-level performance monitoring and management. It provides a unifying abstraction for all performance data in a system and many tools for interrogating, retrieving and processing that data.
+
+## Development Commands
+
+### Building and Packaging
+```bash
+# Configure and build from source (requires autotools)
+./configure --prefix=/usr --libexecdir=/usr/lib --sysconfdir=/etc --localstatedir=/var
+make
+
+# Build packages for the current platform
+./Makepkgs --verbose
+
+# Cross-compile for Windows (requires MinGW)
+./Makepkgs --verbose --target mingw64
+
+# Install manually after building
+sudo make install
+```
+
+### Quality Assurance Testing
+```bash
+# Run QA setup validation
+qa/admin/check-vm
+
+# Install dependencies for your platform
+qa/admin/list-packages -m
+
+# Run all QA tests
+cd qa && ./check
+
+# Run specific tests
+cd qa && ./check 000 # Run test 000
+cd qa && ./check 100-200 # Run tests 100-200
+cd qa && ./check -g pmcd # Run pmcd group tests
+
+# Create new test
+cd qa && ./new
+
+# Remake expected output for a test
+cd qa && ./remake 123
+```
+
+### PMCD Service Management
+```bash
+# Start the PCP daemon
+sudo systemctl start pmcd
+# or
+sudo service pmcd start
+
+# Check PCP metrics
+pminfo -dfmt
+pmprobe -v
+```
+
+## High-Level Architecture
+
+### Core Components
+
+- **libpcp**: Main PCP library providing core functionality
+- **pmcd**: Performance Metrics Collection Daemon - central coordinator
+- **pmlogger**: Performance data logging daemon
+- **pmie**: Performance Metrics Inference Engine - rule-based monitoring
+- **pmproxy**: Web API proxy and time series interface
+
+### Tool Categories
+
+1. **Data Collection Tools**: pmcd, pmlogger, various pmdas
+2. **Data Export Tools**: pcp2arrow, pcp2elasticsearch, pcp2json, etc.
+3. **Analysis Tools**: pminfo, pmval, pmstat, pmchart, pmrep and pcp subtools
+4. **Archive Tools**: pmlogdump, pmlogextract, pmlogrewrite, pmlogsummary
+5. **Administrative Tools**: pmconfig, pmlc, pmafm, pmcheck
+
+### PMDAs (Performance Metrics Domain Agents)
+
+PMDAs collect metrics from specific subsystems. Key directories in `src/pmdas/`:
+
+- **Platform PMDAs**: linux, darwin, aix, windows - core system metrics
+- **Application PMDAs**: apache, mysql, postgres, mongodb, elasticsearch
+- **System PMDAs**: bpf, bpftrace, nvidia, amdgpu
+- **Network PMDAs**: cisco, bind2, apache, nginx
+- **Storage PMDAs**: dm, nfsclient, gluster, xfs
+- **Development PMDAs**: sample, simple, trivial - for testing and examples
+
+### Library Structure
+
+- **libpcp**: Core library with platform abstractions
+- **libpcp_pmda**: PMDA development framework
+- **libpcp_pmcd**: PMCD-specific functionality
+- **libpcp_gui**: GUI toolkit integration
+- **libpcp_web**: Web API and time series support
+- **libpcp_trace**: Event trace instrumentation
+- **libpcp_import**: Data import for PCP archives
+
+## Available Agents
+
+- `pcp-code-reviewer` - Reviews code against PCP project standards (whitespace, naming, structure, PCP patterns)
+
+## Development Guidelines
+
+### QA Testing Philosophy
+- All changes should include appropriate QA tests
+- Tests should be deterministic and portable across platforms
+- Use existing archives and filtering functions where possible
+- Tests run as non-root user with sudo for privileged operations
+
+### PMDA Development
+- Use `src/pmdas/simple` or `src/pmdas/sample` as starting templates
+- Follow the Install/Remove script patterns in existing PMDAs
+- PMDAs can be written in C, Python, or Perl
+
+### Code Conventions
+- Follow existing code style in surrounding files
+- Add permanent diagnostics using pmDebugOptions framework
+- Use GPL-compatible licensing for all contributions
+- Never introduce code that logs or exposes secrets
+
+## Testing Requirements
+
+### Prerequisites
+- PCP must be installed (not run from source tree)
+- User "pcp" must exist for services
+- User "pcpqa" used for testing via pcp-testsuite package
+- Sudo access required for privileged operations
+
+### Essential QA Commands
+```bash
+# First-time setup validation
+cd qa && ./check 000
+
+# Check specific functionality
+cd qa && ./check -g pmcd # PMCD tests
+cd qa && ./check -g pmda # PMDA tests
+cd qa && ./check -g archive # Archive tests
+```
+
+### Platform Support
+PCP supports Linux, macOS, Windows (MinGW), AIX, and Solaris. Tests should be written to be portable or use `_notrun()` for platform-specific limitations.
+
+## macOS Development (Darwin Platform Only)
+
+When developing on macOS (`Platform: darwin` in environment):
+
+### Critical Constraints
+
+1. **Stage changes before VM tests**
+ - The Tart VM accesses the filesystem directly — `git add` is the minimum required
+ - Unstaged changes in `src/pmdas/darwin*` AND `build/mac/` are INVISIBLE to the VM
+ - A full commit also works; either way, run `/macos-qa-test` after staging
+
+2. **Test environments**
+ - Unit tests: Run locally (no PCP needed)
+ - Integration tests: Tart VM only (`/macos-qa-test`)
+
+### macOS-Specific Agent
+
+- `macos-darwin-pmda-qa` - Runs integration tests in isolated Tart VM
+
+### Quick Start
+```bash
+./Makepkgs --verbose # One-time: full build (5-30 min)
+cd build/mac/test && ./run-all-tests.sh # Daily: build + test (20-30s)
+```
+
+### Key Directories
+
+| Directory | Purpose |
+|-----------|---------|
+| `build/mac/` | Test orchestration, PKG packaging, Tart VMs |
+| `dev/darwin/` | Quick-compile tools (~10s vs 30min) |
+| `src/pmdas/darwin/` | Darwin PMDA source code |
+| `src/pmdas/darwin_proc/` | Darwin process PMDA source |
+
+### Documentation
+
+- `build/mac/CLAUDE.md` - Development workflow, test commands
+- `build/mac/MACOS_DEVELOPMENT.md` - Tart VM clean-room builds
+
+## Nix Development
+
+Nix packaging is provided via `flake.nix` and the `build/nix/` directory.
+See `docs/HowTos/nix/index.rst` for full documentation.
+
+```bash
+nix build # Build PCP package
+nix develop # Development shell
+nix flake show # List all packages and apps
+```
diff --git a/CLAUDE.md b/CLAUDE.md
index 9b4c9c1da6..43c994c2d3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,194 +1 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Performance Co-Pilot (PCP) is a mature, extensible, cross-platform toolkit for system-level performance monitoring and management. It provides a unifying abstraction for all performance data in a system and many tools for interrogating, retrieving and processing that data.
-
-## Development Commands
-
-### Building and Packaging
-```bash
-# Configure and build from source (requires autotools)
-./configure --prefix=/usr --libexecdir=/usr/lib --sysconfdir=/etc --localstatedir=/var
-make
-
-# Build packages for the current platform
-./Makepkgs --verbose
-
-# Cross-compile for Windows (requires MinGW)
-./Makepkgs --verbose --target mingw64
-
-# Install manually after building
-sudo make install
-```
-
-### Quality Assurance Testing
-```bash
-# Run QA setup validation
-qa/admin/check-vm
-
-# Install dependencies for your platform
-qa/admin/list-packages -m
-
-# Run all QA tests
-cd qa && ./check
-
-# Run specific tests
-cd qa && ./check 000 # Run test 000
-cd qa && ./check 100-200 # Run tests 100-200
-cd qa && ./check -g pmcd # Run pmcd group tests
-
-# Create new test
-cd qa && ./new
-
-# Remake expected output for a test
-cd qa && ./remake 123
-```
-
-### PMCD Service Management
-```bash
-# Start the PCP daemon
-sudo systemctl start pmcd
-# or
-sudo service pmcd start
-
-# Check PCP metrics
-pminfo -dfmt
-pmprobe -v
-```
-
-## High-Level Architecture
-
-### Core Components
-
-- **libpcp**: Main PCP library providing core functionality
-- **pmcd**: Performance Metrics Collection Daemon - central coordinator
-- **pmlogger**: Performance data logging daemon
-- **pmie**: Performance Metrics Inference Engine - rule-based monitoring
-- **pmproxy**: Web API proxy and time series interface
-
-### Tool Categories
-
-1. **Data Collection Tools**: pmcd, pmlogger, various pmdas
-2. **Data Export Tools**: pcp2arrow, pcp2elasticsearch, pcp2json, etc.
-3. **Analysis Tools**: pminfo, pmval, pmstat, pmchart, pmrep and pcp subtools
-4. **Archive Tools**: pmlogdump, pmlogextract, pmlogrewrite, pmlogsummary
-5. **Administrative Tools**: pmconfig, pmlc, pmafm, pmcheck
-
-### PMDAs (Performance Metrics Domain Agents)
-
-PMDAs collect metrics from specific subsystems. Key directories in `src/pmdas/`:
-
-- **Platform PMDAs**: linux, darwin, aix, windows - core system metrics
-- **Application PMDAs**: apache, mysql, postgres, mongodb, elasticsearch
-- **System PMDAs**: bpf, bpftrace, nvidia, amdgpu
-- **Network PMDAs**: cisco, bind2, apache, nginx
-- **Storage PMDAs**: dm, nfsclient, gluster, xfs
-- **Development PMDAs**: sample, simple, trivial - for testing and examples
-
-### Library Structure
-
-- **libpcp**: Core library with platform abstractions
-- **libpcp_pmda**: PMDA development framework
-- **libpcp_pmcd**: PMCD-specific functionality
-- **libpcp_gui**: GUI toolkit integration
-- **libpcp_web**: Web API and time series support
-- **libpcp_trace**: Event trace instrumentation
-- **libpcp_import**: Data import for PCP archives
-
-## Available Agents
-
-- `pcp-code-reviewer` - Reviews code against PCP project standards (whitespace, naming, structure, PCP patterns)
-
-## Development Guidelines
-
-### QA Testing Philosophy
-- All changes should include appropriate QA tests
-- Tests should be deterministic and portable across platforms
-- Use existing archives and filtering functions where possible
-- Tests run as non-root user with sudo for privileged operations
-
-### PMDA Development
-- Use `src/pmdas/simple` or `src/pmdas/sample` as starting templates
-- Follow the Install/Remove script patterns in existing PMDAs
-- PMDAs can be written in C, Python, or Perl
-
-### Code Conventions
-- Follow existing code style in surrounding files
-- Add permanent diagnostics using pmDebugOptions framework
-- Use GPL-compatible licensing for all contributions
-- Never introduce code that logs or exposes secrets
-
-## Testing Requirements
-
-### Prerequisites
-- PCP must be installed (not run from source tree)
-- User "pcp" must exist for services
-- User "pcpqa" used for testing via pcp-testsuite package
-- Sudo access required for privileged operations
-
-### Essential QA Commands
-```bash
-# First-time setup validation
-cd qa && ./check 000
-
-# Check specific functionality
-cd qa && ./check -g pmcd # PMCD tests
-cd qa && ./check -g pmda # PMDA tests
-cd qa && ./check -g archive # Archive tests
-```
-
-### Platform Support
-PCP supports Linux, macOS, Windows (MinGW), AIX, and Solaris. Tests should be written to be portable or use `_notrun()` for platform-specific limitations.
-
-## macOS Development (Darwin Platform Only)
-
-When developing on macOS (`Platform: darwin` in environment):
-
-### Critical Constraints
-
-1. **Stage changes before VM tests**
- - The Tart VM accesses the filesystem directly — `git add` is the minimum required
- - Unstaged changes in `src/pmdas/darwin*` AND `build/mac/` are INVISIBLE to the VM
- - A full commit also works; either way, run `/macos-qa-test` after staging
-
-2. **Test environments**
- - Unit tests: Run locally (no PCP needed)
- - Integration tests: Tart VM only (`/macos-qa-test`)
-
-### macOS-Specific Agent
-
-- `macos-darwin-pmda-qa` - Runs integration tests in isolated Tart VM
-
-### Quick Start
-```bash
-./Makepkgs --verbose # One-time: full build (5-30 min)
-cd build/mac/test && ./run-all-tests.sh # Daily: build + test (20-30s)
-```
-
-### Key Directories
-
-| Directory | Purpose |
-|-----------|---------|
-| `build/mac/` | Test orchestration, PKG packaging, Tart VMs |
-| `dev/darwin/` | Quick-compile tools (~10s vs 30min) |
-| `src/pmdas/darwin/` | Darwin PMDA source code |
-| `src/pmdas/darwin_proc/` | Darwin process PMDA source |
-
-### Documentation
-
-- `build/mac/CLAUDE.md` - Development workflow, test commands
-- `build/mac/MACOS_DEVELOPMENT.md` - Tart VM clean-room builds
-
-## Nix Development
-
-Nix packaging is provided via `flake.nix` and the `build/nix/` directory.
-See `docs/HowTos/nix/index.rst` for full documentation.
-
-```bash
-nix build # Build PCP package
-nix develop # Development shell
-nix flake show # List all packages and apps
-```
+@AGENTS.md
diff --git a/README.md b/README.md
index 571fe6b39c..6a237178b6 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,25 @@ supporting both live and retrospective analysis. The distributed PCP
architecture makes it especially useful for those seeking centralized
monitoring of distributed processing.
+## Installation
+
+For common Linux distributions with prebuilt Performance Co-Pilot packages
+you can follow the [Quick install instructions]
+[https://pcp.readthedocs.io/en/latest/HowTos/installation/index.html].
See the [INSTALL](INSTALL.md) file for build, installation and configuration steps.
+
+## Usage
+
+The [Performance Co-Pilot Quick Guides]
+[https://pcp.readthedocs.io/en/latest/QG/QuickGuides.html]
+provide information on how to perform basic tasks with
+Performance Co-Pilot. Check the [Performance Co-Pilot
+documentation][https://pcp.io/documentation.html] for addition
+information about
+[man pages][https://man7.org/linux/man-pages/dir_by_project.html#PCP]
+and [guides][https://pcp.readthedocs.io/en/latest/].
+
+## Development
+
For more information and details on how to contribute to the PCP project
-visit [pcp.io](https://pcp.io/community.html)
+visit [pcp.io](https://pcp.io/community.html).
diff --git a/build/mac/AGENTS.md b/build/mac/AGENTS.md
new file mode 100644
index 0000000000..ea91a88574
--- /dev/null
+++ b/build/mac/AGENTS.md
@@ -0,0 +1,114 @@
+# Darwin PMDA Development & Testing
+
+Fast iteration tools for Darwin PMDA development on macOS.
+
+## ⚠️ macOS Development Constraints
+
+1. **PCP is NOT installed locally** - Don't run `pminfo`/`pmval`/`pmprobe`. Read `src/pmdas/darwin/pmns` instead.
+2. **Commit before VM tests** - Tart VM only sees committed git changes.
+3. **Unit tests = local, Integration tests = VM only**
+
+### Git Commit Requirement
+
+**ALL changes MUST be committed to git BEFORE running Tart VM tests.**
+
+This includes:
+- Source code changes (`src/pmdas/darwin*`)
+- Build/test scripts in THIS directory (`build/mac/`)
+- Installation scripts, test fixtures, etc.
+
+The Tart VM clones the git repository - uncommitted local changes are invisible to it.
+
+---
+
+## Prerequisites (One-Time Setup)
+
+PCP must be fully built before using quick builds:
+
+```bash
+cd
+./Makepkgs --verbose
+```
+
+This takes 5-30 minutes and only needs to be done once. It generates headers, builds libraries, and installs PCP.
+
+### Python Build Environment
+
+PCP's Python PMDAs (openmetrics, opentelemetry) require Python packages that aren't available system-wide on modern macOS. Install them using `uv` (which bypasses Homebrew's `externally-managed-environment` restriction):
+
+```bash
+brew install uv # One-time: install uv package manager
+./build/mac/setup-python-env.sh # Installs Python deps to system python
+```
+
+Run this before `./Makepkgs` or `./configure` so that `import requests` succeeds during configure checks.
+
+**Verify setup:**
+```bash
+cd dev/darwin
+make check-deps
+```
+
+## Quick Development Workflow
+
+### Build + Test (Recommended)
+```bash
+cd build/mac/test
+./run-all-tests.sh
+```
+
+Builds PMDA (~5-10s) and runs unit tests (~10-20s). Runs integration tests if pmcd is available.
+
+### Build Only
+```bash
+cd dev/darwin
+make clean && make
+```
+
+### Test Only
+
+**Unit tests** (no installation needed):
+```bash
+# Darwin PMDA
+cd src/pmdas/darwin/test
+./run-unit-tests.sh
+
+# Darwin_proc PMDA
+cd src/pmdas/darwin_proc/test
+./run-unit-tests.sh
+
+# Both PMDAs
+cd build/mac/test
+./run-unit-tests.sh
+```
+
+**Integration tests** (Tart VM only - do NOT run locally):
+
+Integration tests require PCP installed and pmcd running. The Tart VM provides this environment.
+
+**Before running:**
+1. Commit all changes to git (source code AND build/mac scripts)
+2. Use `/macos-qa-test` skill or `macos-darwin-pmda-qa` agent
+
+The VM clones the git repo, so uncommitted changes are invisible
+
+### Centralized Test Orchestration
+Quick test runners available in `build/mac/test/`:
+- `./run-all-tests.sh` - Build + all unit tests + integration tests (20-30 seconds)
+- `./run-unit-tests.sh` - Unit tests only for both PMDAs (no build)
+- `./run-integration-tests.sh` - Integration tests only (no build)
+
+## Adding New Metrics
+
+1. Edit source: `src/pmdas/darwin/pmda.c`
+2. Update PMNS: `src/pmdas/darwin/pmns`
+3. Quick build: `cd dev/darwin && make`
+4. Add test: `src/pmdas/darwin/test/test-.txt`
+5. Run tests: `cd build/mac/test && ./run-all-tests.sh`
+
+## Detailed Documentation
+
+For in-depth procedures and troubleshooting:
+- `MACOS_DEVELOPMENT.md` - Tart VM setup for clean-room builds
+- `qa/TESTING.md` - pmcd launchctl test plan
+
diff --git a/build/mac/CLAUDE.md b/build/mac/CLAUDE.md
index ea91a88574..43c994c2d3 100644
--- a/build/mac/CLAUDE.md
+++ b/build/mac/CLAUDE.md
@@ -1,114 +1 @@
-# Darwin PMDA Development & Testing
-
-Fast iteration tools for Darwin PMDA development on macOS.
-
-## ⚠️ macOS Development Constraints
-
-1. **PCP is NOT installed locally** - Don't run `pminfo`/`pmval`/`pmprobe`. Read `src/pmdas/darwin/pmns` instead.
-2. **Commit before VM tests** - Tart VM only sees committed git changes.
-3. **Unit tests = local, Integration tests = VM only**
-
-### Git Commit Requirement
-
-**ALL changes MUST be committed to git BEFORE running Tart VM tests.**
-
-This includes:
-- Source code changes (`src/pmdas/darwin*`)
-- Build/test scripts in THIS directory (`build/mac/`)
-- Installation scripts, test fixtures, etc.
-
-The Tart VM clones the git repository - uncommitted local changes are invisible to it.
-
----
-
-## Prerequisites (One-Time Setup)
-
-PCP must be fully built before using quick builds:
-
-```bash
-cd
-./Makepkgs --verbose
-```
-
-This takes 5-30 minutes and only needs to be done once. It generates headers, builds libraries, and installs PCP.
-
-### Python Build Environment
-
-PCP's Python PMDAs (openmetrics, opentelemetry) require Python packages that aren't available system-wide on modern macOS. Install them using `uv` (which bypasses Homebrew's `externally-managed-environment` restriction):
-
-```bash
-brew install uv # One-time: install uv package manager
-./build/mac/setup-python-env.sh # Installs Python deps to system python
-```
-
-Run this before `./Makepkgs` or `./configure` so that `import requests` succeeds during configure checks.
-
-**Verify setup:**
-```bash
-cd dev/darwin
-make check-deps
-```
-
-## Quick Development Workflow
-
-### Build + Test (Recommended)
-```bash
-cd build/mac/test
-./run-all-tests.sh
-```
-
-Builds PMDA (~5-10s) and runs unit tests (~10-20s). Runs integration tests if pmcd is available.
-
-### Build Only
-```bash
-cd dev/darwin
-make clean && make
-```
-
-### Test Only
-
-**Unit tests** (no installation needed):
-```bash
-# Darwin PMDA
-cd src/pmdas/darwin/test
-./run-unit-tests.sh
-
-# Darwin_proc PMDA
-cd src/pmdas/darwin_proc/test
-./run-unit-tests.sh
-
-# Both PMDAs
-cd build/mac/test
-./run-unit-tests.sh
-```
-
-**Integration tests** (Tart VM only - do NOT run locally):
-
-Integration tests require PCP installed and pmcd running. The Tart VM provides this environment.
-
-**Before running:**
-1. Commit all changes to git (source code AND build/mac scripts)
-2. Use `/macos-qa-test` skill or `macos-darwin-pmda-qa` agent
-
-The VM clones the git repo, so uncommitted changes are invisible
-
-### Centralized Test Orchestration
-Quick test runners available in `build/mac/test/`:
-- `./run-all-tests.sh` - Build + all unit tests + integration tests (20-30 seconds)
-- `./run-unit-tests.sh` - Unit tests only for both PMDAs (no build)
-- `./run-integration-tests.sh` - Integration tests only (no build)
-
-## Adding New Metrics
-
-1. Edit source: `src/pmdas/darwin/pmda.c`
-2. Update PMNS: `src/pmdas/darwin/pmns`
-3. Quick build: `cd dev/darwin && make`
-4. Add test: `src/pmdas/darwin/test/test-.txt`
-5. Run tests: `cd build/mac/test && ./run-all-tests.sh`
-
-## Detailed Documentation
-
-For in-depth procedures and troubleshooting:
-- `MACOS_DEVELOPMENT.md` - Tart VM setup for clean-room builds
-- `qa/TESTING.md` - pmcd launchctl test plan
-
+@AGENTS.md
diff --git a/dev/darwin/AGENTS.md b/dev/darwin/AGENTS.md
new file mode 100644
index 0000000000..fe9b281687
--- /dev/null
+++ b/dev/darwin/AGENTS.md
@@ -0,0 +1,40 @@
+# Darwin PMDA Quick Build Tools
+
+This directory provides fast iteration for Darwin PMDA development (~10 second compile vs 30 minute full build).
+
+It "cheats" by generating a minimal GNUmakefile that links against pre-built libraries from a complete Makepkgs run.
+
+## Prerequisites
+
+1. Run full build once (generates headers/libs):
+ ```bash
+ cd && ./Makepkgs --verbose
+ ```
+
+2. Initialize the quick-build environment:
+ ```bash
+ ./setup-local-pcp.sh
+ ```
+
+## Quick Commands
+
+| Command | Purpose |
+|---------|---------|
+| `make clean && make` | Compile PMDA (~5-10s) |
+| `./build-quick.sh` | Compile + smoke test |
+| `./dev-test.sh` | Compile + PMDA tests |
+
+## Recommended Workflow
+
+Use the centralized test runner instead of these individual scripts:
+```bash
+cd /build/mac/test && ./run-all-tests.sh
+```
+
+## Source Location
+
+**Edit source in** `src/pmdas/darwin/` - this directory only compiles it.
+
+## See Also
+
+- [macOS Build & Test Hub](../../build/mac/CLAUDE.md)
diff --git a/dev/darwin/CLAUDE.md b/dev/darwin/CLAUDE.md
index fe9b281687..43c994c2d3 100644
--- a/dev/darwin/CLAUDE.md
+++ b/dev/darwin/CLAUDE.md
@@ -1,40 +1 @@
-# Darwin PMDA Quick Build Tools
-
-This directory provides fast iteration for Darwin PMDA development (~10 second compile vs 30 minute full build).
-
-It "cheats" by generating a minimal GNUmakefile that links against pre-built libraries from a complete Makepkgs run.
-
-## Prerequisites
-
-1. Run full build once (generates headers/libs):
- ```bash
- cd && ./Makepkgs --verbose
- ```
-
-2. Initialize the quick-build environment:
- ```bash
- ./setup-local-pcp.sh
- ```
-
-## Quick Commands
-
-| Command | Purpose |
-|---------|---------|
-| `make clean && make` | Compile PMDA (~5-10s) |
-| `./build-quick.sh` | Compile + smoke test |
-| `./dev-test.sh` | Compile + PMDA tests |
-
-## Recommended Workflow
-
-Use the centralized test runner instead of these individual scripts:
-```bash
-cd /build/mac/test && ./run-all-tests.sh
-```
-
-## Source Location
-
-**Edit source in** `src/pmdas/darwin/` - this directory only compiles it.
-
-## See Also
-
-- [macOS Build & Test Hub](../../build/mac/CLAUDE.md)
+@AGENTS.md
diff --git a/qa/check b/qa/check
index ac49b51bfe..9ef4e466f3 100755
--- a/qa/check
+++ b/qa/check
@@ -21,6 +21,9 @@ __aborted=true
myname=`basename $0`
__scriptname=$myname # a synonym
+# Ensure LC_ALL is not set to allow locale-dependent sort order
+unset LC_ALL
+
# lock (and PID) file to prevent concurrent QA execution
#
CHECKLOCK=/tmp/PCP-QA-LOCK
diff --git a/src/pmdas/darwin/AGENTS.md b/src/pmdas/darwin/AGENTS.md
new file mode 100644
index 0000000000..c6eddafe11
--- /dev/null
+++ b/src/pmdas/darwin/AGENTS.md
@@ -0,0 +1,149 @@
+This directory contains the macOS(Darwin) PMDA source code, which provides native integration
+for the macOS operating system.
+
+## CRITICAL: macOS Development Constraints
+
+### PCP Is NOT Installed Locally
+**NEVER assume PCP tools (`pminfo`, `pmval`, `pmprobe`) are available on the development host.**
+
+To check available metrics or PMNS structure:
+- Read `src/pmdas/darwin/pmns` directly - this is the source of truth
+- Do NOT try to run PCP commands locally
+
+### Testing Environments
+
+| Test Type | Where to Run | PCP Required? |
+|-----------|--------------|---------------|
+| **Unit tests** | Local (`./run-unit-tests.sh`) | No |
+| **Integration tests** | Tart VM only (`/macos-qa-test`) | Yes (VM has it) |
+
+### Git Commit Requirement
+
+**ALL source code changes MUST be committed to git BEFORE running integration tests.**
+
+The Tart VM clones the git repository - uncommitted local changes are invisible to it.
+
+```bash
+# Correct workflow:
+git add
+git commit -m "description"
+/macos-qa-test # Now VM can see your changes
+```
+
+## Code Style
+
+* Keep method lengths short, with the "Single Responsibility principal" in mind
+* Make the method names descriptive and readable
+* Keep the code-style inline with other code in this directory
+* Code **MUST** be reviewed and approved by the `pcp-code-reviewer` sub-agent
+
+## Adding New Metrics
+
+### Pattern: Follow VFS Module Template
+When adding new metric clusters, use `vfs.h`/`vfs.c` as the reference pattern:
+- Create `.h` with typedef struct and refresh/fetch prototypes
+- Create `.c` with `refresh_()` using `sysctlbyname()` calls
+- Add `CLUSTER_` to `darwin.h` enum
+- Wire into `pmda.c`: include header, add global vars, add to `darwin_refresh()` and `darwin_fetchCallBack()`
+- Add metrics to `metrics.c`: include header, extern declaration, metric entries
+- Add to `GNUmakefile` CFILES and HFILES
+
+### CRITICAL: Instance Domain Registration
+When adding new instance domains (standard PMDA requirement):
+1. Add enum entry to `darwin.h` (e.g., `FAN_INDOM`)
+2. **MUST** add corresponding entry to `indomtab[]` array in `pmda.c`
+3. Dynamic instance domains: `{ INDOM_NAME, 0, NULL }` (populated at runtime)
+4. Missing indomtab entry causes: "Undefined instance domain serial (N)" - entire PMDA fails to load
+
+### Instance Domain Update Pattern
+Standard PMDA pattern (see `disk.c:update_disk_indom()` or Linux PMDA `proc_buddyinfo.c`):
+```c
+indom->it_set = realloc(indom->it_set, count * sizeof(pmdaInstid));
+indom->it_numinst = count;
+```
+No helper function exists - directly manipulate `it_set` and `it_numinst`.
+
+### CRITICAL: PMNS Root Namespace
+When adding new top-level metric namespaces:
+1. Define metrics in `pmns` file (e.g., `ipc { ... }`)
+2. **MUST** add namespace to `root` file's root block (e.g., add `ipc` to root list)
+3. Failure to update `root` causes "Disconnected subtree" PMNS parsing errors during build
+
+**Example:**
+```diff
+root {
+ kernel
+ ...
++ ipc
+}
+```
+
+## SMC (System Management Controller) Access
+
+The Darwin PMDA includes thermal monitoring via Apple's SMC (System Management Controller),
+which provides access to temperature sensors and fan metrics.
+
+### Important: Reverse-Engineered APIs
+
+SMC access is **community reverse-engineered** and **NOT officially supported by Apple**.
+The APIs may change between macOS versions and may require entitlements on newer systems.
+
+### Reference Documentation
+
+- **iSMC** (https://github.com/dkorunic/iSMC) - CLI tool with Apple Silicon support
+ - Reference for SMC key patterns on M1/M2/M3 Macs
+ - Demonstrates sp78 and fpe2 format conversions
+
+- **SMCKit** (https://github.com/beltex/SMCKit) - Comprehensive Swift library
+ - Extensive SMC key documentation for Intel and Apple Silicon
+ - Reference for fan control and thermal sensor keys
+
+### SMC Key Formats
+
+| Format | Type | Conversion | Usage |
+|--------|------|------------|-------|
+| sp78 | Signed fixed-point | ÷256 | Temperature (°C) |
+| fpe2 | Unsigned fixed-point | ÷4 | Fan RPM |
+| ui8 | Unsigned 8-bit | Direct | Fan count, flags |
+
+### Key Patterns by Platform
+
+**Apple Silicon (M1/M2/M3):**
+- Temperature: `Tp01` (CPU die), `Tg01` (GPU die), `TCXC` (package)
+- Fan: `FNum` (count), `F0Ac`/`F1Ac` (speed), `F0Tg`/`F1Tg` (target)
+
+**Intel Macs:**
+- Temperature: `TC0P` (CPU proximity), `TG0D` (GPU die)
+- Fan patterns same as Apple Silicon
+
+### Graceful Degradation
+
+The thermal subsystem degrades gracefully when SMC access fails:
+- Thermal pressure metrics always work (notify API, no SMC required)
+- Temperature/fan metrics return `PM_ERR_APPVERSION` if SMC unavailable
+- Fanless Macs (MacBook Air) report `hinv.nfan=0` correctly
+
+## Testing & QA
+
+### Unit Tests (Run Locally)
+Unit tests do NOT require PCP installation:
+```bash
+cd src/pmdas/darwin/test && ./run-unit-tests.sh
+```
+
+### Integration Tests (Tart VM Only)
+Integration tests MUST run in the isolated Tart VM environment. Use the `macos-darwin-pmda-qa` agent or invoke `/macos-qa-test`:
+
+**Before running:**
+1. Commit all source changes to git
+2. Then run: `/macos-qa-test`
+
+The agent handles `cirrus run --dirty` and reports results.
+
+### Code Review
+Use the `pcp-code-reviewer` agent to review changes against PCP project standards
+
+## Related code areas
+* .github/workflows/macOS.yml - macOS-specific Github action which builds, packages and runs the unit tests. ANy changes in the Darwin PMDA will impact this. Consider any impact a change might have on this workflow file.
+* .cirrus.yml - local CI runner, acts similar to the macOS Github runner mentioned previously. Also analyse any changes for impacts on this local runner too.
+
diff --git a/src/pmdas/darwin/CLAUDE.md b/src/pmdas/darwin/CLAUDE.md
index c6eddafe11..43c994c2d3 100644
--- a/src/pmdas/darwin/CLAUDE.md
+++ b/src/pmdas/darwin/CLAUDE.md
@@ -1,149 +1 @@
-This directory contains the macOS(Darwin) PMDA source code, which provides native integration
-for the macOS operating system.
-
-## CRITICAL: macOS Development Constraints
-
-### PCP Is NOT Installed Locally
-**NEVER assume PCP tools (`pminfo`, `pmval`, `pmprobe`) are available on the development host.**
-
-To check available metrics or PMNS structure:
-- Read `src/pmdas/darwin/pmns` directly - this is the source of truth
-- Do NOT try to run PCP commands locally
-
-### Testing Environments
-
-| Test Type | Where to Run | PCP Required? |
-|-----------|--------------|---------------|
-| **Unit tests** | Local (`./run-unit-tests.sh`) | No |
-| **Integration tests** | Tart VM only (`/macos-qa-test`) | Yes (VM has it) |
-
-### Git Commit Requirement
-
-**ALL source code changes MUST be committed to git BEFORE running integration tests.**
-
-The Tart VM clones the git repository - uncommitted local changes are invisible to it.
-
-```bash
-# Correct workflow:
-git add
-git commit -m "description"
-/macos-qa-test # Now VM can see your changes
-```
-
-## Code Style
-
-* Keep method lengths short, with the "Single Responsibility principal" in mind
-* Make the method names descriptive and readable
-* Keep the code-style inline with other code in this directory
-* Code **MUST** be reviewed and approved by the `pcp-code-reviewer` sub-agent
-
-## Adding New Metrics
-
-### Pattern: Follow VFS Module Template
-When adding new metric clusters, use `vfs.h`/`vfs.c` as the reference pattern:
-- Create `.h` with typedef struct and refresh/fetch prototypes
-- Create `.c` with `refresh_()` using `sysctlbyname()` calls
-- Add `CLUSTER_` to `darwin.h` enum
-- Wire into `pmda.c`: include header, add global vars, add to `darwin_refresh()` and `darwin_fetchCallBack()`
-- Add metrics to `metrics.c`: include header, extern declaration, metric entries
-- Add to `GNUmakefile` CFILES and HFILES
-
-### CRITICAL: Instance Domain Registration
-When adding new instance domains (standard PMDA requirement):
-1. Add enum entry to `darwin.h` (e.g., `FAN_INDOM`)
-2. **MUST** add corresponding entry to `indomtab[]` array in `pmda.c`
-3. Dynamic instance domains: `{ INDOM_NAME, 0, NULL }` (populated at runtime)
-4. Missing indomtab entry causes: "Undefined instance domain serial (N)" - entire PMDA fails to load
-
-### Instance Domain Update Pattern
-Standard PMDA pattern (see `disk.c:update_disk_indom()` or Linux PMDA `proc_buddyinfo.c`):
-```c
-indom->it_set = realloc(indom->it_set, count * sizeof(pmdaInstid));
-indom->it_numinst = count;
-```
-No helper function exists - directly manipulate `it_set` and `it_numinst`.
-
-### CRITICAL: PMNS Root Namespace
-When adding new top-level metric namespaces:
-1. Define metrics in `pmns` file (e.g., `ipc { ... }`)
-2. **MUST** add namespace to `root` file's root block (e.g., add `ipc` to root list)
-3. Failure to update `root` causes "Disconnected subtree" PMNS parsing errors during build
-
-**Example:**
-```diff
-root {
- kernel
- ...
-+ ipc
-}
-```
-
-## SMC (System Management Controller) Access
-
-The Darwin PMDA includes thermal monitoring via Apple's SMC (System Management Controller),
-which provides access to temperature sensors and fan metrics.
-
-### Important: Reverse-Engineered APIs
-
-SMC access is **community reverse-engineered** and **NOT officially supported by Apple**.
-The APIs may change between macOS versions and may require entitlements on newer systems.
-
-### Reference Documentation
-
-- **iSMC** (https://github.com/dkorunic/iSMC) - CLI tool with Apple Silicon support
- - Reference for SMC key patterns on M1/M2/M3 Macs
- - Demonstrates sp78 and fpe2 format conversions
-
-- **SMCKit** (https://github.com/beltex/SMCKit) - Comprehensive Swift library
- - Extensive SMC key documentation for Intel and Apple Silicon
- - Reference for fan control and thermal sensor keys
-
-### SMC Key Formats
-
-| Format | Type | Conversion | Usage |
-|--------|------|------------|-------|
-| sp78 | Signed fixed-point | ÷256 | Temperature (°C) |
-| fpe2 | Unsigned fixed-point | ÷4 | Fan RPM |
-| ui8 | Unsigned 8-bit | Direct | Fan count, flags |
-
-### Key Patterns by Platform
-
-**Apple Silicon (M1/M2/M3):**
-- Temperature: `Tp01` (CPU die), `Tg01` (GPU die), `TCXC` (package)
-- Fan: `FNum` (count), `F0Ac`/`F1Ac` (speed), `F0Tg`/`F1Tg` (target)
-
-**Intel Macs:**
-- Temperature: `TC0P` (CPU proximity), `TG0D` (GPU die)
-- Fan patterns same as Apple Silicon
-
-### Graceful Degradation
-
-The thermal subsystem degrades gracefully when SMC access fails:
-- Thermal pressure metrics always work (notify API, no SMC required)
-- Temperature/fan metrics return `PM_ERR_APPVERSION` if SMC unavailable
-- Fanless Macs (MacBook Air) report `hinv.nfan=0` correctly
-
-## Testing & QA
-
-### Unit Tests (Run Locally)
-Unit tests do NOT require PCP installation:
-```bash
-cd src/pmdas/darwin/test && ./run-unit-tests.sh
-```
-
-### Integration Tests (Tart VM Only)
-Integration tests MUST run in the isolated Tart VM environment. Use the `macos-darwin-pmda-qa` agent or invoke `/macos-qa-test`:
-
-**Before running:**
-1. Commit all source changes to git
-2. Then run: `/macos-qa-test`
-
-The agent handles `cirrus run --dirty` and reports results.
-
-### Code Review
-Use the `pcp-code-reviewer` agent to review changes against PCP project standards
-
-## Related code areas
-* .github/workflows/macOS.yml - macOS-specific Github action which builds, packages and runs the unit tests. ANy changes in the Darwin PMDA will impact this. Consider any impact a change might have on this workflow file.
-* .cirrus.yml - local CI runner, acts similar to the macOS Github runner mentioned previously. Also analyse any changes for impacts on this local runner too.
-
+@AGENTS.md
diff --git a/src/pmrep/AGENTS.md b/src/pmrep/AGENTS.md
new file mode 100644
index 0000000000..c11ef070bd
--- /dev/null
+++ b/src/pmrep/AGENTS.md
@@ -0,0 +1,166 @@
+# pmrep Configuration Development
+
+Guide for developing pmrep configuration files in `conf/`.
+
+## Critical: ConfigParser Percent Sign Escaping
+
+**pmrep config files are parsed by Python's ConfigParser, which treats `%` as a special interpolation character.**
+
+### The Rule
+
+Always escape percent signs in metric labels and values by doubling them: `%` → `%%`
+
+### Examples
+
+**Wrong (causes InterpolationSyntaxError):**
+```ini
+gpu.util = util%,,,,6
+cpu_usage.label = cpu%
+```
+
+**Correct:**
+```ini
+gpu.util = util%%,,,,6
+cpu_usage.label = cpu%%
+```
+
+### Common Error
+
+```
+configparser.InterpolationSyntaxError: '%' must be followed by '%' or '(', found: '%,,,,6'
+```
+
+**Fix:** Double all `%` characters that should appear literally in output.
+
+## Unit Specifications
+
+**PCP's unit conversion system only recognizes standard units. Custom units cause `PM_ERR_CONV` errors.**
+
+### Supported Units
+
+- **Storage**: KB, MB, GB, TB, PB
+- **Time**: s, ms, us, ns
+- **Count**: count, none (dimensionless)
+
+### Unsupported Units
+
+If the darwin PMDA defines a metric as dimensionless (`PMDA_PMUNITS(0,0,0,0,0,0)`), omit the unit specification in pmrep config:
+
+**Wrong (causes PM_ERR_CONV):**
+```ini
+power.battery.temperature = temp,,dC,,5
+power.battery.capacity.design = design,,mAh,,7
+```
+
+**Correct:**
+```ini
+power.battery.temperature = temp,,,,5 # Raw Celsius value
+power.battery.capacity.design = design,,,,7 # Raw mAh value
+```
+
+Use comments and labels to indicate units - don't try to convert them.
+
+## Configuration File Format
+
+pmrep configs use INI format with specific semantics:
+
+### Basic Metric Definition
+
+```ini
+[view-name]
+header = yes
+unitinfo = no
+globals = no
+timestamp = no
+precision = 0
+delimiter = " "
+repeat_header = auto
+
+# Direct metric mapping
+metric.name = label,,unit,,width
+```
+
+### Derived Metrics with Formulas
+
+```ini
+# Derived metric (computed from other metrics)
+derived_name = base.metric.name
+derived_name.label = label
+derived_name.formula = 100 * rate(metric.a) / hinv.ncpu
+derived_name.unit = s
+derived_name.width = 5
+```
+
+**Note:** If your formula includes division, ensure denominators can't be zero, or accept that pmrep may show "N/A" for those samples.
+
+## Testing pmrep Configurations
+
+### Syntax Validation
+
+```bash
+# Test that a view loads without errors
+pmrep -t 1 -s 1 :view-name
+
+# Test with actual metrics (requires pmcd running)
+pmrep -t 1 -s 3 :view-name
+```
+
+### Integration Testing
+
+pmrep configs are installed to `$(PCP_SYSCONF_DIR)/pmrep` during `make install`. Test changes in the installed location, not the source tree.
+
+On macOS (Darwin PMDA development):
+1. Commit changes to git (VM clones the repo)
+2. Run `/macos-qa-test` skill to test in isolated VM with pmcd running
+
+## Common Patterns
+
+### Percentage Calculations
+
+```ini
+# CPU utilization percentage
+usr = kernel.all.cpu.usrp
+usr.label = us
+usr.formula = 100 * (kernel.all.cpu.user + kernel.all.cpu.nice) / hinv.ncpu
+usr.unit = s
+usr.width = 3
+```
+
+### Aggregation Across Instances
+
+```ini
+# Sum across all network interfaces
+net_total = network.total.bytes
+net_total.label = total
+net_total.formula = sum(network.interface.in.bytes)
+net_total.unit = KB
+net_total.width = 8
+```
+
+### Rate Calculations
+
+```ini
+# IOPS from counter metrics
+iops = disk.rate
+iops.formula = rate(disk.dev.total)
+iops.width = 7
+```
+
+## File Organization
+
+- `conf/*.conf` - View configurations organized by theme
+- `conf/GNUmakefile` - Installs all `.conf` files to system location
+- Pattern: `$(shell echo *.conf)` picks up new files automatically
+
+## Platform-Specific Views
+
+Views can reference platform-specific metrics. If a metric doesn't exist on a platform, pmrep will show "N/A" for that field rather than failing the entire view.
+
+Example: `macstat.conf` uses Darwin-specific metrics like `mem.util.compressed` which don't exist on Linux.
+
+## References
+
+- pmrep(1) man page - Command-line options and behavior
+- Python ConfigParser docs - Understanding interpolation syntax
+- `conf/pmstat.conf` - Simple, well-commented example
+- `conf/collectl.conf` - Complex example with many derived metrics
diff --git a/src/pmrep/CLAUDE.md b/src/pmrep/CLAUDE.md
index c11ef070bd..43c994c2d3 100644
--- a/src/pmrep/CLAUDE.md
+++ b/src/pmrep/CLAUDE.md
@@ -1,166 +1 @@
-# pmrep Configuration Development
-
-Guide for developing pmrep configuration files in `conf/`.
-
-## Critical: ConfigParser Percent Sign Escaping
-
-**pmrep config files are parsed by Python's ConfigParser, which treats `%` as a special interpolation character.**
-
-### The Rule
-
-Always escape percent signs in metric labels and values by doubling them: `%` → `%%`
-
-### Examples
-
-**Wrong (causes InterpolationSyntaxError):**
-```ini
-gpu.util = util%,,,,6
-cpu_usage.label = cpu%
-```
-
-**Correct:**
-```ini
-gpu.util = util%%,,,,6
-cpu_usage.label = cpu%%
-```
-
-### Common Error
-
-```
-configparser.InterpolationSyntaxError: '%' must be followed by '%' or '(', found: '%,,,,6'
-```
-
-**Fix:** Double all `%` characters that should appear literally in output.
-
-## Unit Specifications
-
-**PCP's unit conversion system only recognizes standard units. Custom units cause `PM_ERR_CONV` errors.**
-
-### Supported Units
-
-- **Storage**: KB, MB, GB, TB, PB
-- **Time**: s, ms, us, ns
-- **Count**: count, none (dimensionless)
-
-### Unsupported Units
-
-If the darwin PMDA defines a metric as dimensionless (`PMDA_PMUNITS(0,0,0,0,0,0)`), omit the unit specification in pmrep config:
-
-**Wrong (causes PM_ERR_CONV):**
-```ini
-power.battery.temperature = temp,,dC,,5
-power.battery.capacity.design = design,,mAh,,7
-```
-
-**Correct:**
-```ini
-power.battery.temperature = temp,,,,5 # Raw Celsius value
-power.battery.capacity.design = design,,,,7 # Raw mAh value
-```
-
-Use comments and labels to indicate units - don't try to convert them.
-
-## Configuration File Format
-
-pmrep configs use INI format with specific semantics:
-
-### Basic Metric Definition
-
-```ini
-[view-name]
-header = yes
-unitinfo = no
-globals = no
-timestamp = no
-precision = 0
-delimiter = " "
-repeat_header = auto
-
-# Direct metric mapping
-metric.name = label,,unit,,width
-```
-
-### Derived Metrics with Formulas
-
-```ini
-# Derived metric (computed from other metrics)
-derived_name = base.metric.name
-derived_name.label = label
-derived_name.formula = 100 * rate(metric.a) / hinv.ncpu
-derived_name.unit = s
-derived_name.width = 5
-```
-
-**Note:** If your formula includes division, ensure denominators can't be zero, or accept that pmrep may show "N/A" for those samples.
-
-## Testing pmrep Configurations
-
-### Syntax Validation
-
-```bash
-# Test that a view loads without errors
-pmrep -t 1 -s 1 :view-name
-
-# Test with actual metrics (requires pmcd running)
-pmrep -t 1 -s 3 :view-name
-```
-
-### Integration Testing
-
-pmrep configs are installed to `$(PCP_SYSCONF_DIR)/pmrep` during `make install`. Test changes in the installed location, not the source tree.
-
-On macOS (Darwin PMDA development):
-1. Commit changes to git (VM clones the repo)
-2. Run `/macos-qa-test` skill to test in isolated VM with pmcd running
-
-## Common Patterns
-
-### Percentage Calculations
-
-```ini
-# CPU utilization percentage
-usr = kernel.all.cpu.usrp
-usr.label = us
-usr.formula = 100 * (kernel.all.cpu.user + kernel.all.cpu.nice) / hinv.ncpu
-usr.unit = s
-usr.width = 3
-```
-
-### Aggregation Across Instances
-
-```ini
-# Sum across all network interfaces
-net_total = network.total.bytes
-net_total.label = total
-net_total.formula = sum(network.interface.in.bytes)
-net_total.unit = KB
-net_total.width = 8
-```
-
-### Rate Calculations
-
-```ini
-# IOPS from counter metrics
-iops = disk.rate
-iops.formula = rate(disk.dev.total)
-iops.width = 7
-```
-
-## File Organization
-
-- `conf/*.conf` - View configurations organized by theme
-- `conf/GNUmakefile` - Installs all `.conf` files to system location
-- Pattern: `$(shell echo *.conf)` picks up new files automatically
-
-## Platform-Specific Views
-
-Views can reference platform-specific metrics. If a metric doesn't exist on a platform, pmrep will show "N/A" for that field rather than failing the entire view.
-
-Example: `macstat.conf` uses Darwin-specific metrics like `mem.util.compressed` which don't exist on Linux.
-
-## References
-
-- pmrep(1) man page - Command-line options and behavior
-- Python ConfigParser docs - Understanding interpolation syntax
-- `conf/pmstat.conf` - Simple, well-commented example
-- `conf/collectl.conf` - Complex example with many derived metrics
+@AGENTS.md
diff --git a/tests b/tests
new file mode 120000
index 0000000000..a483eac5ef
--- /dev/null
+++ b/tests
@@ -0,0 +1 @@
+qa
\ No newline at end of file