From 4b1a5fca5752e076ba3d3dd2f58d6c96556d577c Mon Sep 17 00:00:00 2001 From: Alexander Dorn Date: Wed, 6 May 2026 11:41:28 +0200 Subject: [PATCH 01/35] docs(spec/018): scaffold adoption-readiness spec with clarifications Author specs/018-adoption-readiness/spec.md targeting README + onboarding adoption readiness post-spec/017. Four prioritized user stories (P1: 5-min mental simulation; P2: walkthrough credibility; P2: architecture diagram; P3: structural contract for future maintainers). Nineteen functional requirements split across README structure (FR-001..003), onboarding artifacts (FR-004..009a), tone preservation (FR-010..014), Spec Kit deliverables (FR-015..016), and explicit negative requirements (FR-017..019). Twelve+ structural success criteria (grep / wc / file-existence) plus an author self-attested dogfooding pass. Five clarifications integrated in Session 2026-05-06: - Recording sanitization mirrors spec/017 FR-009 (RFC 2606 / RFC 5737, generic prompt, no operator-private values). - Hard cap of 90 seconds on docs/onboarding.cast; narrow scope rather than extend. - Walkthrough plan-output blocks are verbatim from real invocations, `...` elision permitted, no paraphrasing or hand-tuning. - Dogfooding pass via author self-attestation (acknowledged limit traded against feasibility for solo-author project). - Static walkthrough carries plan + idempotent re-run snippet (~25 lines); apply / status are recording-only. Release fragment declares release_intent: patch, scope: docs. Validates as exempt under always_exempt_documentation_or_formatting. Branched from master at v2.2.0 (cfc0914). Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 3 + changes/018-adoption-readiness.md | 7 + specs/018-adoption-readiness/spec.md | 216 +++++++++++++++++++++++++++ 3 files changed, 226 insertions(+) create mode 100644 changes/018-adoption-readiness.md create mode 100644 specs/018-adoption-readiness/spec.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 76ad003..e86ab0d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,9 @@ versioning for public release policy decisions. ## [Unreleased] +### Changed + +- Restructure README around operational comprehension; add Mermaid architecture diagram, 30-second mental model, `examples/03-immich` walkthrough, and `docs/onboarding.cast` asciinema recording. No CLI or behavior changes. ## [2.2.4] - 2026-05-07 diff --git a/changes/018-adoption-readiness.md b/changes/018-adoption-readiness.md new file mode 100644 index 0000000..8f68f58 --- /dev/null +++ b/changes/018-adoption-readiness.md @@ -0,0 +1,7 @@ +--- +change_id: 018-adoption-readiness +release_intent: patch +summary: Restructure README around operational comprehension; add Mermaid architecture diagram, 30-second mental model, `examples/03-immich` walkthrough, and `docs/onboarding.cast` asciinema recording. No CLI or behavior changes. +scope: docs +release_preparation: false +--- diff --git a/specs/018-adoption-readiness/spec.md b/specs/018-adoption-readiness/spec.md new file mode 100644 index 0000000..cc1ecf1 --- /dev/null +++ b/specs/018-adoption-readiness/spec.md @@ -0,0 +1,216 @@ +# Feature Specification: Adoption Readiness — README and Onboarding Experience + +**Feature Branch**: `018-adoption-readiness` +**Created**: 2026-05-06 +**Status**: Draft +**Input**: User description: "Increase adoption likelihood and onboarding experience by restructuring the README around operational comprehension, adding a 30-second mental model, an architecture diagram, an experiential walkthrough using `examples/03-immich`, an asciinema-based onboarding artifact, and elevated real-world examples — without changing CLI surface, behavior, or tone." + +## Summary + +After spec/017 landed in v2.2.0, the repository ships a stateless `--source-repo ` CLI surface and five real-world `examples//` directories. This feature spec turns those substrates into above-the-fold onboarding by restructuring the README around **operational comprehension** rather than philosophy-first exposition. + +This is a **documentation-only** change. No CLI surface, no behavior, no schema, no tests change. Release intent is `patch` per the bump rules (no `src/` modifications). + +## Clarifications + +### Session 2026-05-06 + +- Q: Should the asciinema recording sanitize operator-private values (hostname, paths, domains, IPs)? → A: Yes — mirror spec/017 FR-009 — RFC 2606 reserved domains, RFC 5737 documentation IPs, generic prompt (e.g., `op@example`), project-relative paths, no real credentials or operator-private hostnames. +- Q: Is there a duration cap on the asciinema recording? → A: Hard cap ≤ 90 seconds. If unattainable, narrow demo scope (skip status, skip re-run, drop a service) rather than extend. +- Q: How faithful must the README walkthrough's plan-output block be to actual `core-ops plan` output? → A: Verbatim from a real run, with `...` elision permitted for repeats or uninteresting lines. No paraphrasing, no hand-tuning. Every non-elided line MUST appear byte-for-byte in actual output. +- Q: Who performs the dogfooding pass referenced by SC-011? → A: Author self-attestation only. The author re-reads the rendered README cold (no separate operator), captures takeaways verbatim in `synthesis.md`, and assesses pass/fail against US1's expectations. Self-knowledge of the changes is an acknowledged limit traded against feasibility. +- Q: What beats does the static walkthrough code block cover? → A: Plan output + a short idempotent re-run snippet showing the "no changes" line. Apply and status are carried only by the recording. Approximate budget: ~25 lines. + +## Scope distinction + +The proposal that triggered this spec asked, among other things, that the iteration "increase adoption likelihood." Adoption likelihood is unmeasurable inside this slice — there is no analytics, no funnel, no clone metric this spec can move. The spec therefore replaces "did adoption increase" with **structural** acceptance criteria (artifact existence, README ordering, line budget, stop-list absence) plus a single **dogfooding pass** (one operator unfamiliar with the changes describes the Git→host flow within 5 minutes). "Adoption" is the long-horizon hypothesis; "structural improvement" is what 018 commits to. + +## User Scenarios & Testing *(mandatory)* + +### User Story 1 - First-time visitor mentally simulates a CoreOps workflow within 5 minutes (Priority: P1) + +A technically experienced operator opens the GitHub README cold. Within roughly five minutes of reading, they can answer four questions without leaving the page: + +1. *What is CoreOps?* (operating model — host-native, systemd/Quadlet, declarative reconciliation, Git-driven) +2. *What does using it feel like?* (a representative `core-ops plan` invocation and its output) +3. *Is it serious enough to evaluate?* (CI green, recent release, license clear) +4. *How does Git become host state?* (one diagram, one mental model) + +**Why this priority**: This is the first-impression surface. Every other onboarding artifact is downstream of whether the operator continues past the README. If they bounce in 30 seconds because the page leads with philosophy, no walkthrough or example matters. + +**Independent Test**: The author opens the rendered page on GitHub after restructure. Time-box: 5 minutes for the read. The author then writes down — verbatim, without re-consulting the README — what they took away in answer to "What does CoreOps do and what does running it look like?" The captured answer must reference (a) host-native systemd/Quadlet convergence, (b) the Git → core-ops → systemd flow, (c) at least one CLI command they saw, and (d) a sense of project credibility (badges, version, release cadence). Pass/fail recorded in `synthesis.md`. Self-knowledge of the changes is an acknowledged limit (Clarification 2026-05-06 Q4); the test is still useful as a forcing function for "did the README actually surface these signals on a cold read." + +**Acceptance Scenarios**: + +1. **Given** the rendered README, **When** the reader scrolls from top, **Then** the first non-title content they encounter is a row of trust badges (CI, E2E Gate, Latest Release, License), followed by a `## 30-second mental model` heading within the first 120 lines. +2. **Given** the rendered README, **When** the reader continues scrolling, **Then** they encounter an architecture diagram (rendered Mermaid block on GitHub) and a walkthrough section showing representative `core-ops plan` output, both before any installation instructions. +3. **Given** the rendered README, **When** the reader reaches the bottom, **Then** they have not encountered any of: hype-flagged terms (per FR-014 stop-list), third-party JS embeds, or marketing-style feature comparison matrices. + +--- + +### User Story 2 - Operator sees what `core-ops plan` actually does before installing anything (Priority: P2) + +An operator considering CoreOps wants concrete evidence that the tool produces deterministic, inspectable output before they download a binary or write a single config file. They scroll to a "What using CoreOps feels like" section and see (a) a static text block of representative plan output for a real example, and (b) a link to a recorded asciinema session of the same workflow end-to-end. + +**Why this priority**: Static walkthroughs and live recordings are independent trust signals — the static block proves "the output is shaped like this," the asciinema proves "a real session runs in this time, with this cadence, on this kind of host." P2 because P1 (mental model) gates whether the operator reads this section at all; without P1, P2 is invisible. + +**Independent Test**: A reviewer reads the walkthrough section. They can (a) name two services that appear in the static plan output, (b) follow the link to `docs/onboarding.cast` and play it back locally with `asciinema play`, (c) describe what idempotent re-run behavior looks like from the recording (re-running yields the same plan; no host mutation when state already matches). + +**Acceptance Scenarios**: + +1. **Given** the README walkthrough section, **When** the reader inspects the static plan output block, **Then** the block is a fenced code block of representative `core-ops plan --source-repo examples/03-immich --host immich` output containing recognizable units (e.g., `immich-server.container`, `immich-internal.network`). +2. **Given** the README walkthrough section, **When** the reader clicks the recording link, **Then** they reach `docs/onboarding.cast` (in-tree, valid asciicast v2 format). +3. **Given** the in-tree recording, **When** the reader runs `asciinema play docs/onboarding.cast` locally, **Then** the cast plays back end-to-end and exercises the `examples/03-immich` walkthrough including at least one idempotent re-run demonstrating no host mutation when state already matches. + +--- + +### User Story 3 - Operator visualizes Git → host convergence without reading source code (Priority: P2) + +An operator wants to understand how a Git repository becomes host state on a single page. They find a Mermaid block in the README that names: the Git source, `core-ops`, generated systemd/Quadlet units, the host, and the audit/status side outputs. + +**Why this priority**: Architecture diagrams are the highest-bandwidth onboarding artifact when an operator's question is "where does my repository fit in this system?" Equal priority to US2 because the diagram and the walkthrough together answer the "what is this and what does it do" question; either alone leaves a gap. + +**Independent Test**: A reviewer who has never used CoreOps reads the diagram. They can (a) name the four primary nodes (Git, core-ops, systemd/Quadlet, host), (b) identify audit/status as side outputs (dashed/secondary edges), (c) describe the data flow direction (Git → core-ops → host). + +**Acceptance Scenarios**: + +1. **Given** the rendered README on GitHub, **When** the reader views the Architecture section, **Then** a Mermaid diagram renders inline with at least four nodes including the substrings `Git`, `core-ops`, `systemd`. +2. **Given** the same diagram, **When** the reader follows directional edges, **Then** the primary flow is unambiguous (left-to-right or top-to-bottom) and audit/status side outputs are visually distinguished (e.g., dashed edges or secondary nodes). +3. **Given** a non-GitHub render context (raw markdown, a mirror without Mermaid support), **When** the diagram fails to render, **Then** the surrounding README prose names the same four nodes and the flow direction explicitly so the architecture is recoverable from text alone. + +--- + +### User Story 4 - Future maintainer preserves the operational-first ordering across edits (Priority: P3) + +A future contributor adds a new section to the README (e.g., a new badge, a new credibility signal, a configuration recipe). They consult `specs/018-adoption-readiness/checklists/readme-structure.md` and the spec's structural FRs. Their edit preserves the section ordering, badge row composition, and stop-list discipline. + +**Why this priority**: Documentation drifts. Without an explicit structural contract, the next contributor adds a "Features" matrix back at the top, or sneaks "production-grade" into a section header, and the spec/018 work is undone within three months. P3 because the maintenance load is real but the immediate user is hypothetical. + +**Independent Test**: A future contributor edits the README to add a section. The pre-merge checklist at `specs/018-adoption-readiness/checklists/readme-structure.md` catches any deviation from §FR-001 ordering, the §FR-002 badge row, or the §FR-014 stop-list. + +**Acceptance Scenarios**: + +1. **Given** the structural checklist, **When** a contributor proposes a README edit, **Then** the checklist names every constraint (ordering, badge row, line budget, stop-list, no third-party JS embeds) in a runnable form (`grep`, `wc`, heading inspection). + +--- + +### Edge Cases + +- **Mermaid renders inconsistently outside GitHub** (RSS, mirrors, terminal viewers like `glow`). → Mitigated by US3-AC-3: the surrounding prose names the same four nodes textually, so the architecture is recoverable from text alone. +- **The asciinema recording drifts from CLI output as `core-ops` evolves**. → Accepted bounded risk: a reviewer responsibility, not a CI gate. The `docs/onboarding-script.sh` regeneration entry point exists so re-recording is a one-command operation when output drifts. +- **README walkthrough block diverges from `examples/03-immich` plan output as the example evolves**. → Mitigated by FR-008: the walkthrough block is regenerated from a real `core-ops plan` invocation against `examples/03-immich` at authoring time, and Phase 5 of the implementation re-validates by re-running. +- **GPU device passthrough in `examples/03-immich` cannot be exercised on the recording host**. → The recording script substitutes a placeholder device path or runs on a host with the correct device shape; documented in the script header. +- **Operator reads the README on a network that blocks asciinema.org embeds** (corporate firewall, RSS, terminal viewer). → FR-013 forbids third-party JS embeds entirely; the recording is served from the in-tree `.cast` file with a static text fallback in the README. +- **CHANGELOG.md or release notes drift between the README's badge claim and the actual published release**. → No new failure mode introduced by 018; the existing release governance owns CHANGELOG/version/tag consistency. +- **A future contributor adds a hype-flagged term** (e.g., "production-grade"). → Caught by FR-014 stop-list grep documented in `checklists/readme-structure.md`. + +## Requirements *(mandatory)* + +### Functional Requirements + +#### README structure and ordering + +- **FR-001**: The root `README.md` MUST follow this section ordering, top-to-bottom: + 1. Title block (logo + tagline) — preserved from current README lines 1–10. + 2. Badge row (CI, E2E Gate, Latest Release, License) — single line, no heading, immediately after title block. + 3. `## 30-second mental model` — concise operational framing, ≤ 200 words, covering host-native convergence, systemd/Quadlet centricity, declarative reconciliation, and Git-driven operation. + 4. `## Architecture` — Mermaid block depicting Git → core-ops → systemd/Quadlet → host with audit/status as side outputs, plus surrounding prose recoverable when Mermaid fails to render (per US3-AC-3). + 5. `## What using CoreOps feels like` — walkthrough using `examples/03-immich` and the post-017 `--source-repo` flag; embeds a static plan-output code block plus a link to `docs/onboarding.cast`. + 6. `## Real-world examples` — five-entry list/links pointing to `examples//README.md`. + 7. `## Quick start` — folds current "Installation (Current Phase)" + "First Interaction". + 8. `## Why CoreOps exists` — compressed to ≤ 15 lines. + 9. `## What CoreOps is not` — compressed to ≤ 12 lines. + 10. `## Trust and release model` — folds the existing Credibility *table* (artifacts, verification env), Minimal Trust Story, and Release & Verification Model into one section. + 11. `## AI authorship` — compressed to ≤ 12 lines. + 12. `## Target audience · License · Further reading` — final reference block. +- **FR-002**: The badge row MUST contain exactly four badges in this order: CI, E2E Gate, Latest Release, License. No other badges may be promoted to the top row in this slice. +- **FR-003**: The README MUST be ≤ 400 lines after restructure. + +#### Onboarding artifacts + +- **FR-004**: The README MUST contain a Mermaid fenced code block depicting the architecture flow, with at least four nodes including the substrings `Git`, `core-ops`, `systemd`. Audit/status side outputs MUST be visually distinguished from the primary flow (e.g., dashed edges, secondary node shape). +- **FR-005**: The README walkthrough section MUST use `examples/03-immich` as its canonical example and invoke `core-ops plan --source-repo examples/03-immich --host immich` as the canonical command. +- **FR-006**: The README walkthrough section MUST contain **two** fenced code blocks: (1) a plan-output block from the canonical `core-ops plan --source-repo examples/03-immich --host immich` invocation, and (2) a short re-run snippet showing the idempotent "no changes" output (e.g., a second `core-ops plan` invocation immediately after `core-ops apply` produces no actionable diff). Both blocks MUST be derived **verbatim from real invocations**: every non-elided line MUST appear byte-for-byte in actual command output. Paraphrasing and hand-tuning are forbidden. `...` elision lines (a single line containing only the literal `...` and optional surrounding whitespace) are permitted to omit repeated or uninteresting lines for readability. The plan-output block MUST contain at least one recognizable Quadlet unit identifier from `examples/03-immich/services/` (e.g., `immich-server.container`, `immich-internal.network`). The combined budget for both blocks SHOULD be ≤ ~25 lines (excluding fence markers); if the natural plan output exceeds this, elide aggressively rather than expand the budget. Apply and status outputs are carried by the recording (`docs/onboarding.cast`), not by static blocks. +- **FR-007**: The repository MUST publish an asciinema recording at `docs/onboarding.cast` exercising an end-to-end `examples/03-immich` walkthrough including at least one idempotent re-run that demonstrates no host mutation when state already matches. The recording's total duration MUST be ≤ 90 seconds. If 90 seconds is insufficient to cover the intended beats, the demo scope MUST be narrowed (skip the status read, skip the re-run, drop a service from the example, or use a smaller example) — the duration cap MUST NOT be extended. +- **FR-008**: The recording at `docs/onboarding.cast` MUST be a valid asciicast v2 file (JSON header on first line) playable with `asciinema play`. +- **FR-009**: The repository MUST publish a regeneration entry point at `docs/onboarding-script.sh` that is executable, has a shebang, contains the literal string `examples/03-immich`, and documents in its header the deterministic command sequence used to produce `onboarding.cast` and the version of `asciinema` used at recording time. +- **FR-009a**: The asciinema recording at `docs/onboarding.cast` and the regeneration script at `docs/onboarding-script.sh` MUST mirror spec/017 FR-009's sanitization rule: no operator-private values may appear in the captured session or the script. Specifically: + - Any hostname displayed in the shell prompt MUST be a generic placeholder (e.g., `example`, `op`, `host`); the operator's real machine hostname MUST NOT appear. + - Any domain literal MUST use RFC 2606 reserved domains (`*.example.com`, `*.example.org`, `*.test`, `*.invalid`, `*.localhost`). + - Any IP literal MUST use RFC 5737 documentation ranges (`192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`). + - Filesystem paths MUST be project-relative or use generic placeholders (e.g., `/home/op/...`); the operator's real home-directory path or other private paths MUST NOT appear. + - No real credentials, tokens, secrets, or environment-variable values sourced from the operator's private setup MUST appear. + +#### Tone and structure preservation + +- **FR-010**: The README MUST preserve the existing sober, technically serious tone. The Constitution's Principle 1 (clarity, no hype) is the operating reference. +- **FR-011**: Philosophy content (current "Why CoreOps Exists", "What CoreOps Is Not", "AI Authorship", "Target Audience" sections) MUST remain inline in the README. Extraction to `docs/philosophy.md` or similar is **out of scope** for this slice. +- **FR-012**: The existing "Real-World Examples" section landed in v2.2.0 (current README lines 115–138) MUST be preserved in spirit but renamed to `## Real-world examples` and elevated above `## Quick start` per the FR-001 ordering. The five existing one-line example descriptions are preserved unchanged in content; only ordering changes. +- **FR-013**: The README MUST NOT include any third-party JavaScript embed, iframe, or `