Skip to content

docs(readme): rewrite README as a user-first guide with verified quickstart - #21

Draft
lasomethingsomething wants to merge 3 commits into
runtimeconditions:mainfrom
lasomethingsomething:rewrite-readme-user-first-quickstart
Draft

lasomethingsomething wants to merge 3 commits into
runtimeconditions:mainfrom
lasomethingsomething:rewrite-readme-user-first-quickstart

Conversation

@lasomethingsomething

Copy link
Copy Markdown

Rewrites README.md so a new user who just installed the CLI can succeed without reading anything else, while preserving the maintainer/contributor content.

Structure (new)

  1. What it is (links to https://runtimeconditions.io and runtimeconditions/spec)
  2. Install — Homebrew (brew install runtimeconditions/tools/rc-cli), apt/dnf/yum (https://runtimeconditions.io/packages/setup.sh), from source pointer
  3. Commands — rc --version, rc plugins list with real output
  4. Quickstart — the one path that works end to end on a fresh install: rc profile validate rc-demos/artifacts/request-logger-http.profile.yaml → runtimeconditions: profile validated (verified against a binary built from this branch)
  5. Generating a profile — the three prerequisites with verified error strings, a published-module code sample, the replace-directive rejection explained as intended behavior, and the not-a-module failure mode
  6. Command reference — existing tables kept, flags verified against --help
  7. Optional language profilers — existing section kept and tightened, all flag/override/env-var details intact
  8. Build from source — former "Build locally" content, including the plain-go build schema-linker caveat and release-build notes
  9. Ecosystem map — one line per repo

Verified, not assumed

Every command/flag was checked against --help output of a binary built from this repo. Fresh-install facts were re-run:

  • validate quickstart on a fresh rc-demos clone → runtimeconditions: profile validated
  • no go.mod → rc: <dir>: workload must have a go.mod: ...
  • go.mod replace to a sibling extensions clone → ... uses a go.mod replace; generated bindings must resolve to a published module version
  • runtimeconditions.io/x/rc/common@v0.3.0 exists on the Go proxy and generates a profile that validates; env@v0.3.0 currently fails with dependency Go module archive SHA-256 mismatch (documented as a known gap, with the exact string)
  • install surfaces: tap runtimeconditions/homebrew-tools (Formula/rc-cli.rb), runtimeconditions.io/packages/setup.sh (200), npm @runtimeconditions/typescript-profiler, PyPI runtimeconditions-profiler

Closes none of the open issues directly; pairs with #15/#16/#17 docs direction.

Generated by Mistral Vibe.

…kstart

Reorients README.md so a fresh install succeeds without reading anything
else, while keeping the contributor/maintainer content:

- New order: what it is, install, commands, quickstart, generating a
  profile, command reference, language profilers, build from source,
  ecosystem map.
- Quickstart is the verified validate path:
  rc profile validate rc-demos/artifacts/request-logger-http.profile.yaml
  -> "runtimeconditions: profile validated".
- Generate section documents the three prerequisites with real error
  strings verified against the linked go-rc-profiler v0.8.0: Go toolchain
  on PATH, --dir must contain a go.mod, and published binding modules
  only (go.mod replace rejected by design with the exact message).
- Example workload uses the published modules
  runtimeconditions.io/x/rc/common@v0.3.0 and .../env@v0.3.0; notes the
  verified current env v0.3.0 dependency-archive SHA-256 mismatch.
- Install paths verified against the org: brew runtimeconditions/tools/rc-cli,
  https://runtimeconditions.io/packages/setup.sh + apt/dnf, npm
  @runtimeconditions/typescript-profiler, PyPI runtimeconditions-profiler.
- All commands/flags checked against --help output of a binary built from
  this branch; existing command tables kept; build-from-source section
  preserves the schema-linker caveat and release-build notes.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
@lasomethingsomething
lasomethingsomething marked this pull request as draft November 18, 2026 23:34
"Your first profile" implied the quickstart creates a profile; it only
validates a committed demo one. Heading is now "validate an existing
profile" with a one-line clarification.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
@lasomethingsomething
lasomethingsomething deleted the rewrite-readme-user-first-quickstart branch November 19, 2026 17:44
@lasomethingsomething
lasomethingsomething restored the rewrite-readme-user-first-quickstart branch November 19, 2026 17:45

This branch has not been deployed

No deployments
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