docs updates and formatting

Signed-off-by: Harper, Jason M <jason.m.harper@intel.com>

Author: harp-intel

.claude/CLAUDE.md

@@ -1,3 +1,3 @@
 # CLAUDE.md
 
-@../.github/copilot-instructions.md
+@../.github/copilot-instructions.md

.github/copilot-instructions.md

@@ -2,31 +2,28 @@
 
 ## Project Overview
 
-PerfSpect is a performance analysis tool for Linux systems written in Go. It provides several commands:
-- `metrics`: Collects CPU performance metrics using hardware performance counters
-- `report`: Generates system configuration and health reports from collected data
-- `benchmark`: Runs performance micro-benchmarks to evaluate system health
-- `telemetry`: Gathers system telemetry data
-- `flamegraph`: Creates CPU flamegraphs
-- `lock`: Analyzes lock contention
-- `config`: Modifies system configuration for performance tuning
+PerfSpect is a performance analysis tool for Linux systems written in Go. It provides commands for collecting CPU performance metrics, generating system configuration reports, running micro-benchmarks, gathering telemetry, creating flamegraphs, analyzing lock contention, and modifying system configuration. It can target both local and remote systems via SSH.
 
-The tool can target both local and remote systems via SSH.
+See `ARCHITECTURE.md` for detailed architecture, data flow diagrams, and concurrency model.
 
 ## Project Structure
 
 - `main.go` - Application entry point
-- `cmd/` - Command implementations (metrics, report, telemetry, flamegraph, lock, config)
-- `internal/` - Internal packages (common, cpus, progress, report, script, table, target, util)
-- `internal/common/` - Shared types, functions, and workflows for commands
-- `internal/target/` - Abstraction for local and remote target systems
-- `internal/table/` - Table definitions and helpers for reports
-- `internal/script/` - Script execution framework and script dependencies as embedded resources
-- `internal/report/` - Report generation and formatting
-- `internal/progress/` - Progress tracking utilities
-- `internal/cpus/` - CPU architecture detection and metadata
-- `internal/util/` - General utility functions
-- `tools/` - External tools and utilities, i.e., dependencies used for collecting data on target systems
+- `cmd/` - Command implementations (metrics, report, benchmark, telemetry, flamegraph, lock, config)
+  - Subcommands: `metrics trim`, `config restore`
+  - `update` and `extract` commands are defined in `cmd/root.go`
+- `internal/`
+  - `app/` - Application context and shared types
+  - `workflow/` - Shared workflow orchestration for reporting commands
+  - `extract/` - Data extraction functions from script outputs
+  - `target/` - Target abstraction (local and remote via SSH)
+  - `script/` - Script execution framework; scripts and tool dependencies are embedded via `//go:embed`
+  - `report/` - Report generation and formatting (txt, json, html, xlsx)
+  - `table/` - Table definitions and helpers for reports
+  - `cpus/` - CPU architecture detection and metadata
+  - `progress/` - Progress indicator (multi-spinner)
+  - `util/` - General utility functions
+- `tools/` - Binaries used by scripts (embedded at build time)
 - `builder/` - Docker-based build system
 - `scripts/` - Helper scripts
 
@@ -45,18 +42,11 @@ The tool can target both local and remote systems via SSH.
 
 ### Building and Testing
 
-#### Build Commands
-
 - `make` - Build the x86_64 binary
-
-#### Testing
-
+- `make perfspect-aarch64` - Build the ARM64 binary
 - `make test` - Run all unit tests
-- Follow standard Go testing practices
-
-#### Code Quality Checks
-
-Run `make check` to perform all code quality checks
+- `make check` - Run all code quality checks
+  - Individual checks: `make check_format`, `make check_vet`, `make check_static`, `make check_lint`, `make check_vuln`, `make check_sec`, `make check_semgrep`
 
 ### Logging
 
@@ -67,7 +57,6 @@ Run `make check` to perform all code quality checks
 
 - Uses `github.com/spf13/cobra` for CLI
 - Each command is in its own subdirectory under `cmd/`
