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, H4 16px/600, body and table content 16px/400, labels 14px/600, metadata and table headers 13px, and buttons 14px/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 and other content-bearing text at no less than 16px, including finding content, report text, Grid cell content, and Raw Data.
• 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 the rounded grouped background; a tile is a rounded, individually bordered element 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 use the light neutral group surface, a fine border, --segment-radius, one uniform inset, and one uniform gap. Segments remain flat and do not receive a floating shadow.
• Tiles use the common white or theme-equivalent surface, fine gray border, --tile-radius, and the single subtle --tile-card-shadow. Hover may change border and surface but must not lift or translate the tile.
• Status color belongs only in a small accent line, marker, data visualization, or selected contour. Never fill the complete tile with a status color.
• Selected tiles use the shared selected border/outline. Action tiles and add tiles use the same geometry as content tiles.
• 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.