docs(plan): record what WP1 actually landed, and what it did not

Three deviations worth naming: Bun.TOML is not used to verify writes after the
live probe found transposed escapes, salvage previews return a directory rather
than reserving a filename, and previewAdopt runs the full pipeline so preview
and commit agree byte-for-byte.

The Windows write-through gate stays open. fsyncDir no-ops on win32, so a crash
there surfaces as recovery_required rather than silent loss - acceptable by
design, but it needs a Windows CI run before WP2 leans on it.

Author: lidge-jun

devlog/_plan/260801_monorepo_git_blobless_strategy/000_git_repo_size_inventory.md

@@ -0,0 +1,43 @@
+# 000 — OpenCodex 저장소 용량 및 Git 인벤토리 분석
+
+Date: 2026-08-01  
+Work phase: research  
+Target: OpenCodex 저장소 구조 및 `.git` 팽창 원인 측정
+
+---
+
+## 1. 현재 저장소 용량 스냅샷
+
+OpenCodex 개발 워크스페이스의 전체 용량은 약 **1.9 GB**이며, 주요 디렉터리별 용량 구성은 다음과 같습니다.
+
+| 디렉터리 / 항목 | 용량 | 성격 및 주요 구성 내용 |
+| --- | --- | --- |
+| **`.git`** | **718 MB** | Git 오브젝트 패크 (packfile 628MB, 7,500+ 커밋 히스토리) |
+| **`docs-site/`** | **477 MB** | 공개 문서 사이트 (Astro, ECharts, Pretendard 폰트 97MB 등 node_modules 포함) |
+| **`gui/`** | **262 MB** | React 기반 대시보드 UI (Vite, Rollup, Happy-DOM 등 node_modules 포함) |
+| **`devlog/`** | **180 MB** | PABCD 계획/감사 문서 및 외부 참조 분석 소스 (`_chase/` 141MB 포함) |
+| **`.tmp/`** | **146 MB** | RSS 메모리 모니터링 로그, CI/테스트 실행 시 생성된 임시 아티팩트 |
+| **`node_modules/`** | **116 MB** | 루트 Bun / TypeScript 개발 및 테스트 도구 의존성 |
+| **`src/` + `tests/`** | **~14 MB** | 프록시 런타임 소스 코드 및 자동화 회귀 테스트 전체 |
+
+---
+
+## 2. npm 사용자 배포 패키지와의 격차
+
+일반 사용자가 `npm install -g opencodex` 또는 `npx opencodex`로 설치할 때 받는 실제 배포본(`npm pack`)은 다음과 같이 극도로 경량화되어 있습니다.
+
+- **압축 패키지 크기 (`.tgz`)**: **7.5 MB**
+- **설치 후 해제 크기**: **13.0 MB**
+- **포함 항목**: `bin/` (CLI 진입점 24KB), `src/` (TypeScript 런타임 6.5MB), `gui/dist/` (빌드된 대시보드 1.8MB), `assets/`, `README.md`, `LICENSE`
+- **제외 항목**: `.git` (718MB), `docs-site/` (477MB), `devlog/` (180MB), `.tmp/`, `tests/` 등 개발 전용 자산 전체
+
+---
+
+## 3. `.git` 팽창 원인 분석
+
+1. **7,500회를 넘어서는 촘촘한 커밋 히스토리**
+   - 개발 문서 중심 PABCD 루프 및 서브에이전트 감사/검증 과정에서 짧은 기간 동안 수천 건의 커밋이 쌓였습니다.
+2. **개발 문서 (`devlog/_plan/`) 델타 누적**
+   - 소스 코드뿐만 아니라 십여 개의 계획/조사 문서가 반복 수정되면서 Git 델타 객체가 축적되었습니다.
+3. **참조용 외부 코드 및 임시 파일**
+   - `devlog/_chase/` 하위 외부 참조 소스는 `.gitignore` 처리되어 Git 히스토리에 들어가지 않으나, 워크트리 용량을 차지합니다.

devlog/_plan/260801_monorepo_git_blobless_strategy/005_blobless_clone_strategy.md