-- Some commands have subcommands (e.g., `metrics trim`, `config restore`)
 - Common flags are defined in `cmd/root.go`
 
 ### Target Systems
@@ -79,8 +68,13 @@ Run `make check` to perform all code quality checks
 
 ### Documentation
 
-- Update README.md for user-facing changes
 - Use comments for complex logic
-- Document public APIs
 - Add examples for new features
-- Keep command help text up to date
+- Update cobra command help strings in source, then run `make docs` to regenerate `docs/perfspect_*.md` (requires a built binary)
+- Update README.md for user-facing changes
+- Update ARCHITECTURE.md for architectural changes
+
+## Agent Instructions
+
+- Ask clarifying questions if requirements are ambiguous
+- Unless it is a very simple task, start with an explanation and plan instead of jumping directly to coding a solution

ARCHITECTURE.md

@@ -6,7 +6,7 @@ This document describes the high-level architecture of PerfSpect to help new con
 
 PerfSpect is a performance analysis tool for Linux systems. It collects system configuration data, hardware performance metrics, and generates reports. The tool supports both local execution and remote targets via SSH.
 
-```
+```text
 ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
 │                                        CLI (cmd/root.go)                                         │
 │  report │ benchmark │ telemetry │ flamegraph │ lock │ metrics │ config │ update │ extract        │
@@ -52,7 +52,7 @@ PerfSpect is a performance analysis tool for Linux systems. It collects system c
 
 ## Directory Structure
 
-```
+```text
 perfspect/
 ├── main.go              # Entry point
 ├── cmd/                 # Command implementations
