Description
Repair the copy-paste and mental-model defects across README and the docs site without duplicating the deeper product features tracked elsewhere. Explain what synthkit workloads are, how blueprint load/enable differs from YAML authoring, and how users observe current state.
Acceptance Criteria
- #1 README uses port 8088, qualified blueprint/workload scaling IDs, and authenticated mutation examples when CONTROL_TOKEN is set
- #2 README no longer implies an enabled YAML field and clearly distinguishes a synthetic workload model from deploying a real application
- #3 Quick Start declares jq as optional or provides a dependency-free fallback
- #4 Blueprint docs correctly describe bundled, selected-directory, custom paste/upload, and git-source paths without telling users to copy into an ignored BLUEPRINT_DATA_DIR root
- #5 Control docs explain loaded, enabled, emitting, staged, pending, and active states and expose status, inventory, health, diagnostics, and pending entrypoints
- #6 Blueprint and scenario array endpoints are documented as full replacements, not additive mutations
- #7 Landing copy states the first Grafana-visible outcome before protocol/architecture detail
Definition of Done
- #1 make gate (build vet test race rw-proto-check spdx-check forbidden-words)
- #2 make blueprint-schema (only if a blueprint field or construct/workload config struct changed)
- #3 DRY_RUN=true go run ./cmd/synthkit -once -dump — inventory diffed against signals/
Implementation Plan
-
Reconcile landing, Quick Start, blueprint, and control-plane copy against the now-landed selector and mutation contracts.
-
Rewrite the beginner path around first Grafana-visible value, synthetic workload mental model, exact state vocabulary, safe authenticated examples, and dependency-free fallbacks.
-
Validate navigation/links and exercise all copy-paste examples that do not require live credentials.
Implementation Notes
Reworked README and beginner docs around first Grafana-visible value, correct port/auth/qualified scaling examples, the distinction between synthetic workload models and real app deployment, jq-free checks, accurate blueprint source paths, and explicit loaded/enabled/emitting/staged/pending/active state vocabulary. Documented full-replacement arrays and atomic item endpoints. make docs-check, diff checks, Bash/Zsh auth setup with token set/unset, and stale-claim searches passed. Live control-plane requests and Grafana queries remain root forward-test skips because no configured live instance is in scope.
Root integration: CodeRabbit reviews 7 and 8 completed; curl failure handling, registered feature/integration kinds, selected-file strict decode, native OTLP contract, Compose env semantics, and documentation link/reference validation were reconciled. make docs-check, make gate, and default/focused dry runs passed. No schema regeneration was applicable.
Final Summary
Corrected the beginner journey and control-plane documentation in 265ecd9 (pushed via dab60de): accurate port/auth/scaling examples, synthetic-workload mental model, source lifecycle/state vocabulary, replacement semantics, first Grafana-visible outcome, and stronger navigation/link validation. Live control-plane and Grafana queries remain unverified without a configured live instance.