Skip to content

README.md

Latest commit

 

History

History
141 lines (119 loc) · 7.21 KB

README.md

File metadata and controls

141 lines (119 loc) · 7.21 KB
Raw

Renma Documentation

For an initial overview, read user-manual.md.

For authoring Skills and Context Assets, read authoring-guide.md.

For diagnostics and remediation, read diagnostics.md.

For security-related metadata and policy, read security-policy.md.

For machine-readable contracts, use the schemas under schemas/.

Development and internal design documents are under development/. They describe implementation rationale and are not normative user guidance.

Start Here

  • README is the product entrypoint: what Renma is, why a Context Repository exists, the primary product boundary, installation, first use, and a short command overview.
  • User Manual is authoritative for the complete operational metadata and repository configuration references and for current CLI workflows, command purposes, options, formats, examples, expected outputs, and next steps. Emitted renma --help and renma <command> --help remain the command-line authority.
  • Authoring Guide is authoritative for Renma authoring boundaries, evidence rules, the creation gate, asset responsibilities, and the handoff contract. It offers adaptive interaction guidance but does not prescribe the consuming LLM's internal reasoning algorithm.

Diagnostics And Security

  • Diagnostics Reference defines Finding semantics, diagnostic interpretation, classification and evidence conventions, compatibility-sensitive identifiers, repair constraints, and verification expectations.
  • Security Policy Guide defines effective-policy semantics, revision-transition governance, and bounded agent-facing instruction analysis; the User Manual owns the complete security field mapping. The guide also defines the boundary between Renma, SAST, secret scanning, dependency scanning, and runtime controls.
  • Renma Quality Profile records the exact deterministic thresholds, units, provenance, rationale, and configuration status used by quality checks.
  • Metadata Budget focuses on metadata size diagnostics.
  • Context Lifecycle Diagnostics, Context Conflict Diagnostics, and Context Language Diagnostics explain their respective focused diagnostic families.

Asset And Relationship Contracts

  • Agent Skills Compatibility and Migration defines canonical Skill paths and metadata, accepted migration-only forms, validation, and the one-way migration boundary.
  • Advanced Skill Authoring applies the canonical authoring model to focused workflows, orchestration, and progressive disclosure.
  • Context Lens defines when a Context Lens is justified, its fields and relationships, and its non-runtime boundary.
  • Declared Composition defines the forward explicit required/optional closure, provenance, completeness, conflicts, and cycles.
  • Declared Impact defines the reverse explicit composition closure and its change-review boundary.
  • Skill Discovery defines declared continuations, publication, route resolution, reachability, coverage, renma.skill-index.v1, Discovery diff, and warn-only CI policy without describing runtime routing.
  • Repository Context BOM v3 defines renma.repository-context-bom.v3, deterministic ordering, reproducibility, and the declared-manifest boundary.
  • Machine-Readable JSON Compatibility inventories top-level command contracts, defines the 1.x additive/breaking policy, and identifies environment-derived fields.
  • Experimental Execution Contract defines the renma.experimental-execution-contract.v1 static possible relationship artifact, single-snapshot guarantee, bounded completeness, and external revision/hash binding boundary.
  • Trust Graph v2 defines renma.trustGraph.v2, node and edge provenance, ordering, and the distinction between evidence and a trust score.
  • Published JSON Schemas contains the machine-readable BOM v3, Trust Graph v2, and Skill Authoring Handoff v1 contracts shipped in the npm package.

The development architecture, design, and roadmap documents below are source-repository-only and intentionally excluded from the npm package.

Development

  • Public Architecture owns the high-level layers, data flow, stable product boundaries, and public contract surfaces.
  • Internal Architecture owns module responsibilities, dependency direction, shared projections, compatibility facades, invariants, and implementation rationale.
  • Product Design owns durable product decisions and distinctions, including capabilities intentionally outside Renma core.
  • External Review Governance records a candidate design direction and SkillSpector experiment plan, not a current CLI, metadata, schema, or configuration contract.
  • Current Roadmap owns the completed 1.0 stabilization baseline, open candidates, deferred ecosystem concerns, and explicit non-commitments.
  • Renma 1.0 Stabilization Boundary records the completed pre-1.0 reduction, retained shell-family and ci-report contracts, precision-first natural-language boundary, and remaining release assurance gates.
  • Skill Discovery Design records the durable rationale behind the current static Discovery boundary; the current operational contract remains in Skill Discovery.
  • Release Publication Security documents the repository-visible npm publication checks, their limits, and the required npm and GitHub controls outside the repository.
  • Changelog owns chronological release history, version-specific changes, and compatibility notes.

Examples

Repository examples are source-checkout resources rather than npm package contents:

Maintaining The Documentation Site

The Markdown in this directory remains the documentation source of truth. Run the site locally from the repository root:

npm run docs:dev
npm run docs:build
npm run docs:preview

Fenced mermaid blocks under docs/ render automatically, while their Mermaid source remains the canonical editable form. Test diagram changes with npm run docs:build and a local preview. Diagrams must not require loose security or executable click behavior.