Furnish schemas and release Relay 0.2.1

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -15,7 +15,7 @@ body:
     attributes:
       label: Relay version
       description: Run `relay --version`.
-      placeholder: relay 0.2.0
+      placeholder: relay 0.2.1
     validations:
       required: true
   - type: dropdown

.github/workflows/ci.yml

@@ -46,7 +46,7 @@ jobs:
         run: >-
           python -c "from pathlib import Path;
           required=['architecture.md','configuration.md','rules.md','timing-model.md',
-          'limitations.md','security.md','tutorials.md'];
+          'limitations.md','schemas.md','security.md','tutorials.md'];
           assert all((Path('docs') / name).is_file() for name in required)"
       - uses: actions/upload-artifact@v7
         with:

.gitignore

@@ -10,3 +10,5 @@ __pycache__/
 build/
 dist/
 relay.toml
+/relay-report.md
+/timing-summary.md

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.2.1 — 2026-07-29
+
+- Added versioned JSON Schemas for Relay report schema 2.0 and parsed `relay.toml` configuration.
+- Added `relay schema config` and `relay schema report`, with optional atomic `--output`.
+- Included both schemas in the installed wheel and validated them against real reports and
+  configuration in CI.
+- Updated the primary installation path to a directly installable, checksum-published GitHub
+  release wheel.
+- Expanded `pathspec` compatibility to supported 1.x releases while retaining a `<2` upper bound.
+- Removed generated reports from version control and ignored the documented local output names.
+
 ## 0.2.0 — 2026-07-29
 
 - Reframed Relay as a conservative local source-review tool rather than compiler-grade static

README.md

@@ -9,7 +9,7 @@
 **Relay shows what blocking code prevents from running.**
 
 Relay is a local-first source-review tool for timing and blocking risks in polyglot control
-programs. Version 0.2.0 is an alpha: useful as a review assistant, but intentionally not presented
+programs. Version 0.2.1 is an alpha: useful as a review assistant, but intentionally not presented
 as compiler-grade semantic analysis or safety certification. Analysis never executes, imports,
 compiles, or uploads the source being inspected.
 
@@ -25,7 +25,14 @@ can be sensitive, and a review tool should not need to upload that source just t
 
 ## Install
 
-Relay supports Python 3.9–3.14.
+Relay 0.2.1 supports Python 3.9–3.14. Install the verified wheel from the GitHub release:
+
+```console
+python -m pip install https://github.com/devkyato/Relay/releases/download/v0.2.1/relay_lint-0.2.1-py3-none-any.whl
+relay --version
+```
+
+For development from a clone:
 
 ```powershell
 python -m venv .venv
@@ -44,6 +51,7 @@ relay check examples
 relay check examples/arduino/blocking_robot.ino --format markdown --output relay-report.md
 relay explain examples/arduino/blocking_robot.ino --level beginner
 relay summary examples/arduino/blocking_robot.ino --config relay.toml.example --duration 5s
+relay schema report --output relay-report.schema.json
 relay rules
 relay doctor .
 ```
@@ -63,7 +71,7 @@ Confidence: medium
 Exit status is non-zero when a finding reaches `--fail-on` (default: `warning`). Formats are
 `text`, `json`, `sarif`, and `markdown`. Use `--suggest` or
 `--suggestions-out relay-suggestions.md` for reviewable patterns; Relay never edits source in
-0.2.0 and never claims a suggestion is automatically safe for machinery.
+0.2.1 and never claims a suggestion is automatically safe for machinery.
 
 ## How it works
 
@@ -108,6 +116,20 @@ emergency_stop = "checkEmergencyStop"
 
 See [configuration](docs/configuration.md) and the [timing model](docs/timing-model.md).
 
+## Machine-readable contracts
+
+Relay bundles versioned JSON Schemas inside the installed package:
+
+```console
+relay schema report --output relay-report.schema.json
+relay schema config --output relay-config.schema.json
+relay check . --format json --output relay-report.json
+```
+
+The report schema validates JSON schema version `2.0`. The configuration schema describes the
+data produced by parsing `relay.toml`; Relay still performs the final cross-field validation.
+See [schemas and integrations](docs/schemas.md).
+
 ## Supported sources and rules
 
 | Language | Extensions | Analysis model |

