Skip to content

Rebuild the README as an adoption surface and stop pinning claim text to it - #6

Open
0j0bit wants to merge 1 commit into
mainfrom
docs/discoverability-readme
Open

0j0bit wants to merge 1 commit into
mainfrom
docs/discoverability-readme

Conversation

@0j0bit

@0j0bit 0j0bit commented Sep 13, 2026

Copy link
Copy Markdown
Contributor

The README is the adoption and indexing surface for MCL, and it is now written as one.

README

  • Leads with a searchable definition: machine-to-machine protocol, device discovery, transport negotiation, BLE/IP/acoustic, C99.
  • New sections: what MCL solves, where it fits beside MQTT/ROS 2/DDS/HTTP/CAN, use cases (robotics, embedded/IoT, provisioned fleets, offline networking, cross-transport), how it works, supported transports, get started, compiling mcl/machine.h example, architecture, repository map, compatibility and maturity, security model, specifications and conformance, contributing.
  • Removed: the "What this release claims, and what it does not" section, the What is claimed navigation link, the scientist/researcher section, review-status prose, and "not adopted, not standardized, not stable".
  • The code example was compiled against the release developer SDK with gcc and clang (-Wall -Wextra -Werror -pedantic) through find_package(mcl_sdk).

Publication gate

  • check-publication-readiness.sh section 6 now requires the claim boundary only in conformance/ICS.md, governance/V1_SCOPE.md and releases/v1.0.0/manifest.txt. It passes with no NOT claim in the README.

Cross-references

  • V1_SCOPE.md §5.9, RELEASE_GATE_V1.md and the manifest (and its generator) said the four lines also appear in README.md. They now name only the three authorities.
  • The two edited governance documents are bundle artifacts, so their digests in releases/v1.0.0/SHA256SUMS.txt are refreshed from the committed bytes. All bundle checksums verify.

No protocol or specification semantics change.

🤖 Generated with Claude Code

… to it

The README now leads with a searchable definition, what MCL solves, where it
fits beside MQTT/ROS 2/DDS, use cases, supported transports, a compiling SDK
example, maturity and the security model. The claim-boundary block, the
research-audience section and review-status prose are removed.

check-publication-readiness.sh section 6 now checks only the normative release
authorities: ICS.md, V1_SCOPE.md and the release manifest. The cross-references
in V1_SCOPE.md 5.9, RELEASE_GATE_V1.md and the manifest that said the four
lines also appear in README.md are corrected, and the bundle digests of the two
edited governance documents are refreshed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@0j0bit
0j0bit requested a review from sed-boi as a code owner September 13, 2026 07:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant