[DONE] 원래 레포로 올릴 깨끗한 브랜치 — #7·#8·#9 를 engmung/Patternflow main 위 커밋 셋으로 (기록용, 머지하지 않음)

[patternflow-bot]

studio / https://claude.ai/code/session_01VaFtEmtx2AkdH1wnbQpV3Z

기록용 PR 이라 이 포크에선 머지하지 않는다. 원래 레포 main 최신 위에 포크 PR #7·#8·#9 를 커밋 셋으로 다시 얹었고, 작업용 파일은 하나도 없다. 총괄이 이 브랜치로 engmung/Patternflow 에 PR 을 올리면 웹 가이드의 첫 굽기 순서, /flash 리다이렉트, 새 README, BUILD_GUIDE §8 이 원래 레포에 들어간다.

기록용 PR — 이 포크에 머지하지 않는다. 포크 main 은 원래 레포 main 보다 뒤처져 있어서(abe7eb1) 이 PR 의 Files changed 에는 원래 레포에 이미 있는 engmung#489–engmung#491 커밋까지 보인다. 원래 레포에 올라갈 실제 차이는 커밋 셋뿐이고, 아래 비교 주소에서 그대로 보인다:
engmung/Patternflow@main...Patternflow-lab:Patternflow:claude/patternflow-upstream-docs-r4eab8

원래 레포에 올릴 제목·요약

Title

docs, web: the first flash starts in download mode everywhere, /flash goes to the guide, and the README is rewritten

Body (the repo's pull request template)

## What
Three commits that bring the first-flash steps into one order across the site and the docs, and rewrite the README:

1. `web, docs:` The Play guide's 01 Flash (and /ko) starts in download mode on every first flash (hold BOOT, tap RST, let go), expects the Wi-Fi step after "Installation complete!" not to come (RST, Flash Patternflow again, Connect to Wi-Fi), and ends on the panel's own `patternflow-xxxx` network at `192.168.4.1` when that does not take; the device simulator draws the NETWORK screen's hotspot. The Build guide's flash card, the Pattern tab's notes and the breadboard page say the same thing. The bare `/flash` redirects to `/guide/play#flash`; `/flash/manifest.json` and `/flash/bin/*` are untouched. The docs that give the first flash (`firmware/README.md`, `PATTERN_GUIDE.md`, `SUPPORT.md`, `docs/assembly/`) use the same order, the indexes list the guide pages, the three case remixes and the bundles that exist, CONTRIBUTING gets a row for the interactive guide's copy, and the PR template asks which row a change is.
2. `docs:` The README opens with the manifesto's fixed lines (L1–L3) and three ways in (try it in the browser, build one, get one assembled). Paik is told once, in *Where it began*. **First light** comes after the build, with the steps it was missing: unplug before seating the DevKit, Origin as the sign of success, *Format storage* on the first Basics install. Stale lines are corrected against the repo.
3. `docs:` `BUILD_GUIDE.md` §8.1 follows the Play guide's Flash chapter step by step. §7 no longer seats the DevKit before it has firmware, so it is *Wiring* (`#7-wiring`), and Besoiobiy's case README cites the renumbered steps. The README's Crowd Supply lines read as the campaign stands: past its goal and open until 15 October.

## Why
The guide, the README, BUILD_GUIDE and the site each gave a different first flash. Download mode was a fallback for an empty port list, though every first flash needs it. The Wi-Fi step was described as if it always comes, though it usually doesn't after a download-mode install. The panel's own hotspot was missing. And `/flash`, which the device's Update page and every release's FLASHING.md point at, had no page. The README buried the way in under the story.

## Tested
- `web/`: `npm ci`, `npm run lint` (0 errors; the changed files show the same 5 `no-img-element` warnings they have on `main`), `npm run typecheck`, `npm run build`, `npm run check:ci` (vitest 35 files / 478 tests, including the new `flash.test.ts`, plus every smoke suite). All pass.
- `next start`: `/flash` returns 307 to `/guide/play#flash`; `/flash/manifest.json` and `/guide/play` return 200.
- `python3 .github/scripts/check_links.py`: all 623 relative links resolve.
- `firmware/` changes are README text only (no code). `check_boundaries.py` and `check_presets.py` pass anyway.

## Which row
A fix to a guide, a README or a spec (`docs-links`), and a fix to the interactive guide (`web-ci`).

---
- [x] Touches `web/` → it builds (`npm run build`)
- [x] Touches `firmware/` → README text only; the core still names no feature (`python firmware/toolchain/check_boundaries.py`)
- [x] Touches a markdown file → its relative links resolve (`python3 .github/scripts/check_links.py`)

체크리스트

• 원래 레포 engmung/Patternflow main 최신(511e776, push 직전에 다시 fetch 해서 확인)에서 이 세션 브랜치를 새로 만들었다
• 포크 dev 의 [DONE] 웹 가이드 펌웨어 굽기·와이파이를 BOOT+RST 기본으로 고치고, 메인 README·문서를 정리한다 #7(caaf2c1)·[DONE] 메인 README 한 번 더 — 독자별 비판 검토부터 하고 다시 다듬는다 #8(bfc4b22)·[DONE] BUILD_GUIDE 굽기 순서를 웹 가이드와 맞추고, README 의 Crowd Supply 캠페인을 「진행 중, 10월 15일 마감」으로 바로잡는다 #9(16eca1b) squash 커밋만 차례로 cherry-pick 했다. 충돌은 없었다
• 작업용 파일(.claude/, .github/pr-evidence/, incoming/)은 0개다
• 커밋 메시지가 원래 레포 CONTRIBUTING 대로 영역부터 시작한다(web, docs:, docs:, docs:)
• web-ci 의 lint·typecheck·next build·check:ci 를 다시 돌렸고, check_links.py 도 통과했다
• 원래 레포에 올릴 영문 제목·요약을 위 절에 써 두었다
• 원래 레포에는 push 도 PR 도 하지 않았다

한 일

c894a5f docs: BUILD_GUIDE flashes in the Play guide's order, and the README's campaign is still open      ← #9
9a68428 docs: the README opens with the fixed lines and three ways in, and First light follows the build  ← #8
04062dc web, docs: the first flash starts in download mode, /flash goes to the guide's Flash chapter, and the README is new from its first screen  ← #7
511e776 Merge pull request #491 from engmung/dev   ← 원래 레포 main

• [DONE] 웹 가이드 펌웨어 굽기·와이파이를 BOOT+RST 기본으로 고치고, 메인 README·문서를 정리한다 #7 의 squash 에는 포크 dev 가 원래 레포에서 가져온 변경(ZuperZuche 빌드, 3D 미리보기 이름표, CHANGELOG 한 줄)도 섞여 있었다. 원래 레포 main 에 이미 똑같이 있어서 cherry-pick 에서 저절로 빠졌다. 그래서 커밋 [DONE] 웹 가이드 펌웨어 굽기·와이파이를 BOOT+RST 기본으로 고치고, 메인 README·문서를 정리한다 #7 은 squash 의 57개 파일 중 50개만 바꾼다. 빠진 7개는 사진 셋, HeroScene.tsx·.module.css, builds.ts, groups.test.ts 다.
• 커밋 본문은 squash 에 쌓여 있던 남의 커밋 메시지(mbchars·ZuperZuche)를 걷어내고, 각 PR 이 실제로 바꾼 것만 남겼다. 끝에 From Patternflow-lab/Patternflow#N (sha) 를 달아 출처를 적었다.

증거

작업용 파일 없음, 결과는 포크 dev 와 같다

$ git diff --name-only upstream/main HEAD | grep -E '^(\.claude/|\.github/pr-evidence/|incoming/)' || echo none
none
$ git diff --stat upstream/main HEAD | tail -1
 52 files changed, 858 insertions(+), 368 deletions(-)
$ git diff --stat HEAD origin/dev          # 포크 dev 와 다른 건 작업용 설정 하나뿐
 .claude/settings.json | 1 +
 1 file changed, 1 insertion(+)
$ git diff --name-only upstream/main HEAD -- firmware/ | grep -v '\.md$' || echo none
none

web-ci (원래 레포 기준, Node 22 로컬)

$ npm ci                → exit 0
$ npm run lint          → ✖ 12 problems (0 errors, 12 warnings)  exit 0
  (바뀐 .ts/.tsx 파일만 돌리면 5 warnings — 원래 레포 main 에서 같은 파일도 똑같이 5 warnings)
$ npm run typecheck     → tsc --noEmit  exit 0
$ npm run build         → ✓ Compiled successfully in 22.8s  exit 0
$ npm run check:ci      → exit 0
   ✓ src/components/guide/flash.test.ts (5 tests)
   ✓ src/lib/guide/deviceSim.test.ts (21 tests)
   ✓ src/components/sections/InsideGlobe/groups.test.ts (14 tests)
   Test Files  35 passed (35)
        Tests  478 passed (478)
   All module cache checks passed.

문서 링크·펌웨어 검사

$ python3 .github/scripts/check_links.py
all 623 relative links resolve
$ python3 firmware/toolchain/check_boundaries.py
boundary holds: 73 core files know none of 42 feature namespaces across 9 features
$ python3 firmware/toolchain/check_presets.py
presets in step: 34 twins, 14 web-only on purpose, 1 firmware-only on purpose

빌드한 사이트 (next start)

/flash               -> 307 http://localhost:3123/guide/play#flash
/flash/manifest.json -> 200
/guide/play          -> 200

실행법

git fetch https://github.com/Patternflow-lab/Patternflow claude/patternflow-upstream-docs-r4eab8
git checkout FETCH_HEAD
cd web && npm ci && npm run lint && npm run typecheck && npm run build && npm run check:ci
cd .. && python3 .github/scripts/check_links.py

원래 레포에 올릴 때: base engmung/Patternflow:main, head Patternflow-lab/Patternflow:claude/patternflow-upstream-docs-r4eab8. 제목과 본문은 위 「원래 레포에 올릴 제목·요약」 절의 것을 그대로 쓴다.

가정

• 커밋은 PR 하나에 하나씩, 모두 셋이다. [DONE] 웹 가이드 펌웨어 굽기·와이파이를 BOOT+RST 기본으로 고치고, 메인 README·문서를 정리한다 #7 은 웹과 문서를 함께 바꾸므로 web, docs: 로 시작한다. 원래 레포에 이미 firmware, tools: 같은 선례가 있다. 둘로 쪼개는 것도 생각했지만 총괄의 「squash 커밋 셋을 차례로」를 따랐다.
• 커밋 작성자는 Claude 다. squash 커밋의 작성자 Patternflow Bot 이 아니다. 메시지를 새로 썼으므로 새 커밋으로 보고, 원래 레포 hardware+web: mbchars' horizontal desktop case as the third remix, and the fourth case in /build's 3D preview (supersedes #488) engmung/Patternflow#489 때처럼 맞췄다. 출처는 커밋 본문의 From Patternflow-lab/Patternflow#N (sha) 줄에 있다.
• [DONE] 메인 README 한 번 더 — 독자별 비판 검토부터 하고 다시 다듬는다 #8 의 「캠페인 펀딩 완료」 문구는 [DONE] BUILD_GUIDE 굽기 순서를 웹 가이드와 맞추고, README 의 Crowd Supply 캠페인을 「진행 중, 10월 15일 마감」으로 바로잡는다 #9 가 고친다. 최종 상태는 「목표를 넘었고 10월 15일까지 열려 있다」다. 다만 원래 레포 머지가 10월 15일 뒤로 밀리면 README 배지(funded, ends Oct 15)와 「The campaign is past its goal and runs until 15 October 2026.」 한 문장이 낡는다. 그때는 마감된 문구로 한 줄 고쳐서 올린다.
• PR base 는 포크 main 이다. 포크 main 이 원래 레포 main 을 비춘 브랜치라서 골랐다. 포크 main 을 원래 레포 최신으로 올리는 건 기본 브랜치 push 라 하지 않았다. 그래서 Files changed 에 원래 레포 hardware+web: mbchars' horizontal desktop case as the third remix, and the fourth case in /build's 3D preview (supersedes #488) engmung/Patternflow#489–ZuperZuche's build joins the map; the 3D preview names whose case it is engmung/Patternflow#491 이 함께 보이고, 실제 차이는 맨 위 compare 주소에서 본다.
• 세션 브랜치 이름이 원격에 이미 있는 줄 알았는데 없었다. 로컬 추적 ref 만 dev(16eca1b)를 가리키고 있었다. 그래서 force push 없이 새 브랜치로 올렸다.
• 스크린샷은 붙이지 않았다. 그림 주소는 이 레포 커밋 SHA 여야 하는데, 그러려면 그림 커밋을 이 브랜치에 얹어야 한다. 그러면 원래 레포로 가는 브랜치가 더러워진다. 화면 증거는 [DONE] 웹 가이드 펌웨어 굽기·와이파이를 BOOT+RST 기본으로 고치고, 메인 README·문서를 정리한다 #7·[DONE] 메인 README 한 번 더 — 독자별 비판 검토부터 하고 다시 다듬는다 #8·[DONE] BUILD_GUIDE 굽기 순서를 웹 가이드와 맞추고, README 의 Crowd Supply 캠페인을 「진행 중, 10월 15일 마감」으로 바로잡는다 #9 각 PR 에 이미 있다. 이 PR 의 코드·문서는 포크 dev 와 바이트까지 같다(.claude/settings.json 만 다르다).

🤖 Generated with Claude Code

https://claude.ai/code/session_01VaFtEmtx2AkdH1wnbQpV3Z