From 4a13c12ee998a2e4f6129a38864eddd23a8edee7 Mon Sep 17 00:00:00 2001 From: Stephen Waits Date: Tue, 12 May 2026 09:26:10 -0600 Subject: [PATCH] docs(readme): add prominent Provenance disclosure and Author section Prepare the repo for public release by stating openly: - The spec is AI-authored (Claude / Anthropic) under Stephen Waits's direction. It is an independent project, not affiliated with the upstream MeshCore project. - The official MeshCore C++ firmware is the golden source of truth for all protocol behavior; when this spec and upstream disagree, upstream wins. - Clarifications have been driven by observations from building DongLoRa firmware and apps against live deployments, but DongLoRa divergences from upstream are treated as DongLoRa bugs, not spec changes. - Conformance against this corpus is a useful signal but not a substitute for cross-checking against upstream. Tighten Project Status to reference the new section. Add an Author section with attribution. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 43 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 37 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index a224f2d..7d402f0 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,34 @@ MeshCore wire format — much like [RubySpec](https://github.com/ruby/spec) beca the definitive specification of the Ruby language. Any implementation that passes the full test corpus can claim bit-perfect MeshCore compatibility. +## Provenance + +This is an **independent, AI-authored project**. It is not affiliated with, +endorsed by, or maintained by the upstream MeshCore project. Read this section +before relying on the spec for anything load-bearing. + +- **Authorship.** The spec, the corpus, and the tooling were written by Claude + (Anthropic, primarily Opus 4.x) under the direction of Stephen Waits. + Substantive edits — additions, clarifications, audit passes — are produced + through model-driven analysis of the official MeshCore source and reviewed + before commit. +- **Source of truth.** The official MeshCore firmware at + [meshcore-dev/MeshCore](https://github.com/meshcore-dev/MeshCore) is the + **golden source of truth** for all protocol behavior. Whenever this spec and + the upstream C++ disagree, **upstream wins** — this spec is downstream and + the canonical text is the C++. Each substantive change in `CHANGELOG.md` + records the upstream commit hash it was validated against. +- **Refined through DongLoRa.** Clarifications and edge-case detail in this + spec have been driven in part by observations from building DongLoRa + firmware and apps against live MeshCore deployments. Where DongLoRa + behavior diverges from upstream, this spec follows upstream and treats the + DongLoRa side as a follow-up bug, not a spec change. +- **Use it carefully.** Conformance against this corpus is a useful signal + but not a substitute for cross-checking against upstream firmware for any + behavior that affects interoperability. If you find a divergence from + upstream, please file an issue — that is exactly the kind of report this + project exists to catch. + ## What's Here - **`spec/`** — RFC-style protocol specification in Markdown, covering every @@ -45,9 +73,8 @@ implementation. ## Project Status -This project is under active development. The specification and corpus are being -built from the [official MeshCore firmware](https://github.com/meshcore-dev/MeshCore) -source code. +This project is under active development. See [Provenance](#provenance) above +for how the spec is produced and what to verify against. ## Protocol Versions @@ -65,6 +92,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). ## Acknowledgments -Based on the [MeshCore firmware](https://github.com/meshcore-dev/MeshCore) by -the MeshCore developers. Protocol documentation derived from the official -[MeshCore docs](https://docs.meshcore.io). +This spec would not exist without the [MeshCore firmware](https://github.com/meshcore-dev/MeshCore) +by the MeshCore developers and the official [MeshCore docs](https://docs.meshcore.io), +which together are the authoritative reference this spec derives from. + +## Author + +Stephen Waits