docs/architecture.md

@@ -17,6 +17,8 @@ importantly, what it does not know.
    scheduler.
 7. `reports` writes deterministic text, Markdown, JSON schema 2.0, and SARIF with stable
    fingerprints and explicit model metadata.
+8. `schemas` packages the configuration and report contracts so an installed `relay` command can
+   furnish the exact files used by editors, CI jobs, and other integrations.
 
 `analyser.analyse_path` is the public orchestration boundary. Oh—one design choice I do not want
 to blur: no stage invokes a compiler, interpreter, hardware tool, network service, or target

docs/configuration.md

@@ -20,3 +20,18 @@ The Python API uses the `RelayConfig` passed by its caller.
 
 Durations accept `us`, `ms`, `s`, and `m`. Unknown configuration keys and unknown rule IDs are
 rejected so a typo cannot silently change an analysis. Invalid values fail with exit code 2.
+
+## Configuration schema
+
+Relay 0.2.1 bundles a JSON Schema for the data model produced after parsing `relay.toml`:
+
+```console
+relay schema config --output relay-config.schema.json
+```
+
+Editors and integrations can use that file for keys, primitive types, duration syntax, and rule
+IDs. Relay remains the final validator because it also enforces relationships between values—for
+example, `maximum_total_bytes` cannot be smaller than `maximum_file_bytes`.
+
+The schema is versioned with the release and is also available in
+[`src/relay/schemas/relay-config.schema.json`](../src/relay/schemas/relay-config.schema.json).

docs/releases/0.2.1.md

@@ -0,0 +1,53 @@
+# Relay 0.2.1
+
+After publishing 0.2.0, I went through the project again from the point of view of somebody who
+had not built it locally. The analyser was there, the wheel worked, and the report format had a
+version—but an integration still had to infer the contract from examples. I thought too on that
+point that “stable” should mean Relay can hand you the exact schema, not only tell you its number.
+
+## What I furnished
+
+Relay now bundles two JSON Schemas:
+
+- `report` validates machine-readable `relay check --format json` output with schema version
+  `2.0`;
+- `config` describes the data model produced by parsing `relay.toml`.
+
+You can print either schema or write it atomically:
+
+```console
+relay schema report --output relay-report.schema.json
+relay schema config --output relay-config.schema.json
+```
+
+Oh! On this part, I kept runtime validation authoritative. The configuration schema is useful for
+editors and CI, while Relay still checks relationships such as the aggregate byte limit being at
+least as large as the per-file limit.
+
+## Installation and compatibility
+
+The README now begins with a directly installable GitHub release wheel instead of treating an
+editable development checkout as the normal installation path. The schemas are included inside
+that wheel and tested through the installed command.
+
+This patch also accepts supported `pathspec` 1.x releases while retaining a `<2` upper bound. The
+dependency update passed Relay’s complete Python 3.9–3.14 matrix before it was merged.
+
+## Clean repository state
+
+The example commands create `relay-report.md` and `timing-summary.md` locally. Those generated
+files no longer live in version control, and the documented root-level names are ignored so trying
+Relay does not leave a dirty checkout.
+
+## Compatibility
+
+- Relay runtime: Python 3.9–3.14
+- Analysed languages: Python, C, C++, Arduino, JavaScript, TypeScript, Java, C#, Go, Rust,
+  Kotlin, Swift, Ruby, and PHP
+- JSON report schema: `2.0` (unchanged)
+- SARIF: 2.1.0 (unchanged)
+- Operation: local and offline after installation
+
+This remains an alpha review assistant, not a compiler, scheduler simulator, hardware model, or
+safety certification system. The patch makes Relay easier to install and integrate without making
+its semantic claims any larger.

docs/roadmap.md

@@ -1,6 +1,7 @@
 # Roadmap
 
