safetynet/AGENTS.md

# SafetyNet development instructions

## Use observability throughout development

The user explicitly requires OpenTelemetry diagnostics to be used for ongoing
debugging, optimization and feature work, not merely implemented and left idle.

- Start the protected local development collector with `npm run debug:collector`.
  Check `http://127.0.0.1:4318/health` before relying on it. An existing live listener
  must be inspected rather than blindly restarted.
- The backend uses `OTEL_EXPORTER_OTLP_ENDPOINT`; browser diagnostics require the
  centrally signed `policy.diagnostics` configuration. Both remain centrally
  disableable. Never bypass mandatory publication review to enable debugging.
- Exercise the relevant feature and inspect `/api/summary` and
  `/api/trace/<traceId>`. Confirm actual exports, timings and parent/child correlation.
  Successful startup alone is not proof of observability.
- On failures or slow paths, inspect the affected trace and add missing named
  stages. Use `traceOperation` for backend code and the browser diagnostics helper
  for privileged browser code. Record the relevant proof/trace IDs in local test
  evidence without copying credentials or confidential content into ordinary logs.
- Use the durable event's `traceId` to retrieve the actual exported trace. Native
  upload failures must include a recording `browser.upload.fault` span and a fixed
  `safetynet.reason`; inherited ended spans can otherwise suppress diagnostic logs.
  Do not put arbitrary rule text, exception messages, paths or credentials in reasons.
- Check collector `storedBytes` and exporter failures before long debug sessions.
  The local protected receiver has a finite storage budget; missing exports or
  rejected writes must not be mistaken for a successful observability proof.
- Check diagnostics `lifetimeFailedExports` as well as the current generation's
  `failedExports`; disable/reconfiguration must not erase evidence of earlier
  failures within the same browser process. Pre-enrollment startup has no signed
  export authorization: use bounded local startup snapshots, and do not infer a
  timeout's cause from later successful traces.
- Do not hide failed tests, weaken enforcement, or repeat a protected operation
  because telemetry failed. Diagnostic traces are distinct from durable security
  audit and encrypted forensic evidence.
- Local collector data is under ignored `data/observability`, encrypted with an
  AES key protected by Windows DPAPI. This developer receiver is not a production
  SIEM, durable forensic archive or remote authenticated collector.
- The collector pins its first previous encrypted archive and rotates later
  generated segments. `/api/trace` indexes this process's recent spans only.
  Older proof readers must inspect the guarded encrypted legacy/rolling segments
  with the existing DPAPI key; never dump decrypted batches or key material.

## Repository and infrastructure

- Do not add CI/CD workflows, GitHub/Gitea Actions or forge configuration; the user
  explicitly requested ordinary commits/pushes only.
- Keep credentials, `.env`, local databases, models, runtimes, builds and test
  artifacts out of Git. Selected synthetic screenshots belong in `docs/media`.
- Infrastructure credentials are authoritative in Infisical. Read
  `C:/Users/karl/Workspaces/InfrastructureOps/AGENTS.md` and `START-HERE.md` and use
  protected selected-secret helpers; never print values or use legacy `local.env`.
- Windows file links use the actual absolute `C:/...` path, never `/C:/...`.