@@ -99,6 +99,7 @@ type Target interface {
 ```
 
 **Implementations:**
+
 - `LocalTarget`: Executes commands directly on the local machine
 - `RemoteTarget`: Executes commands via SSH on remote machines
 
@@ -118,6 +119,7 @@ type ReportingCommand struct {
 ```
 
 **Workflow (`ReportingCommand.Run()`):**
+
 1. Parse flags and validate inputs
 2. Initialize targets (local or from `--target`/`--targets` flags)
 3. For each target in parallel:
@@ -132,12 +134,14 @@ type ReportingCommand struct {
 Collection scripts are defined in `internal/script/scripts.go`. Script dependencies, i.e., tools used by the scripts to collect data, are in `internal/script/resources/` and embedded in the binary using `//go:embed`. The scripts are executed on targets via a controller script that manages concurrent/sequential execution and signal handling.
 
 **Key concepts:**
+
 - `ScriptDefinition`: Defines a script (template, dependencies, required privileges)
 - `ScriptOutput`: Captures stdout, stderr, and exit code
 - `controller.sh`: Generated script that orchestrates all scripts on a target
 
 **Flow:**
-```
+
+```text
 1. Scripts defined in code with templates and dependencies
 2. Controller script generated from concurrent + sequential scripts
 3. Scripts and dependencies copied to target temp directory
@@ -161,6 +165,7 @@ type TableDefinition struct {
 ```
 
 **Field value retrieval:**
+
 - `ValuesFunc`: Function that parses script output and returns field values
 - Supports regex extraction, JSON parsing, and custom logic
 
@@ -175,6 +180,7 @@ type Loader interface {
 ```
 
 **Implementations:**
+
 - `LegacyLoader`: Original format (CLX, SKX, BDX, AMD processors)
 - `PerfmonLoader`: Intel perfmon JSON format (GNR, EMR, SPR, ICX)
 - `ComponentLoader`: ARM processors (Graviton, Axion, Ampere)
@@ -183,7 +189,7 @@ The `NewLoader()` factory function returns the appropriate loader based on CPU m
 
 ## Data Flow Example: `perfspect report`
 
-```
+```text
 1. User runs: perfspect report --target 192.168.1.2 --user admin --key ~/.ssh/id_rsa
 
 2. cmd/report/report.go:
@@ -224,7 +230,8 @@ PerfSpect uses goroutines for parallel operations:
 3. **Signal handling**: A goroutine listens for SIGINT/SIGTERM and coordinates graceful shutdown across all targets
 
 **Signal handling flow:**
-```
+
+```text
 SIGINT received
     → Signal handler goroutine activated
     → For each target: send SIGINT to controller.sh PID
@@ -243,4 +250,5 @@ make check      # Run all code quality checks (format, vet, lint)
 Test files are colocated with source files (e.g., `extract_test.go` alongside `extract.go`).
 
 ## Functional Testing
-Functional tests are located in an Intel internal GitHub repository. The tests run against various Linux distributions and CPU architectures on internal servers and public cloud systems to validate end-to-end functionality.
+
+Functional tests are located in an Intel internal GitHub repository. The tests run against various Linux distributions and CPU architectures on internal servers and public cloud systems to validate end-to-end functionality.

CODE_OF_CONDUCT.md

@@ -128,4 +128,5 @@ For answers to common questions about this code of conduct, see the FAQ at
 [homepage]: https://www.contributor-covenant.org
 [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
 [Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

GEMINI.md

@@ -1,7 +1,5 @@
 # Gemini Guidelines
 
-Unless it is a very simple task, start with an explanation and plan instead of jumping directly to coding a solution.
-
 When creating or replacing files, use your native `write_file` tool instead of the `cat << EOF` heredoc pattern in the shell.
 
 Include the project-wide development guidelines from the Copilot instructions file.

SECURITY.md

@@ -1,14 +1,16 @@
 Security Policy
 ===============
 
-## Report a Vulnerability
+Report a Vulnerability
+----------------------
 
 Submit your vulnerabilities as bug reports to the GitHub issues page. Refer to GitHub's [Creating an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue) for instructions.
 
 Provide the following information:
+
 * Title
 * Location of the vulnerability
 * Steps to reproduce
 * Expected result
 * Actual result
-* Proof
+* Proof

SUPPORT.md

@@ -1,4 +1,4 @@
 Support
 =======
 
-Submit your support needs to the GitHub issues page. Refer to GitHub's [Creating an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue) for instructions.
+Submit your support needs to the GitHub issues page. Refer to GitHub's [Creating an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue) for instructions.

docs/perfspect-daemonset.md

@@ -1,8 +1,8 @@
-## Example DaemonSet for PerfSpect for GKE
+# Example DaemonSet for PerfSpect for GKE
 
 This is an example DaemonSet for exposing PerfSpect metrics as a prometheus compatible metrics endpoint. This example assumes the use of Google Kubernetes Engine (GKE) and using the `PodMonitoring` resource to collect metrics from the metrics endpoint.
 
-```
+``` yaml
 apiVersion: apps/v1
 kind: DaemonSet
 metadata:
@@ -61,4 +61,5 @@ spec:
   - port: metrics-port
     interval: 30s
 ```
- * Replace `docker.registry/user-sandbox/ar-us/perfspect` with the location of your perfspect container image.
+
+* Replace `docker.registry/user-sandbox/ar-us/perfspect` with the location of your perfspect container image.

docs/perfspect_flamegraph.md

@@ -1,6 +1,5 @@
 # perfspect flamegraph
 
-
 ```text
 Collect flamegraph data from target(s)
 
@@ -18,7 +17,7 @@ Flags:
     --frequency            number of samples taken per second (default: 11)
     --pids                 comma separated list of PIDs. If not specified, all PIDs will be collected (default: [])
     --perf-event           perf event to use for native sampling (e.g., cpu-cycles, instructions, cache-misses, branches, context-switches, mem-loads, mem-stores, etc.) (default: cycles:P)
-    --dual-native-stacks   also record DWARF unwind perf and merge with frame-pointer stacks per process (larger profiles) (default: false)
+    --dual-native-stacks   also record DWARF unwind perf and merge with frame-pointer stacks per process (larger profiles, longer post-processing time) (default: false)
     --asprof-args          arguments to pass to async-profiler, e.g., $ asprof start <these arguments> -i <interval> <pid>. (default: -t -F probesp+vtable)
     --max-depth            maximum render depth of call stack in flamegraph (0 = no limit) (default: 0)
     --format               choose output format(s) from: all, html, txt, json (default: [html])