-Relay 0.2.0 corrects the semantic overclaims in the first alpha. It adds qualified identities,
+Relay 0.2.1 corrects the semantic overclaims in the first alpha and furnishes versioned schemas
+for integrations. It adds qualified identities,
 async-aware Python handling, conservative cross-language profiles, explicit model metadata,
 reachability-scoped impacts, resource bounds, atomic reports, and reproducible-build verification.
 
@@ -9,7 +10,6 @@ For 0.3.0, I am thinking about:
 - add source-level suppression directives with auditable reasons;
 - add opt-in compiler, Tree-sitter, or language-server front ends behind the existing capability
   boundary;
-- publish a representative multi-language corpus with positive, negative, and ambiguous cases;
 - measure per-rule precision, recall, and false-positive budgets before marking any detector
   stable;
 - add mutation tests for rule boundaries and corpus regressions;

docs/schemas.md

@@ -0,0 +1,50 @@
+# Schemas and integrations
+
+I thought about machine-readable output from the other side: a stable version number is useful,
+but an integration still needs the actual contract. Relay therefore ships its schemas inside the
+wheel instead of asking an editor or CI job to copy an example from the documentation.
+
+## Furnish a schema
+
+```console
+relay schema report --output relay-report.schema.json
+relay schema config --output relay-config.schema.json
+```
+
+Without `--output`, Relay writes the selected schema to standard output. Existing output files are
+replaced atomically, and symlink targets are refused just like other Relay reports.
+
+## JSON reports
+
+```console
+relay check firmware --format json --output relay-report.json
+```
+
+The bundled report schema describes schema version `2.0`, including summary counts, analysis
+models, findings, confidence, source locations, evidence, impacts, call paths, and warnings.
+Consumers should select a parser by `schema_version`, ignore no validation failure silently, and
+pin the schema file from the same Relay release used to produce the report.
+
+Report objects reject unknown fields. Relay will increment `schema_version` for a breaking
+machine-report change; consumers should not silently reinterpret a report from an unsupported
+schema generation.
+
+The canonical source is
+[`src/relay/schemas/relay-report-2.0.schema.json`](../src/relay/schemas/relay-report-2.0.schema.json).
+
+## Configuration
+
+The configuration schema describes the JSON-like data model obtained after parsing `relay.toml`.
+It covers known sections and keys, types, rule IDs, duration strings, and positive resource
+limits. Relay performs final semantic validation after schema validation because JSON Schema does
+not express every useful relationship between configuration fields.
+
+The canonical source is
+[`src/relay/schemas/relay-config.schema.json`](../src/relay/schemas/relay-config.schema.json).
+The repository also carries intentionally
+[valid](../examples/config/relay.valid.toml) and
+[invalid](../examples/config/relay.invalid.toml) configuration fixtures so integrations can test
+both outcomes.
+
+Oh—SARIF remains SARIF 2.1.0 rather than a Relay-specific schema. Relay includes stable
+`relayFinding/v1` partial fingerprints and links SARIF output to the official SARIF schema.

examples/config/relay.invalid.toml

@@ -0,0 +1,4 @@
+# Intentionally invalid: use this fixture to verify that integrations reject unknown keys.
+[analysis]
+maximum_files = 0
+unknown_option = true

examples/config/relay.valid.toml

@@ -0,0 +1,23 @@
+# A small valid Relay configuration for editor and CI integration tests.
+[project]
+target = "esp32"
+entrypoints = ["setup", "loop"]
+
+[tasks.control_loop]
+every = "20ms"
+execution_context = "main-loop"
+
+[tasks.emergency_stop]
+maximum_latency = "10ms"
+execution_context = "main-loop"
+safety_critical = true
+
+[functions]
+control_loop = "updateMotors"
+emergency_stop = "checkEmergencyStop"
+
+[analysis]
+disable = ["RLY115"]
+maximum_file_bytes = 2000000
+maximum_files = 2000
+maximum_total_bytes = 50000000

pyproject.toml

@@ -32,6 +32,7 @@ dependencies = [
 [project.optional-dependencies]
 dev = [
   "build>=1.0",
+  "jsonschema>=4.18,<5",
   "mypy>=1.8,<1.20",
   "pytest>=7.4",
   "pytest-cov>=4.1",