kingfisher/docs/viewer/AGENTS.md

AGENTS.md

Guidance for editing the local report viewer under docs/viewer/.

Scope

• Applies to docs/viewer/ and all files under it.
• This file overrides broader documentation guidance for this subtree.

Current Architecture

• The shipped viewer is the single-file app in index.html.
• Treat index.html as the authoritative implementation for the UI, parsing, and rendering logic.
• sample-report.json is the canonical example payload for native Kingfisher viewer data.
• app.js, viewer.js, and viewer.css may exist as older or non-authoritative assets. Do not assume changes there affect the shipped viewer unless you also update how the app is loaded.

Editing Expectations

• Prefer targeted edits over broad refactors. This file is large, so keep changes localized and easy to review.
• Keep new parsing or normalization logic grouped into small helper functions instead of scattering format-specific conditionals throughout the file.
• Preserve the distinction between native Kingfisher reports and imported third-party reports in both data handling and UI messaging.
• Do not imply feature parity for imported reports when native-only features such as access_map, validate commands, revoke commands, or blast-radius linking are unavailable.
• Prefer ASCII when editing text unless the file already relies on another character.

Data Model Guidance

• Native viewer inputs should continue to normalize around the Kingfisher envelope shape: findings, optional access_map, and optional metadata.
• When supporting imported formats, map them into the viewer envelope instead of building parallel rendering paths.
• Keep fingerprint behavior stable and explicit. If imported reports need synthetic fingerprints, use a deterministic approach and document the fidelity limits in the UI or docs.
• Preserve graceful handling of both JSON and JSONL inputs.

UI Guidance

• Keep imported-report limitations visible in the viewer when access-map data or command workflows are unavailable.
• Prefer small explanatory notices and empty states over hiding entire sections without explanation.
• Maintain client-side-only behavior. Do not add network calls from the viewer except for the existing local GET /report loading path used by kingfisher view.

Validation

• After substantive edits to index.html, run a syntax check on the embedded JavaScript by extracting the <script> block and using node --check.
• For doc or sample changes, make sure examples still match the current viewer behavior and accepted report formats.