docs: split README into showcase + user/setup guide by jonocodes · Pull Request #148 · jonocodes/deckd

jonocodes · 2026-08-14T02:41:00Z

Why

The README had grown to ~1330 lines — mostly setup, per-platform install, configuration reference, and per-feature deep-dives (Now Playing alone was ~270 lines). That buried the showcase. This splits it so the README is a ~180-line showcase and everything technical lives in one guide.

What changed

README.md — trimmed to showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). Keeps the ASCII architecture diagram as the hero. In-page links to moved sections now point into docs/GUIDE.md.
docs/GUIDE.md(new) — install/run, macOS + KDE Plasma Wayland + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features (manual control, editor, tuning, a11y), uinput/focus watcher, dev UX, production, full configuration reference, and the media surfaces (VLC, Now Playing, running programs). Relative file links fixed for the docs/ location (packaging/ → ../packaging/).
Dedup — the guide's CLI and Under the hood sections collapse to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources instead of restating them.
Reverse links — REFERENCE.md, ARCHITECTURE.md, and ONBOARDING.md now list GUIDE.md and describe the README as showcase-only.

Verification

Every cross-doc file link and #anchor verified to resolve.
README 1331 → 177 lines; docs/GUIDE.md 1181 lines.

🤖 Generated with Claude Code

Follow-up to b38e575, closing the gaps a two-axis review found against the issue's acceptance criteria. The swatch lied about non-hex colours. `<input type="color">` coerces anything it can't parse to #000000, so a `rebeccapurple` widget rendered a black swatch beside a purple canvas cell — and left an accidental confirm one click from clobbering the authored CSS string. Values the picker can't hold (named colours, `hsl(...)`, `#RRGGBBAA`) now show as a read-only preview of the real colour, with the text input as the escape hatch the any-CSS-string schema needs. `#RGB` shorthand expands rather than falling into that bucket, since the picker can represent it losslessly; an unset widget still gets the picker, which is the main way into it. A hand-authored `color:` on a non-button kind was stranded: ADR-0006 keeps the field button-only, but EditorCanvas still paints it, so the value was invisible to the panel and unclearable. The field now also appears on any kind that already carries a colour. AC4 (save round-trips the colour unchanged) had no test. Adds write-path coverage over hex, named and `hsl(...)` values — the hex case also pins that the writer quotes a leading `#` rather than emitting a YAML comment — plus the clear-to-unset case. Also: give the text input an accessible name (it had none, which is why the tests had reached for CSS-class selectors), drop a pass-through callback, rename `parseHexColor` to `toSwatchHex` since it formats rather than parses, fold the duplicated focus rule into the file's `:focus-visible` convention, and document the picker in the README. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The README had grown to ~1330 lines, mostly setup, per-platform install, configuration reference, and per-feature deep-dives. Move all of that into a new docs/GUIDE.md so the README is a ~180-line showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). - README.md: trimmed to showcase; keeps the ASCII architecture diagram as the hero; in-page links to moved sections now point into docs/GUIDE.md. - docs/GUIDE.md: new — install/run, macOS + KDE + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features, uinput/focus watcher, dev UX, production, full configuration reference, media surfaces. Relative file links fixed for the docs/ location (packaging/ -> ../packaging/). - Dedup: GUIDE's CLI and "Under the hood" sections collapsed to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources. - Reverse links: REFERENCE.md, ARCHITECTURE.md, ONBOARDING.md now list GUIDE.md and describe the README as showcase-only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

jonocodes · 2026-08-14T02:41:00Z

Why

The README had grown to ~1330 lines — mostly setup, per-platform install, configuration reference, and per-feature deep-dives (Now Playing alone was ~270 lines). That buried the showcase. This splits it so the README is a ~180-line showcase and everything technical lives in one guide.

What changed

