Skip to content

docs: clarify README structure before i18n (slim + Codex clarity)#35

Merged
ShunmeiCho merged 4 commits intomainfrom
docs/slim-readme-for-i18n
Apr 21, 2026
Merged

docs: clarify README structure before i18n (slim + Codex clarity)#35
ShunmeiCho merged 4 commits intomainfrom
docs/slim-readme-for-i18n

Conversation

@ShunmeiCho
Copy link
Copy Markdown
Owner

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:

  1. Smaller — translation cost scales with line count × 3 languages.
  2. Stable — otherwise every structural change in English means three downstream updates.
  3. Free of positioning errors — overclaims and duplications will be faithfully translated and become harder to fix later.

This PR is step 1 of the 5-step i18n sequence agreed in review:

  1. README structural slim + clarity ← this PR
  2. i18n scaffold (separate PR; adds stubs, language bar, glossary, TRANSLATION_BRIEF.md)
  3. README translation (separate PR)
  4. Subdoc translation (separate PR)
  5. i18n sync-check CI (separate PR; uses source-hash markers, not time diffs)

What landed

Codex setup clarity (was #34)

Promoted from <details> collapsible to a first-class Quick Start step:

  • "Which setup command do I run?" decision table
  • New Step 3 "what --codex adds" explaining Xvfb + x11-bridge + DISPLAY injection
  • Codex-specific verify block (uses only existing CLI flags — no invented cc-clip doctor --codex)
  • setup vs connect decision table

Structural extractions

From To Lines saved
SSH Notifications setup / manual config / nonce registration / troubleshooting docs/notifications.md (new, 136 lines) ~95
Full command reference + env vars docs/commands.md (new, 69 lines) ~60
4 troubleshooting entries that duplicated docs/troubleshooting.md (SSH ControlMaster, stale sshd, token expired, launchd pngpaste) deleted (already in docs) ~45
"Setup fails: killed during re-deployment" (was README-only) appended to docs/troubleshooting.md kept

Positioning fixes (flagged in v0.6.0 post-release review)

  • Headline notification claim: "receive notifications … Claude Code, Codex CLI & opencode" → "notifications for Claude Code and Codex CLI" (opencode notifications are ⚠️ in the Supported Remote CLIs table; headline was overclaiming).
  • Solution data flow: added opencode row (previously only Claude Code and Codex CLI).
  • Windows status: added experimental callout in Quick Start pointing to open fix: harden Windows clipboard persistence (#27 part 2) #30 (clipboard persistence hardening), so users don't assume v0.6.0 fixed both parts of issue Windows: clipboard empty after paste + hotkey conflicts with paste keystroke #27.
  • Configuration table: collapsed duplicated "top + details" split into a single table with a link to 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

  • No translation work (step 2-4 of the sequence)
  • No i18n scaffold (README.zh-CN.md, README.ja.md, docs/i18n/) — separate PR
  • No more aggressive troubleshooting trim — keeping Codex Ctrl+V step-by-step verify in README because it's the Codex-specific fix recipe that non-obvious users land on
  • No cc-clip doctor --codex invented flag

Verification

  • cc-clip --help — every command referenced in README Commands section exists
  • All docs/*.md cross-links resolved against actual file paths
  • TOC unchanged (extractions only remove H3/H4 under existing H2s)
  • Codex clarity content reverse-validated with test in feat: support opencode clipboard invocations out of the box #32 still passing after cherry-pick

Relation to other PRs

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.
@ShunmeiCho ShunmeiCho merged commit d15a990 into main Apr 21, 2026
@ShunmeiCho ShunmeiCho deleted the docs/slim-readme-for-i18n branch April 21, 2026 16:50
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.
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant