From 1cf8a8eaf12ab6d846784629080444c5e761230c Mon Sep 17 00:00:00 2001
From: Midia Kiasat <contact@speedkit.eu>
Date: Mon, 2 Mar 2026 20:20:28 +0100
Subject: [PATCH] docs: standardize readme baseline

---
 README.md | 46 ++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 38 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 0f19d59..629aa69 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,46 @@
 # VERIFRAX-SPEC
 
-Published SPEC artifacts derived from `Verifrax/VERIFRAX` (`public/spec`).
+## Purpose
 
-**DO NOT EDIT MANUALLY.**
+Normative specification for the Verifrax protocol and formats.
 
----
+## Status
 
-## Normative Surface
+- **Stability**: Experimental
+- **SemVer**: Not guaranteed until v1.0.0
+- **Security**: See **Security** section below
 
-The normative specification lives under `spec/`.
-Version: see `spec/VERSION`.
+## Scope
 
-## Change Control
+- What this repo is responsible for
+- What it explicitly does **not** do
 
-Edits MUST preserve stable section identifiers and anchor targets.
+## Quickstart
+
+```bash
+# clone
+git clone https://github.com/Verifrax/VERIFRAX-SPEC.git
+cd VERIFRAX-SPEC
+
+# install (adjust if needed)
+# (placeholder) npm install / pnpm install / go test ./... / etc.
+```
+
+## Repository layout
+
+- `/` Root sources
+- `/.github/` Issue + PR templates
+- `/docs/` Documentation (if present)
+
+## Security
+
+- Report vulnerabilities privately: **security@verifrax.org**
+- Do **not** open public issues for sensitive findings
+
+## Contributing
+
+See `CONTRIBUTING.md`.
+
+## License
+
+MIT. See `LICENSE`.