Source: site/PRESENTATION-NOTES.md
# Database presentation PoC — operator comparison Start at /explore/. Every law offers A (outline) and B (element × variant matrix) from the same read-only SQLite snapshot. Compare these first: - /explore/law/42usc1983/ and /explore/law/42usc1983/matrix/ - /explore/law/18usc1962/ and /explore/law/18usc1962/matrix/ ## A — outline/tree Best for reading the recorded AND/OR/exception/defense hierarchy, claim expressions, constraints, and each element's variant descriptions and example cases. Parent-child indentation is explicit; a link leads to the element's complete evidence view. Weaknesses: a large law is long, counts are scattered, and hierarchy does not by itself explain every sequential burden, relational condition or alternative theory. The displayed expressions are the database's descriptive model, not an executable legal decision or a statement that every element has been proved. ## B — element × variant matrix Best for comparing where this annotation sample has support. Cells show merits instance blocks and distinct cases; zero means a declared variant has no counted instance, while a dash means the variant is not declared for that element. Shading repeats the counts and is not confidence, quality, frequency in all litigation, or probability of legal applicability. Weaknesses: many variant labels are specific to one element/case, so the matrix is sparse and wide. Horizontal scrolling preserves all columns on small screens. A case appearing in multiple cells is not a new independent case in each cell. The matrix is a coverage overview, not a replacement for reading the evidence. ## Element and case views Element pages show all declared variants, including zero-count entries, source anchors, and a 'How courts decided this element' table. Case pages show every annotation block and its element, holding, basis, role/scope, variant, qualifiers and evidence. Procedural/comparator/not-reached material remains visible but is explicitly excluded from merits counts. Fact polarity, absence and quoted-rule flags remain visible; counterevidence is not presented as affirmative support. Quotes are read from their corpus source pointer and Unicode offsets, checked against the stored full-source SHA256 and quote, and HTML-escaped without text normalization. A missing/mismatched source or schema stops the build before it replaces the prior presentation. Statutory and interpretation quotations are checked too. The corpus and database are not edited by this renderer. ## Coverage, quality and limits Every page identifies its annotation coverage and logical SQLite-dump snapshot SHA256. This digest identifies the consistent in-memory database snapshot; it is not the raw SQLite file hash. Counts use the database's is_instance policy; the legacy fallback requires explicit applied/merits/reached metadata. Legal review status is unavailable to this view until an explicit per-page review mapping is supplied by the evolving DB schema. Exact quote verification is not legal review. The PoC does not infer approval from global QA documents. Cases used only as interpretation sources are marked as such, without invented CASE contexts or factual instances. Case identifiers are used where the DB has no caption. The current prototype has no JavaScript dependency. Source links to the production site are plain external case-page links only. neochart.com is otherwise untouched. Only /explore/ is replaced by the presentation builder; general site publication remains additive and generates the combined sitemap and allow-all robots file. Removed DB records can therefore leave older remote URLs until a separate cleanup; they are omitted from the current navigation, and their snapshot digest distinguishes them from current pages. No remote deletion was introduced. ## Build and review Build the local canonical database with tools/load.py (or tools/build_db.sh when available), then run tools/publish_v2.sh. NEOV2_CORPUS chooses the read-only corpus; NEOV2_PRESENTATION_DB may select a specific DB snapshot. Publication requires a DB and fails closed if it is missing or fails source validation. The standalone entry is tools/build_presentation.py --db ... --corpus ... --site-dir ... . Lead: please dispatch independent QA to compare both presentations, verify counts against the DB, inspect exact quotations and non-merits exclusions, and check mobile navigation/readability. This document is author handoff, not QA sign-off. From the repository root, with the current loader: ```bash export NEOV2_CORPUS=/home/mma/repos/neochart/neochartdocroot python3 neov2/tools/load.py --corpus "$NEOV2_CORPUS" AWS_PROFILE=admin bash neov2/tools/publish_v2.sh ``` The renderer needs the canonical model tables (including evidence joins, claims, constraints and source anchors). Additive schema columns/tables do not require inventing new review semantics; incompatible schemas fail rather than silently omit model content. An evolving review schema needs an explicit per-page mapping. ## Independent review received during this task Fable's independent review (qa/presentation-review-Fable.md, published as its HTML source page) checked 1,819 quotations and 433 counts on three laws with zero mismatches. It finds A useful but B too sparse: the raw-label matrix is about 93% empty in that reviewed sample. It recommends curated routes, a case×element grid, case captions and revision-bound review provenance as the next design direction. Those are operator decisions; this PoC retains the requested A/B comparison. The review also exposed a transparency gap. Banners now explicitly distinguish the frozen DB's 165 case–law contexts from the current source-tree CASE-file count. The DB is deliberately kept fixed for the reviewed comparison; newly authored factory cases are not silently treated as reviewed or imported into it. Both variant tables and matrix cells now split satisfied/not-satisfied counts and show excluded-context uses. Zero-count variants with non-merits uses link those examples separately, rather than saying only that no counted example exists. Case links include available DB court/year metadata and will use a DB caption when supplied. The current snapshot has no captions or per-case legal-review provenance, so those limitations remain explicit. Raw label rows must not be mistaken for the newer curated route taxonomy. Counts and labels are annotation observations, not an exhaustive catalogue of legally successful fact patterns.