graphcheck 0.2.0__tar.gz → 0.4.0__tar.gz

{graphcheck-0.2.0 → graphcheck-0.4.0}/.gitignore

@@ -97,6 +97,7 @@ ipython_config.py
 # Pipfile.lock
 
 # UV
+.uv-cache*/
 #   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
 #   This is especially recommended for binary packages to ensure reproducibility, and is more
 #   commonly ignored for libraries.
@@ -222,8 +223,8 @@ __marimo__/
 # GraphCheck
 /checks/
 profiles.yml
-!/profiles.yml
 .graphcheck/
+.hostile-artifacts/
 .superpowers/
 
 

{graphcheck-0.2.0 → graphcheck-0.4.0}/CHANGELOG.md

@@ -2,7 +2,221 @@
 
 All notable changes to this project are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.4.0] - 2026-09-18
+
+### Added
+
+- The agent guide and schema descriptions now explain regression value shapes, evidence identities,
+  and count scope, with a complete aggregate-witness example in the guide. Missing-evidence
+  diagnostics identify accepted element aliases and retain the failed assertion.
+
+- Published a 10-million-node audit ceiling and sampling thresholds.
+  Larger graphs fail before check dispatch with `engine.graph_size_exceeded` and a
+  `Fix:` diagnostic; the reference 2 GiB transaction-memory limit cannot complete PII at 10M.
+
+- Published the [artifact compatibility policy](docs/reference/artifact-compatibility.md), with
+  committed results fixtures for schemas 1.0, 1.1, 1.2, and 2.0 and archived 1.x JSON Schemas.
+  The policy includes a tested transformer that writes a validated 2.0 copy. Migration of 1.0/1.1
+  requires trusted historical inventory because those schemas did not record it.
+- GraphRAG `chunk_coverage` reports the share of Chunks linked to at least one Entity against
+  a configurable threshold (default 0.95), naming entity-less Chunks in evidence.
+  `label_explosion` flags labels and relationship types across the whole schema at or below
+  a configurable threshold (default 1), reporting findings and node evidence; graphs under a
+  configurable minimum node count (default 50) are not evaluated rather than flagged, since a
+  small graph makes almost every label look like a singleton.
+- After a comparable previous run, `summary.json` includes a compact `changes` block with new
+  failures, fixed checks, and node/relationship count deltas from the runs. Check lists retain
+  at most 20 entries each and report omitted counts; first runs and unavailable comparisons
+  omit the block. Artifact retries preserve the original block after history is pruned.
+- Runs now include `previous_run_id`, `baseline_ref`, and `config_hash` in results schema 2.0,
+  with compatibility for older artifacts and a new lineage fixture. Profile references identify
+  the latest existing timestamped snapshot; running checks does not trigger profiling. History
+  summaries and `graphcheck report --history` show the previous-run links, assigned under the
+  publication lock for concurrent CLI and MCP runs. Redacted exports clear lineage metadata.
+- Added `graphcheck changes [--since <run-id|previous>] [--json]` to combine check outcome,
+  coverage, suite-score, and profile deltas through the existing report comparison and profile
+  diff implementations. JSON is deterministic; exit codes distinguish no regressions (`0`),
+  regressions or new failures (`1`), and invalid or unavailable comparison inputs (`2`).
+- Changes output includes appeared and disappeared evidence element IDs per check, sharing the
+  smaller input evidence cap across both directions, counting dropped deltas, and identifying
+  truncated input evidence. Added fraud-ring and public-scale hostile acceptance coverage.
+- GraphRAG `embedding_consistency` checks every chunk for missing, invalid, empty, zero,
+  NaN-containing, and inconsistent-dimension embeddings. It uses the most frequent valid
+  dimension (smallest on ties) and returns exact counts plus capped element-ID, dimension,
+  and defect evidence without transferring vectors to Python.
+- Hostile GraphRAG planted/clean cases with expected CLI exit codes, assertions identifying every
+  planted defect, and a copyable suite under `examples/graphrag/`. Singleton labels and uncovered
+  chunks remain fixture-only assertions. The public-scale hostile lane exercises all five checks
+  with a 60-second pack-run budget and verifies planted embedding defects over 265,214 nodes.
+- Drift metrics `degree_distribution` (degree quantiles `p50`/`p95`/`max` per label, relationship
+  type, and direction, using `percentileDisc` and `COUNT { }` for Cypher 5/25 compatibility) and
+  `schema_inventory` (labels, relationship types, and label-scoped property names added or
+  removed since baseline, evaluated as the count of differences rather than net inventory size
+  so a simultaneous addition and removal cannot cancel out to zero). See
+  [SPEC-04](docs/specifications/spec-04-engine.md) and
+  [SPEC-05](docs/specifications/spec-05-profiler-baseline.md) for details.
+- Optional GraphRAG pack enabled by `graphcheck init --pack graphrag`, with configurable
+  Document, Chunk, and Entity labels, relationship types/directions, extraction relationship
+  selection, and name/embedding properties in `graphcheck.yml`.
+- GraphRAG provenance checks `orphan_chunks`, `entity_without_provenance`, and
+  `dangling_extraction_relationships`, with exhaustive counts, capped element-ID evidence,
+  and missing configured paths. Chunks may have multiple documents; entity provenance requires
+  a direct chunk link, and extraction relationships are flagged when either endpoint lacks one.
+- Seeded `near_duplicate_entities` sampling with normalized-name equality or character-bigram
+  Dice similarity strictly above a configurable threshold (default 0.9). Connected duplicate
+  groups include normalized keys and element IDs. Samples default to 1,000 names, allow up to
+  2,000 subject to engine limits, and exclude non-string names and names over 256 characters.
+  Sampled results state sample size/population without inferring a population confidence interval.
+- GraphRAG metadata/schema validation, planted and clean builder fixtures, and opt-in fraud-ring
+  and public-scale acceptance coverage. [GraphRAG documentation](docs/graphrag.md) details the new
+  check semantics requiring separate approval.
+- Added `engine.result_row_limit` project configuration, shared by CLI and MCP, with a default
+  ceiling of 100,000 competency rows and strict positive-integer validation.
+- Baseline schema 1.1 preserves declared RANGE index property order while reading legacy 1.0
+  profiles with unknown order. Diff format 1.1 explains property inventory/type changes and
+  distinguishes newly available index-order metadata from known definition changes.
+
+### Changed
+
+- Source distributions now contain only application sources, runtime compatibility schemas, and
+  release metadata/documentation. Repository tooling, tests, examples, and local caches are excluded.
+- Schema file generation moves to `tools/generate_schemas.py`; runtime schema generation and
+  validation remain available. Removed unused Python helpers `default_profiles`, `print_profile`,
+  and `count_band`, plus the repository-only `SCHEMAS_DIR` constant and `write_*schema*` helpers
+  from `graphcheck.contracts.schemas`.
+
+- Reading pre-2.0 results emits one `results.schema_deprecated` warning on stderr per artifact
+  read. Removal is planned for CLI 0.5.0, postponed while the current/previous-schema guarantee
+  requires support. The warning must ship at least one release before removal. Migrate saved
+  artifacts with the transformer above; current 2.0 reads and model revalidation stay quiet.
+- GraphRAG checks report `skipped:model_absent` with an explicit reason when the model is
+  unconfigured or any configured role label has no nodes. Completed runs containing only these
+  skips exit 0 with a null score and incomplete report coverage. Missing relationship types remain
+  defects when role populations exist; actual execution errors remain errors. This new skip/exit
+  policy requires separate approval.
+- `no_orphans` accepts optional `to_label` filtering for the opposite endpoint; omitting it
+  preserves existing behavior. This additional check semantic requires separate approval.
+- Runs prepare suites once, prefer the C-backed safe YAML parser, and show loading, connecting,
+  running, and report-writing stages in interactive terminals.
+- Graph inventory uses one combined request, and built-in same-label completeness checks share
+  bounded scans while retaining individual verdicts, evidence, and executed-query provenance.
+- PII candidate selection orders eligible properties within each node while preserving its
+  deterministic sampling inputs and final sample ordering.
+- Optional telemetry delivery gets a 50 ms command-exit allowance and pending events may be dropped.
+- Report IDs include a unique component; redacted exports use independent random identifiers.
+  Existing history names remain readable, and identical artifact publication can be retried.
+- Corrected read-consistency documentation: measurement and evidence share a transaction and
+  deadline, but Neo4j read-committed isolation permits concurrent writes to change observations.
+
+### Fixed
+
+- Redaction preserves historical results schema context: 1.0/1.1 artifacts retain unknown
+  inventory and 1.2 artifacts keep their original version when exported by `graphcheck redact`.
+- Historical results are validated against their declared archived JSON Schema before
+  normalization, rejecting fields and enum values introduced by later schemas. Installed wheels
+  include the same contracts.
+- Historical exports also validate the final payload before serialization, rejecting incompatible
+  model mutations such as aggregate evidence in schema 1.0 before writing any output file.
+- Schema 1.0 exports always omit graph counts, even if a loaded model was subsequently populated.
+  Schema 1.1 exports preserve recorded counts and omit unknown (null) counts.
+- Run configuration hashes include the authenticated username so permission changes between
+  users have distinct provenance, while passwords and password environment variables stay excluded.
+- Integration CI initializes the pinned fraud-ring fixture submodule for every Neo4j target,
+  so the changes acceptance test can load its Cypher parser and seed data.
+- The fraud-ring changes acceptance test uses the explicit `node_element_id` evidence alias,
+  so its planted tax-ID finding fails with evidence and then passes after the repair.
+- GraphRAG embedding consistency accepts stored numeric arrays on Neo4j 5.26 LTS by using
+  concrete non-null integer/float list predicates. GraphRAG integration tests now run in every
+  supported CI lane, including stored integer, float, and mixed-numeric embedding regressions.
+- Drift checks retain partial run status when using present measurements from incomplete
+  baselines, without changing their measured verdict or exit-code precedence.
+- Connection and credential preflight now share the run deadline with check execution.
+- Baseline references and parsed snapshots are pinned per run, and snapshots/selection metadata
+  are published atomically so interrupted writes cannot become selectable partial files.
+- Distinct runs cannot overwrite history on timestamp collisions. Managed report readers now
+  coordinate with publication/deletion and retain access to healthy records beside corrupt ones.
+- Pruning uses compact summaries instead of retaining full historical results, and partial
+  profiles preserve successfully collected relationship counts and property coverage.
+- Equality checks stop on decisive unexpected values or excess duplicates while preserving bag
+  semantics, honest partial-stream measurements, and graph-evidence requirements.
+- Escaped Unicode-encoded backticks in schema identifiers and shared the same escaping between
+  check compilation and profiling to prevent identifiers from changing the generated Cypher.
+- Configuration errors no longer echo input values or YAML source snippets, connection profile
+  representations hide passwords, and project/profile files reject duplicate mapping keys.
+- Missing requested suites now make a run partial with an actionable diagnostic, including when
+  the other requested suites pass.
+- Read preflights now reject missing-schema warnings before bounded queries can stop early;
+  permissive empty-graph preflights cannot satisfy a stricter cached read.
+- Competency assertions compare every field of ordinary result maps, including maps resembling
+  evidence pointers, and graph properties cannot override actual Neo4j element identities.
+- Reduced `contains` assertion work from repeated scans to hash-based membership in both streaming
+  and final evaluation while preserving typed value comparisons.
+- Report deletion and pruning now share the publication lock so history mutations cannot race
+  with publication or restoration of the `latest` report.
+- The local report explorer rejects malformed authentication without crashing, responds to
+  unauthorized requests without waiting for their bodies, and limits socket inactivity.
+
+## [0.3.0] - 2026-09-04
+
+### Added
+
+- The GitHub Action now emits bounded inline workflow annotations for failed, errored, and
+  warning-severity checks, attaches repository source locations when available, and reports any
+  annotations dropped at the per-run cap while retaining the existing Step Summary.
+- Added one CI/CD guide with copy-paste workflows for pull-request gating, scheduled audits with
+  alerting, staging merges, and server-enforced read-only production runs.
+- Added a scripted hostile-graph certification set that runs the real `debug`, `profile`, and
+  `run` command boundary against noisy LLM Graph Builder-shaped data, a checksum-pinned Stanford
+  SNAP scale graph, a three-member Neo4j 4.4 cluster, an APOC-less server, and an empty graph. Its
+  manifest drives the runner and integration expectations; the legacy lane uses Docker-assigned
+  ports and verifies three unique cluster members, one leader, and two followers before testing.
+
+### Changed
+
+- Reduced pull-request CI from 26 expanded jobs to 12: driver compatibility now tests the two
+  supported edge combinations, pull requests scan only their commit range for secrets, and the
+  Neo4j 4.4 hostile lane, cross-platform first-run trials, and Windows performance gates moved to
+  a weekly and manually runnable Extended CI workflow.
+- Added Python 3.14 to the CI test matrix and package classifiers.
+- Reduced GitHub Action startup overhead with cached `uv` and Python setup, binary-only package
+  installation, consolidated configuration/profile preparation, and direct helper execution from
+  the Action environment.
+- Regenerated the canonical fraud-ring sample reports and linked them from `README.md` and
+  `docs/guides/user-guide.md`.
+- Reorganized repository-facing material into dedicated `examples/`, `docs/`, `tools/`, and
+  layered `tests/` directories, including a minimal starter and the preserved fraud-ring demo, so
+  the repository root stays focused on project essentials.
+- First-run CI now records three independent clean-runner install-to-first-valid-result samples on
+  Linux, macOS, and Windows/WSL, uploads structured timing evidence, publishes the per-platform
+  medians in the Actions summary, records both the tested GitHub SHA and pull-request head SHA, and
+  enforces the under-15-minute adoption budget.
+- The default check concurrency is now two workers across project scaffolding, the engine, and the
+  Neo4j connection pool; `graphcheck.yml` and `graphcheck run --concurrency N` still override it.
+- Migrated the breaking results contract from schema 1.2 to 2.0: `run.status` is now
+  `run.run_status`, summary `status` is now `coverage_status`, and `load_results()` retains a
+  compatibility path for historical artifacts.
+- The Step Summary of `graphora/graphcheck-action` reports the run status and the coverage status
+  separately from `v1.0.2`, which reads the schema 2.0 fields and falls back to the historical
+  `run.status` and summary `status` for artifacts produced before this migration.
+- The measured first-run path now installs a built wheel without a package cache and verifies the
+  baseline-free `init` → `run` path directly and persists that evidence before `profile` runs as a
+  separate post-timing smoke check.
+
+### Fixed
+
+- Preserved the established GitHub Pages URLs for both sample reports with tested compatibility
+  redirects after moving the canonical HTML files under `docs/samples/reports/`.
+- Kept the minimal example's documented first run baseline-free by moving its optional drift check
+  outside the default `checks/` discovery directory.
+- Restored pull-request smoke CI after the repository reorganization by staging the fraud-ring
+  `graphcheck.yml` and `checks/` at the workspace root expected by the published GitHub Action.
+- First-run stage failures, unexpected profiling faults, and baseline write errors now return an
+  actionable `Fix:` diagnostic without exposing a Python traceback.
+
+### Removed
+
+- Removed the retired in-repository GraphCheck Action copy and its implementation tests; CI now
+  guards the boundary and consumes only the standalone `graphora/graphcheck-action@v1` release.
 
 ## [0.2.0] - 2026-08-20
 