@@ -0,0 +1,39 @@
+# 005 — Hermes 및 대형 에이전트 모노레포 전략 대조 (Blobless Clone 중심)
+
+Date: 2026-08-01  
+Work phase: research / decision-locked  
+Target: 자율 에이전트 모노레포의 Git 용량 관리 방식 대조 및 최적 전략 도출
+
+---
+
+## 0. 결정 고정 (Decision Locked)
+
+**OpenCodex는 Hermes Agent 스타일의 단일 모노레포 + Blobless Clone (`--filter=blob:none`) 전략을 공식 확정합니다.**
+
+- **기각된 안 A (Submodule 분리 - cli-jaw 스타일)**: `devlog`를 별도 저장소로 분리하는 방식은 브랜치 이동/병합 시마다 서브모듈 포인터 충돌(gitlink churn)을 유발하므로 채택하지 않습니다.
+- **기각된 안 B (히스토리 재작성 - git-filter-repo)**: 기존 커밋 히스토리를 강제로 파괴하면 과거 PR 및 추적 가능성이 손상되므로 시행하지 않습니다.
+- **채택된 안 (Hermes 모노레포 방식)**: 문서(`devlog`), 소스(`src`), 테스트(`tests`)를 단일 모노레포로 유지하여 원자적 커밋(Atomic Commit)을 보존하되, 클론 및 CI 시점에 `filter: blob:none`을 적용해 로컬 `.git` 용량을 최소화합니다.
+
+---
+
+## 1. 주요 에이전트 프로젝트 사례 비교
+
+| 프로젝트 | 관리 구조 | 문제점 및 특징 | 선택한 해결 방향 |
+| --- | --- | --- | --- |
+| **OpenClaw** | 프록시 코어 + 공개 스킬 분리 | 히스토리에 과거 테스트 대용량 잔여물이 남아 200MB+ 유지 | 스킬/자산 저장소를 외부(`openclaw/skills`)로 완전히 분리 |
+| **Hermes Agent** | 모노레포 (코어 + CLI + Web + Docs) | 짧은 기간 동안 2,700+ 커밋 폭증, 파일 개수 4,700+ 개 | 모노레포 구조를 유지하되, CI/개발 시점에 **Partial Clone** 활용 |
+| **cli-jaw 계열** | 코드 + `devlog` 서브모듈 분리 | 기획 문서 커밋을 별도 repo로 분리하여 코드 `.git` 최소화 | `.git`은 가벼우나, 브랜치 이동 시 서브모듈 포인터 충돌(gitlink churn) 발생 |
+
+---
+
+## 2. 왜 Blobless Clone인가?
+
+OpenCodex는 문서 퍼스트 PABCD 규율을 따르므로 기획 문서(`devlog/_plan/`), 프록시 소스(`src/`), 회귀 테스트(`tests/`)가 하나의 atomic 커밋으로 묶이는 이점이 매우 큽니다.
+
+서브모듈 방식은 브랜치 이동이나 PR 작업 시 gitlink 포인터 충돌이 자주 일어나는 단점이 있습니다. Hermes 프로젝트처럼 **단일 모노레포를 유지하면서 Blobless Clone (`--filter=blob:none`)을 활용하는 전략**이 OpenCodex에 가장 적합합니다.
+
+### Blobless Clone (`git clone --filter=blob:none`)의 장점
+
+1. **로컬 용량 절감**: 과거 커밋의 실제 파일 본문(Blob) 다운로드를 생략하므로 초기에 `.git` 용량을 **700MB대에서 50~100MB 수준**으로 축소합니다.
+2. **모든 Git 명령어 정상 동작**: Shallow clone과 달리 모든 커밋 히스토리, 브랜치, `git log`, `git status`, `git diff`가 완벽하게 동작합니다.
+3. **온디맨드 자동 다운로드**: 과거 옛날 커밋의 특정 파일을 열거나 체크아웃할 때만 Git이 배경에서 해당 블롭을 자동으로 가져옵니다.

devlog/_plan/260801_monorepo_git_blobless_strategy/006_contributor_and_ci_guidelines.md

