docs: clarify README structure before i18n (slim + Codex clarity)#35
Merged
ShunmeiCho merged 4 commits intomainfrom Apr 21, 2026
Merged
docs: clarify README structure before i18n (slim + Codex clarity)#35ShunmeiCho merged 4 commits intomainfrom
ShunmeiCho merged 4 commits intomainfrom
Conversation
Extracts long-form sections to docs/ to reduce README from 784 to ~400 lines before introducing trilingual translation. Also fixes three positioning issues flagged in the v0.6.0 post-release review. Extractions (content preserved in docs/, replaced in README with intent + link): - SSH Notifications setup/manual config/nonce registration/ troubleshooting -> docs/notifications.md (new, 136 lines). README section shrinks from ~120 lines to ~25. - Full command reference (all flags, Windows workflow, environment variables) -> docs/commands.md (new, 69 lines). README section shrinks to the 10 most-used commands. - Four troubleshooting entries already duplicated in docs/troubleshooting.md (SSH ControlMaster, stale sshd, token expired, launchd pngpaste) -> deleted from README. - "Setup fails: killed during re-deployment" -> appended to docs/troubleshooting.md (was README-only). Content fixes (no extraction, just correctness): - Headline: clarified that notifications apply to Claude Code and Codex CLI, not opencode (which is listed but notifications are⚠️ in the Supported Remote CLIs table — avoid headline overclaim). - Solution data flow: added opencode row (previously only Claude Code and Codex CLI were shown, but opencode is a supported remote CLI since v0.6.0). - Windows Quick Start: added experimental callout with pointer to open #30 (clipboard persistence hardening) so users don't assume v0.6.0 fixed both parts of #27. - Configuration table: collapsed duplicate "top + details" into a single table with a link to docs/commands.md. Out of scope (future PRs): - Any translation work. - i18n scaffold (README.zh-CN.md, README.ja.md, docs/i18n/). - Removing more low-frequency troubleshooting entries — pending evidence from post-release issue frequency. Ref: i18n prep sequence (step 1 of 5).
Promotes the Codex workflow from a collapsed `<details>` block to a first-class Quick Start step so users running Codex CLI don't miss the `--codex` flag on their first install. Targets the "not very clear" complaint raised during v0.6.0 review. Scope: 1. "Which setup command do I run?" decision table at Step 2: maps remote CLI (Claude only / Claude + Codex / opencode / Windows local) to the exact command, with a rule-of-thumb callout so people don't add `--codex` unnecessarily. 2. New Step 3 "what `--codex` adds" — explains the three things `--codex` actually does on the remote (Xvfb, x11-bridge, DISPLAY injection) so users have a model for later troubleshooting. 3. Codex-specific verify block at the Verify section: four commands that check DISPLAY, Xvfb, x11-bridge, and end-to-end xclip negotiation on the remote, with expected outputs. Uses only existing CLI flags — does NOT invent a `cc-clip doctor --codex` flag. 4. "`setup` vs `connect`" table: explains when to use first-time setup vs the repair/redeploy path (`connect --force`, with `--codex` preserved for the Codex variant), plus `--token-only`. Deliberately out of scope: - No changes to How It Works, SSH Notifications, or Related. - No release-notes inlining (badge already shows latest version). - No contributor/agent process regs (those belong in CLAUDE.md). - No invented flags. The Codex verify uses the four commands already documented in the Troubleshooting section. Change: +58/-16 in README.md, no other files touched. TOC is unaffected because new sub-sections are H4/H3 under the existing Quick Start H2.
MEDIUM (README:228) — `setup` vs `connect` table used `cc-clip setup myserver [--codex]` as if the brackets were literal shell syntax. First-time users copy-pasting it would hit `zsh: no matches found: [--codex]`. Split the column into two explicit commands (Claude-only / Claude + Codex), each a ready-to-paste string. Reverted the bracket-annotation anti-pattern at the same time. MEDIUM (README:247) — the Mermaid diagram and numbered path list under "How It Works" omitted opencode, even though the Solution data-flow block at README:59 and the Supported Remote CLIs table both call it out. This is exactly the canonical-source inconsistency that would get multiplied into the ZH and JA translations, so fix it before the i18n scaffold: - Added an `M["opencode"]` node to the Mermaid graph routed through the same `xclip / wl-paste shim` edge as Claude Code (shim is now renamed in the diagram to reflect both binaries it intercepts). - Inserted a new numbered path 2 describing the opencode flow explicitly as "same shim as the Claude Code path" so readers don't have to infer it from the diagram. - Expanded the Codex path 4 annotation with the `arboard` reason for why that path needs its own Xvfb/x11-bridge instead of the shim. No LOW items fixed in this commit: - LOW on `--from-codex-stdin` not appearing in `cc-clip --help` is a CLI gap, not a doc gap (the flag does work). Tracking separately. - LOW on "slim to 400" framing applied to chat context, not the PR body (which already reads "-20% from 784 to 631").
Review flagged that the "two sudo-requiring contents" (Xvfb install on Debian/Ubuntu via apt, on RHEL/Fedora via dnf) were mentioned only in Step 3's parenthetical and in the Requirements section — after users had already decided to add --codex. Users on servers without passwordless sudo would walk through the entire setup flow before discovering they need to open a ticket with IT. Fixes: 1. Decision table now has a fourth column "Remote sudo needed?" with check/cross per workflow. Only the Claude + Codex row needs sudo; Claude-only, opencode, and Windows workflows do not. 2. A new callout directly under the table explains the sudo prerequisite, the two package-manager commands, the abort-and-retry flow, and the fallback (skip --codex if neither passwordless sudo nor manual install is possible). 3. Step 3 bullet 1 (Xvfb) promotes the sudo requirement from a parenthetical to a bolded "Requires sudo" statement so readers skimming the "what --codex adds" section also see it. Semantics-preserving: no new prerequisites invented, just made existing ones visible at the decision point rather than after commitment.
4 tasks
ShunmeiCho
added a commit
that referenced
this pull request
Apr 21, 2026
* docs(i18n): scaffold for EN/ZH/JA README and subdocs Step 2 of the 5-step i18n sequence agreed in the review of #35. Sets up the skeleton so translation work can start without having to re-litigate layout, marker convention, or voice rules. No translation content lands in this commit. Every added file is either scaffolding or a stub that directs readers to the English canonical until real translations land. Added: - README.zh-CN.md, README.ja.md: stubs carrying the language switcher, the canonical-English disclaimer, and the `i18n-source` marker comment (pinned to d15a990, the current README.md HEAD). - docs/i18n/TRANSLATION_BRIEF.md: voice / tone / structure / source-marker rules for Simplified Chinese and Japanese. Covers what does and does not get translated, how translated files track the English source by commit SHA, the mandatory disclaimer, and the per-file review checklist. - docs/i18n/glossary.md: 17 core terms in EN / 简体中文 / 日本語 with notes on when to keep English. Includes a list of non- translated surface (command names, flags, env vars, GitHub IDs). - docs/zh-CN/README.md, docs/ja/README.md: directory placeholders explaining the purpose, listing future-translated subdocs, and linking back to the rules. Modified: - README.md: added the language switcher bar at the top so readers landing on the canonical English file can see translated versions exist once they're filled in. Current-language entry is bold; others link. Out of scope (future PRs): - Actually translating any content into Chinese or Japanese. - i18n sync-check CI using the source-hash markers. - Translation of docs/troubleshooting.md, docs/windows-quickstart.md, docs/notifications.md, docs/commands.md. CI impact: none. `make test` passes; only markdown files added. * docs(i18n): use full commit SHA in i18n-source marker The stubs in README.zh-CN.md and README.ja.md used a 7-char short SHA (d15a990), but docs/i18n/TRANSLATION_BRIEF.md mandates the full 40-char SHA and specifies `git log -1 --format=%H` as the command to obtain it. Self-inconsistency flagged in #37 review. Replaced short with the full hash resolved by `git log -1 --format=%H -- README.md` at d15a990: d15a990 This keeps the scaffold compliant with its own stated convention, so the i18n-sync-check CI (step 5 of the i18n sequence) can be implemented assuming every marker is a full SHA and will not need a short/long normalization layer. Files touched: README.zh-CN.md, README.ja.md only.
4 tasks
ShunmeiCho
added a commit
that referenced
this pull request
Apr 22, 2026
Closes #36. `cc-clip notify` supports two mutually-exclusive Codex JSON input modes, both implemented in cmd/cc-clip/main.go:1510-1511: - `--from-codex "$1"` — parse JSON passed as a string argument - `--from-codex-stdin` — read JSON from stdin docs/commands.md has documented both since its creation in #35, and the flags work correctly at runtime, but the top-level `cc-clip` help text only listed `--from-codex`. Users running `cc-clip | grep notify` (or skimming the help output for available flags before reading docs/) would not discover the stdin variant. Fix is pure help-text: add `--from-codex-stdin` below `--from-codex` with a description that flags the mutual-exclusivity constraint (which the runtime already enforces at main.go:1522, but was not visible to help-only readers). Column alignment widened to 21 characters so the longest flag name fits without misalignment across the whole block. Verified via: go build -o /tmp/cc-clip-test ./cmd/cc-clip /tmp/cc-clip-test | grep -A7 '^Notifications:' shows the new line in the expected position. `make test` passes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Supersedes #34. Combines README structural slim-down with the Codex setup clarity work, as planned in the i18n prep sequence: stabilize the English canonical before starting translation.
Why now
Before introducing trilingual README (EN / ZH / JA), the English source needs to be:
This PR is step 1 of the 5-step i18n sequence agreed in review:
What landed
Codex setup clarity (was #34)
Promoted from
<details>collapsible to a first-class Quick Start step:--codexadds" explaining Xvfb + x11-bridge + DISPLAY injectioncc-clip doctor --codex)setupvsconnectdecision tableStructural extractions
docs/notifications.md(new, 136 lines)docs/commands.md(new, 69 lines)docs/troubleshooting.md(SSH ControlMaster, stale sshd, token expired, launchd pngpaste)docs/troubleshooting.mdPositioning fixes (flagged in v0.6.0 post-release review)
docs/commands.md.Result
README.md: 784 → 631 lines (-20%)docs/notifications.md: new, 136 lines (extracted content)docs/commands.md: new, 69 lines (extracted content)docs/troubleshooting.md: 156 → 170 (appended "Setup fails killed")Net: ~45 lines of pure duplication deleted; ~150 lines of extracted content moved to discoverable docs/ files.
Deliberately NOT in this PR
README.zh-CN.md,README.ja.md,docs/i18n/) — separate PRcc-clip doctor --codexinvented flagVerification
cc-clip --help— every command referenced in README Commands section existsdocs/*.mdcross-links resolved against actual file pathsRelation to other PRs