Skip to content

docs: README overhaul + DEVELOPERS/EFFECTS/WORKLOG, funding link, wordmark - #4

Merged
fughilli merged 6 commits into
mainfrom
docs/readme-refactor
Aug 9, 2026
Merged

docs: README overhaul + DEVELOPERS/EFFECTS/WORKLOG, funding link, wordmark#4
fughilli merged 6 commits into
mainfrom
docs/readme-refactor

Conversation

@fughilli

@fughilli fughilli commented Jul 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

A documentation-focused pass. The README had grown into a build-state changelog

  • handoff notes; this splits it into a proper first-time-user front page, a
    contributor guide, a standalone effects-engine reference, and a historical build
    log — then adds a funding link and refreshes the splanc.svg wordmark. Ports
    forward and supersedes the stale docs: README overhaul + DEVELOPERS/EFFECTS/WORKLOG, funding link, wordmark #4 (docs README refactor), rebased onto current
    main and fine-tuned.

No code, protocol, or build-logic changes — the only non-doc file is the wordmark
SVG asset.

README → first-time-user intro

  • Rewrote README.md as a concise intro: what splanc does (map LEDs in 3D from a
    phone, then design/play effects on the real geometry), getting started
    (ledmapper.pages.dev), hardware, and how it works.
  • Leads with the splanc.svg wordmark banner and a status-chip row:
    Test (CI) + HITL Actions status, live app, and Built-with-Bazel.
  • Onboarding notes that a brand-new ESP32-C6 dev board can be flashed straight
    from the PWA     over USB (Web Serial / WebUSB).