@@ -34,7 +248,7 @@ All notable changes to this project are documented here. Format follows [Keep a
 - PyPI release tooling: a Trusted Publishing (OIDC) release workflow triggered by a published
   GitHub Release, guarding that the release tag matches the built version and smoke-testing a
   clean install before upload; packaging metadata (project URLs, classifiers, keywords, author);
-  and a single-source version literal in `src/graphcheck/__init__.py`, read at build time by hatch. See `docs/releasing.md`.
+  and a single-source version literal in `src/graphcheck/__init__.py`, read at build time by hatch. See `docs/maintainers/releasing.md`.
 - A release-oriented top-level README with a versioned project header, embedded CLI demo,
   concise problem statement, quickstart, check-suite example, explicit non-goals, and a preserved
   full user guide for detailed operational workflows.
@@ -126,7 +340,7 @@ All notable changes to this project are documented here. Format follows [Keep a
   timed-out, refused, or otherwise unsuccessful delivery.
 - Telemetry privacy and transparency safeguards: no queries, schema tokens, graph values,
   credentials, project/check identity, results, verdicts, paths, arguments, or free-form
-  diagnostics; a complete public event/field inventory in `docs/telemetry.md`; CI enforcement
+  diagnostics; a complete public event/field inventory in `docs/reference/telemetry.md`; CI enforcement
   against allowlist drift; property-based anonymization coverage; explicit network-failure tests;
   and a fresh-install command matrix proving zero events before opt-in.
 - A fifteen-part performance roadmap with repeatable cold-CLI, query-plan, allocation-retention,
@@ -143,7 +357,8 @@ All notable changes to this project are documented here. Format follows [Keep a
   predicates while preserving the existing eager connector API.
 - Positive project and CLI concurrency controls through `graphcheck.yml` and
   `graphcheck run --concurrency`, with deterministic output ordering, deadline-aware scheduling,
-  a conservative default of one worker, and Neo4j pool sizing matched to effective concurrency.
+  an initial conservative default of one worker, and Neo4j pool sizing matched to effective
+  concurrency.
 - A secure local report explorer launched by `graphcheck report --open`, with searchable history,
   in-place report switching, two-run comparisons, multi-select deletion, safe `latest` repair,
   authenticated same-origin APIs, restrictive browser security headers, and idle shutdown.

{graphcheck-0.2.0 → graphcheck-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphcheck
-Version: 0.2.0
+Version: 0.4.0
 Summary: Semantic observability for property graphs.
 Project-URL: Homepage, https://github.com/graphora/graphcheck
 Project-URL: Repository, https://github.com/graphora/graphcheck
@@ -17,6 +17,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Database
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Software Development :: Testing
@@ -39,8 +40,8 @@ Description-Content-Type: text/markdown
 
 # GraphCheck
 
-[![Release](https://img.shields.io/badge/release-v0.1.0-5b5bd6)](https://github.com/graphora/graphcheck/releases)
-[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-3776ab)](https://www.python.org/)
+[![Release](https://img.shields.io/badge/release-v0.4.0-5b5bd6)](https://github.com/graphora/graphcheck/releases)
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-3776ab)](https://www.python.org/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-2ea44f)](LICENSE)
 
 **Semantic observability for property graphs.**
@@ -48,7 +49,12 @@ Description-Content-Type: text/markdown
 </div>
 
 <p align="center">
-  <img src="docs/graphcheck-demo.gif" width="900" alt="GraphCheck command-line demo">
+  <img src="docs/assets/graphcheck-demo.gif" width="900" alt="GraphCheck command-line demo">
+</p>
+
+<p align="center">
+  See a real report: <a href="https://graphora.github.io/graphcheck/docs/samples/report-findings.html">findings</a> and
+  <a href="https://graphora.github.io/graphcheck/docs/samples/report-clean.html">clean run</a>
 </p>
 
 ## The problem
@@ -62,10 +68,12 @@ YAML and produces deterministic, evidence-backed JSON and offline HTML reports f
 ## Quickstart
 
 For complete setup, credential, authoring, redaction, baseline, and configuration instructions, see
-the **[full user guide](docs/user-guide.md)**.
+the **[full user guide](docs/guides/user-guide.md)**.
 
-GraphCheck requires Python 3.12 or 3.13 and a supported Neo4j server. See the
-[compatibility matrix](docs/compatibility.md) for the tested Neo4j and Cypher versions.
+GraphCheck requires Python 3.12, 3.13, or 3.14 and a supported Neo4j server. See the
+[compatibility matrix](docs/reference/compatibility.md) for the tested Neo4j and Cypher versions.
+The audit ceiling is **10 million nodes**, see [supported graph size](docs/reference/compatibility.md#supported-graph-size)
+for measured runtimes, sampling, and the transaction-memory limitation observed with PII at 10M.
 
 Install the published CLI and scaffold a project:
 
@@ -95,6 +103,9 @@ checks/example.yml      Example check suite
 .graphcheck/            Baselines, run history, JSON, and HTML reports
 ```
 
+New projects run up to two checks concurrently by default. Set `concurrency` in `graphcheck.yml`
+or pass `graphcheck run --concurrency N` to choose a different positive worker limit.
+
 Edit `profiles.yml` with the URI, database, and credential for your Neo4j instance. Enterprise and
 Developer deployments must use a user assigned only Neo4j's built-in `reader` role plus the
 automatic `PUBLIC` role; GraphCheck rejects missing, additional, or custom roles. Community
@@ -112,14 +123,18 @@ Each prepared run writes immutable history plus convenient `latest` copies:
 
 ```text
 .graphcheck/runs/<run-id>/results.json
+.graphcheck/runs/<run-id>/summary.json
 .graphcheck/runs/<run-id>/report.html
 .graphcheck/runs/latest/results.json
+.graphcheck/runs/latest/summary.json
 .graphcheck/runs/latest/report.html
 ```
 
 The HTML report is self-contained and works offline. Exit codes are stable for CI: `0` means all
 executed checks passed, `1` means an error-severity finding or execution error, `2` means a warning or
 incomplete evaluation, and `3` means the run could not be prepared or completed.
+See the **[CI/CD guide](docs/guides/ci-cd.md)** for copy-paste pull-request, scheduled, staging, and
+production workflows using the published GitHub Action.
 
 For development, use the locked environment instead:
 
@@ -128,6 +143,9 @@ uv sync --group dev
 uv run graphcheck --version
 ```
 
+Complete runnable projects and reference deployments live under [`examples/`](examples/), including
+the self-contained fraud-ring Docker quickstart and the Prometheus/Grafana monitoring stack.
+
 ## Example
 
 Replace `checks/example.yml` with a suite that matches labels in your graph:
@@ -174,11 +192,21 @@ Suite YAML is strict: duplicate keys, unknown fields, invalid payloads, and inco
 fail before execution. Runtime evaluation is rule-based; generated check suggestions remain inert
 until a person reviews and activates them.
 
-For the full contracts, see the [check YAML specification](docs/specs/SPEC-02-check-yaml.md),
-[`results.json` specification](docs/specs/SPEC-01-results-json.md), and
-[engine and CLI specification](docs/specs/SPEC-04%20Engine.md). The
-[agent guide](docs/agents.md), [telemetry disclosure](docs/telemetry.md),
-and [contributor guide](CONTRIBUTING.md) cover integration and operational workflows.
+For document/chunk/entity graphs, enable the optional [GraphRAG pack](docs/graphrag.md) with
+`graphcheck init --pack graphrag`. It checks provenance, embedding consistency, and sampled duplicate names using your
+configured labels, relationships, and properties.
+
+For authoring and execution details, see the [user guide](docs/guides/user-guide.md) and
+[JSON Schemas](docs/schemas/). The [agent guide](docs/guides/agents.md),
+[telemetry disclosure](docs/reference/telemetry.md), and [contributor guide](CONTRIBUTING.md)
+cover integration and operational workflows.
+
+## Support
+
+See the [Neo4j compatibility matrix](docs/reference/compatibility.md) for supported servers and
+the [artifact compatibility policy](docs/reference/artifact-compatibility.md) for schema support,
+deprecation deadlines, and migration of saved `results.json` files. Schema versions are independent
+of CLI versions; the current and previous schemas remain readable.
 
 ## Non-goals
 

{graphcheck-0.2.0 → graphcheck-0.4.0}/README.md

@@ -2,8 +2,8 @@
 
 # GraphCheck
 
-[![Release](https://img.shields.io/badge/release-v0.1.0-5b5bd6)](https://github.com/graphora/graphcheck/releases)
-[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-3776ab)](https://www.python.org/)
+[![Release](https://img.shields.io/badge/release-v0.4.0-5b5bd6)](https://github.com/graphora/graphcheck/releases)
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-3776ab)](https://www.python.org/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-2ea44f)](LICENSE)
 
 **Semantic observability for property graphs.**
@@ -11,7 +11,12 @@
 </div>
 
 <p align="center">
-  <img src="docs/graphcheck-demo.gif" width="900" alt="GraphCheck command-line demo">
+  <img src="docs/assets/graphcheck-demo.gif" width="900" alt="GraphCheck command-line demo">
+</p>
+
+<p align="center">
+  See a real report: <a href="https://graphora.github.io/graphcheck/docs/samples/report-findings.html">findings</a> and
+  <a href="https://graphora.github.io/graphcheck/docs/samples/report-clean.html">clean run</a>
 </p>
 
 ## The problem
@@ -25,10 +30,12 @@ YAML and produces deterministic, evidence-backed JSON and offline HTML reports f
 ## Quickstart
 
 For complete setup, credential, authoring, redaction, baseline, and configuration instructions, see
-the **[full user guide](docs/user-guide.md)**.
+the **[full user guide](docs/guides/user-guide.md)**.
 
-GraphCheck requires Python 3.12 or 3.13 and a supported Neo4j server. See the
-[compatibility matrix](docs/compatibility.md) for the tested Neo4j and Cypher versions.
+GraphCheck requires Python 3.12, 3.13, or 3.14 and a supported Neo4j server. See the
+[compatibility matrix](docs/reference/compatibility.md) for the tested Neo4j and Cypher versions.
+The audit ceiling is **10 million nodes**, see [supported graph size](docs/reference/compatibility.md#supported-graph-size)
+for measured runtimes, sampling, and the transaction-memory limitation observed with PII at 10M.
 
 Install the published CLI and scaffold a project:
 
@@ -58,6 +65,9 @@ checks/example.yml      Example check suite
 .graphcheck/            Baselines, run history, JSON, and HTML reports
 ```
 
+New projects run up to two checks concurrently by default. Set `concurrency` in `graphcheck.yml`
+or pass `graphcheck run --concurrency N` to choose a different positive worker limit.
+
 Edit `profiles.yml` with the URI, database, and credential for your Neo4j instance. Enterprise and
 Developer deployments must use a user assigned only Neo4j's built-in `reader` role plus the
 automatic `PUBLIC` role; GraphCheck rejects missing, additional, or custom roles. Community
@@ -75,14 +85,18 @@ Each prepared run writes immutable history plus convenient `latest` copies:
 
 ```text
 .graphcheck/runs/<run-id>/results.json
+.graphcheck/runs/<run-id>/summary.json
 .graphcheck/runs/<run-id>/report.html
 .graphcheck/runs/latest/results.json
+.graphcheck/runs/latest/summary.json
 .graphcheck/runs/latest/report.html
 ```
 
 The HTML report is self-contained and works offline. Exit codes are stable for CI: `0` means all
 executed checks passed, `1` means an error-severity finding or execution error, `2` means a warning or
 incomplete evaluation, and `3` means the run could not be prepared or completed.
+See the **[CI/CD guide](docs/guides/ci-cd.md)** for copy-paste pull-request, scheduled, staging, and
+production workflows using the published GitHub Action.
 
 For development, use the locked environment instead:
 
@@ -91,6 +105,9 @@ uv sync --group dev
 uv run graphcheck --version
 ```
 
+Complete runnable projects and reference deployments live under [`examples/`](examples/), including
+the self-contained fraud-ring Docker quickstart and the Prometheus/Grafana monitoring stack.
+
 ## Example
 
 Replace `checks/example.yml` with a suite that matches labels in your graph:
@@ -137,11 +154,21 @@ Suite YAML is strict: duplicate keys, unknown fields, invalid payloads, and inco
 fail before execution. Runtime evaluation is rule-based; generated check suggestions remain inert
 until a person reviews and activates them.
 
-For the full contracts, see the [check YAML specification](docs/specs/SPEC-02-check-yaml.md),
-[`results.json` specification](docs/specs/SPEC-01-results-json.md), and
-[engine and CLI specification](docs/specs/SPEC-04%20Engine.md). The
-[agent guide](docs/agents.md), [telemetry disclosure](docs/telemetry.md),
-and [contributor guide](CONTRIBUTING.md) cover integration and operational workflows.
+For document/chunk/entity graphs, enable the optional [GraphRAG pack](docs/graphrag.md) with
+`graphcheck init --pack graphrag`. It checks provenance, embedding consistency, and sampled duplicate names using your
+configured labels, relationships, and properties.
+
+For authoring and execution details, see the [user guide](docs/guides/user-guide.md) and
+[JSON Schemas](docs/schemas/). The [agent guide](docs/guides/agents.md),
+[telemetry disclosure](docs/reference/telemetry.md), and [contributor guide](CONTRIBUTING.md)
+cover integration and operational workflows.
+
+## Support
+
+See the [Neo4j compatibility matrix](docs/reference/compatibility.md) for supported servers and
+the [artifact compatibility policy](docs/reference/artifact-compatibility.md) for schema support,
+deprecation deadlines, and migration of saved `results.json` files. Schema versions are independent
+of CLI versions; the current and previous schemas remain readable.
 
 ## Non-goals