README.md — trimmed to showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). Keeps the ASCII architecture diagram as the hero. In-page links to moved sections now point into docs/GUIDE.md.
docs/GUIDE.md(new) — install/run, macOS + KDE Plasma Wayland + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features (manual control, editor, tuning, a11y), uinput/focus watcher, dev UX, production, full configuration reference, and the media surfaces (VLC, Now Playing, running programs). Relative file links fixed for the docs/ location (packaging/ → ../packaging/).
Dedup — the guide's CLI and Under the hood sections collapse to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources instead of restating them.
Reverse links — REFERENCE.md, ARCHITECTURE.md, and ONBOARDING.md now list GUIDE.md and describe the README as showcase-only.

Verification

Every cross-doc file link and #anchor verified to resolve.
README 1331 → 177 lines; docs/GUIDE.md 1181 lines.

🤖 Generated with Claude Code

Follow-up to b38e575, closing the gaps a two-axis review found against the issue's acceptance criteria. The swatch lied about non-hex colours. `<input type="color">` coerces anything it can't parse to #000000, so a `rebeccapurple` widget rendered a black swatch beside a purple canvas cell — and left an accidental confirm one click from clobbering the authored CSS string. Values the picker can't hold (named colours, `hsl(...)`, `#RRGGBBAA`) now show as a read-only preview of the real colour, with the text input as the escape hatch the any-CSS-string schema needs. `#RGB` shorthand expands rather than falling into that bucket, since the picker can represent it losslessly; an unset widget still gets the picker, which is the main way into it. A hand-authored `color:` on a non-button kind was stranded: ADR-0006 keeps the field button-only, but EditorCanvas still paints it, so the value was invisible to the panel and unclearable. The field now also appears on any kind that already carries a colour. AC4 (save round-trips the colour unchanged) had no test. Adds write-path coverage over hex, named and `hsl(...)` values — the hex case also pins that the writer quotes a leading `#` rather than emitting a YAML comment — plus the clear-to-unset case. Also: give the text input an accessible name (it had none, which is why the tests had reached for CSS-class selectors), drop a pass-through callback, rename `parseHexColor` to `toSwatchHex` since it formats rather than parses, fold the duplicated focus rule into the file's `:focus-visible` convention, and document the picker in the README. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The README had grown to ~1330 lines, mostly setup, per-platform install, configuration reference, and per-feature deep-dives. Move all of that into a new docs/GUIDE.md so the README is a ~180-line showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). - README.md: trimmed to showcase; keeps the ASCII architecture diagram as the hero; in-page links to moved sections now point into docs/GUIDE.md. - docs/GUIDE.md: new — install/run, macOS + KDE + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features, uinput/focus watcher, dev UX, production, full configuration reference, media surfaces. Relative file links fixed for the docs/ location (packaging/ -> ../packaging/). - Dedup: GUIDE's CLI and "Under the hood" sections collapsed to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources. - Reverse links: REFERENCE.md, ARCHITECTURE.md, ONBOARDING.md now list GUIDE.md and describe the README as showcase-only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

jonocodes · 2026-08-14T02:41:00Z

Why

The README had grown to ~1330 lines — mostly setup, per-platform install, configuration reference, and per-feature deep-dives (Now Playing alone was ~270 lines). That buried the showcase. This splits it so the README is a ~180-line showcase and everything technical lives in one guide.

What changed

README.md — trimmed to showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). Keeps the ASCII architecture diagram as the hero. In-page links to moved sections now point into docs/GUIDE.md.
docs/GUIDE.md(new) — install/run, macOS + KDE Plasma Wayland + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features (manual control, editor, tuning, a11y), uinput/focus watcher, dev UX, production, full configuration reference, and the media surfaces (VLC, Now Playing, running programs). Relative file links fixed for the docs/ location (packaging/ → ../packaging/).
Dedup — the guide's CLI and Under the hood sections collapse to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources instead of restating them.
Reverse links — REFERENCE.md, ARCHITECTURE.md, and ONBOARDING.md now list GUIDE.md and describe the README as showcase-only.

Verification

Every cross-doc file link and #anchor verified to resolve.
README 1331 → 177 lines; docs/GUIDE.md 1181 lines.

🤖 Generated with Claude Code

Follow-up to b38e575, closing the gaps a two-axis review found against the issue's acceptance criteria. The swatch lied about non-hex colours. `<input type="color">` coerces anything it can't parse to #000000, so a `rebeccapurple` widget rendered a black swatch beside a purple canvas cell — and left an accidental confirm one click from clobbering the authored CSS string. Values the picker can't hold (named colours, `hsl(...)`, `#RRGGBBAA`) now show as a read-only preview of the real colour, with the text input as the escape hatch the any-CSS-string schema needs. `#RGB` shorthand expands rather than falling into that bucket, since the picker can represent it losslessly; an unset widget still gets the picker, which is the main way into it. A hand-authored `color:` on a non-button kind was stranded: ADR-0006 keeps the field button-only, but EditorCanvas still paints it, so the value was invisible to the panel and unclearable. The field now also appears on any kind that already carries a colour. AC4 (save round-trips the colour unchanged) had no test. Adds write-path coverage over hex, named and `hsl(...)` values — the hex case also pins that the writer quotes a leading `#` rather than emitting a YAML comment — plus the clear-to-unset case. Also: give the text input an accessible name (it had none, which is why the tests had reached for CSS-class selectors), drop a pass-through callback, rename `parseHexColor` to `toSwatchHex` since it formats rather than parses, fold the duplicated focus rule into the file's `:focus-visible` convention, and document the picker in the README. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The README had grown to ~1330 lines, mostly setup, per-platform install, configuration reference, and per-feature deep-dives. Move all of that into a new docs/GUIDE.md so the README is a ~180-line showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). - README.md: trimmed to showcase; keeps the ASCII architecture diagram as the hero; in-page links to moved sections now point into docs/GUIDE.md. - docs/GUIDE.md: new — install/run, macOS + KDE + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features, uinput/focus watcher, dev UX, production, full configuration reference, media surfaces. Relative file links fixed for the docs/ location (packaging/ -> ../packaging/). - Dedup: GUIDE's CLI and "Under the hood" sections collapsed to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources. - Reverse links: REFERENCE.md, ARCHITECTURE.md, ONBOARDING.md now list GUIDE.md and describe the README as showcase-only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

jonocodes · 2026-08-14T02:41:00Z

Why

The README had grown to ~1330 lines — mostly setup, per-platform install, configuration reference, and per-feature deep-dives (Now Playing alone was ~270 lines). That buried the showcase. This splits it so the README is a ~180-line showcase and everything technical lives in one guide.

What changed

README.md — trimmed to showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). Keeps the ASCII architecture diagram as the hero. In-page links to moved sections now point into docs/GUIDE.md.
docs/GUIDE.md(new) — install/run, macOS + KDE Plasma Wayland + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features (manual control, editor, tuning, a11y), uinput/focus watcher, dev UX, production, full configuration reference, and the media surfaces (VLC, Now Playing, running programs). Relative file links fixed for the docs/ location (packaging/ → ../packaging/).
Dedup — the guide's CLI and Under the hood sections collapse to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources instead of restating them.
Reverse links — REFERENCE.md, ARCHITECTURE.md, and ONBOARDING.md now list GUIDE.md and describe the README as showcase-only.

Verification

Every cross-doc file link and #anchor verified to resolve.
README 1331 → 177 lines; docs/GUIDE.md 1181 lines.

🤖 Generated with Claude Code

