Skip to content

Commit db28385

Browse files
lidge-junlidge-jun
committed
docs: flatten structure source of truth
1 parent ef2cf1c commit db28385

7 files changed

Lines changed: 81 additions & 33 deletions

‎structure/00_overview.md‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,15 @@ belong in `docs-site/`; historical investigations belong in `docs/`.
55

66
## Reading order
77

8-
| Folder | Purpose |
8+
| File | Purpose |
99
| --- | --- |
10-
| [`runtime/`](runtime/) | Process lifecycle, CLI, server endpoints, config, providers, adapters, GUI API. |
11-
| [`codex/`](codex/) | `CODEX_HOME`, config injection, shared catalog, Codex App, subagent ordering. |
12-
| [`transports/`](transports/) | Responses HTTP/SSE, optional WebSocket advertisement, sidecars, native passthrough. |
13-
| [`docs-release/`](docs-release/) | Public docs site, GitHub Pages publishing, release/build ownership. |
10+
| [`00_overview.md`](00_overview.md) | Product boundary, local state, and non-negotiable invariants. |
11+
| [`01_runtime.md`](01_runtime.md) | Process lifecycle, CLI, server endpoints, config, providers, adapters. |
12+
| [`02_config-and-codex-home.md`](02_config-and-codex-home.md) | `CODEX_HOME`, config injection, profile files, restore rules. |
13+
| [`03_catalog-and-subagents.md`](03_catalog-and-subagents.md) | Shared Codex catalog, Codex App picker, subagent ordering. |
14+
| [`04_transports-and-sidecars.md`](04_transports-and-sidecars.md) | Responses HTTP/SSE, WebSocket opt-in, sidecars, compatibility guards. |
15+
| [`05_gui-and-management-api.md`](05_gui-and-management-api.md) | Dashboard serving and `/api/*` management surface. |
16+
| [`06_docs-and-release.md`](06_docs-and-release.md) | Public docs site, GitHub Pages, README ownership, release flow. |
1417

1518
## Product boundary
1619

@@ -49,3 +52,9 @@ configured `defaultProvider`.
4952
- Routed model slugs use `provider/model`.
5053
- Codex `spawn_agent` visibility depends on the first five featured catalog entries.
5154
- `ocx stop`, `ocx restore`, and service stop/uninstall must leave native Codex usable.
55+
56+
## Writing rule
57+
58+
Keep this directory flat. Add or extend lexicographically ordered `NN_topic.md` files; do not add
59+
subdirectories. If one file grows too broad, split the next stable topic into the next unused number
60+
instead of creating nested folders.

structure/runtime/README.md renamed to structure/01_runtime.md

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,3 @@ uninstall still restore.
3232

3333
Adapter output must stay in internal `AdapterEvent` form until `bridge.ts` converts it back to
3434
Responses SSE or WebSocket frames.
35-
36-
## Dashboard API
37-
38-
The bundled React dashboard is served from `gui/dist` by the same proxy. `ocx gui` starts the proxy
39-
when needed and opens `http://localhost:<port>`.
40-
41-
Management endpoints live in `src/server.ts` under `/api/*`: config get/put, provider CRUD, models,
42-
disabled models, OAuth login/status/logout, key-provider presets, subagent models, and logs. `GET
43-
/api/config` masks API keys; provider writes must not round-trip masked keys as real secrets.

structure/codex/README.md renamed to structure/02_config-and-codex-home.md

Lines changed: 5 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Codex Integration SOT
1+
# Config And Codex Home SOT
22

33
## Codex home
44

@@ -35,25 +35,11 @@ blocks, stale root context-window overrides, and stale opencodex catalog paths b
3535

3636
`supports_websockets = true` is appended only when `websocketsEnabled(config)` returns true.
3737

38-
## Shared catalog
38+
## Profile and fast tier
3939