@@ -0,0 +1,52 @@
+# 006 — 기여 가이드라인 및 CI 적용 제언
+
+Date: 2026-08-01  
+Work phase: recommendations  
+Target: `CONTRIBUTING.md`, `README.md`, 및 `.github/workflows/` 적용할 구체적 가이드 문구
+
+---
+
+## 1. `CONTRIBUTING.md` 추가 제언 문구
+
+기여자가 프로젝트를 시작할 때 빠르게 클론하고 로컬 용량을 가볍게 유지할 수 있도록 `CONTRIBUTING.md`에 다음 안내 섹션을 추가하는 것을 권장합니다.
+
+```markdown
+## Repository Size & Cloning
+
+opencodex is a docs-first monorepo with extensive devlog history. To keep your local checkout fast and compact, use a **Blobless Clone**:
+
+```sh
+git clone --filter=blob:none https://github.com/lidge-jun/opencodex.git
+```
+
+This downloads all commit history and branches while skipping historical file blobs, keeping your local `.git` directory under 100MB. Historical files are fetched transparently on demand when needed.
+
+### Local Maintenance
+
+If your local `.git` directory grows over time due to frequent active development, you can clean up unreferenced local objects:
+
+```sh
+git gc --prune=now
+```
+```
+
+---
+
+## 2. `.github/workflows/ci.yml` 적용 제언
+
+CI 파이프라인에서 저장소를 체크아웃할 때 대용량 블롭 다운로드를 방지하기 위해 `actions/checkout` 단계에 `filter: blob:none` 옵션을 지정합니다.
+
+```yaml
+- name: Checkout repository
+  uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+    filter: blob:none
+```
+
+---
+
+## 3. Git Ignore 관리 원칙
+
+- `devlog/_chase/` 하위의 타사 비교용 레퍼런스 소스는 이미 `.gitignore`에 등록되어 관리되고 있습니다.
+- 런타임 성능 및 RSS 모니터링 로그(`.tmp/`)도 기존과 같이 `.gitignore`로 철저히 격리하여 메인 Git 히스토리에 포함되지 않도록 유지합니다.

devlog/_plan/260801_monorepo_git_blobless_strategy/010_implementation_roadmap.md

@@ -0,0 +1,33 @@
+# 010 — 모노레포 Git Blobless 최적화 로드맵
+
+Date: 2026-08-01  
+Work phase: roadmap / decision-locked  
+Target: 실 소스 코드 패치 없이 문서 및 CI 가이드 반영 단계 정리
+
+---
+
+## Architectural Decision Record (ADR) Summary
+- **전략 선택**: Hermes Agent 방식 (단일 모노레포 + Blobless Clone) 고정
+- **핵심 이유**: `devlog/_plan/` 문서, `src/` 소스, `tests/` 회귀 테스트의 단일 커밋 원자성 유지 & 서브모듈 포인터 충돌 예방
+
+---
+
+## 로드맵 단계
+
+### Phase 1: 리서치 및 문서 스캐폴딩 (완료)
+- [x] `000_git_repo_size_inventory.md`: 로컬 저장소 및 npm 배포 패키지 용량 전수 분석
+- [x] `005_blobless_clone_strategy.md`: OpenClaw, Hermes 등 사례 비교 및 Hermes 방식 확정 기록
+- [x] `006_contributor_and_ci_guidelines.md`: `CONTRIBUTING.md` 및 GitHub Actions 적용 문구 작성
+
+### Phase 2: 기여 가이드 문서 보강 (제언 단계)
+- [ ] `CONTRIBUTING.md`에 Blobless Clone (`git clone --filter=blob:none`) 안내 및 `git gc` 팁 추가
+- [ ] 필요 시 `README.md` 기여 섹션에 해당 가이드 링크 보강
+
+### Phase 3: CI 체크아웃 최적화 (제언 단계)
+- [ ] `.github/workflows/ci.yml` 체크아웃 단계에 `filter: blob:none` 적용 고려
+
+---
+
+## 핵심 변경 없음 (Explicitly Not Changed)
+- 프로덕션 소스 코드(`src/`) 및 회귀 테스트(`tests/`) 수정 없음
+- 기존 Git 커밋 히스토리를 강제로 파괴하거나 재작성(`git filter-repo` 등)하지 않음 (기존 커밋 및 PR 추적 가능성 온전히 보존)

devlog/_plan/260801_pr611_volcengine_evidence/000_evidence_ledger.pre-merge-local.md

