|
| 1 | +# 050 — Phase 5: user-facing docs + hardening |
| 2 | + |
| 3 | +Second work-phase of this unit, appended after the four implementation phases |
| 4 | +closed (LOOP-UNIT-CHAIN-01). The feature ships; nothing tells a user it exists. |
| 5 | + |
| 6 | +## Why this phase exists |
| 7 | + |
| 8 | +`ocx export` and the GUI panel landed in `f7ac037e0`. A grep of `docs-site/` |
| 9 | +finds: |
| 10 | + |
| 11 | +- `reference/cli.md` — the command table lists `ocx access`, `ocx config`, |
| 12 | + `ocx observe`. There is no `ocx export` row and no subcommand section. |
| 13 | +- `guides/opencode.md` — 106 lines about `ocx opencode`. It states "your own |
| 14 | + config is never modified", which is still true, but there is now a supported |
| 15 | + way to GET the block into your own config and the guide does not mention it. |
| 16 | +- Pi — no guide, no mention anywhere in the repo. |
| 17 | +- BYOK — the term appears nowhere in `src/`, `gui/`, or `docs-site/`. |
| 18 | + |
| 19 | +A feature a user cannot discover is not shipped. |
| 20 | + |
| 21 | +## The BYOK question |
| 22 | + |
| 23 | +The user asked for "byok 같은 곳 설정하는 법". Read against the tree, BYOK here |
| 24 | +is not a new subsystem — it is the **credential half** of the export story, and |
| 25 | +it spans two different keys that are easy to confuse: |
| 26 | + |
| 27 | +| Key | What it is | Where it goes | |
| 28 | +|-----|-----------|---------------| |
| 29 | +| Proxy admission (`ocx_…`) | opencodex's own key, generated on the API tab | the exported config's env reference | |
| 30 | +| Provider key (`sk-…`, etc.) | your Anthropic/OpenAI/OpenRouter key | `providers.<name>.apiKey` in opencodex config | |
| 31 | + |
| 32 | +The export flow only ever references the FIRST. The second is what "bring your |
| 33 | +own key" normally means, is documented in `guides/providers.md` §Auth modes and |
| 34 | +`reference/configuration.md` (`apiKey`, `apiKeyPool`, `${ENV_VAR}`), and is NOT |
| 35 | +re-documented here — this phase links to it instead of forking a second |
| 36 | +explanation that would drift. |
| 37 | + |
| 38 | +What is genuinely missing is the seam: a reader who exports a config has no |
| 39 | +page telling them which key the `{env:...}` reference wants, how to generate |
| 40 | +it, or that a loopback proxy does not require one at all. |
| 41 | + |
| 42 | +## Scope |
| 43 | + |
| 44 | +IN |
| 45 | +- MODIFY `docs-site/src/content/docs/reference/cli.md` — command table row + |
| 46 | + an `ocx export` subcommand section. |
| 47 | +- MODIFY `docs-site/src/content/docs/guides/opencode.md` — a section on taking |
| 48 | + the provider block into your own config, pointing at `ocx export`. |
| 49 | +- NEW `docs-site/src/content/docs/guides/pi.md` — the Pi guide, including the |
| 50 | + credential seam. |
| 51 | +- Locale sync for any translated page whose English source changed, per |
| 52 | + AGENTS.md ("keep translated locales from contradicting the English source"). |
| 53 | + |
| 54 | +OUT |
| 55 | +- No `src/` or `gui/` behavior change. This phase is docs + whatever hardening |
| 56 | + the docs review exposes, and a code change discovered here becomes its own |
| 57 | + amendment rather than a silent edit. |
| 58 | +- No re-documentation of provider auth modes; link to `guides/providers.md`. |
| 59 | +- No new BYOK subsystem. BYOK is an existing capability, not a feature to add. |
| 60 | + |
| 61 | +## Hardening review (the docs pass doubles as an adversarial read) |
| 62 | + |
| 63 | +Writing the docs forces every claim to be checked against the shipped code. |
| 64 | +Four claims to verify while writing, each a real failure if wrong: |
| 65 | + |
| 66 | +1. **The destination path we print is the one Pi/OpenCode actually reads.** |
| 67 | + `EXPORT_CLIENTS.*.destination` honors `XDG_CONFIG_HOME` for OpenCode. |
| 68 | + Pi's path is still UNVERIFIED against a real install (`001` §2) — the guide |
| 69 | + must say so rather than assert it. |
| 70 | +2. **The env var name in the docs matches the one in the emitted config.** |
| 71 | + `OPENCODEX_OPENCODE_API_KEY` for OpenCode, `OPENCODEX_API_KEY` for Pi. Two |
| 72 | + different names; a doc that mixes them sends the reader in a circle. |
| 73 | +3. **A loopback-only user needs no key at all.** `shouldInjectApiAuthHeader` |
| 74 | + decides this. If the docs tell every reader to generate a key, most readers |
| 75 | + do unnecessary work; if they tell nobody, non-loopback binds break. |
| 76 | +4. **The merge warning is in the docs, not just the CLI.** The download and the |
| 77 | + `--out` refusal both exist because replacing an existing config destroys |
| 78 | + other providers. The docs must carry the same warning. |
| 79 | + |
| 80 | +## Accept criteria |
| 81 | + |
| 82 | +1. `ocx export` appears in the `reference/cli.md` command table AND has a |
| 83 | + subcommand section documenting `--client`, `--json`, `--out`, `--force`. |
| 84 | + **Activation:** grep the built page for `ocx export`. |
| 85 | +2. The Pi guide states the exact destination path, the exact env var, and marks |
| 86 | + the Pi schema as unverified against a real install. |
| 87 | +3. Every env var name in the new docs matches the string the code emits. |
| 88 | + **Activation:** grep `OPENCODEX_OPENCODE_API_KEY` / `OPENCODEX_API_KEY` in |
| 89 | + both `src/clients/config-export.ts` and the new docs; the sets must agree. |
| 90 | +4. The docs state that loopback binds need no admission key, and that a config |
| 91 | + must be merged rather than used to replace an existing file. |
| 92 | +5. `bun run privacy:scan` green — the new docs use `~/…`, never a real home path. |
| 93 | +6. Docs build passes. |
0 commit comments