사이트 구조·프로토콜 문서와 목표 TBD를 정렬한다

[developer-1px]

Goal Anchor

• Outcome: 사이트와 저장소 문서가 우리가 지향하는 책임 구조·명칭·프로토콜을 일관되게 설명하고, 아직 닫히지 않은 TBD도 목표 위치와 함께 드러낸다.
• Done: 먼저 사이트의 탐색 구조·페이지 제목·명칭·프로토콜 안내를 맞추고, 이어 본문·owner API reference·README·LLM 요약을 갱신한다. 현재 계약과 목표/TBD를 구분하며, 문서 링크·목차·public subpath 누락을 실제 소비 경로와 검사로 검증한다.
• Don't: runtime 동작, Stable profile의 관찰 계약, 기존 public identifier와 package 배치를 바꾸지 않는다. TBD를 구현 완료나 호환성 보장으로 표시하지 않는다. 기존 미커밋 변경과 별도 진행 중인 편집 문법 설계 PR #726을 덮어쓰지 않는다. 이번 위임에는 merge를 포함하지 않는다.

Closes #739

결과

• 사이트 탐색을 Introduction / Foundation / Building Blocks / Hands / Artifact / Applications로 맞추고, JSON Document Protocol과 Editing Protocol을 각각 해당 책임 위치에 둔다.
• 이 구조는 읽기 지도이며 직렬 package 의존 계층이 아니다. Adapter와 Connector는 독립적으로 선택하고 Collaboration은 같은 JSONDocument 계약의 대체 구현이다.
• Document Type 9개 후보, Official Hands Profile, Artifact에 현재 증거 / 목표 책임 / 남은 완료 조건을 표시한다. 목표를 구현 완료나 새 호환성 약속으로 표현하지 않는다.
• 정본 명명·Core profile의 설명, public 문서, README와 llms.txt의 과거 Host 책임 및 Projection 용어를 현재 방향과 맞춘다. Host는 조합·제품 정책·copy·fixture·layout·구체 인스턴스 주입만 소유한다.
• 로컬 inverse History와 actor-local 협업 History, Copy와 selection-only 경로의 의미를 구분한다.

drift와 재발 경로 수정

• site/site-routes.json.documentSource에서 105개 Markdown의 경로·본문을 연결한다. 별도 filename catalog와 중복 raw import 목록을 제거했다.
• TOC가 실제 Markdown renderer의 heading ID를 소비한다. underscore·구두점·중복 heading·code fence를 다른 slug 규칙으로 해석하지 않는다.
• API metadata의 Owner를 실제 의미인 탐색 분류로 고치고 package가 API owner임을 명시했다. Collaboration /text를 추가하여 public TypeScript entrypoint 33개를 모두 등록한다.
• /docs/api를 index leaf로 옮겼다. 기존 부모 페이지가 30개 package API의 실제 본문을 가리던 문제를 고치고 직접 진입 회귀 검사를 추가했다.
• 상대 파일 링크, source 등록 누락·중복, public subpath 누락의 검사를 추가했다.

검증

• npm run docs:evaluate
• API/route 등록 양성·음성 검사 5개
• site unit: 27개 파일, 298개 통과 — 105개 Markdown과 30개 API 실제 route 포함
• site typecheck 및 UI·구조·정본 모듈 가드
• npm run site:verify:pages: build, 정적 검사, HTTP 검사
• npm run standard:check: Core conformance 351개 통과, 기존 4개 skip
• 기존 Chrome profile: Concept Map → Document Types → Calendar TBD, TOC anchor, Editing/Building Blocks/Official Hands, Rich Text API underscore, Collaboration /text, Artifact의 MD·PPT·Sheet 전환
• 추가한 Playwright browser 회귀 시나리오: PR CI 결과 확인 예정

로컬 Playwright는 새 Chrome profile을 띄우지 않기 위해 실행하지 않았으며 실제 사용 중인 Chrome에서 변경 흐름을 제어·확인했다. 검사한 경로에서 가로 넘침, Vite error overlay, 실패 resource 응답은 없었다.

처음 site unit을 build/typecheck와 동시에 실행했을 때 탐색 2건이 시간 초과했다. 코드나 timeout을 바꾸지 않은 단독 전체 재실행에서 298개가 통과했다.

보존한 경계

production package 코드·public identifier·package 배치·Stable 관찰 계약은 변경하지 않았다.
standards/editing-grammar.md와 별도 PR #726, 원래 checkout의 미커밋 변경은 보존했다.
이번 PR은 검토 인계이며 merge는 포함하지 않는다.

[developer-1px]

최신 main과 통합했습니다. Calendar·Object의 RC 소유권과 Canvas 등 새 API 경로를 보존하고, documentSource 정본 등록에서 package 소유 계약 문서를 함께 읽는 documentIncludes를 지원합니다. 기존 Chrome의 1366px iframe에서 CI 실패와 같은 UI Primitives API 목차 가로 넘침(1370px)을 재현하여 목차 최소 너비·줄바꿈을 수정했고 대표 경로 10개의 scrollWidth가 모두 1366px 이하임을 확인했습니다. 사이트 28 files / 314 tests, route 등록 3 tests, site typecheck·정본/UI guards, docs:evaluate, docs:api, Pages build·정적·HTTP 검사, pre-push build가 통과했습니다. 과거 자동 CI 실행 자체를 재실행한 것은 아니며 기존 Chrome 프로필을 사용했습니다. 여러 owner 문서가 같은 canonical Demo를 보여주는 현재 Usage를 보존하고 live-demo registry 검사는 중복 노출 허용·등록 경로 완전성을 확인하도록 맞췄습니다.