Skip to content

docs: tighten release trust surfaces#27

Merged
GsCommand merged 2 commits intomainfrom
codex/implement-documentation-and-trust-improvements
Mar 20, 2026
Merged

docs: tighten release trust surfaces#27
GsCommand merged 2 commits intomainfrom
codex/implement-documentation-and-trust-improvements

Conversation

@GsCommand
Copy link
Contributor

Motivation

  • Reduce duplicated guidance across top-level docs so authoritative rules live in SPEC.md and POLICY.md, lowering maintenance risk and avoiding conflicting claims.
  • Improve release discoverability and long-term trust signals by adding an explicit CHANGELOG.md, clarifying $id resolution, and making the index file’s intent explicit.
  • Remove unverifiable or misleading guidance (notably npm install instructions) when package publication could not be confirmed.
  • Close governance and security gaps with a concise steward-succession rule and an explicit PGP statement.

Description

  • Consolidated and shortened consumer/maintainer guidance in README.md, INTEGRATOR.md, and ONBOARDING.md to reference canonical rules in SPEC.md and POLICY.md, and removed immediate npm install @commandlayer/commercial install instructions where publication could not be verified.
  • Added CHANGELOG.md at repo root and added it to package.json files so release history is discoverable.
  • Clarified $id resolution and source-of-truth: SPEC.md now states commandlayer.org is the canonical namespace while the repository is the source of truth and mirrors may be temporarily unavailable, and README.md contains a brief mirror/namespace summary.
  • Marked schemas/v1.1.0/index.json as an inventory (removed "$schema" JSON-Schema framing, added "document_type": "inventory" and a description), regenerated checksums.txt, and updated package.json to include CHANGELOG.md.
  • Strengthened governance and security signals: added a short “Steward succession” section to GOVERNANCE.md and added PGP: none currently provided to SECURITY.md while keeping contact email.
  • Files changed: README.md, SPEC.md, POLICY.md (referenced), SECURITY.md, ONBOARDING.md, INTEGRATOR.md, GOVERNANCE.md, CHANGELOG.md (new), package.json (files list), schemas/v1.1.0/index.json (made an inventory), and checksums.txt (regenerated).
  • Intentional non-changes: no protocol/schema semantics were altered, no $id values changed, and the repo export/package name and index entrypoint were left intact so runtime semantics remain unchanged.

Testing

  • Ran npm run generate:checksums, which updated checksums.txt for the changed inventory and succeeded.
  • Ran npm run validate (which runs validate:schemas, validate:examples, and validate:integrity), and all validation steps completed successfully.
  • Ran sha256sum -c checksums.txt and all checksum entries reported OK.
  • Attempted npm view @commandlayer/commercial version --json to verify publication, but the registry request returned 403 Forbidden, so package publication could not be confirmed from this environment and install guidance was intentionally omitted.

Codex Task

@GsCommand GsCommand merged commit b966c0f into main Mar 20, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant