engmung · Oct 22, 2026 · Oct 18, 2026 · Oct 19, 2026 · Oct 21, 2026 · Oct 21, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -78,7 +78,7 @@ A pin on the map is one entry in [`web/src/components/sections/InsideGlobe/build
 
 Inside includes builds, projects derived from Patternflow, and places where it is used. Add one entry to `web/src/components/sections/InsideGlobe/builds.ts`: a short `title`, `maker`, public `location`, `date`, `description`, and any external `links`. Photos are optional. Keep existing `id` and `slug` values stable so shared links keep working.
 
-Choose one primary `category`: `builds` for assembled devices and enclosure changes, `projects` for ports and new tools, or `in-use` for installations, performances and other uses. This is separate from `kind`, which preserves the existing build/collaboration relationship and marker style. A maker can have several entries: a new tool and a later exhibition are different records. Link to the maker's own documentation for ongoing updates; a short introduction here is enough. Do not add unannounced work or assume an event happened from a sale or a planned appearance.
+Choose one primary `category`: `builds` for assembled devices and enclosure changes, `projects` for ports and new tools, or `in-use` for installations, performances and other uses. This is separate from `kind`, which says what the pin is and picks its marker on the globe: `build`, `collaboration`, `sold` or `showing`, each explained in the comment above `BuildKind`. A collaboration, a sale or a showing names the pin it grew out of in `originId`, and the globe draws a line back to it. Left out, the line goes to the first build in the file. A maker can have several entries: a new tool and a later exhibition are different records. Link to the maker's own documentation for ongoing updates; a short introduction here is enough. Do not add unannounced work or assume an event happened from a sale or a planned appearance.
 
 Classify the subject of the entry, not its surroundings. A completed device photographed in a studio or DJ booth is still a `builds` entry. Use `in-use` when the entry documents actual use in an exhibition, performance or installation; a sale or delivery alone is not enough. Leave a category empty until a qualifying case is available.
 

diff --git a/docs/EDITIONS.md b/docs/EDITIONS.md
@@ -218,7 +218,7 @@ deliberately re-pinned in the same commit.
 feature code that recompiles against a checkout, in-tree or out. Widening
 is tail-append only (the rule and its reason are written on the struct);
 the compiler surfaces every break at build, and `build.sh all` makes sure
-"builds" means all three compositions. The two composition filenames and
+"builds" means all five compositions. The two composition filenames and
 their macros are the out-of-tree seam - renamed spellings are shimmed, and
 shims get deleted only after their consumers migrate.
 

diff --git a/docs/README.md b/docs/README.md
@@ -58,6 +58,7 @@ The interactive guide at [patternflow.work/guide](https://patternflow.work/guide
 ## Records
 
 - [`investigations/`](investigations/) — dated post-mortems, and the cleanup's plans. `npm run doc-map` in `web/` writes the two lists here: `2026-10-doc-map.csv`, every link in the tree and whether it resolves, and `2026-10-doc-parity.csv`, every Korean/English pair and which side is missing or short
+- [`rfc-cleanup.md`](rfc-cleanup.md) and its [progress log](rfc-cleanup-progress.md) — the October 2026 tidy-up before the any-resolution work, done on 16 October. It changed where things live and what CI checks, and nothing the firmware or the site does. §2.9 lists the writing it locked
 - [`releases/`](releases/) — every release's changelog section as written, one file each (`vX.Y.Z.md`), back to v1.0.0; `CHANGELOG.md` at the root keeps the three newest in full and links the rest. `v3.0.0-notes.md` and `v3.1.0-notes.md` are long-form notes for two July 2026 releases, beside the v3.0.0 launch checklist; notes since 3.2 are on [GitHub Releases](https://github.com/engmung/Patternflow/releases)
 - [`manifesto.md`](manifesto.md) — why Patternflow exists, and (section 6) how we treat each other
 - [`images/`](images/), [`media/`](media/) — assets the guides and the site reference
diff --git a/docs/REPOSITORY.md b/docs/REPOSITORY.md
@@ -44,9 +44,13 @@ Filenames are lowercase with underscores. Tags are `vX.Y.Z`; the firmware source
 
 The site, the firmware and the release notes hold absolute `blob/main/…` links into this tree, and a pull request that breaks one fails `check:links-absolute`. Before renaming or moving any of these, grep `web/src`, `web/content`, `firmware/patternflow/console` and `firmware/patternflow/features/*/*_index.h`:
 
-- `README.md`, `BUILD_GUIDE.md` (the site links its section anchors — §1, §2, §4, §8, §8.2 and §10 when this was written — so a renamed heading breaks them), `FEATURE_GUIDE.md`, `PATTERN_GUIDE.md`
+- `README.md`, `BUILD_GUIDE.md` (the site links its section anchors — §1, §2, §4, §8, §8.2 and §10 when this was written — so a renamed heading breaks them), `FEATURE_GUIDE.md`, `PATTERN_GUIDE.md`, `CHANGELOG.md`, `CONTRIBUTING.md` and `.github/SUPPORT.md` (the issue forms link the last two)
 - `docs/AUDIO_GUIDE.md`, `docs/assembly/README.md`, `docs/midi-ableton.md`, `docs/midi-spec.md` (the last two are baked into the Audio edition's console pages)
-- `docs/EDITIONS.md`, `docs/rest-api.md`, `firmware/README.md`, `hardware/bom/bom_v3.9.csv`
+- `docs/EDITIONS.md`, `docs/rest-api.md`, `docs/osc-spec.md`, `docs/mqtt-spec.md`, `docs/audio-ws-spec.md`, `docs/pfst-v2-spec.md`, `docs/director-midi.md` (the features page links each of these)
+- `docs/panel-compatibility.md`, `docs/legacy/BUILD_GUIDE_v2.md`, `docs/LICENSE-SUMMARY.md`, `docs/releases/v2.0.0.md`, `firmware/README.md`, `firmware/CUSTOM_PATTERNS.md`, `hardware/README.md`, `hardware/bom/bom_v3.9.csv`, `tools/patternflow-audio-android/README.md`
+- `hardware/case/README.md`, and each folder in `hardware/case/remixes/` with the files in it. The Build panel's case cards link them by name: a README, a `print_layout.3mf`, the mbchars case's `assembly.md` and `bom.md`
 - `web/src/app/compliance/` — the `/compliance` URL is printed on the box. Never move, redirect or noindex it.
 
+Folders are linked too. The features page links each feature's folder in `firmware/patternflow/features/`, and the site's Build guide links files in `hardware/case/bed_256mm/`, `hardware/case/bed_330mm/` and `hardware/pcb/`. Every row, with the file the link sits in, is in [`investigations/2026-10-doc-map.csv`](investigations/2026-10-doc-map.csv) under the kind `absolute-blob`. `npm run doc-map` in `web/` writes that list again from the tree as it is.
+
 `.github/scripts/check_links.py` checks the *relative* links in every tracked markdown file and runs on every pull request that touches one. `check:links-absolute` (`web/scripts/doc-map.ts --check absolute`, in `drift.yml`) checks the absolute ones on every pull request, against the tree or the tag a link names.
diff --git a/docs/SERVICES.md b/docs/SERVICES.md
@@ -1,6 +1,6 @@
 # Patternflow Server Services & Worker Management
 
-Patternflow 커뮤니티 웹 서버 및 C++ 펌웨어 웹플래시 컴파일 빌드 워커 서비스 구성과 운영 방법 가이드입니다.
+Patternflow 커뮤니티 웹 서버와, 패턴 C++ 헤더를 `.pfm` 모듈로 굽는 빌드 워커 서비스 구성과 운영 방법 가이드입니다.
 
 ---
 
@@ -32,10 +32,10 @@ RestartSec=3
 OOM 킬은 `dmesg -T | grep -i "killed process"` 로 봅니다.
 
 ### ② `patternflow-worker.service`
-- **역할**: C++ 펌웨어 빌드 워커 (`scripts/build-worker.ts`)
-- **설명**: 웹플래시 요청 대기열(`queued`)을 수신하여 `arduino-cli`를 이용해 ESP32-S3 바이너리를 컴파일합니다.
+- **역할**: 패턴 모듈 빌드 워커 (`scripts/build-worker.ts`)
+- **설명**: 빌드 대기열(`queued`)에서 잡을 하나씩 가져가 헤더마다 `firmware/toolchain/build_module.py`와 Xtensa 컴파일러로 ESP32-S3용 `.pfm` 모듈을 굽습니다. 펌웨어 이미지 통째 빌드는 2026-08-12(`4c13474`)에 끝났고, 그 뒤로 워커는 `arduino-cli`를 부르지 않습니다.
 - **위치**: `/etc/systemd/system/patternflow-worker.service`
-- **환경변수 중요 사항**: `Environment=PATH`에 `arduino-cli` 설치 경로(`~/.local/bin` 또는 `/usr/local/bin`) 포함 필수
+- **환경변수 중요 사항**: 워커는 `python`(다른 이름이면 `PYTHON_PATH`)과 `PF_XTENSA_BIN`이 가리키는 컴파일러(아래 2단계)를 띄웁니다. `Environment=PATH`에는 Python이 있어야 하고, 예전에 넣은 `arduino-cli` 경로는 이제 쓰이지 않습니다.
 
 #### 워커는 격리된 채로 돈다 — `hardening.conf` (2026-09-04)
 
@@ -93,9 +93,10 @@ strace로 확인한 전부다: 데이터 디렉터리(DB·WAL·산출물), 워
 것으로 재현했다. 두 단계 중 첫째는 끝났다:
 
 1. **시크릿은 유닛 밖 (완료, 2026-09-04).** 워커가 필요로 하는 변수
-   (`COMMUNITY_ENABLED`, `BUILD_ENABLED`, `BUILD_FQBN`, `COMMUNITY_DB_PATH`)는
-   root 전용 `/etc/patternflow/worker.env`(0600)에서 `EnvironmentFile=`로
-   받는다. `.env.local`은 `InaccessiblePaths`로 막으면 워커가 못 뜬다 —
+   (`COMMUNITY_ENABLED`, `BUILD_ENABLED`, `COMMUNITY_DB_PATH`, 2단계의
+   `PF_XTENSA_BIN`)는 root 전용 `/etc/patternflow/worker.env`(0600)에서
+   `EnvironmentFile=`로 받는다. 그날 같이 넣은 `BUILD_FQBN`은 통째 이미지
+   빌드의 보드 옵션이라 8월 12일 뒤로 읽는 코드가 없다. `.env.local`은 `InaccessiblePaths`로 막으면 워커가 못 뜬다 —
    `scripts/loadEnv.ts`의 `existsSync`는 접근 불가 파일에도 `true`를 돌려주고,
    그다음 `process.loadEnvFile`이 EACCES에 예외를 던진다. 그래서
    `BindReadOnlyPaths=/dev/null:…/.env.local`로 **빈 파일로 보이게** 한다:
@@ -314,8 +315,11 @@ npm run build:enqueue
 
 ## 3. 자주 발생하는 문제 & 조치법 (Troubleshooting)
 
-- **웹플래시 요청이 계속 `queued`에서 안 넘어감**:
+- **빌드 요청이 계속 `queued`에서 안 넘어감**:
   - `patternflow-worker.service`가 켜져 있는지 확인: `sudo systemctl status patternflow-worker.service`
   - 꺼져 있다면 재시작: `sudo systemctl restart patternflow-worker.service`
-- **`spawn arduino-cli ENOENT` 에러 발생**:
-  - `patternflow-worker.service` 파일 내 `PATH` 환경변수에 `arduino-cli` 설치 경로가 올바르게 지정되었는지 확인.
+- **빌드 오류가 `The build service's compiler is not available right now. No Xtensa compiler found`로 시작함**:
+  - 워커가 `xtensa-esp32s3-elf-g++`를 찾지 못했습니다. `/etc/patternflow/worker.env`의 `PF_XTENSA_BIN`이 래퍼 디렉터리(`/etc/patternflow/xtensa-sandbox`)를 가리키는지, 래퍼가 부르는 `~/.arduino15/packages/esp32/tools/esp-x32/2601`이 그대로 있는지 확인.
+  - 오류 전문은 `npm run build:status -- <BUILD_ID>`의 `--- error ---` 아래에 나옵니다.
+- **빌드 오류에 `[cannot run python: spawn python ENOENT]`가 나옴**:
+  - 유닛의 `PATH`에 `python`이 없습니다. `worker.env`에 `PYTHON_PATH=python3`처럼 실행 파일 이름이나 경로를 넣고 워커를 재시작.
diff --git a/web/.env.example b/web/.env.example
@@ -2,6 +2,12 @@
 NEXT_PUBLIC_POSTHOG_KEY=phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
 
+# ── Roadmap ─────────────────────────────────────────────────────────────────
+# /api/roadmap reads the repository's open issues from the GitHub API on the
+# server. A token raises GitHub's rate limit; the repository is public, so the
+# route works without one.
+#GITHUB_TOKEN=
+
 # ── Community (self-hosted deployment only) ──────────────────────────────────
 # The community runs where this flag is set (the Raspberry Pi / VPS). Leave it
 # unset on Vercel — community pages then show a pointer to the community host.
@@ -36,27 +42,36 @@ NEXT_PUBLIC_COMMUNITY_URL=https://community.patternflow.work
 # here or cross-origin sign-in and publishing are rejected.
 COMMUNITY_ALLOWED_ORIGINS=https://patternflow.work
 
-# ── Firmware build service (community host with a worker) ────────────────────
-# Server side: enables POST /api/community/builds. Needs arduino-cli installed
-# and `npm run worker` running. Compiling submitted C++ is arbitrary code
-# execution at compile time — keep this off unless the worker's unit carries
-# the sandbox in docs/SERVICES.md (no network, read-only system, limits).
+# ── Pattern module builds (community host with a worker) ────────────────────
+# Server side: enables POST /api/community/builds and the module cache. Needs
+# `npm run worker` running, which compiles each pattern header into a .pfm
+# module with firmware/toolchain/build_module.py and the Xtensa compiler. It
+# has not built whole firmware images since 12 August. Compiling submitted
+# C++ is arbitrary code execution at compile time — keep this off unless the
+# worker's unit carries the sandbox in docs/SERVICES.md (no network,
+# read-only system, limits).
 #BUILD_ENABLED=1
-# Client side: shows the "Build firmware" buttons. Set both, or neither.
+# Client side: shows the deck, "Send to my Patternflow" and Pattern Lab's
+# "To hardware". Set both, or neither.
 #NEXT_PUBLIC_BUILD_ENABLED=1
 # Overrides for the worker (defaults are usually right in a repo checkout):
 #FIRMWARE_SRC_DIR=/home/pi/Patternflow/firmware/patternflow
 #BUILD_WORK_DIR=/home/pi/patternflow-data/build-worker
 #BUILD_ARTIFACT_DIR=/home/pi/patternflow-data/builds
-#ARDUINO_CLI_PATH=arduino-cli
 #
-# BUILD_FQBN — normally leave this unset. The built-in default already pins the
-# board options firmware/README.md requires (PSRAM, flash size, partition
-# scheme, CDC on boot), and a build is refused if an override drops any of
-# them: leaving one out compiles against the board defaults and produces
-# firmware that boots but is not the firmware we release.
-# To inspect the available options: arduino-cli board details --fqbn esp32:esp32:esp32s3
-#BUILD_FQBN=esp32:esp32:esp32s3:PSRAM=opi,FlashSize=16M,PartitionScheme=app3M_fat9M_16MB,CDCOnBoot=cdc,USBMode=hwcdc
+# The directory holding xtensa-esp32s3-elf-g++ and the nm beside it. Unset, the
+# worker looks where the ESP32 Arduino core installs its compiler
+# (ARDUINO_DIRECTORIES_DATA, then ~/.arduino15 and the macOS and Windows
+# equivalents), then in PlatformIO (PLATFORMIO_CORE_DIR, else ~/.platformio).
+# The Pi points it at the bwrap wrappers in docs/SERVICES.md.
+#PF_XTENSA_BIN=/etc/patternflow/xtensa-sandbox
+#
+# PF_TARGET_ABI — normally leave this unset, which builds descriptor 2 for a
+# pattern that reads the absolute knob tier. 1 makes a module that also
+# installs on firmware older than v3.5.1, and compiles that tier out: a
+# Director show then sets values the pattern cannot read. Changing it changes
+# the toolchain revision, so the worker rebakes every public header.
+#PF_TARGET_ABI=1
 
 # Moderators — comma-separated USERNAMES (not ids) who may remove other
 # people's patterns, posts and comments. Unset means nobody can, which is the