AGENTS.md · diff
git:20260724.2c13572 to git:20260725.2a588be
9 added, 9 removed. Audit A to A.
- # WebTrace — AI Agent Instructions
+ # PerfGraph — AI Agent Instructions
- This file tells AI coding agents (Claude, ChatGPT, Copilot, etc.) how to work with WebTrace.
+ This file tells AI coding agents (Claude, ChatGPT, Copilot, etc.) how to work with PerfGraph.
- ## What WebTrace is
+ ## What PerfGraph is
A CLI tool that collects real browser performance data via CDP, runs it through a 5-stage pipeline, and produces a structured JSON report with causal chains and prioritized fixes. Designed to be consumed by AI agents.
```
collect → normalize → extract → analyze → report
```
- ## How AI agents should use WebTrace
+ ## How AI agents should use PerfGraph
### Quick entry point
```bash
- npx @gmod.one/webtrace run --url https://example.com --pretty
+ npx perfgraph run --url https://example.com --pretty
```
This runs the full pipeline. The output is a `report.json` with:
- `summary.score` — `good` / `moderate` / `poor`
- `issues[]` — each with severity, confidence, metric value, threshold, remediation
- `chains[]` — causal degradation paths from root cause to user-facing impact
- `recommendations[]` — prioritized, with evidence and expected impact
### MCP mode (for AI agents with MCP support)
```bash
- webtrace mcp
+ perfgraph mcp
```
- Starts an MCP stdio server. Agents can call `webtrace_analyze` with a URL and get structured results back. The response includes paths to:
+ Starts an MCP stdio server. Agents can call `perfgraph_analyze` with a URL and get structured results back. The response includes paths to:
| File | When to read |
|------|-------------|
| `insights.json` | **Read first.** Agent-optimized ~5-15 KB summary: Lighthouse scores, LCP element selector, render-blocking URLs, critical path depth |
| `report.json` | Read for causal chains and prioritized recommendations |
| `manifest.json` | File index with descriptions. Only needed if you want raw data |
| `lighthouse.json` / `trace.json` | Deep dives only — these are large |
### Workflow for agents
- 1. Call `webtrace_analyze` or run `webtrace run --url ... --pretty`
+ 1. Call `perfgraph_analyze` or run `perfgraph run --url ... --pretty`
2. Read `insights.json` for the quick picture
3. Read `report.json` for causal analysis and prioritized fixes
4. Only open raw files (`lighthouse.json`, `trace.json`, `network.json`) when you need specifics not covered by insights
## Diagnostics categories
| Category | What it detects |
|----------|----------------|
| LCP | Large Contentful Paint, TTFB, render-blocking resources |
| JavaScript | Long tasks, Total Blocking Time, heavy execution, unused code |
| Network | Request chains, bandwidth bottlenecks, waterfall depth |
| Layout | Layout shifts (CLS), DOM size, forced reflows |
| Third-party | Overhead from embedded scripts, tracking pixels, widgets |
## Development commands
```bash
npm install # install deps
npm run build # compile TypeScript
npm run typecheck # type-check only
npm test # run tests
npm run dev # tsx watch mode
```
## Type system
- Strict TypeScript with `noUncheckedIndexedAccess`
- Zod schemas at every data boundary: `src/*/types.ts`
- CDP data, Lighthouse audits, file I/O — all validated on ingress
- Internal code works with typed interfaces, not raw JSON
## Project conventions
- **kebab-case** for files (`lcp-breakdown.ts`, not `lcpBreakdown.ts`)
- **camelCase** for variables and functions
- **PascalCase** for types, interfaces, and classes
- Early returns. Keep nesting ≤ 3.
- No `@ts-ignore`, `@ts-expect-error`, or `as any` — ever.
## Causal rules
Rules live in `src/causal/rules/`. Each rule file exports an array of `CausalRule` objects. A rule:
- Has a unique `id`, `label`, `category`
- Has a `build()` function that takes `FeatureSet` and returns an array of `CausalNode` + `CausalEdge`
- Can attach `evidence` (URLs, selectors, metric values) to nodes
Adding a new rule: create a file in `src/causal/rules/`, register it in `src/causal/builder.ts`, write a test in `test/causal/`.
## Reporting issues
- If WebTrace gives wrong results, file an issue with:
+ If PerfGraph gives wrong results, file an issue with:
- The URL tested
- The command run
- The `report.json` (or at least the summary section)