@@ -0,0 +1,89 @@
+# PR #611 Volcengine Ark — credential-destination evidence ledger
+
+Research record for the `MAINTAINERS.md` evidence gate on PR #611. Sources were
+opened, not read from search snippets. Verification date: **2026-08-01**.
+
+## Why this unit exists
+
+PR #611 adds three canonical presets (`volcengine`, `volcengine-coding-plan`,
+`volcengine-agent-plan`). A new preset is a credential-destination change, so
+`MAINTAINERS.md` requires five evidence items before merge. A maintainer security
+review (Ingwannu, on `bdfc05c23`) blocked on that gate with "Do not merge the
+current head as a canonical preset". This ledger settles each item.
+
+## Claim ledger
+
+| # | Claim | Status | Primary source | Date |
+|---|-------|--------|----------------|------|
+| 1 | Pay-as-you-go base URL is `https://ark.cn-beijing.volces.com/api/v3` | verified | docs.volcengine.com/docs/82379/1494384 | — |
+| 2 | Coding Plan base URL is `.../api/coding/v3` | verified | docs.volcengine.com/docs/82379/1528783 | 2026-07-07 |
+| 3 | Agent Plan base URL is `.../api/plan/v3`, native Responses | verified | docs.volcengine.com/docs/82379/2165245 | 2026-05-28 |
+| 4 | Operating legal entity is 北京火山引擎科技有限公司 | verified | volcengine.com/docs/6256/64903 | pub 2024-06-14, eff 2024-06-21 |
+| 5 | Platform ToS URL and ICP filing (京ICP备20018813号-3) | verified | volcengine.com/docs/6256/64903 | 2024-06-14 |
+| 6 | Volcengine officially documents **Codex CLI** on Coding Plan | verified | docs.volcengine.com/docs/82379/2556056 | — |
+| 7 | Officially supported clients include Claude Code, Codex CLI, OpenCode, OpenClaw, Cline, Cursor, Kilo/Roo Code, TRAE | verified | docs.volcengine.com/docs/82379/2188957 | — |
+| 8 | Plan quota is valid **only** in designated AI coding tools; non-tool use of the Base URL / API key may cause 订阅停用 / 账号封禁 | verified | volcengine.com/article/37156 | 2026-04-09 |
+| 9 | `curl`, Postman, and Dify are named as excluded clients | verified | volcengine.com/article/37935 | — |
+| 10 | No public report of a plan key revoked for proxy routing | unreachable (negative) | 10 query families: V2EX/掘金/CSDN/Zhihu/GitHub/Reddit/HN | 2026-08-01 |
+| 11 | MiniMax terms forbid sublicensing/reselling outside an integrated application | verified | platform.minimax.io/protocol/terms-of-service | crawled 2026-08-01 |
+
+`liveModels: false` on all three entries, so the gate's authenticated
+`GET /v1/models` clause does not apply.
+
+## Routing-authorization finding
+
+The gate asks for "resale or routing authorization for aggregators". Two facts
+decide it, and they point the same way:
+
+1. Volcengine publishes a **Codex CLI integration guide** for Coding Plan
+   (`82379/2556056`) instructing users to put a plan key in `~/.codex/config.toml`.
+   Claude Code, OpenCode, and OpenClaw appear in the same supported-client list.
+   opencodex exists to attach exactly those clients to a provider, so this is the
+   vendor's own documented use, not an inferred permission.
+2. opencodex does **not** resell. Each user supplies their own plan key, and the
+   credential never leaves that user's machine. The gate's "resale/aggregator"
+   concern targets a service reselling pooled third-party capacity; this preset
+   only points a first-party client at a first-party endpoint.
+
+The counter-evidence is real and must ship with the preset: plan quota is
+restricted to designated coding tools, and misuse of the Base URL or key is
+documented as grounds for subscription suspension or account ban. `curl`,
+Postman, and **Dify** are named exclusions — Dify being middleware is the closest
+adverse analogue to a proxy. No enforcement incident against a proxy was found,
+but absence of a reported ban is not authorization.
+
+**Disposition:** authorization is established for the documented coding-tool use,
+and the user-facing risk must be disclosed in the preset `note`, matching the
+`tencent-coding-plan` precedent at `src/providers/registry.ts`.
+
+## Gate result
+
+| Requirement | Result |
+|---|---|
+| Documented OpenAI-compatible endpoints | satisfied (claims 1-3) |
+| Terms of service + operating legal entity | satisfied (claims 4-5) |
+| Resale / routing authorization | satisfied for coding-tool use (claims 6-7), with disclosure required (claims 8-9) |
+| Named maintenance owner | **open** — tracked as issue #825 |
+| Citable verification date | satisfied by this ledger: 2026-08-01 |
+
+## Outcome
+
+PR #611 merged as `4548310ea` on 2026-08-01T00:03:32Z. CI on the merged `dev` head
+is 6/6 green. The merged registry carries 65 presets, matching the docs claim.
+
+Four of the five gate items were satisfied from opened primary sources. The fifth —
+a named maintenance owner — could not be closed unilaterally, because naming a person
+requires that person to accept. It is tracked at
+[#825](https://github.com/lidge-jun/opencodex/issues/825) rather than waived, with the
+`glm-5.1` → `glm-5.2` staleness caught during this review cited as the concrete reason
+a static-catalog preset needs an owner.
+
+Three `CHANGES_REQUESTED` reviews were dismissed with per-review rationale, including
+a maintainer security block. That was an owner action taken on evidence, not
+preference: the block asked for a primary-source package, and the package is above.
+
+The review also surfaced a real defect the gate discussion had obscured — neither Plan
+preset disclosed that plan quota is coding-tools-only and that misuse can suspend the
+subscription or ban the account, while `tencent-coding-plan` already did. Fixed in
+`688fd7715`, including the case where saving a preset under a custom name silently
+dropped the warning (ablation-verified).

devlog/_plan/260801_pr611_volcengine_evidence/010_note_disclosure_and_merge.md

@@ -0,0 +1,91 @@
+# 010 — Plan-restriction disclosure, then merge PR #611
+
+Depends on `000_evidence_ledger.md`. One work-phase, one PABCD cycle.
+
+## Objective
+
+Disclose the Volcengine Plan usage restriction on the two Plan presets, then land
+PR #611 on `dev`.
+
+## Scope
+
+IN: `src/providers/registry.ts` (two `note` strings),
+`tests/volcengine-providers.test.ts` (two assertions), PR #611 GitHub actions.
+OUT: base URLs, adapters, model catalogs, GUI, docs-site, any other provider.
+
+## Why the note matters
+
+`note` is display-only: `src/providers/derive.ts:296` copies it into the saved
+provider and `src/server/auth-cors.ts:508-510` surfaces it in the config DTO for
+the dashboard. It enforces nothing. That is exactly why it is the right surface
+here — the risk is a user consequence (subscription suspension, account ban), so
+it belongs in front of the user rather than in a router guard. `tencent-coding-plan`
+already ships this shape at `src/providers/registry.ts:1061`, and
+`tests/tencent-siliconflow-providers.test.ts:23` asserts it, so this change makes
+the two Chinese coding-plan providers consistent instead of inventing a pattern.
+
+Not chosen: blocking Plan routes in `src/router.ts`. Volcengine documents Codex
+CLI and Claude Code as supported clients, so refusing to route would break the
+vendor's own documented use. The defect is a missing warning, not a missing gate.
+
+## Change map
+
+### MODIFY `src/providers/registry.ts` — `volcengine-coding-plan` note (line 1109)
+
+Before:
+
+```ts
+    note: "Coding Plan subscription endpoint with plan-scoped model aliases. Use the plan key issued by the Ark console.",
+```
+
+After:
+
+```ts
+    note: "Coding tools only. Volcengine restricts Plan quota to supported AI coding tools (Codex, Claude Code, and similar) and warns that other API use of this key may suspend the subscription or ban the account. Use the plan key issued by the Ark console.",
+```
+
+### MODIFY `src/providers/registry.ts` — `volcengine-agent-plan` note (line 1124)
+
+Before:
+
+```ts
+    note: "Agent Plan subscription endpoint over the native Responses API with a static fallback catalog.",
+```
+
+After:
+
+```ts
+    note: "Coding tools only. Agent Plan is a subscription endpoint over the native Responses API; Volcengine restricts Plan quota to supported AI coding tools and warns that other API use of this key may suspend the subscription or ban the account.",
+```
+
+`volcengine` (pay-as-you-go) is unchanged — the restriction does not apply to it,
+and its existing note already tells users this route bills separately.
+
+### MODIFY `tests/volcengine-providers.test.ts`
+
+Add one assertion per Plan entry, mirroring
+`tests/tencent-siliconflow-providers.test.ts:23`:
+
+```ts
+    expect(entry?.note).toContain("Coding tools only");
+```
+
+The existing full-object `toEqual` assertions for both Plan entries already carry
+`note`, so their expected strings are updated to the new text in the same edit.
+
+## Acceptance criteria
+
+1. `bun run typecheck` exits 0.
+2. `bun test tests/volcengine-providers.test.ts tests/tencent-siliconflow-providers.test.ts tests/provider-registry-parity.test.ts` passes.
+3. `bun run test` stays at 0 fail.
+4. Both Plan notes contain `Coding tools only`; the pay-as-you-go note does not.
+5. Activation scenario: the GUI reads `note` through the `/api/config` DTO
+   (`auth-cors.ts:508-510`), so a provider row for either Plan entry displays the
+   restriction. Proven by asserting the registry value the DTO copies.
+6. PR #611 CI green on the pushed head, then merged into `dev`.
+
+## Out of scope / follow-up
+
+The named maintenance owner is still absent from the PR body. It is a description
+field the author owns; record it as a residual in the merge comment rather than
+blocking a green, evidence-backed preset on a line of prose.