Follow-up to b38e575, closing the gaps a two-axis review found against the issue's acceptance criteria. The swatch lied about non-hex colours. `<input type="color">` coerces anything it can't parse to #000000, so a `rebeccapurple` widget rendered a black swatch beside a purple canvas cell — and left an accidental confirm one click from clobbering the authored CSS string. Values the picker can't hold (named colours, `hsl(...)`, `#RRGGBBAA`) now show as a read-only preview of the real colour, with the text input as the escape hatch the any-CSS-string schema needs. `#RGB` shorthand expands rather than falling into that bucket, since the picker can represent it losslessly; an unset widget still gets the picker, which is the main way into it. A hand-authored `color:` on a non-button kind was stranded: ADR-0006 keeps the field button-only, but EditorCanvas still paints it, so the value was invisible to the panel and unclearable. The field now also appears on any kind that already carries a colour. AC4 (save round-trips the colour unchanged) had no test. Adds write-path coverage over hex, named and `hsl(...)` values — the hex case also pins that the writer quotes a leading `#` rather than emitting a YAML comment — plus the clear-to-unset case. Also: give the text input an accessible name (it had none, which is why the tests had reached for CSS-class selectors), drop a pass-through callback, rename `parseHexColor` to `toSwatchHex` since it formats rather than parses, fold the duplicated focus rule into the file's `:focus-visible` convention, and document the picker in the README. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The README had grown to ~1330 lines, mostly setup, per-platform install, configuration reference, and per-feature deep-dives. Move all of that into a new docs/GUIDE.md so the README is a ~180-line showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). - README.md: trimmed to showcase; keeps the ASCII architecture diagram as the hero; in-page links to moved sections now point into docs/GUIDE.md. - docs/GUIDE.md: new — install/run, macOS + KDE + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features, uinput/focus watcher, dev UX, production, full configuration reference, media surfaces. Relative file links fixed for the docs/ location (packaging/ -> ../packaging/). - Dedup: GUIDE's CLI and "Under the hood" sections collapsed to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources. - Reverse links: REFERENCE.md, ARCHITECTURE.md, ONBOARDING.md now list GUIDE.md and describe the README as showcase-only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

jonocodes · 2026-08-14T02:41:00Z

Why

The README had grown to ~1330 lines — mostly setup, per-platform install, configuration reference, and per-feature deep-dives (Now Playing alone was ~270 lines). That buried the showcase. This splits it so the README is a ~180-line showcase and everything technical lives in one guide.

What changed

README.md — trimmed to showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). Keeps the ASCII architecture diagram as the hero. In-page links to moved sections now point into docs/GUIDE.md.
docs/GUIDE.md(new) — install/run, macOS + KDE Plasma Wayland + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features (manual control, editor, tuning, a11y), uinput/focus watcher, dev UX, production, full configuration reference, and the media surfaces (VLC, Now Playing, running programs). Relative file links fixed for the docs/ location (packaging/ → ../packaging/).
Dedup — the guide's CLI and Under the hood sections collapse to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources instead of restating them.
Reverse links — REFERENCE.md, ARCHITECTURE.md, and ONBOARDING.md now list GUIDE.md and describe the README as showcase-only.

Verification

Every cross-doc file link and #anchor verified to resolve.
README 1331 → 177 lines; docs/GUIDE.md 1181 lines.

🤖 Generated with Claude Code

Follow-up to b38e575, closing the gaps a two-axis review found against the issue's acceptance criteria. The swatch lied about non-hex colours. `<input type="color">` coerces anything it can't parse to #000000, so a `rebeccapurple` widget rendered a black swatch beside a purple canvas cell — and left an accidental confirm one click from clobbering the authored CSS string. Values the picker can't hold (named colours, `hsl(...)`, `#RRGGBBAA`) now show as a read-only preview of the real colour, with the text input as the escape hatch the any-CSS-string schema needs. `#RGB` shorthand expands rather than falling into that bucket, since the picker can represent it losslessly; an unset widget still gets the picker, which is the main way into it. A hand-authored `color:` on a non-button kind was stranded: ADR-0006 keeps the field button-only, but EditorCanvas still paints it, so the value was invisible to the panel and unclearable. The field now also appears on any kind that already carries a colour. AC4 (save round-trips the colour unchanged) had no test. Adds write-path coverage over hex, named and `hsl(...)` values — the hex case also pins that the writer quotes a leading `#` rather than emitting a YAML comment — plus the clear-to-unset case. Also: give the text input an accessible name (it had none, which is why the tests had reached for CSS-class selectors), drop a pass-through callback, rename `parseHexColor` to `toSwatchHex` since it formats rather than parses, fold the duplicated focus rule into the file's `:focus-visible` convention, and document the picker in the README. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The README had grown to ~1330 lines, mostly setup, per-platform install, configuration reference, and per-feature deep-dives. Move all of that into a new docs/GUIDE.md so the README is a ~180-line showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). - README.md: trimmed to showcase; keeps the ASCII architecture diagram as the hero; in-page links to moved sections now point into docs/GUIDE.md. - docs/GUIDE.md: new — install/run, macOS + KDE + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features, uinput/focus watcher, dev UX, production, full configuration reference, media surfaces. Relative file links fixed for the docs/ location (packaging/ -> ../packaging/). - Dedup: GUIDE's CLI and "Under the hood" sections collapsed to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources. - Reverse links: REFERENCE.md, ARCHITECTURE.md, ONBOARDING.md now list GUIDE.md and describe the README as showcase-only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