DEVELOPERS.md (expanded contributor guide)

  • Design & architecture docs section linking the durable spec, every
    docs/design/* note, the docs/ operational notes, and EFFECTS.md.
  • Architecture overview of the two major components — the PWA (web/,
    subsystem by subsystem) and the firmware (firmware/) — plus the shared
    protocol, solver, and Pi path.
  • Build notes refreshed: the ESP32-C6 image builds in-container now with an
    explicit target; documented that it is still tags=["manual"] (excluded from
    //...) and built explicitly by the dedicated CI firmware job. Corrected the
    firmware to ESP32-C6 (RP2350 is a declared Rust triple with no board target
    yet).
  • Hardware-in-the-loop (HITL) testing section: rig architecture, the on-device
    suite, the FX performance benchmark + regression gate, CI wiring, and a
    step-by-step guide to standing up your own rig for private use.

EFFECTS.md (new — effects-engine reference)

A standalone reference for the whole effects stack:

  • The GLSL-ish language (entry points, types, uniforms/state/buffers/textures,
    built-ins, topology sources) with a worked example.
  • The stack-machine VM and execution model, and the full opcode table.
  • The .fxb container format and uniform plumbing (numeric slots +
    out-of-band JSON manifest).
  • Texture / video-texture streaming (formats, delta/RLE codec, on-device
    dequant) and MIDI mapping (a web-layer feature over set_uniform).
  • Measured ESP32-C6 performance with representative frame-cycle numbers and
    the golden/margin regression gate.
  • AI effect generation — how claude-opus-4-8 is prompted (system prompt
    assembled from the language spec, one-shot vs. tool-use chat, self-repair from
    compiler diagnostics).

WORKLOG.md (new)

The old README's dated changelog / directives / TODO, migrated verbatim as
historical record with a current-state handoff entry on top.

Other

  • .github/FUNDING.yml — a Buy Me a Coffee funding link
    (buy_me_a_coffee: fughilli, renders the repo Sponsor button).
  • firmware/landing/README.md, tools/sim_studio/README.md — refreshed the
    claude-container reachability instructions to the current named-service model.
  • web/public/icons/splanc.svg — updated wordmark artwork (the README banner
    references this file, so it picks up the new art automatically).

Testing

prettier and markdownlint (repo-pinned versions) pass on all changed
Markdown, and the full pre-commit suite passes on every commit. Docs-only; no
runtime behavior is affected.

🤖 Generated with Claude Code

@fughilli
fughilli force-pushed the docs/readme-refactor branch from 0e318d4 to 98686ec Compare July 28, 2026 02:08
@fughilli
fughilli force-pushed the docs/readme-refactor branch 3 times, most recently from 38c2c06 to 9f4065a Compare July 28, 2026 18:22
fughilli pushed a commit that referenced this pull request Aug 9, 2026
Claude Agent @claude
docs: refactor README for first-time users; add DEVELOPERS.md + WORKL…
85372c9 
…OG.md

The README had grown into a build-state changelog + handoff notes. Split it
into three docs and give the front page a proper banner + status chips:

- README.md: a concise first-time-user intro — what splanc does (map LEDs in
  3D from a phone, then design/play effects on the real geometry), how it
  works, getting started (ledmapper.pages.dev), and hardware. Now leads with
  the splanc.svg wordmark banner and a standard chip row (CI/HITL Actions
  status, live app, Bazel, controller).
- DEVELOPERS.md (new): contributor guide — prerequisites, build/test, the
  hardware-free pipeline demo, repo layout, CI/pre-commit, container/CI gotchas.
- WORKLOG.md (new): a current-state handoff entry on top, then the old README's
  dated changelog / directives / TODO migrated verbatim as historical record.

Also refreshes the claude-container named-service instructions in
firmware/landing/README.md and tools/sim_studio/README.md. Docs-only;
prettier + markdownlint clean.

Ported forward from PR #4 onto current main.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@fughilli
fughilli force-pushed the docs/readme-refactor branch from d0568e4 to 85372c9 Compare August 9, 2026 16:03
@github-actions

github-actions Bot commented Aug 9, 2026 •
edited
Loading

Copy link
Copy Markdown
PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-08-09 18:59 UTC

fughilli pushed a commit that referenced this pull request Aug 9, 2026
Claude Agent @claude
docs: refactor README for first-time users; add DEVELOPERS.md + WORKL…
e0e7bb9 
…OG.md

The README had grown into a build-state changelog + handoff notes. Split it
into three docs and give the front page a proper banner + status chips:

- README.md: a concise first-time-user intro — what splanc does (map LEDs in
  3D from a phone, then design/play effects on the real geometry), getting
  started (ledmapper.pages.dev), hardware, and how it works. Leads with the
  splanc.svg wordmark banner and a standard chip row (CI/HITL Actions status,
  live app, Bazel). Onboarding notes that a brand-new ESP32-C6 dev board can
  be flashed directly from the PWA over USB (Web Serial / WebUSB).
- DEVELOPERS.md (new): contributor guide — prerequisites, build/test, the
  hardware-free pipeline demo, repo layout, CI/pre-commit, container/CI gotchas.
- WORKLOG.md (new): a current-state handoff entry on top, then the old README's
  dated changelog / directives / TODO migrated verbatim as historical record.

Also refreshes the claude-container named-service instructions in
firmware/landing/README.md and tools/sim_studio/README.md. Docs-only;
prettier + markdownlint clean.

Ported forward from PR #4 onto current main.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@fughilli
fughilli force-pushed the docs/readme-refactor branch from 6b10755 to bd52206 Compare August 9, 2026 17:01
@fughilli fughilli changed the title docs: refactor README for first-time users; add DEVELOPERS.md + WORKL… docs: README overhaul + DEVELOPERS/EFFECTS/WORKLOG, funding link, wordmark Aug 9, 2026
Claude Agent and others added 6 commits August 9, 2026 18:17
Claude Agent @claude
docs: refactor README for first-time users; add DEVELOPERS.md + WORKL…
f66e832 
…OG.md

The README had grown into a build-state changelog + handoff notes. Split it
into three docs and give the front page a proper banner + status chips:

- README.md: a concise first-time-user intro — what splanc does (map LEDs in
  3D from a phone, then design/play effects on the real geometry), how it
  works, getting started (ledmapper.pages.dev), and hardware. Now leads with
  the splanc.svg wordmark banner and a standard chip row (CI/HITL Actions
  status, live app, Bazel, controller).
- DEVELOPERS.md (new): contributor guide — prerequisites, build/test, the
  hardware-free pipeline demo, repo layout, CI/pre-commit, container/CI gotchas.
- WORKLOG.md (new): a current-state handoff entry on top, then the old README's
  dated changelog / directives / TODO migrated verbatim as historical record.

Also refreshes the claude-container named-service instructions in
firmware/landing/README.md and tools/sim_studio/README.md. Docs-only;
prettier + markdownlint clean.

Ported forward from PR #4 onto current main.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude Agent @claude
docs: refactor README for first-time users; add DEVELOPERS.md + WORKL…
fc8a7f3 
…OG.md

The README had grown into a build-state changelog + handoff notes. Split it
into three docs and give the front page a proper banner + status chips:

- README.md: a concise first-time-user intro — what splanc does (map LEDs in
  3D from a phone, then design/play effects on the real geometry), getting
  started (ledmapper.pages.dev), hardware, and how it works. Leads with the
  splanc.svg wordmark banner and a standard chip row (CI/HITL Actions status,
  live app, Bazel). Onboarding notes that a brand-new ESP32-C6 dev board can
  be flashed directly from the PWA over USB (Web Serial / WebUSB).
- DEVELOPERS.md (new): contributor guide — prerequisites, build/test, the
  hardware-free pipeline demo, repo layout, CI/pre-commit, container/CI gotchas.
- WORKLOG.md (new): a current-state handoff entry on top, then the old README's
  dated changelog / directives / TODO migrated verbatim as historical record.

Also refreshes the claude-container named-service instructions in
firmware/landing/README.md and tools/sim_studio/README.md. Docs-only;
prettier + markdownlint clean.

Ported forward from PR #4 onto current main.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude Agent @claude
docs: expand DEVELOPERS.md and add EFFECTS.md engine reference
008ac8c 
DEVELOPERS.md:
- Add a "Design & architecture docs" section linking the durable spec, all
  docs/design/ notes, docs/ operational notes, and EFFECTS.md.
- Add an architecture overview of the two major components — the PWA (web/)
  and the firmware (firmware/) — with a subsystem-by-subsystem layout, plus
  the shared protocol, solver, and Pi path.
- Refresh the build notes: the ESP32-C6 image builds in-container now with an
  explicit target; document that it is still tags=manual (excluded from //...)
  and built explicitly by the dedicated CI firmware job. Correct firmware to
  ESP32-C6 (RP2350 is a declared triple with no board target yet).
- Add a "Hardware-in-the-loop (HITL) testing" section: rig architecture, the
  suite, the FX performance benchmark + regression gate, CI wiring, and how to
  stand up your own rig for private use.

EFFECTS.md (new): a standalone reference for the effects engine — the GLSL-ish
language, the stack-machine VM and execution model, the full opcode table, the
.fxb container format, uniform/texture/video-streaming/MIDI plumbing, measured
ESP32-C6 performance and the regression gate, and how the built-in AI
(claude-opus-4-8) is prompted to write and self-repair effects.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude Agent @claude
chore: add GitHub funding link (Buy Me a Coffee)
ee981fa 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude Agent @claude
assets: update splanc.svg wordmark
b4f6819 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude Agent @claude
docs: refresh EFFECTS.md for the #65 FX-VM hill-climb
96cdf03 
Rebased onto #65 (FX VM hill-climb + effects-AI perf awareness), which changed
the engine EFFECTS.md documents:
- opcode enum extended to 0..=79 — add the native int/fixed ops (AbsI/MinI/MaxI/
  ClampI, SignI/StepI/FloorFix/CeilFix/FractFix/MixFix); note builtins now run
  natively on int/fixed args instead of coercing to soft-float.
- refresh the representative ESP32-C6 frame-cycle numbers from the regenerated
  golden (LUT sin/cos and integer hash dropped sharply; exp still soft-float).
- note the AI prompt is now perf-aware (fixed-point/soft-float cost + per-device
  builtin cost table).

Margins (10% / sweep16 15%) and the 13% software-estimator gate are unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@fughilli
fughilli force-pushed the docs/readme-refactor branch from bd52206 to 96cdf03 Compare August 9, 2026 18:25
@fughilli
fughilli merged commit 9c4acfa into main Aug 9, 2026
7 checks passed
fughilli pushed a commit that referenced this pull request Aug 15, 2026
Claude Agent @claude
FUG-105: bump sbc-deploy pin to 18a5346 (auto-managed macOS builder)
a3f78c4 
Move the sbc-deploy pin from cb70fcc to 18a5346 in lockstep across all four
spots (MODULE.bazel git_override + pi/hitl/flake.{nix,lock} + pi/provisioning/
nix/flake.lock). The new revs (upstream PRs #4 + #5) make the zero-conf macOS
aarch64 builder work for EXTERNAL bazel_dep consumers — the builder flake now
rides in each sbc_application target's runfiles, so `bazel run …image_sd` on
macOS auto-manages the sized VM from the pin (no --framework-subdir, no
vendoring, no --cross). Verified on hardware: the Pi 3 image builds via the
auto-started VM and deploys.

Locks regenerated with `nix flake update sbc-deploy` (only the sbc-deploy node
moved; transitive inputs unchanged). MODULE.bazel.lock needs no change
(git_override isn't content-pinned). Also gitignore .sbc-build/ (consumer-side
builder gc-roots/logs).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
fughilli pushed a commit that referenced this pull request Aug 15, 2026
Claude Agent @claude
FUG-105: bump sbc-deploy pin to 18a5346 (auto-managed macOS builder)
ad29086 
Move the sbc-deploy pin from cb70fcc to 18a5346 in lockstep across all four
spots (MODULE.bazel git_override + pi/hitl/flake.{nix,lock} + pi/provisioning/
nix/flake.lock). The new revs (upstream PRs #4 + #5) make the zero-conf macOS
aarch64 builder work for EXTERNAL bazel_dep consumers — the builder flake now
rides in each sbc_application target's runfiles, so `bazel run …image_sd` on
macOS auto-manages the sized VM from the pin (no --framework-subdir, no
vendoring, no --cross). Verified on hardware: the Pi 3 image builds via the
auto-started VM and deploys.

Locks regenerated with `nix flake update sbc-deploy` (only the sbc-deploy node
moved; transitive inputs unchanged). MODULE.bazel.lock needs no change
(git_override isn't content-pinned). Also gitignore .sbc-build/ (consumer-side
builder gc-roots/logs).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
fughilli pushed a commit that referenced this pull request Aug 15, 2026
Claude Agent @claude
FUG-105: bump sbc-deploy pin to 18a5346 (auto-managed macOS builder)
407864b 
Move the sbc-deploy pin from cb70fcc to 18a5346 in lockstep across all four
spots (MODULE.bazel git_override + pi/hitl/flake.{nix,lock} + pi/provisioning/
nix/flake.lock). The new revs (upstream PRs #4 + #5) make the zero-conf macOS
aarch64 builder work for EXTERNAL bazel_dep consumers — the builder flake now
rides in each sbc_application target's runfiles, so `bazel run …image_sd` on
macOS auto-manages the sized VM from the pin (no --framework-subdir, no
vendoring, no --cross). Verified on hardware: the Pi 3 image builds via the
auto-started VM and deploys.

Locks regenerated with `nix flake update sbc-deploy` (only the sbc-deploy node
moved; transitive inputs unchanged). MODULE.bazel.lock needs no change
(git_override isn't content-pinned). Also gitignore .sbc-build/ (consumer-side
builder gc-roots/logs).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@fughilli