add readme

README.md

@@ -1,77 +1,74 @@
-<!-- This is a comment in Markdown 
+# spec-tests
 
-🛠 Repository Setup Instructions
+This repository contains **generated JSON test vectors** for the `ssv-spec` project.
+The JSONs are generated in `ssv-spec` and synchronized here via CI.
 
-After forking or cloning this template, run the following:
+## Repository layout
 
-1. Replace all occurrences of 'template-repository' with your actual repo name:
-   sed -i 's/template-repository/your-repo-name/g' README.md
-
-2. Fill in all TODO sections below.
-
-3. Update [.github/CODEOWNERS](.github/CODEOWNERS) to reflect your team or maintainers.
-
-4. Check `.gitignore` and `.dockerignore` files and modify them according to your project's structure.
-
-5. Update GitHub Actions in `.github/workflows/` if needed (e.g., rename, add secrets).
-
--->
-<p align="center"><img src="https://raw.githubusercontent.com/ssvlabs/.github/refs/heads/main/assets/ssvnetwork-dark.svg" alt="SSV Network"></p>
+```
+spec-tests/
+  qbft/
+    tests/
+    state_comparison/
+    tests.json
+  ssv/
+    tests/
+    state_comparison/
+    tests.json
+  types/
+    tests/
+    state_comparison/
+    tests.json
+```
 
-<img src="https://github.com/ssvlabs/template-repository/actions/workflows/main.yml/badge.svg" alt="Check" />
-<a href="https://discord.com/invite/ssvnetworkofficial"><img src="https://img.shields.io/badge/discord-%23ssvlabs-8A2BE2.svg" alt="Discord" /></a>
+- `tests/` — individual test JSON files.
+- `state_comparison/` — post‑state comparison JSONs used by spec tests.
+- `tests.json` — a single, aggregated JSON file for each module.
 
-## ✨ Introduction
+## How JSONs are generated
 
-<!-- Describe the purpose of this repository. -->
-This project provides a foundational structure for [describe your use case: e.g., smart contracts, node operators, CLI tools].
+JSONs are generated by `ssv-spec`:
 
-## ⚙️  How to Build
+- `make generate-jsons` (runs `go generate ./...`)
+- Generators live under:
+  - `qbft/spectest/generate/main.go`
+  - `ssv/spectest/generate/main.go`
+  - `types/spectest/generate/main.go`
 
-```bash
-# Clone the repo
-git clone https://github.com/ssvlabs/template-repository.git
+The generators write to an **external sibling** directory:
 
-# Navigate
-cd your-repo-name
+```
+../spec-tests/{qbft,ssv,types}/...
+```
 
-# Install dependencies
-TODO
+This repo should **not** be edited manually — it’s generated.
 
-# Build the code
-TODO
-```
+## CI sync behavior
 
+The `ssv-spec` CI workflow:
 
-## 🚀 How to Run
+1. Generates JSONs.
+2. Opens/updates a PR in this repo with the same PR name.
+3. On merge to `main` in `ssv-spec`, syncs the JSONs here and merges the matching PR.
 
+## Requirements for CI sync
 
-```bash
-# Run the main service
-npm start
-# or
-go run main.go
-# or
-python app.py
-```
+In `ssv-spec` GitHub Actions:
 
-## 🧪 Testing
+- Repo variable: `SPEC_TESTS_REPO` (e.g., `ssvlabs/spec-tests`)
+- Secret: `SPEC_TESTS_TOKEN` with write access to this repo
 
-```bash
-npm test
-# or
-go test ./...
-# or
-pytest
-```
+## Usage
 
+Consumers should treat this repo as a **read‑only artifact**:
 
-## Contributing
+- Pin to a tag/commit for reproducible test runs.
+- Pull latest JSONs to keep in sync with `ssv-spec`.
 
-We welcome community contributions!
+## Troubleshooting
 
-- See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-- Create a branch, push your changes, and open a PR.
+- If JSONs look out of date, re-run `make generate-jsons` in `ssv-spec`.
+- If CI doesn’t sync, check `SPEC_TESTS_REPO` and `SPEC_TESTS_TOKEN`.
 
 ## License