docs(voice): clarify client transport and proxy ownership

[lidge-jun]

Summary

Document Codex's ownership of local audio, WebRTC, captions and spoken handoffs, and OpenCodex's ownership of call creation, sideband relay and delegated text routing. Explain metadata-only diagnostics and why service-tier speed descriptions do not establish voice latency or a desktop rollout date.

Manual stack: depends on #3968. This cumulative head includes the runtime fix; retarget to dev after the parent lands and merge bottom-up.

Verification

• Cross-platform CI 34174322981: 26/26 jobs passed on exact cumulative head 16ddf43c92f7cfa164a6bcb0d80101abc9450b81, based on dev 900567af3.
• Pinned upstream WebRTC and TUI source inspected, with an independent Aside source-fetch route. Aside reached its CLI deadline before saving a final report; source observations were retained.
• Independent final code/documentation/security review: PASS. git diff --check: PASS. No unresolved review threads.
• Local product tests, typecheck, build and installation: NOT RUN, as explicitly instructed.
• Docs-site build: NOT RUN; its existing build workflow also deploys, which is outside this task. Prose/link/source consistency was reviewed.
• Microphone/audio behavior and end-to-end latency: NOT MEASURED.

Maintainer integration decision: acting as lidge-jun under MAINTAINERS.md, integrate into dev without a second maintainer approval after the parent lands. Revalidate current head/base/actor and prospective merge-tree equality with the verified cumulative tree. This is maintainer integration, not self-approval.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Landing verified: #3968 merged as ac84ab2c5cf767d1ca7cd5612cdc80348b1e6139; #3969 merged as 9e1468d4b7a41b498ed2aca98507ada2c741afea. Fetched dev contains the tested cumulative head, and both trees are exactly 68b6eb5a5644b19e321be916de8b4d6429174648. The only merge-generated duplicate product CI (parent push run 34176133959) was cancelled; it is not verification evidence.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (2)

• ^dev$
• ^preview$

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: f31fffb6-344f-4c27-b531-a12d13ffb2e7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-07T23:42:25.532213Z	704839d	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[lidge-jun]

리뷰 · 우선순위 48 / 80

이 PR은 Codex 음성 클라이언트와 OpenCodex 프록시의 소유 경계를 docs-site 가이드에 글로 고정하는 문서-only 레이어다. base가 dev가 아니라 형제 구현 브랜치 codex/voice-relay-0908(#3968)이라, 단독으로 dev에 얹히면 안 되고 #3968이 먼저 또는 함께 누적 검증된 뒤에야 의미가 있다. 지금 dev HEAD(bbea77a48) 기준으로 Voice live 구현·진단 스키마 변경은 #3968에 있고, 이 PR은 그 결과를 사용자/기여자 가이드 언어로 옮긴다.

무엇을 말하나. Codex가 마이크·스피커·WebRTC·캡션·mute·스레드 전환 cleanup을 갖고, OpenCodex는 call-create와 sideband 릴레이·위임된 텍스트의 일반 Responses 라우팅만 맡는다는 점. 텍스트 provider를 고른다고 realtime speech 모델이 바뀌거나, voice 미지원 클라이언트에 음성이 켜지지 않는다는 점. upstream Codex 커밋 두 개(WebRTC helper / TUI voice)는 클라이언트 책임을 설명하는 참고이고, merge 날짜가 데스크톱 앱 출시 시점을 증명하지 않는다는 점. 선택 진단 OCX_LIVE_FRAME_LOG는 ts/dir/kind/bytes/fffd만 남기고 본문·excerpt는 저장하지 않으며, 바이너리 UTF-8 decode가 스스로 U+FFFD를 만들 수 있어 플래그만으로 책임 peer를 단정하면 안 된다는 점. Fast mode / service-tier 설명은 마이크·WebRTC·종단 voice 지연을 보장하지 않는다는 점. 이 문장들은 #3968의 structure/04_transports-and-sidecars.md 보강과 같은 계약을 사용자 가이드 쪽으로 복제한다.

왜 점수가 구현 PR보다 낮은가. 코드 경로·동작은 #3968이 바꾸고, 이 PR은 가이드 한 파일(docs-site/src/content/docs/guides/codex-integration.md) +23줄이다. dev 방향(라우팅/namespace·릴리즈 2.48.0 라인)과 충돌하지 않고 types/config split과도 무관하다. 가치는 “기여자가 upstream Codex 음성 커밋을 보고 OpenCodex가 지연을 깎아 줄 것처럼 오해하거나, 진단 로그에 transcript가 남는다고 가정하는 것”을 막는 데 있다. 누적 헤드가 Cross-platform CI의 최종 증거 지점이라는 스택 규칙과도 맞다.

docs-site/.../codex-integration.md Voice 절 - 소유 경계와 “텍스트 provider ≠ voice enable”이 초등학생도 읽히게 쓰여 있다. 좋다.
같은 절 upstream 링크 - 핀 커밋을 직접 걸어 두어 출처가 명확하다. 다만 링크만으로 “OpenCodex가 그 동작을 그대로 구현했다”로 읽히지 않게, 이미 있는 “클라이언트 책임” 문장이 앞에 있어 오해 여지는 작다.
OCX_LIVE_FRAME_LOG 문단 - #3968 스키마와 키가 일치한다. #3968이 머지되기 전 가이드만 단독 머지되면 문서가 아직 context를 쓰는 코드를 거짓으로 설명하게 되므로, 반드시 스택 순서를 지켜야 한다.
Fast mode 보강 - Fast tier 메타와 voice 지연을 분리한 문장은 최근 소스 비교(001_sources.md)와 맞다. 과장 광고를 막는 유지보수에 도움이 된다.
파일 범위 - production 코드·테스트 변경이 없다. 문서 PR로서 범위가 깨끗하다.

메인테이너의 판단이 필요한 지점

• fix(voice): keep diagnostic logs free of frame content #3968 머지 직후 이 PR base를 dev로 retarget할지, merge commit으로 스택 ancestry를 유지한 채 올릴지 (본문은 후자를 요청)
• 가이드에만 두고 structure/04_…와 가이드 사이 중복을 장기적으로 한쪽으로 수렴할지
• 누적 헤드 CI가 끝나기 전 preview/docs-site 미리보기가 필요한지 (보통은 불필요)

너의 추천
#3968이 누적 CI와 함께 통과한 뒤 bottom-up으로 머지하고, 이어서 이 docs PR을 올린다. 내용 자체는 머지해도 된다. #3968보다 먼저 단독 머지하지 말 것. labels는 건드리지 않았다.

이 댓글은 grok-bot이 작성했습니다

[github-actions]

✅ Deterministic PR hygiene checks passed.

[Ingwannu]

Independent documentation-build evidence for the exact cumulative head 3468a2d: the Astro build completed successfully with 425 pages in an isolated checkout. I reused a dependency installation with the identical frozen docs lockfile and used fresh HOME/OPENCODEX_HOME/CODEX_HOME, reduced CPU priority, and an eight-core cap. No install, deployment, microphone test, service restart, or production configuration write was performed. Existing chunk-size and missing 404-content warnings remain.

This fills the non-deploying build gap described in the PR, not the runtime or live-audio validation gap. Full cumulative CI run 34172698360 is still the separate exact-head gate; cancelled per-layer jobs are not passing evidence. Keep the parent-first landing order for #3968 and this child. This comment is build evidence only, not final approval of the entire voice stack.