Assessor_2.0/AGENTS.md

ASSESSOR project guidance

Implementation plan

• Read docs/IMPLEMENTATION_PLAN.md before architecture changes, broad refactors, persistence changes, importer/profile work, or server-readiness work.
• State which plan phase the requested work belongs to and keep the change within the user's requested scope.
• Preserve the currently working local application while moving toward the documented browser/server target architecture.
• Do not mark a milestone or phase complete until its acceptance criteria have been verified.
• After a material, verified implementation step, update the plan's status, decisions, risks, and change log in the same change. Do not rewrite historical decisions silently.
• If the requested implementation conflicts with the plan, explain the conflict and update the plan only with the user's agreement or when the request explicitly supersedes it.

Architectural boundaries

• Keep format parsing, structural analysis, semantic mapping, normalization, comparison, persistence, and presentation separated.
• Preserve original source values and provenance; normalized values must not destroy source data.
• Known tool profiles must extend the generic import pipeline rather than bypass it.
• React components must not contain source-specific parsing or direct database logic.
• Treat Tauri as the current local shell and a possible optional future shell. Do not make new domain logic depend on Tauri when a platform-neutral boundary is possible.
• The target deployment is an internal browser application with a backend and PostgreSQL. The browser must not access the database directly.

UI typography

• Use the locally bundled Inter variable font as the single application typeface. Do not introduce view-specific display, condensed, serif, or monospace families; hierarchy comes from size and weight.
• Use only the visual weights Regular 400, Semibold 600, and Bold 700. Bold is reserved for branding and exceptional emphasis.
• Use the semantic typography roles: H1 56px/600, H2 32px/600, H3 18px/600, detail titles 20px/600, H4 16px/600, continuous prose 16px/400, structured table/Grid/Raw Data content 14px/400, labels and table headers 12px/600, metadata 12px, badges 11px, and buttons/controls 13px/600.
• Preserve normal title case for H1-H4, field labels, and buttons. Uppercase is limited to compact table headers, badges/categories, and the ASSESSOR wordmark.
• Render continuous prose such as finding and report text at no less than 16px. Structured data in tables, Grid, and Raw Data uses the dedicated compact 14px role.
• Compact interface text such as button captions, field labels, metadata, badges, and comparable control annotations may use a smaller type size.
• When adding or changing styles, preserve this distinction instead of reducing content text to a compact UI-label token.

UI panel spacing

• The Work panel is the binding spacing reference: content inside every rounded main panel starts 20px from each outer edge.
• Use --panel-content-inset through its compatibility alias --panel-inset; do not introduce local substitute values for existing or future main panels.
• Apply the inset exactly once on the view's root content container. Split panes and edge-to-edge structures belong inside that inset and must not add a second outer inset.
• Keep the 20px outer inset at responsive breakpoints unless the user explicitly changes this standard.

UI segments and tiles

• Treat segments and tiles as a binding two-level visual grammar independent of their content. A segment is a transparent grouped layout; a tile is a flat, square-cornered surface inside it.
• Use only the shared --segment-* and --tile-* tokens for segment surfaces, borders, radii, insets, gaps, tile surfaces, shadows, widths, hover states, and selected contours. Do not create view-local substitute geometry.
• Segments are visually transparent and have no visible border or shadow. They retain --segment-radius, one uniform inset, and one uniform gap as shared layout geometry.
• Tiles use the common white or theme-equivalent surface without a visible normal-state border, radius, or shadow. Hover changes the surface only and must not add a decorative contour, lift, or translation.
• Status color belongs only in a small accent line, marker, data visualization, or selected contour. Never fill the complete tile with a status color.
• Keyboard focus and selected tiles use the shared functional focus or selected outline. Action tiles and add tiles use the same flat geometry as content tiles.
• The persistent marking and selection color is always the shared yellow --marking-color in both themes. Purple must not be used for selected contours or markers. Blue remains reserved for keyboard focus, while green, red, orange, and severity colors remain domain status signals rather than selection colors.
• Keep unused segment space intentionally empty: lay tiles out from the start at their shared compact or content width and never stretch a partial final row merely to fill the container.
• Tile content must never cross the tile boundary or cover a neighboring tile. Nothing may be clipped, clamped, truncated, or replaced by an ellipsis. Text and actions reflow inside the tile; media scales within the available inner area. If content does not fit, enlarge or reflow the tile.
• Avoid line breaks in compact tile labels where practical. If wrapping is necessary, wrap only at word boundaries: never split ordinary words or numeric values across lines. Use a wider or responsive tile whenever a complete word or value cannot fit.

UI donut charts

• Every donut chart uses the same full 360-degree geometry: a continuous neutral-gray track and a colored clockwise value arc starting at 12 o'clock.
• Donut arcs use flat ends and the shared --donut-ring-stroke, --donut-track, value, and typography tokens. Do not introduce 270-degree gauges, open gaps, rounded arc caps, or local substitute geometry.
• Place the primary numeric value itself on the exact visual center of the ring. Append a percent sign or other short unit to its right on the same baseline in the smaller shared UI size without letting that unit shift the number away from the center. Supporting counts may remain as subdued secondary text inside the ring, but every text element must stay fully within the clear inner area and must never touch or overlap the ring at any supported value width.
• Multi-segment distributions retain their categorical segments, but use the same track, stroke proportion, start position, centered value treatment, and shared tokens as single-value donuts.

UI branding position

• Use the Data Hub header as the binding position reference for the ASSESSOR logo, wordmark, and version.
• Keep the brand container geometry identical across every application view; do not add area- or view-specific brand padding, margin, alignment, height, or transforms.
• Switching views must never move the logo, wordmark, or version.

Security and verification

• Preserve local-only behavior until a server transition is explicitly implemented and documented.
• Do not introduce external uploads, telemetry, CDN assets, network APIs, shell access, or broader Tauri capabilities without explicit user approval and a security-model update.
• Treat imported HTML, XML, Excel, JSON, and CSV files as untrusted input. Never execute active content from imported files.
• Use npm test and npm run build as the baseline verification commands for relevant changes.
• Preserve unrelated user changes and keep implementation-plan updates factual and concise.

Privacy-safe testing

• Treat all real tenant, customer, project, scan, finding, and imported-file data as sensitive.
• Never inspect, extract, log, quote, summarize, screenshot, or otherwise expose real file names, finding titles, field values, raw report content, or rendered report text during testing or debugging.
• Use synthetic fixtures for content-level, parser, importer, mapping, and UI tests.
• Against a real running application, verify functionality only through content-free technical signals such as HTTP status, health state, anonymized counts, boolean DOM state, control availability, and element existence.
• Do not read innerText, response bodies containing domain data, or screenshots of populated views merely to prove that a feature works.
• If real content inspection is genuinely unavoidable, stop and obtain the user's explicit permission for the minimum required scope before accessing it.
• Remove temporary browser profiles and test artifacts immediately after an approved real-application check.