jonocodes · 2026-08-14T02:41:00Z

Why

The README had grown to ~1330 lines — mostly setup, per-platform install, configuration reference, and per-feature deep-dives (Now Playing alone was ~270 lines). That buried the showcase. This splits it so the README is a ~180-line showcase and everything technical lives in one guide.

What changed

README.md — trimmed to showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). Keeps the ASCII architecture diagram as the hero. In-page links to moved sections now point into docs/GUIDE.md.
docs/GUIDE.md(new) — install/run, macOS + KDE Plasma Wayland + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features (manual control, editor, tuning, a11y), uinput/focus watcher, dev UX, production, full configuration reference, and the media surfaces (VLC, Now Playing, running programs). Relative file links fixed for the docs/ location (packaging/ → ../packaging/).
Dedup — the guide's CLI and Under the hood sections collapse to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources instead of restating them.
Reverse links — REFERENCE.md, ARCHITECTURE.md, and ONBOARDING.md now list GUIDE.md and describe the README as showcase-only.

Verification

Every cross-doc file link and #anchor verified to resolve.
README 1331 → 177 lines; docs/GUIDE.md 1181 lines.

🤖 Generated with Claude Code

Follow-up to b38e575, closing the gaps a two-axis review found against the issue's acceptance criteria. The swatch lied about non-hex colours. `<input type="color">` coerces anything it can't parse to #000000, so a `rebeccapurple` widget rendered a black swatch beside a purple canvas cell — and left an accidental confirm one click from clobbering the authored CSS string. Values the picker can't hold (named colours, `hsl(...)`, `#RRGGBBAA`) now show as a read-only preview of the real colour, with the text input as the escape hatch the any-CSS-string schema needs. `#RGB` shorthand expands rather than falling into that bucket, since the picker can represent it losslessly; an unset widget still gets the picker, which is the main way into it. A hand-authored `color:` on a non-button kind was stranded: ADR-0006 keeps the field button-only, but EditorCanvas still paints it, so the value was invisible to the panel and unclearable. The field now also appears on any kind that already carries a colour. AC4 (save round-trips the colour unchanged) had no test. Adds write-path coverage over hex, named and `hsl(...)` values — the hex case also pins that the writer quotes a leading `#` rather than emitting a YAML comment — plus the clear-to-unset case. Also: give the text input an accessible name (it had none, which is why the tests had reached for CSS-class selectors), drop a pass-through callback, rename `parseHexColor` to `toSwatchHex` since it formats rather than parses, fold the duplicated focus rule into the file's `:focus-visible` convention, and document the picker in the README. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The README had grown to ~1330 lines, mostly setup, per-platform install, configuration reference, and per-feature deep-dives. Move all of that into a new docs/GUIDE.md so the README is a ~180-line showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). - README.md: trimmed to showcase; keeps the ASCII architecture diagram as the hero; in-page links to moved sections now point into docs/GUIDE.md. - docs/GUIDE.md: new — install/run, macOS + KDE + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features, uinput/focus watcher, dev UX, production, full configuration reference, media surfaces. Relative file links fixed for the docs/ location (packaging/ -> ../packaging/). - Dedup: GUIDE's CLI and "Under the hood" sections collapsed to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources. - Reverse links: REFERENCE.md, ARCHITECTURE.md, ONBOARDING.md now list GUIDE.md and describe the README as showcase-only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

jonocodes · 2026-08-14T02:41:00Z

Why

The README had grown to ~1330 lines — mostly setup, per-platform install, configuration reference, and per-feature deep-dives (Now Playing alone was ~270 lines). That buried the showcase. This splits it so the README is a ~180-line showcase and everything technical lives in one guide.

