# GraphCheck

> GraphCheck is a read-only validation framework for property graphs, currently supporting Neo4j, providing both a command-line interface (CLI) and a Model Context Protocol (MCP) server. It helps engineers validate the semantic correctness of graphs used by GraphRAG systems, AI agents, analytics platforms, and enterprise applications through deterministic, rule-based validation.

GraphCheck executes declarative validation suites and produces:

- Machine-readable JSON results
- Self-contained HTML reports
- Evidence for every fail/warn finding
- CI-friendly exit codes

GraphCheck never modifies customer graphs.

**Version Scope:** This document applies to GraphCheck v0.1.0. 

---

## Overview

- [README](../README.md): Project overview, goals, installation, and quickstart.
- [User Guide](user-guide.md): Credentials, check authoring, execution, artifacts, baselines, generated suggestions, safety, telemetry, and configuration.

---

## Specifications

- [Check YAML Specification](specs/SPEC-02-check-yaml.md): Validation suite format, supported check types, and YAML schema.
- [Results Specification](specs/SPEC-01-results-json.md): `results.json` schema, verdicts, evidence, scoring, and exit codes.
- [Connector Specification](specs/SPEC-03-connector.md): Project initialization, connection profiles, capability probing, and read-only execution.
- [Engine Specification](specs/SPEC-04%20Engine.md): Validation pipeline, execution model, and run orchestration.
- [Profiler & Baseline Specification](specs/SPEC-05-profiler-baseline.md): Graph profiling, baseline generation, and drift detection inputs.
- [Pack Specification](specs/SPEC-09-packs.md): Built-in packs, supported checks, and pack metadata.
- [HTML Report Specification](specs/SPEC-06-scorer-html-report.md): Report generation and rendering.
- [Telemetry Specification](specs/SPEC-10-telemetry-events.md): Telemetry events, privacy, and opt-in behavior.
- [Telemetry Guide](telemetry.md): User-facing telemetry overview and collected events.
- [Agent Guide](agents.md): Guidance for AI agents generating GraphCheck validation suites.

---

## Features

- Semantic Validation
- Competency Question Testing
- Conformance Library
- Drift Detection
- Graph Profiling
- PII Detection
- HTML Reporting
- MCP Integration

---

## CLI

- [CLI Quickstart](../README.md#quickstart): Installation and the first `init`, `debug`, and `run` workflow.
- [CLI User Guide](user-guide.md): Detailed project setup, run selection, redaction, profiling, and generated suggestions.

---

## Architecture

- [Core Engine](specs/SPEC-04%20Engine.md): Executes validation suites.
- [Neo4j Connector](specs/SPEC-03-connector.md): Read-only graph access.
- [Graph Profiler](specs/SPEC-05-profiler-baseline.md): Collects graph schema and statistical metadata.
- [Check Packs](specs/SPEC-09-packs.md): Reusable validation rules.
- [Results & Reports](specs/SPEC-01-results-json.md): JSON and HTML outputs.
- [MCP Server](#): Model Context Protocol integration.

---

## Important Invariants

- [Read-only Execution](specs/SPEC-03-connector.md): Never modify customer graph data.
- [Deterministic Validation](specs/SPEC-04%20Engine.md): Same inputs produce the same results.
- [Thin Adapters](specs/SPEC-04%20Engine.md): CLI and MCP wrap existing engine logic.
- [Connector Abstraction](specs/SPEC-03-connector.md): All graph access goes through connectors.

---

## Accuracy Guarantees

- [Evidence](specs/SPEC-01-results-json.md): Every `fail` and `warn` result includes supporting evidence.
- [No LLM-as-Judge](../README.md): Validation is rule-based.
- [Offline Reports](specs/SPEC-06-scorer-html-report.md): HTML reports require no network connection.
- [Opt-in Telemetry](specs/SPEC-10-telemetry-events.md): Telemetry is disabled by default.

---

## Development

- [CONTRIBUTING](../CONTRIBUTING.md): Contribution guidelines.
- [CHANGELOG](../CHANGELOG.md): Release history.
- [LICENSE](../LICENSE): Licensing information.
