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.
• 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:/....