What changed

README.md — trimmed to showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). Keeps the ASCII architecture diagram as the hero. In-page links to moved sections now point into docs/GUIDE.md.
docs/GUIDE.md(new) — install/run, macOS + KDE Plasma Wayland + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features (manual control, editor, tuning, a11y), uinput/focus watcher, dev UX, production, full configuration reference, and the media surfaces (VLC, Now Playing, running programs). Relative file links fixed for the docs/ location (packaging/ → ../packaging/).
Dedup — the guide's CLI and Under the hood sections collapse to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources instead of restating them.
Reverse links — REFERENCE.md, ARCHITECTURE.md, and ONBOARDING.md now list GUIDE.md and describe the README as showcase-only.

Verification

Every cross-doc file link and #anchor verified to resolve.
README 1331 → 177 lines; docs/GUIDE.md 1181 lines.

🤖 Generated with Claude Code

Follow-up to b38e575, closing the gaps a two-axis review found against the issue's acceptance criteria. The swatch lied about non-hex colours. `<input type="color">` coerces anything it can't parse to #000000, so a `rebeccapurple` widget rendered a black swatch beside a purple canvas cell — and left an accidental confirm one click from clobbering the authored CSS string. Values the picker can't hold (named colours, `hsl(...)`, `#RRGGBBAA`) now show as a read-only preview of the real colour, with the text input as the escape hatch the any-CSS-string schema needs. `#RGB` shorthand expands rather than falling into that bucket, since the picker can represent it losslessly; an unset widget still gets the picker, which is the main way into it. A hand-authored `color:` on a non-button kind was stranded: ADR-0006 keeps the field button-only, but EditorCanvas still paints it, so the value was invisible to the panel and unclearable. The field now also appears on any kind that already carries a colour. AC4 (save round-trips the colour unchanged) had no test. Adds write-path coverage over hex, named and `hsl(...)` values — the hex case also pins that the writer quotes a leading `#` rather than emitting a YAML comment — plus the clear-to-unset case. Also: give the text input an accessible name (it had none, which is why the tests had reached for CSS-class selectors), drop a pass-through callback, rename `parseHexColor` to `toSwatchHex` since it formats rather than parses, fold the duplicated focus rule into the file's `:focus-visible` convention, and document the picker in the README. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The README had grown to ~1330 lines, mostly setup, per-platform install, configuration reference, and per-feature deep-dives. Move all of that into a new docs/GUIDE.md so the README is a ~180-line showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). - README.md: trimmed to showcase; keeps the ASCII architecture diagram as the hero; in-page links to moved sections now point into docs/GUIDE.md. - docs/GUIDE.md: new — install/run, macOS + KDE + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features, uinput/focus watcher, dev UX, production, full configuration reference, media surfaces. Relative file links fixed for the docs/ location (packaging/ -> ../packaging/). - Dedup: GUIDE's CLI and "Under the hood" sections collapsed to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources. - Reverse links: REFERENCE.md, ARCHITECTURE.md, ONBOARDING.md now list GUIDE.md and describe the README as showcase-only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

jonocodes · 2026-08-14T02:41:00Z

Why

The README had grown to ~1330 lines — mostly setup, per-platform install, configuration reference, and per-feature deep-dives (Now Playing alone was ~270 lines). That buried the showcase. This splits it so the README is a ~180-line showcase and everything technical lives in one guide.

What changed

README.md — trimmed to showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). Keeps the ASCII architecture diagram as the hero. In-page links to moved sections now point into docs/GUIDE.md.
docs/GUIDE.md(new) — install/run, macOS + KDE Plasma Wayland + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features (manual control, editor, tuning, a11y), uinput/focus watcher, dev UX, production, full configuration reference, and the media surfaces (VLC, Now Playing, running programs). Relative file links fixed for the docs/ location (packaging/ → ../packaging/).
Dedup — the guide's CLI and Under the hood sections collapse to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources instead of restating them.
Reverse links — REFERENCE.md, ARCHITECTURE.md, and ONBOARDING.md now list GUIDE.md and describe the README as showcase-only.