40-
`src/codex-catalog.ts` builds a shared Codex-shaped catalog for CLI, TUI, App, and SDK. It:
41-
42-
- preserves native OpenAI entries from the live catalog or static fallback;
43-
- clones a native template for routed `provider/model` entries;
44-
- forces strict Codex catalog fields required by the current parser;
45-
- hides `disabledModels`;
46-
- strips native-only service tier and WebSocket metadata unless explicitly enabled;
47-
- backs up the pristine catalog once to `~/.opencodex/catalog-backup.json`;
48-
- invalidates `$CODEX_HOME/models_cache.json` when model visibility changes.
49-
50-
Codex App model picker visibility comes from this shared catalog, not from patching the App.
51-
52-
## Subagents
53-
54-
Codex `spawn_agent` advertises only the highest-priority first five catalog models. `subagentModels`
55-
is capped at five ids and may contain routed `provider/model` slugs or native model slugs. Startup
56-
seeds native GPT defaults only when the field is unset; an explicit empty list persists.
40+
opencodex also writes `$CODEX_HOME/opencodex.config.toml` as an explicit profile target. Codex config
41+
uses `service_tier = "fast"` and `[features].fast_mode = true`; catalog/request tier metadata may use
42+
`priority`. Do not collapse these spellings into one value.
5743

5844
## Restore
5945

‎structure/03_catalog-and-subagents.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Catalog And Subagents SOT
2+
3+
## Shared catalog
4+
5+
`src/codex-catalog.ts` builds a shared Codex-shaped catalog for CLI, TUI, App, and SDK. It:
6+
7+
- preserves native OpenAI entries from the live catalog or static fallback;
8+
- clones a native template for routed `provider/model` entries;
9+
- forces strict Codex catalog fields required by the current parser;
10+
- hides `disabledModels`;
11+
- strips native-only service tier and WebSocket metadata unless explicitly enabled;
12+
- backs up the pristine catalog once to `~/.opencodex/catalog-backup.json`;
13+
- invalidates `$CODEX_HOME/models_cache.json` when model visibility changes.
14+
15+
Codex App model picker visibility comes from this shared catalog, not from patching the App.
16+
17+
## Entry shape
18+
19+
Routed entries keep Codex-required metadata such as reasoning levels, shell type, API support flags,
20+
base instructions, modalities, auto-compact fields, and strict parser booleans. The public slug and
21+
display name use `provider/model`.
22+
23+
## Native passthrough
24+
25+
Native OpenAI entries remain available for ChatGPT passthrough. Routed non-OpenAI models must not
26+
inherit native-only service tier or WebSocket metadata unless the user explicitly enables that
27+
capability.
28+
29+
## Subagents
30+
31+
Codex `spawn_agent` advertises only the highest-priority first five catalog models. `subagentModels`
32+
is capped at five ids and may contain routed `provider/model` slugs or native model slugs. Startup
33+
seeds native GPT defaults only when the field is unset; an explicit empty list persists.

structure/transports/README.md renamed to structure/04_transports-and-sidecars.md

File renamed without changes.

‎structure/05_gui-and-management-api.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# GUI And Management API SOT
2+
3+
## Dashboard serving
4+
5+
The bundled React dashboard is built into `gui/dist` and served by the same Bun proxy. `ocx gui`
6+
starts the proxy when needed and opens `http://localhost:<port>`.
7+
8+
## API ownership
9+
10+
Management endpoints live in `src/server.ts` under `/api/*`:
11+
12+
| Endpoint area | Responsibility |
13+
| --- | --- |
14+
| Config | Read/write `~/.opencodex/config.json`; mask secrets on read. |
15+
| Providers | Create/update/delete provider configs and enrich registry metadata. |
16+
| Models | Fetch routed model lists, disabled model visibility, and catalog-facing ids. |
17+
| OAuth | Login/status/logout for OAuth-backed providers. |
18+
| Key providers | Expose API-key provider presets for setup and dashboard flows. |
19+
| Subagents | Read/write the featured `subagentModels` list capped at five ids. |
20+
| Logs | Surface request/runtime logs for local diagnosis. |
21+
22+
Provider writes must not round-trip masked API keys as real secrets. Dashboard actions that change
23+
model visibility or subagent selection should trigger catalog/cache sync behavior through the server
24+
path that owns it.
25+
26+
## UX boundary
27+
28+
The dashboard is a local control surface, not a separate service. It should reflect the same config
29+
and catalog invariants documented in this folder rather than inventing parallel state.

structure/docs-release/README.md renamed to structure/06_docs-and-release.md

File renamed without changes.

0 commit comments

Comments
 (0)