Verification

Every cross-doc file link and #anchor verified to resolve.
README 1331 → 177 lines; docs/GUIDE.md 1181 lines.

🤖 Generated with Claude Code

Follow-up to b38e575, closing the gaps a two-axis review found against the issue's acceptance criteria. The swatch lied about non-hex colours. `<input type="color">` coerces anything it can't parse to #000000, so a `rebeccapurple` widget rendered a black swatch beside a purple canvas cell — and left an accidental confirm one click from clobbering the authored CSS string. Values the picker can't hold (named colours, `hsl(...)`, `#RRGGBBAA`) now show as a read-only preview of the real colour, with the text input as the escape hatch the any-CSS-string schema needs. `#RGB` shorthand expands rather than falling into that bucket, since the picker can represent it losslessly; an unset widget still gets the picker, which is the main way into it. A hand-authored `color:` on a non-button kind was stranded: ADR-0006 keeps the field button-only, but EditorCanvas still paints it, so the value was invisible to the panel and unclearable. The field now also appears on any kind that already carries a colour. AC4 (save round-trips the colour unchanged) had no test. Adds write-path coverage over hex, named and `hsl(...)` values — the hex case also pins that the writer quotes a leading `#` rather than emitting a YAML comment — plus the clear-to-unset case. Also: give the text input an accessible name (it had none, which is why the tests had reached for CSS-class selectors), drop a pass-through callback, rename `parseHexColor` to `toSwatchHex` since it formats rather than parses, fold the duplicated focus rule into the file's `:focus-visible` convention, and document the picker in the README. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The README had grown to ~1330 lines, mostly setup, per-platform install, configuration reference, and per-feature deep-dives. Move all of that into a new docs/GUIDE.md so the README is a ~180-line showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). - README.md: trimmed to showcase; keeps the ASCII architecture diagram as the hero; in-page links to moved sections now point into docs/GUIDE.md. - docs/GUIDE.md: new — install/run, macOS + KDE + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features, uinput/focus watcher, dev UX, production, full configuration reference, media surfaces. Relative file links fixed for the docs/ location (packaging/ -> ../packaging/). - Dedup: GUIDE's CLI and "Under the hood" sections collapsed to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources. - Reverse links: REFERENCE.md, ARCHITECTURE.md, ONBOARDING.md now list GUIDE.md and describe the README as showcase-only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

jonocodesand others added 2 commits August 13, 2026 09:08

jonocodes merged commit 0b2a664 into mainAug 15, 2026
1 of 2 checks passed

jonocodesand others added 2 commits August 13, 2026 09:08

jonocodes merged commit 0b2a664 into mainAug 15, 2026
1 of 2 checks passed

jonocodesand others added 2 commits August 13, 2026 09:08

jonocodes merged commit 0b2a664 into mainAug 15, 2026
1 of 2 checks passed

jonocodesand others added 2 commits August 13, 2026 09:08

jonocodes merged commit 0b2a664 into mainAug 15, 2026
1 of 2 checks passed

jonocodesand others added 2 commits August 13, 2026 09:08

jonocodes merged commit 0b2a664 into mainAug 15, 2026
1 of 2 checks passed

jonocodesand others added 2 commits August 13, 2026 09:08

jonocodes merged commit 0b2a664 into mainAug 15, 2026
1 of 2 checks passed

jonocodesand others added 2 commits August 13, 2026 09:08

jonocodes merged commit 0b2a664 into mainAug 15, 2026
1 of 2 checks passed

jonocodesand others added 2 commits August 13, 2026 09:08

jonocodes merged commit 0b2a664 into mainAug 15, 2026
1 of 2 checks passed

Conversation

jonocodes commented Aug 14, 2026

Why

What changed

Verification

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

jonocodes commented Aug 14, 2026

Why

What changed

Verification

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

jonocodes commented Aug 14, 2026

Why

What changed

Verification

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

jonocodes commented Aug 14, 2026

Why

What changed

Verification

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

jonocodes commented Aug 14, 2026

Why

What changed

Verification

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

jonocodes commented Aug 14, 2026

Why

What changed

Verification