@litfamily/litcodex 1.0.7 → 1.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/README-Ko-KR.md +207 -0
  2. package/README.md +155 -576
  3. package/dist/install/doctor-render.js +1 -0
  4. package/dist/install/doctor.js +8 -0
  5. package/dist/install/generated-skill-payload-hashes.d.ts +2 -2
  6. package/dist/install/generated-skill-payload-hashes.js +2 -2
  7. package/dist/install/types.d.ts +3 -0
  8. package/marketplace/plugins/litcodex/.codex-plugin/plugin.json +1 -1
  9. package/marketplace/plugins/litcodex/components/auto-update/package.json +1 -1
  10. package/marketplace/plugins/litcodex/components/comment-checker/package.json +1 -1
  11. package/marketplace/plugins/litcodex/components/git-bash/package.json +1 -1
  12. package/marketplace/plugins/litcodex/components/lit-loop/dist/hook-cli.d.ts +8 -1
  13. package/marketplace/plugins/litcodex/components/lit-loop/dist/hook-cli.js +36 -4
  14. package/marketplace/plugins/litcodex/components/lit-loop/dist/jev-hint.d.ts +123 -0
  15. package/marketplace/plugins/litcodex/components/lit-loop/dist/jev-hint.js +553 -0
  16. package/marketplace/plugins/litcodex/components/lit-loop/package.json +1 -1
  17. package/marketplace/plugins/litcodex/components/lsp/package.json +1 -1
  18. package/marketplace/plugins/litcodex/components/rules/package.json +1 -1
  19. package/marketplace/plugins/litcodex/components/start-work-continuation/package.json +1 -1
  20. package/marketplace/plugins/litcodex/components/telemetry/package.json +1 -1
  21. package/marketplace/plugins/litcodex/components/wikify-knowledge/package.json +1 -1
  22. package/marketplace/plugins/litcodex/skills/lit-pptx/scripts/office-run.mjs +7 -1
  23. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/runtime.mjs +5 -1
  24. package/node_modules/@litcodex/lit-loop/dist/hook-cli.d.ts +8 -1
  25. package/node_modules/@litcodex/lit-loop/dist/hook-cli.js +36 -4
  26. package/node_modules/@litcodex/lit-loop/dist/jev-hint.d.ts +123 -0
  27. package/node_modules/@litcodex/lit-loop/dist/jev-hint.js +553 -0
  28. package/node_modules/@litcodex/lit-loop/package.json +1 -1
  29. package/package.json +4 -3
  30. package/readme-assets/badge-version.svg +1 -1
package/README.md CHANGED
@@ -1,632 +1,211 @@
1
- <p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: five armored robots power on one by one, the LitCodex robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
2
-
3
- <p align="center"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ascii-readme.svg" width="480" alt="LIT ASCII B mark" /></p>
4
-
5
- <details>
6
- <summary>Copy ASCII logo</summary>
7
-
8
- ```
9
- ▄▄▄▄
10
- ▗███▌ ▗██████▖
11
- ▗▄▄▄▄▄ ▗▟████▌ ▝██████▘
12
- ▐█████ ▗▟██████▌ ▝▀▜█▀▘
13
- ▐█████ ▗▟███████▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
14
- ▐█████ ▗▟█████████████████████████ ▐█▀
15
- ▐█████ ████████████████████████████▀
16
- ▐█████ ██▛▘ ▄ ▄▄▄▄▖▄▄▄▄▄▄▄▄▄▄▄▄▄▖
17
- ▐█████ ▀ ▄██ ████▌█████████████▌
18
- ▐█████ ▄████ ████▌█████████████▌
19
- ▐█████ ▄█████▛
20
- ▐█████ ▗▟█████▀▘ ▄▄▄▄▄ ▗▖
21
- ▐█████ ▐█████▀ █████ ▐▛▀
22
- ▐█████ ▐███▀ █████
23
- ▐█████ ▐█▀ █████
24
- ▐█████ ▝ █████
25
- ▐█████▄▄▄▄▄▄▄▖ █████
26
- ▐███████████▛ █████
27
- ▐██████████▀ █████
28
-
29
- LIT · codex
30
- ```
31
-
32
- </details>
33
-
34
- <p align="center"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/litcodex-wordmark.svg" width="480" alt="LITCODEX display type" /></p>
35
- <p align="center"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/clay-icon.png" width="160" alt="LitCodex clay mark" /></p>
1
+ <p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.9/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.9/readme-assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: five armored robots power on one by one, the LitCodex robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
36
2
 
37
3
  <p align="center">
38
- <a href="#install"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/badge-version.svg" alt="1.0.7" /></a>
39
- <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/badge-license.svg" alt="MIT license" /></a>
4
+ <a href="#install"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.9/readme-assets/badge-version.svg" alt="1.0.9" /></a>
5
+ <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.9/readme-assets/badge-license.svg" alt="MIT license" /></a>
40
6
  </p>
41
7
 
42
8
  <p align="center">
43
- <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/lucide-book-open.svg" width="16" alt="" /> Docs</a> &nbsp; <a href="#install">Install</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
9
+ <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.9/readme-assets/lucide-book-open.svg" width="16" alt="" /> Docs</a> &nbsp; <a href="#install">Install</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.9/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.9/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
44
10
  </p>
45
11
 
46
- # @litfamily/litcodex
12
+ # LitCodex
47
13
 
48
14
  **Keep the work lit.**
49
15
 
50
- [한국어](https://github.com/wjgoarxiv/litcodex/blob/main/README-Ko-KR.md) · [Install](#install) · [Quick start](#activate-lit) · [Key features](#key-features) · [Skills](#skills-at-a-glance) · [Commands](#commands) · [Troubleshooting](#troubleshooting) · [Links](#links)
51
-
52
- ## What is LitCodex
16
+ LitCodex is a plugin for Codex CLI. It adds planning, review, research and a durable execution loop, so a
17
+ piece of work can outlast the conversation it started in. Add `lit` to a request, and the goal, its checks and
18
+ the results stay in your project, where a later session can pick them up.
53
19
 
54
- LitCodex adds planning, review, research, and a durable execution loop to Codex CLI.
20
+ **[Full guide, skills gallery and A/B results on GitHub](https://github.com/wjgoarxiv/litcodex#readme)** · [한국어](https://github.com/wjgoarxiv/litcodex/blob/main/packages/litcodex-ai/README-Ko-KR.md)
55
21
 
56
22
  ## Install
57
23
 
58
- > Install `@litfamily/litcodex@1.0.7` with the scoped command below. See [migration guidance](https://github.com/wjgoarxiv/litcodex/blob/main/docs/npm-migration.md).
59
-
60
- With **Node.js 22+** and **Codex CLI** installed, run:
24
+ You need Node.js 22 or later and Codex CLI.
61
25
 
62
26
  ```sh
63
- npm exec --yes --package @litfamily/litcodex@1.0.7 -- litcodex install
27
+ npm exec --yes --package @litfamily/litcodex@1.0.9 -- litcodex install
64
28
  ```
65
29
 
66
- The installer registers the plugin, hooks, and agents, then updates managed keys in `~/.codex/config.toml`.
67
- It asks for the lead model, helper model, and output style. Codex authentication and model access are required
68
- when you run model work; installation itself does not require GitHub credentials.
69
-
70
- Fresh installs default to `gpt-6-astra` at `xhigh` for the lead route and `gpt-6-luna` at `max` for ordinary helpers. The installer also accepts supported model and effort choices.
30
+ The installer registers the plugin, hooks and agents, and updates the keys it manages in
31
+ `~/.codex/config.toml`. It asks for a lead model, a helper model and an output style; fresh installs default
32
+ to `gpt-6-astra` at `xhigh` for the lead and `gpt-6-luna` at `max` for helpers. To preview first, run
33
+ `npm exec --yes --package @litfamily/litcodex@1.0.9 -- litcodex --dry-run install`; for an unattended setup,
34
+ add `--yes` after `install`.
71
35
 
72
- Preview changes with `npm exec --yes --package @litfamily/litcodex@1.0.7 -- litcodex --dry-run install`. For unattended setup, use
73
- `npm exec --yes --package @litfamily/litcodex@1.0.7 -- litcodex install --yes`. An explicit `--style <id>` still applies.
74
-
75
- For a persistent command:
36
+ For a global command:
76
37
 
77
38
  ```sh
78
39
  npm install -g @litfamily/litcodex
79
40
  litcodex install
80
41
  ```
81
42
 
82
- > Without a global install, use `npm exec --yes --package @litfamily/litcodex@1.0.7 -- litcodex <command>`, such as `npm exec --yes --package @litfamily/litcodex@1.0.7 -- litcodex doctor`.
43
+ A global install runs a postinstall script. Unless `CI` is set, it prints a short welcome and tries to
44
+ pre-warm the runtime for `lit-typographic-motion` in `${XDG_CACHE_HOME:-~/.cache}/litcodex/motion-runtime/`.
45
+ That step uses the network: pinned npm packages come from your registry, pinned font and license files from
46
+ GitHub and apache.org, and no browser is downloaded. If it does not finish, the package stays installed and
47
+ you can retry with `litcodex motion-runtime install`. Add `--ignore-scripts` or set `CI=1` to leave it out.
48
+ `litcodex install` runs the same pre-warm and has no switch to turn it off.
83
49
 
84
- For an isolated trial apart from existing settings, follow the [isolated trial guide](https://github.com/wjgoarxiv/litcodex/blob/main/docs/npm-migration.md#isolated-local-trial).
85
- Changing only `CODEX_HOME` can still discover settings in your existing home.
50
+ > Without a global install, use `npm exec --yes --package @litfamily/litcodex@1.0.9 -- litcodex <command>`.
86
51
 
87
- Windows supports the installer and CLI shims. Descriptor-dependent Python routes require POSIX and fail
88
- closed on Windows with `BLOCKED_UNSUPPORTED_PYTHON_POSIX_RUNTIME`. See [platform and prompt policy](https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md#install).
52
+ To try LitCodex apart from your existing settings, follow the
53
+ [isolated trial guide](https://github.com/wjgoarxiv/litcodex/blob/main/docs/npm-migration.md#isolated-local-trial);
54
+ changing only `CODEX_HOME` is not enough. On Windows the installer and CLI shims work, but Python routes that
55
+ need POSIX stop with `BLOCKED_UNSUPPORTED_PYTHON_POSIX_RUNTIME`.
89
56
 
90
- ## Activate lit
57
+ ## First task
91
58
 
92
- Open Codex in your project, approve the LitCodex hooks in startup review, and type:
59
+ Open Codex in your project, approve the LitCodex hooks in the startup review, and type:
93
60
 
94
61
  ```text
95
62
  lit add input validation to the signup form
96
63
  ```
97
64
 
98
- A bare `lit` selects `<lit-loop-mode>`. The hook emits the same plain-text, five-row activation mark
99
- through `UserPromptSubmit`'s `systemMessage` regardless of terminal color settings. The reply begins with
100
- `🔥 **LIT IGNITED · <discipline>** 🔥`. `split`, `literal`, and `litmus` stay inert.
101
- Code spans and fences are ignored; slash-command-style mentions are ignored except the explicit `/litresearch` research route.
102
-
103
- The exact bare `lit-scientific-visualization` hook route selects
104
- `<lit-scientific-visualization-mode>`; it does not install Python dependencies. Both this and
105
- exact bare `handoff` are exact-only routes.
106
-
107
- ### Make one small thing
65
+ The reply opens with `🔥 **LIT IGNITED · <discipline>** 🔥`. That mark only means the request was routed.
66
+ A goal is complete when every one of its success criteria passes, and the records live under
67
+ `.litcodex/lit-loop/` in your project.
108
68
 
109
- Start in an empty project with a task you can inspect:
69
+ For a first run you can judge yourself, try this in an empty folder:
110
70
 
111
71
  ```text
112
72
  lit build a single-file HTML task list in this folder. Do not install dependencies.
113
73
  Check adding and completing a task, and record anything you could not verify.
114
74
  ```
115
75
 
116
- Look for the result, the checks actually performed, and the unfinished work. A status mark confirms
117
- routing; it does not prove the page works. Ask for `lit recap` to read the recorded state. Before
118
- leaving the session, send exact bare `handoff` as its own message. In the next session, ask Codex
119
- to read that packet and the project goals before continuing.
120
-
121
- | Step | What stays with the work |
122
- | --- | --- |
123
- | Plan | A goal with checks that can pass or fail |
124
- | Make | A small result you can inspect |
125
- | Verify | Evidence for each completed criterion; blockers stay open |
126
- | Hand off | Decisions, remaining work, and where to resume |
127
-
128
- Native Codex goals and the local loop ledger have separate boundaries. A paused or blocked native
129
- goal needs the documented recovery step below; a handoff does not silently resume it.
130
-
131
- ## Key features
132
-
133
- **You have been handed a spark.<br>
134
- Bring it to the work you want to finish.**
135
-
136
- A bug to fix. A screen to build. A project to finish.
137
-
138
- Starting takes a sentence. Picking up where you left off takes more: the decisions you made,
139
- the checks you ran, and the next thing to try.
140
-
141
- **LIT keeps that spark with your project.** Goals, plans, checked results, and next steps stay in
142
- local records that a later session can read. An enduring spark means work you can return to;
143
- it is not a promise that an agent runs forever.
144
-
145
- **Where one conversation ends, the next stretch of work can begin.**
146
-
147
- Plan, execute, and verify work in Codex CLI. Type `lit` to keep goals, checks, and evidence with your project.
148
-
149
- Its `UserPromptSubmit`
150
- hook routes your request into the right discipline; the bundled library provides 40 skills. A goal is complete
151
- only after every success criterion passes. The npm package is self-contained and installs without a GitHub clone.
152
-
153
- Use `lit` to start a bounded task, `handoff` or `/lit-handoff` to carry checked work forward,
154
- `lit-plan` to set criteria before editing, `lit start work <approved-plan>` to execute an approved
155
- plan, `review-work` to inspect the change, and `litresearch` to record sources and uncertainty. Each
156
- route keeps its expected effect in project-local records; no new slash route is introduced here.
157
- Host limit: Codex CLI owns hook and agent execution, while authentication, model access, permissions,
158
- and any visual check remain host capabilities. A route mark or static editorial image is not completion
159
- evidence.
160
-
161
- <p align="center"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/litcodex-ignition-1600.webp" width="49%" alt="LitCodex ignition editorial cue" /> <img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/litcodex-continuity-1600.webp" width="49%" alt="LitCodex continuity editorial cue" /></p>
162
-
163
- ### How it fits together
164
-
165
- Codex hosts the plugin and runs its hooks. The hooks supply routing and context; skills guide the
166
- agent's work. The loop CLI keeps project records and prints instructions for native goal tools.
167
-
168
- ```mermaid
169
- flowchart TD
170
- P["Installed LitCodex plugin"] --> H["Codex hooks: UserPromptSubmit and lifecycle"]
171
- P --> S["Bundled skills"]
172
- U["Your request in Codex"] --> H
173
- H --> A["Codex agent"]
174
- S --> A
175
- A --> L["lit-loop CLI: goals, evidence, checkpoints"]
176
- L --> R["Project records: .litcodex/lit-loop/"]
177
- L -. "goal instructions" .-> A
178
- A -. "native tools, when available" .-> G["Codex native /goal"]
179
- R -. "read when continuing" .-> A
180
- ```
181
-
182
- The dotted native-goal connection is an agent protocol: the package does not call native goal tools
183
- itself. When those tools are unavailable, keep the local records and report that native goal sync
184
- was unavailable. A paused or blocked goal needs the documented recovery step; reading a handoff
185
- does not automatically resume it. [Runtime and state reference](https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md).
186
-
187
- ## Skills at a glance
188
-
189
- Each row is a skill you can start by name or route, with how to start it and what you get. The last row groups the checks that run on their own.
190
-
191
- <table>
192
- <tr><th>What it looks like</th><th>Skill</th><th>What you get</th></tr>
193
- <tr>
194
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-loop.webp" width="240" alt="Add lit to a request. Codex binds the scope, works with evidence and records what it could not verify." /></td>
195
- <td><code>lit-loop</code><br /><sub><code>lit</code> · <code>$litcodex:lit-loop</code></sub></td>
196
- <td>Add <code>lit</code> to a request. Codex binds the scope, works with evidence and records what it could not verify.</td>
197
- </tr>
198
- <tr>
199
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/litwork.webp" width="240" alt="Careful end-to-end build or fix: RED first, then proof on the real surface." /></td>
200
- <td><code>litwork</code><br /><sub><code>litwork</code> · <code>$litcodex:litwork</code></sub></td>
201
- <td>Careful end-to-end build or fix: RED first, then proof on the real surface.</td>
202
- </tr>
203
- <tr>
204
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-plan.webp" width="240" alt="An approved plan in .litcodex/plans/ with numbered rows. Planning only." /></td>
205
- <td><code>lit-plan</code><br /><sub><code>lit plan</code> · <code>$litcodex:lit-plan</code></sub></td>
206
- <td>An approved plan in <code>.litcodex/plans/</code> with numbered rows. Planning only.</td>
207
- </tr>
208
- <tr>
209
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/start-approved-plan.webp" width="240" alt="Runs an approved plan through five gates. All five review lanes must pass at the end." /></td>
210
- <td>Start Work<br /><sub><code>lit start work &lt;approved-plan&gt;</code></sub></td>
211
- <td>Runs an approved plan through five gates. All five review lanes must pass at the end.</td>
212
- </tr>
213
- <tr>
214
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/review-work.webp" width="240" alt="Five blocking review lanes. One failing lane blocks approval." /></td>
215
- <td><code>review-work</code><br /><sub><code>lit review</code> · <code>$litcodex:review-work</code></sub></td>
216
- <td>Five blocking review lanes. One failing lane blocks approval.</td>
217
- </tr>
218
- <tr>
219
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/litgoal.webp" width="240" alt="Binds one goal with observable criteria to the durable lit-loop." /></td>
220
- <td><code>litgoal</code><br /><sub><code>lit goal</code> · <code>$litcodex:litgoal</code></sub></td>
221
- <td>Binds one goal with observable criteria to the durable lit-loop.</td>
222
- </tr>
223
- <tr>
224
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-recap.webp" width="240" alt="A read-only summary: done, in progress, blocked, where the evidence is, what comes next." /></td>
225
- <td><code>lit-recap</code><br /><sub><code>lit recap</code> · <code>$litcodex:lit-recap</code></sub></td>
226
- <td>A read-only summary: done, in progress, blocked, where the evidence is, what comes next.</td>
227
- </tr>
228
- <tr>
229
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-handoff.webp" width="240" alt="Type handoff to get a continuation file the next session can read and resume from." /></td>
230
- <td><code>lit-handoff</code><br /><sub><code>handoff</code> · <code>/lit-handoff</code></sub></td>
231
- <td>Type <code>handoff</code> to get a continuation file the next session can read and resume from.</td>
232
- </tr>
233
- <tr>
234
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/deep-interview.webp" width="240" alt="One question at a time until the idea is clear enough to build. Quick, Standard and Deep set the target." /></td>
235
- <td><code>deep-interview</code><br /><sub><code>deep-interview</code> · <code>$litcodex:deep-interview</code></sub></td>
236
- <td>One question at a time until the idea is clear enough to build. Quick, Standard and Deep set the target.</td>
237
- </tr>
238
- <tr>
239
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/litresearch.webp" width="240" alt="Parallel evidence gathering and a cited synthesis, only when you ask for research." /></td>
240
- <td><code>litresearch</code><br /><sub><code>lit research</code> · <code>$litcodex:litresearch</code></sub></td>
241
- <td>Parallel evidence gathering and a cited synthesis, only when you ask for research.</td>
242
- </tr>
243
- <tr>
244
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-crucible.webp" width="240" alt="Pressure-tests a brief before planning. Only the risks that survive critique reach the plan." /></td>
245
- <td><code>lit-crucible</code><br /><sub><code>lit-crucible</code> · <code>$litcodex:lit-crucible</code></sub></td>
246
- <td>Pressure-tests a brief before planning. Only the risks that survive critique reach the plan.</td>
247
- </tr>
248
- <tr>
249
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-init.webp" width="240" alt="Sparse AGENTS.md guidance backed by what is in the repository." /></td>
250
- <td><code>lit-init</code><br /><sub><code>lit-init</code> · <code>$litcodex:lit-init</code></sub></td>
251
- <td>Sparse AGENTS.md guidance backed by what is in the repository.</td>
252
- </tr>
253
- <tr>
254
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-comprehend.webp" width="240" alt="An explainer page for agent-written work: intuition first, then the walkthrough, then a short quiz." /></td>
255
- <td><code>lit-comprehend</code><br /><sub><code>lit-comprehend</code> · <code>$litcodex:lit-comprehend</code></sub></td>
256
- <td>An explainer page for agent-written work: intuition first, then the walkthrough, then a short quiz.</td>
257
- </tr>
258
- <tr>
259
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-humanizer.webp" width="240" alt="Rewrites stiff model prose in English or Korean. Facts and hedges stay; filler goes." /></td>
260
- <td><code>lit-humanizer</code><br /><sub><code>$litcodex:lit-humanizer</code></sub></td>
261
- <td>Rewrites stiff model prose in English or Korean. Facts and hedges stay; filler goes.</td>
262
- </tr>
263
- <tr>
264
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-diagram-drawer.webp" width="240" alt="A checked, editable diagram for slides and documents, with PNG and Office-safe SVG exports." /></td>
265
- <td><code>lit-diagram-drawer</code><br /><sub><code>$litcodex:lit-diagram-drawer</code></sub></td>
266
- <td>A checked, editable diagram for slides and documents, with PNG and Office-safe SVG exports.</td>
267
- </tr>
268
- <tr>
269
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-pptx.webp" width="240" alt="Ask for slides with lit and get an editable PowerPoint deck with its Markdown source, AZURE-PRO and Pretendard by default. Layout QA runs on the file; rendered slides are inspected when LibreOffice is present." /></td>
270
- <td><code>lit-pptx</code><br /><sub><code>$litcodex:lit-pptx</code></sub></td>
271
- <td>Ask for slides with <code>lit</code> and get an editable PowerPoint deck with its Markdown source, AZURE-PRO and Pretendard by default. Layout QA runs on the file; rendered slides are inspected when LibreOffice is present.</td>
272
- </tr>
273
- <tr>
274
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-docx.webp" width="240" alt="Ask for a report with lit and get a styled Word file with its Markdown source; Korean text uses korean-generic. The file is reopened and linted, and pages are inspected when LibreOffice is present." /></td>
275
- <td><code>lit-docx</code><br /><sub><code>$litcodex:lit-docx</code></sub></td>
276
- <td>Ask for a report with <code>lit</code> and get a styled Word file with its Markdown source; Korean text uses korean-generic. The file is reopened and linted, and pages are inspected when LibreOffice is present.</td>
277
- </tr>
278
- <tr>
279
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-fetch.webp" width="240" alt="Reads a public page with URL, DNS and text-safety checks when ordinary retrieval falls short." /></td>
280
- <td><code>lit-fetch</code><br /><sub><code>$litcodex:lit-fetch</code></sub></td>
281
- <td>Reads a public page with URL, DNS and text-safety checks when ordinary retrieval falls short.</td>
282
- </tr>
283
- <tr>
284
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-scientific-visualization.webp" width="240" alt="A journal-sized figure with vector and 600 DPI exports. The chart type follows the data." /></td>
285
- <td><code>lit-scientific-visualization</code><br /><sub><code>lit-scientific-visualization</code> · <code>$litcodex:lit-scientific-visualization</code></sub></td>
286
- <td>A journal-sized figure with vector and 600 DPI exports. The chart type follows the data.</td>
287
- </tr>
288
- <tr>
289
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-team.webp" width="240" alt="Coordinates several workers with separate slices, each reporting back with evidence." /></td>
290
- <td><code>lit-team</code><br /><sub><code>lit team</code> · <code>$litcodex:lit-team</code></sub></td>
291
- <td>Coordinates several workers with separate slices, each reporting back with evidence.</td>
292
- </tr>
293
- <tr>
294
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/litcodex-doctor.webp" width="240" alt="Checks LitCodex and Codex install health after an update, drift or a failed setup." /></td>
295
- <td><code>litcodex-doctor</code><br /><sub><code>$litcodex:litcodex-doctor</code></sub></td>
296
- <td>Checks LitCodex and Codex install health after an update, drift or a failed setup.</td>
297
- </tr>
298
- <tr>
299
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/litcodex-report-bug.webp" width="240" alt="Drafts a bug report for LitCodex or Codex, backed by sources." /></td>
300
- <td><code>litcodex-report-bug</code><br /><sub><code>$litcodex:litcodex-report-bug</code></sub></td>
301
- <td>Drafts a bug report for LitCodex or Codex, backed by sources.</td>
302
- </tr>
303
- <tr>
304
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/litcodex-contribute-bug-fix.webp" width="240" alt="Turns a diagnosed defect into a tested bug-fix PR." /></td>
305
- <td><code>litcodex-contribute-bug-fix</code><br /><sub><code>$litcodex:litcodex-contribute-bug-fix</code></sub></td>
306
- <td>Turns a diagnosed defect into a tested bug-fix PR.</td>
307
- </tr>
308
- <tr>
309
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/coding-session-audit.webp" width="240" alt="Reads a past Codex session from its evidence and shows where it stopped." /></td>
310
- <td><code>coding-session-audit</code><br /><sub><code>$litcodex:coding-session-audit</code></sub></td>
311
- <td>Reads a past Codex session from its evidence and shows where it stopped.</td>
312
- </tr>
313
- <tr>
314
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/debugging.webp" width="240" alt="Reproduces the bug, tests at least three explanations, and fixes only the confirmed cause." /></td>
315
- <td><code>debugging</code><br /><sub><code>$litcodex:debugging</code></sub></td>
316
- <td>Reproduces the bug, tests at least three explanations, and fixes only the confirmed cause.</td>
317
- </tr>
318
- <tr>
319
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/refactor.webp" width="240" alt="Restructures code while tests pin its behavior before and after every step." /></td>
320
- <td><code>refactor</code><br /><sub><code>$litcodex:refactor</code></sub></td>
321
- <td>Restructures code while tests pin its behavior before and after every step.</td>
322
- </tr>
323
- <tr>
324
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-code.webp" width="240" alt="Strict implementation rules: tests first, typed boundaries, small files." /></td>
325
- <td><code>lit-code</code><br /><sub><code>$litcodex:lit-code</code></sub></td>
326
- <td>Strict implementation rules: tests first, typed boundaries, small files.</td>
327
- </tr>
328
- <tr>
329
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-commit.webp" width="240" alt="Splits your changes into atomic commits in the repo's own style and leaves unrelated work alone." /></td>
330
- <td><code>lit-commit</code><br /><sub><code>$litcodex:lit-commit</code></sub></td>
331
- <td>Splits your changes into atomic commits in the repo's own style and leaves unrelated work alone.</td>
332
- </tr>
333
- <tr>
334
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lsp-setup.webp" width="240" alt="Checks language-server setup and runs a real diagnostics check on demand." /></td>
335
- <td><code>lsp-setup</code><br /><sub><code>$litcodex:lsp-setup</code></sub></td>
336
- <td>Checks language-server setup and runs a real diagnostics check on demand.</td>
337
- </tr>
338
- <tr>
339
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/readme-studio.webp" width="240" alt="A factual README with a moving cover, checked at phone and desktop widths in light and dark." /></td>
340
- <td><code>readme-studio</code><br /><sub><code>$litcodex:readme-studio</code></sub></td>
341
- <td>A factual README with a moving cover, checked at phone and desktop widths in light and dark.</td>
342
- </tr>
343
- <tr>
344
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-typographic-motion.webp" width="240" alt="Ask for a video with lit. A treatment comes first, then an authored stage page or the type engine, a sound bed, and look rounds on the rendered stills." /></td>
345
- <td><code>lit-typographic-motion</code><br /><sub><code>$litcodex:lit-typographic-motion</code></sub></td>
346
- <td>Ask for a video with <code>lit</code>. A treatment comes first, then an authored stage page or the type engine, a sound bed, and look rounds on the rendered stills.</td>
347
- </tr>
348
- <tr>
349
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/structural-search.webp" width="240" alt="Finds code by its syntax shape, not its text, and previews rewrites before applying them." /></td>
350
- <td><code>structural-search</code><br /><sub><code>$litcodex:structural-search</code></sub></td>
351
- <td>Finds code by its syntax shape, not its text, and previews rewrites before applying them.</td>
352
- </tr>
353
- <tr>
354
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/visual-qa.webp" width="240" alt="Checks a real screen at each viewport and returns an honest verdict, or names exactly what blocked it." /></td>
355
- <td><code>visual-qa</code><br /><sub><code>$litcodex:visual-qa</code></sub></td>
356
- <td>Checks a real screen at each viewport and returns an honest verdict, or names exactly what blocked it.</td>
357
- </tr>
358
- <tr>
359
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/browser-drive.webp" width="240" alt="Drives a real page after verifying the browser driver. If there is none, it says so." /></td>
360
- <td><code>browser-drive</code><br /><sub><code>browser-drive</code> · <code>$litcodex:browser-drive</code></sub></td>
361
- <td>Drives a real page after verifying the browser driver. If there is none, it says so.</td>
362
- </tr>
363
- <tr>
364
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/frontend-ui-ux.webp" width="240" alt="Builds a working interface, then a measured probe renders it in seven views: four widths, dark, reduced motion and 200% zoom." /></td>
365
- <td><code>frontend-ui-ux</code><br /><sub><code>$litcodex:frontend-ui-ux</code></sub></td>
366
- <td>Builds a working interface, then a measured probe renders it in seven views: four widths, dark, reduced motion and 200% zoom.</td>
367
- </tr>
368
- <tr>
369
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-burnoff.webp" width="240" alt="Cleans AI-written bloat out of a change set after tests lock what it does." /></td>
370
- <td><code>lit-burnoff</code><br /><sub><code>$litcodex:lit-burnoff</code></sub></td>
371
- <td>Cleans AI-written bloat out of a change set after tests lock what it does.</td>
372
- </tr>
373
- <tr>
374
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/lit-burnoff-file.webp" width="240" alt="The same cleanup for one file: fewer narrating comments, less defensive noise, flatter code." /></td>
375
- <td><code>lit-burnoff-file</code><br /><sub><code>$litcodex:lit-burnoff-file</code></sub></td>
376
- <td>The same cleanup for one file: fewer narrating comments, less defensive noise, flatter code.</td>
377
- </tr>
378
- <tr>
379
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/wikify.webp" width="240" alt="Keeps reviewed project knowledge on disk and answers later questions from it, with sources." /></td>
380
- <td><code>wikify</code><br /><sub><code>$litcodex:wikify</code></sub></td>
381
- <td>Keeps reviewed project knowledge on disk and answers later questions from it, with sources.</td>
382
- </tr>
383
- <tr>
384
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/autoresearch.webp" width="240" alt="An approved, budgeted experiment loop. Each round changes one thing and keeps or reverts it." /></td>
385
- <td><code>autoresearch</code><br /><sub><code>$litcodex:autoresearch</code></sub></td>
386
- <td>An approved, budgeted experiment loop. Each round changes one thing and keeps or reverts it.</td>
387
- </tr>
388
- <tr>
389
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/autoconference.webp" width="240" alt="A budgeted research conference: separate researchers, reviewers, and a synthesis that keeps disagreement." /></td>
390
- <td><code>autoconference</code><br /><sub><code>$litcodex:autoconference</code></sub></td>
391
- <td>A budgeted research conference: separate researchers, reviewers, and a synthesis that keeps disagreement.</td>
392
- </tr>
393
- <tr>
394
- <td><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/skills/automatic-checks.webp" width="240" alt="Runs on its own: project rules on each prompt, LSP and comment checks after edits." /></td>
395
- <td><code>rules</code> · <code>lsp</code> · <code>comment-checker</code><br /><sub>runs on its own</sub></td>
396
- <td>Runs on its own: project rules on each prompt, LSP and comment checks after edits.</td>
397
- </tr>
398
- </table>
399
-
400
- ## A/B: plain Codex vs lit
401
-
402
- Each prompt below is one casual Korean line. The baseline got the line as typed; the lit arm got the same line with ` lit` added and nothing else. Both arms ran Codex CLI 0.157.1 with `gpt-6-sol` at high effort on 2026-09-26, one trial per arm, each in its own disposable home. The lit arm used a local pre-release build of LitCodex, not a published version. Where LitCodex was fixed and run again, the table compares the latest lit run with the same baseline. A blind judge (Claude Opus 5.5) compared each pair in both orders. The maintainer then looked at both outputs side by side and made the final call; the judge's verdict is kept next to it for reference.
403
-
404
- S3 and S4 were run again in a later interface round, together with S11. S5 was run again in an office round, together with S8 and S9; there the lit arm used `lit-pptx` and `lit-docx`.
405
-
406
- | Task | Prompt | Final verdict | Blind judge (same round) |
407
- | --- | --- | --- | --- |
408
- | S1 terminal to-do CLI | `터미널에서 쓰는 할 일 관리 CLI 만들어줘` | **Baseline won** | Baseline won |
409
- | S2 API server bugs | `이 API 서버 가끔 이상하게 동작하는데 고쳐줘` | **Tie** | Baseline won |
410
- | S3 budget dashboard | `개인 가계부 대시보드 웹페이지 만들어줘` | **LitCodex won** | Baseline won |
411
- | S4 café landing page | `동네 카페 브랜드 랜딩페이지 만들어줘` | **LitCodex won** | Tie |
412
- | S5 report and slides from sources | `sources 폴더 자료로 보고서랑 발표자료 만들어줘` | **LitCodex won** | Tie |
413
- | S6 Node 22 to 24 research | `Node 22에서 24로 올릴 때 달라지는 거 조사해줘` | **LitCodex won** | LitCodex won |
414
- | S7 order, payment and shipping diagram | `주문-결제-배송 서비스 구조도 그려줘` | **LitCodex won** (blind judge; not reviewed by eye) | LitCodex won |
415
- | S8 quarterly results deck | `분기 실적 발표자료 만들어줘` | **LitCodex won** | Baseline won |
416
- | S9 new product plan | `신제품 기획서 써줘` | **LitCodex won** | LitCodex won |
417
- | S11 meeting-room booking app | `회의실 예약 웹앱 만들어줘` | **LitCodex won** | Baseline won |
418
- | Total | | **8 won, 1 tie, 1 lost** | 3 won, 2 ties, 5 lost |
419
-
420
- The motion skill, `lit-typographic-motion`, was rebuilt after its first A/B and has no A/B result yet. The cover at the top was made with the LitFamily motion skill.
421
-
422
- In the interface round the Codex sandbox blocked the browser, so the lit arm's interface probe could not measure its pages; neither arm checked its rendered screen. In the office round the renderer failed inside the sandbox, so the lit arm never saw previews of its slides and pages, and each reply said so. Looking at the office round as a whole, the maintainer found the LitCodex files much better suited to real work.
423
-
424
- ### What each side produced
425
-
426
- - **S1, lost.** The baseline CLI can add, list, edit, complete, reopen and delete items, with checked due dates. The LitCodex CLI had fewer commands (no editing, no due dates), claimed Python 3.10 support while importing a 3.11-only API, and its own tests did not pass in the checker. The blind judge also preferred the baseline over the two earlier LitCodex runs, and the maintainer called it a clear loss.
427
- - **S2, tie.** Both sides fixed all six seeded bugs, with no failing visible tests. The judge leaned to the baseline because its reply mentioned that creating an item now returns 201 instead of 200, which the LitCodex reply left out. The maintainer called it a tie.
428
- - **S3, won.** The LitCodex dashboard shows monthly income, spending and the budget, and lets you add, delete and search transactions and change the budget. The judge preferred the baseline's richer analysis: an income and expense line chart, a category donut and budgets per category. The maintainer preferred the LitCodex page.
429
- - **S4, won.** The judge called it a tie: the baseline's shop-front photos and menu felt more finished, while the LitCodex page showed mock-up labels to visitors because the prompt gave no address or hours. The checker found no clipped text on the LitCodex page (9 items on the baseline) but more accessibility findings (38 against 29).
430
- - **S5, won.** LitCodex made a Word report and a 7-slide deck, each with an editable Markdown source. The judge called it a tie: the baseline report was better built (a data-period box, an interpretation column and numbered citations), while the LitCodex slides looked more polished. The checker counted 12 of 12 facts right for the baseline and 11 of 12 for LitCodex, none wrong on either side, and 5 invented-number flags against 14.
431
- - **S6, won.** LitCodex correctly lists `dirent.path` as removed, where the baseline called it only deprecated, and notes that `require(esm)` and type stripping already exist in Node 22. The checker found 3 of 10 expected facts against 2; 75% of LitCodex's links were official sources, against 100% for the baseline.
432
- - **S7, won (blind judge; not reviewed by eye).** LitCodex saved a rendered PNG and an editable HTML diagram with labelled arrows and a payment-failure path. The baseline gave Mermaid code in its reply and no rendered file, although its architecture covered more services.
433
- - **S8, won.** The prompt gave no figures. The baseline made a 10-slide fill-in template with blanks for every number, and the checker flagged 18 overflowing text boxes. LitCodex made an 8-slide deck for a fictional company with sample figures labelled as examples and 3 tables; the checker flagged one overflowing box and one overlap. The judge preferred the baseline's template.
434
- - **S9, won.** The baseline answered in chat with a short plan and made no document. LitCodex wrote a 6-page Word plan with its Markdown source: decision gates, scope, schedule, risks and unit economics, with every figure marked as an assumption. The judge agreed, noting leftover checklist files, wrong numbering in one list and too many caveats.
435
- - **S11, won.** The judge preferred the baseline: a weekly date strip and a room-by-time timeline with click-to-book, where the LitCodex app shows a large header and a room list with no view of existing bookings. LitCodex finds rooms by date, size and equipment, blocks overlapping bookings, includes unit tests and had 2 accessibility findings against 124.
436
-
437
- ### Pictures
438
-
439
- **S3, budget dashboard (baseline left, LitCodex right).**
440
-
441
- <p><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s3-baseline-desktop.webp" width="49%" alt="Baseline budget dashboard at desktop width" /> <img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s3-lit-desktop.webp" width="49%" alt="LitCodex budget dashboard at desktop width" /></p>
442
-
443
- <details><summary>S3 on a phone</summary>
444
-
445
- <p><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s3-baseline-phone.webp" width="240" alt="Baseline budget dashboard on a phone" /> <img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s3-lit-phone.webp" width="240" alt="LitCodex budget dashboard on a phone" /></p>
446
-
447
- </details>
448
-
449
- **S4, café landing page (baseline left, LitCodex right).**
450
-
451
- <p><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s4-baseline-desktop.webp" width="49%" alt="Baseline café landing page at desktop width" /> <img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s4-lit-desktop.webp" width="49%" alt="LitCodex café landing page at desktop width" /></p>
452
-
453
- <details><summary>S4 on a phone</summary>
454
-
455
- <p><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s4-baseline-phone.webp" width="240" alt="Baseline café landing page on a phone" /> <img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s4-lit-phone.webp" width="240" alt="LitCodex café landing page on a phone" /></p>
456
-
457
- </details>
458
-
459
- **S5, first five slides (baseline above, LitCodex below).**
76
+ Then look at the result, the checks that actually ran, and what is still open. `lit recap` reads back what
77
+ was recorded, and sending `handoff` on its own before you leave gives the next session a place to start.
460
78
 
461
- <p><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s5-baseline-slides.webp" width="100%" alt="Baseline slides for the report-and-slides task" /></p>
462
- <p><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s5-lit-slides.webp" width="100%" alt="LitCodex slides for the report-and-slides task" /></p>
79
+ ## Routes people use most
463
80
 
464
- **S7, the LitCodex diagram.** The baseline returned Mermaid code without a rendered file.
465
-
466
- <p><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s7-lit-diagram.webp" width="720" alt="LitCodex order, payment and shipping service diagram" /></p>
467
-
468
- **S8, first five slides (baseline above, LitCodex below).**
469
-
470
- <p><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s8-baseline-slides.webp" width="100%" alt="Baseline quarterly results template slides" /></p>
471
- <p><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s8-lit-slides.webp" width="100%" alt="LitCodex quarterly results slides with sample figures" /></p>
472
-
473
- **S9, first three pages of the LitCodex plan.** The baseline answered in chat and made no file.
474
-
475
- <p><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s9-lit-pages.webp" width="100%" alt="LitCodex new product plan, first three pages" /></p>
476
-
477
- **S11, meeting-room booking app (baseline left, LitCodex right).**
478
-
479
- <p><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s11-baseline-desktop.webp" width="49%" alt="Baseline meeting-room booking app at desktop width" /> <img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s11-lit-desktop.webp" width="49%" alt="LitCodex meeting-room booking app at desktop width" /></p>
480
-
481
- <details><summary>S11 on a phone</summary>
482
-
483
- <p><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s11-baseline-phone.webp" width="240" alt="Baseline meeting-room booking app on a phone" /> <img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ab-simple/assets/s11-lit-phone.webp" width="240" alt="LitCodex meeting-room booking app on a phone" /></p>
484
-
485
- </details>
486
-
487
- ## Commands
488
-
489
- ### Start with one lit task
490
-
491
- Append `lit` to a prompt to activate the Codex CLI hook. It routes the request into the durable loop; Codex still owns model execution.
492
-
493
- | Prompt or route | Effect |
81
+ | Type this | What happens |
494
82
  | --- | --- |
495
- | `lit` | Start a bounded task with goals and checks in the project. |
496
- | `handoff` or `/lit-handoff` | Carry the checked result and next step to another session. |
497
- | `lit-plan` | Prepare a plan and success criteria before editing. |
498
- | `lit start work <approved-plan>` | Execute an approved plan. |
499
- | `review-work` | Review the change and its evidence. |
500
- | `litresearch` | Record source-backed research and uncertainty. |
501
-
502
- The hook is an entry signal; it does not prove that a model result or visual check completed.
503
-
504
- <p align="center"><a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ignition-poster.png" width="720" alt="Ignition motion poster" /></a></p>
505
-
506
- Select the poster for the optional film; this README keeps motion opt-in.
507
-
508
- ### In the Codex composer
509
-
510
- | Type this | Mode | What it does |
511
- | --- | --- | --- |
512
- | `lit` or `lit-loop` | **lit-loop** | Durable, evidence-checkpointed execution |
513
- | `litwork` | **litwork** | Outcome-first work with manual-QA evidence |
514
- | `lit-plan` or `lit plan` | **lit-plan** | Planning-only, bounded plan with evidence and a Final DoneClaim |
515
- | `deep-interview` or `lit deep interview` | **deep-interview** | Planning-only discovery for ambiguous briefs |
516
- | `litgoal` or `lit goal` | **litgoal** | Bind an objective and criteria into loop state |
517
- | `lit-recap` or `lit recap` | **lit-recap** | Read-only recap from `.litcodex` ledgers |
518
- | `lit-comprehend` or `comprehend` | **lit-comprehend** | Build a self-contained explainer outside the worktree |
519
- | `review-work` or `lit review` | **review-work** | Read-only plan or completed-work review |
520
- | `litresearch`, `/litresearch`, or `lit research` | **litresearch** | Research journal separating facts, hypotheses, sources, and uncertainty |
521
- | `lit start work <plan-name>` | **Start Work** | Execute an approved plan with durable evidence |
522
- | exact bare `handoff` | **lit-handoff** | Create or refresh a secret-safe continuation packet |
523
- | exact bare `lit-scientific-visualization` | **lit-scientific-visualization** | Load the publication plotting adapter through the hook |
524
- | `$litcodex:lit-diagram-drawer` | **lit-diagram-drawer** | Create and verify conceptual, workflow, and system diagrams; export Office-safe SVG or high-resolution PNG |
525
- | `$litcodex:lit-docx` | **lit-docx** | Create and edit Word reports with publisher profiles and visual review |
526
- | `$litcodex:lit-pptx` | **lit-pptx** | Compile and QA editable PowerPoint decks from Markdown |
527
-
528
- Typing the same mode again in one session is idempotent. Standalone skills can also be selected by exact ID
529
- from the Codex picker or with a scoped mention, including `$litcodex:lit-handoff` and
530
- `$litcodex:lit-scientific-visualization`, `$litcodex:lit-humanizer`, and `$litcodex:lit-fetch`.
531
- For diagrams, select `lit-diagram-drawer` or use `$litcodex:lit-diagram-drawer`; ordinary product screens and measured-data plots stay on their dedicated skills.
532
- For Word reports use `lit-docx`; for slides use `lit-pptx`. A bounded `lit` request for both outputs loads both skills. `litcodex install` prepares the pinned Office runtime in the product cache before a Codex session. Check it with `litcodex office-runtime status` or `litcodex doctor`; if network was unavailable, run `litcodex office-runtime install` later outside the sandbox. The Office runner's doctor command reports optional host tools.
533
-
534
- ### CLI commands
535
-
536
- | Command | Purpose |
537
- | --- | --- |
538
- | `litcodex install` | Register the LitCodex plugin and hook |
539
- | `litcodex doctor` | Diagnose installation, loop state, host capabilities, and effective config |
540
- | `litcodex uninstall` | Remove the plugin and LitCodex-managed config |
541
- | `litcodex config migrate` | Preview or apply managed Codex config keys |
542
- | `litcodex hook user-prompt-submit` | Run the host hook entrypoint |
543
- | `litcodex loop create` | Derive goals and criteria from a brief |
544
- | `litcodex loop status --json` | Inspect loop state as JSON |
545
- | `litcodex loop run` | Select the next runnable goal |
546
- | `litcodex loop record-evidence` | Record a criterion pass, fail, or blocked result |
547
- | `litcodex loop checkpoint` | Complete a goal only when every criterion passes |
548
- | `litcodex loop doctor` | Diagnose or recover loop state |
549
-
550
- Use the Codex skill picker for the full library. Previous leading skill names redirect for one release;
551
- see [rename compatibility](https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md#skill-rename-compatibility) and [CHANGELOG.md](https://github.com/wjgoarxiv/litcodex/blob/main/CHANGELOG.md).
552
-
553
- ## Loop state
554
-
555
- Project state stays under `.litcodex/lit-loop/`: `brief.md`, `goals.json`, `ledger.jsonl`, and `evidence/`.
556
- Writes are atomic; a damaged goals file is preserved as `.bak`. Local state is excluded from Git and packages.
557
- See [state and recovery](https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md#loop-state).
558
-
559
- ## Verify it worked
83
+ | `lit` | Starts a bounded task, with goals and checks kept in the project. |
84
+ | `handoff` or `/lit-handoff` | Carries the checked result and the next step into another session. |
85
+ | `lit-plan` | Writes a plan and success criteria before anything is edited. |
86
+ | `lit start work <approved-plan>` | Runs a plan you have approved. |
87
+ | `review-work` | Reviews the change and its evidence. |
88
+ | `litresearch` | Researches with sources and keeps track of what is still uncertain. |
89
+
90
+ Send exact bare `handoff` as its own message to write a continuation packet. The exact bare
91
+ `lit-scientific-visualization` hook route loads the plotting adapter; it does not install Python dependencies.
92
+
93
+ ## What else is in the package
94
+
95
+ You can pick these skills in the Codex skill picker or mention one by scoped name, such as
96
+ `$litcodex:lit-humanizer`, `$litcodex:lit-fetch`, `$litcodex:lit-handoff` or
97
+ `$litcodex:lit-scientific-visualization`. The GitHub page has a picture for each one.
98
+
99
+ **Planning and running work**
100
+
101
+ - `lit-loop` (`lit`): works inside the durable loop and records what it could not verify.
102
+ - `litwork`: a careful end-to-end build or fix, failing test first, then proof on the real surface.
103
+ - `lit-plan`: an approved plan with numbered rows in `.litcodex/plans/`; planning only.
104
+ - Start Work (`lit start work <approved-plan>`): runs an approved plan through five gates.
105
+ - `litgoal`: binds one goal with observable criteria to the loop.
106
+ - `deep-interview`: one question at a time until the idea is clear enough to build.
107
+ - `lit-crucible`: pressure-tests a brief before planning, so only surviving risks reach the plan.
108
+ - `lit-team`: gives several workers separate slices, each reporting back with evidence.
109
+ - `lit-recap` and `lit-handoff`: a read-only summary of where things stand, and a file the next session resumes from.
110
+
111
+ **Review, research and knowledge**
112
+
113
+ - `review-work`: five blocking reviews; one failure blocks approval.
114
+ - `litresearch`: parallel evidence gathering and a cited synthesis, only when you ask for research.
115
+ - `autoresearch` and `autoconference`: an approved, budgeted experiment loop, and a budgeted research conference.
116
+ - `lit-fetch`: reads a public page with URL, DNS and text-safety checks when ordinary retrieval falls short.
117
+ - `wikify`: keeps reviewed project knowledge on disk and answers later questions from it, with sources.
118
+ - `coding-session-audit`: reads a past Codex session from its evidence and shows where it stopped.
119
+ - `lit-comprehend`: an explainer page for agent-written work, ending in a short quiz.
120
+
121
+ **Documents, figures and interfaces**
122
+
123
+ - `lit-docx` and `lit-pptx`: a styled Word file or an editable PowerPoint deck, each with its Markdown source.
124
+ - `lit-diagram-drawer`: an editable diagram, checked and exported to PNG and Office-safe SVG.
125
+ - `lit-scientific-visualization`: a journal-sized figure with vector and 600 DPI exports.
126
+ - `lit-typographic-motion`: a short film, starting from a written treatment.
127
+ - `lit-humanizer`: rewrites stiff model prose in English or Korean, keeping facts and hedges.
128
+ - `readme-studio`: a factual README with a moving cover.
129
+ - `frontend-ui-ux`, `visual-qa` and `browser-drive`: builds an interface, checks a real screen at each
130
+ viewport, and drives a real page once the browser driver is verified.
131
+
132
+ **Code**
133
+
134
+ - `debugging`: reproduces the bug, tests at least three explanations, fixes only the confirmed cause.
135
+ - `refactor`: restructures code while tests pin its behavior.
136
+ - `lit-code`: strict implementation rules, with tests first and typed boundaries.
137
+ - `lit-commit`: atomic commits in the repository's own style.
138
+ - `lit-burnoff` and `lit-burnoff-file`: clean AI-written bloat from a change set or from one file.
139
+ - `structural-search`: finds code by syntax shape and previews rewrites.
140
+ - `lsp-setup` and `lit-init`: language-server setup checks, and sparse AGENTS.md guidance.
141
+
142
+ **Keeping LitCodex healthy**
143
+
144
+ - `litcodex-doctor`, `litcodex-report-bug` and `litcodex-contribute-bug-fix`: install health checks, a
145
+ source-backed bug report, and a tested bug-fix PR.
146
+ - `rules`, `lsp` and `comment-checker` run on their own: project rules on each prompt, LSP and comment
147
+ checks after edits.
148
+
149
+ ## A/B results
150
+
151
+ In ten one-line A/B tasks against plain Codex, the final verdicts for LitCodex were 8 won, 1 tie, 1 lost
152
+ (the maintainer's call, except S7, which only the blind judge reviewed); the blind judge's were
153
+ 3 won, 2 ties, 5 lost. Each arm ran once, and the lit arm used a local pre-release build. The GitHub page has
154
+ [every task, both verdicts and the screenshots](https://github.com/wjgoarxiv/litcodex#ab-plain-codex-vs-lit).
155
+
156
+ ## What it changes
157
+
158
+ Codex hosts the plugin and runs its hooks. The hooks work out which mode a request belongs to, the skills
159
+ guide the agent, and the loop CLI keeps the project records. The package never calls Codex's native goal
160
+ tools itself; the agent uses them when they are available, and a paused or blocked goal needs the recovery
161
+ step below.
162
+
163
+ - Codex gets the plugin, hooks and agents, plus the managed keys in `~/.codex/config.toml`. Your unrelated
164
+ Codex settings stay as they are. Look at the planned changes before you use `--reconfigure`.
165
+ - A model route is a configuration choice. It does not guarantee access to that model or that it runs.
166
+ - Each project gets local records under `.litcodex/lit-loop/`, kept out of Git and packages.
167
+ - The doctor diagnostic core never modifies Codex config, install state or plugin state. An eligible
168
+ interactive doctor run may show a cached advisory notice. Its detached worker performs a fixed registry
169
+ refresh at `~/.litcodex/update-check.json` and never installs packages. A separate foreground updater can
170
+ install a newer global package after eligible interactive management commands; set
171
+ `LITCODEX_NO_UPDATE_CHECK=1` to turn off both. Failed, `--json`, `--dry-run`, non-TTY, CI and opt-out doctor
172
+ runs stay side-effect-free.
173
+ - Tests, fixtures, test helpers and the Vitest configuration live only in the repository. Neither the npm
174
+ package nor the installed marketplace plugin includes them.
175
+
176
+ The optional Jev skill hint is off by default. Turning it on (`LITCODEX_JEV=1` plus your own
177
+ `TYPESAFE_API_KEY`) sends each eligible prompt to TypeSafe (typesafe.ai), cut to 2,000 characters with home
178
+ paths, email addresses and token-shaped strings redacted; the rest of the prompt is sent as written, but no files, tool output or history.
179
+ Read [the full description](https://github.com/wjgoarxiv/litcodex#jev-skill-hint-optional) and the
180
+ [privacy notes](https://github.com/wjgoarxiv/litcodex/blob/main/docs/privacy.md#optional-jev-skill-hint)
181
+ before you turn it on.
182
+
183
+ ## Check, fix, remove
560
184
 
561
185
  ```sh
562
- npm exec --yes --package @litfamily/litcodex@1.0.7 -- litcodex doctor
186
+ npm exec --yes --package @litfamily/litcodex@1.0.9 -- litcodex doctor
563
187
  ```
564
188
 
565
- `litcodex doctor` checks registration, hooks, config, and host capabilities. `litcodex loop doctor` checks
566
- project loop state. A successful installation check does not prove authenticated model or child execution.
567
-
568
- ## Safety
569
-
570
- - Plans and evidence stay reviewable. No criterion is marked complete merely because a test command ran.
571
- - Installation preserves unrelated Codex settings. Preview changes before `--reconfigure`.
572
- - The doctor diagnostic core never modifies Codex config, install state, or plugin state. An eligible interactive
573
- doctor may show a cached advisory notice. Its detached worker performs a fixed registry refresh at
574
- `~/.litcodex/update-check.json`; that worker never installs packages.
575
- A separate foreground updater can install a newer global package after eligible interactive management commands.
576
- Set `LITCODEX_NO_UPDATE_CHECK=1` to disable both update paths. Failed, `--json`, `--dry-run`, non-TTY, CI,
577
- and opt-out doctor paths stay side-effect-free. See [privacy](https://github.com/wjgoarxiv/litcodex/blob/main/docs/privacy.md).
578
- - Model routes are configuration choices, not guarantees of access or execution. See [managed model compatibility](https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md#safety).
579
-
580
- ## Troubleshooting
581
-
582
- - **Pane closes before any output:** the failing stage is unknown. In an already-open terminal, run help,
583
- install, and doctor separately and retain each exit status. Follow the [staged trial](https://github.com/wjgoarxiv/litcodex/blob/main/docs/npm-migration.md#isolated-local-trial),
584
- then launch the host yourself.
585
- - No activation: run `litcodex doctor` and check hook approval in Codex.
586
- - Command missing: use the npx form above or check the npm global bin directory in `PATH`.
587
- - Native goal paused or blocked: use `/goal resume`, confirm it is active, then retry
588
- `litcodex loop run --retry-failed`. Preserve the unfinished goal. [Recovery details](https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md#troubleshooting).
189
+ `litcodex doctor` checks registration, hooks, config and host capabilities; `litcodex loop doctor` checks the
190
+ current project's loop state. A clean check does not prove that authenticated model work will run.
589
191
 
590
- ## Uninstall
192
+ - **`lit` does nothing.** Run `litcodex doctor` and check that the hooks are approved in Codex.
193
+ - **The command is missing.** Use the `npm exec` form above, or put npm's global bin directory on your `PATH`.
194
+ - **A native goal is paused or blocked.** Run `/goal resume`, confirm the goal is active, then retry with
195
+ `litcodex loop run --retry-failed`. Keep the unfinished goal.
196
+ - **The pane closes before any output.** Run help, install and doctor one at a time in an open terminal,
197
+ keep each exit status, and see [troubleshooting](https://github.com/wjgoarxiv/litcodex#troubleshooting).
591
198
 
592
199
  ```sh
593
- npm exec --yes --package @litfamily/litcodex@1.0.7 -- litcodex uninstall
200
+ npm exec --yes --package @litfamily/litcodex@1.0.9 -- litcodex uninstall
594
201
  ```
595
202
 
596
- `litcodex uninstall` removes the plugin and LitCodex-managed config while preserving unrelated settings.
597
-
598
- ## License
599
-
600
- MIT
203
+ This removes the plugin and the config LitCodex manages, and leaves your other settings alone.
601
204
 
602
205
  ## Links
603
206
 
604
- ### Documentation
605
-
606
- - [Usage reference](https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md) — complete routes, model configuration, platform limits, and recovery.
607
- - [LitCodex contract](https://github.com/wjgoarxiv/litcodex/blob/main/docs/spec/litcodex-contract.md) — hooks, native goal boundaries, and evidence requirements.
608
- - [Reference analysis](https://github.com/wjgoarxiv/litcodex/blob/main/docs/reference-analysis.md) — design and compatibility decisions.
609
- - [Release provenance](https://github.com/wjgoarxiv/litcodex/blob/main/docs/release/provenance.md), [publish checklist](https://github.com/wjgoarxiv/litcodex/blob/main/docs/release/publish-checklist.md), and [CHANGELOG.md](https://github.com/wjgoarxiv/litcodex/blob/main/CHANGELOG.md).
610
-
611
- The bundled skill library also includes `autoconference`, `autoresearch`, `browser-drive`, `coding-session-audit`,
612
- `comment-checker`, `debugging`, `frontend-ui-ux`, `lit-commit`, `lit-crucible`, `lit-init`, `lit-humanizer`, `lit-fetch`, `lit-docx`, `lit-pptx`,
613
- `litcodex-contribute-bug-fix`, `litcodex-doctor`, `litcodex-report-bug`, `lsp`, `lsp-setup`, `lit-code`, `refactor`,
614
- `lit-burnoff`, `readme-studio`, `structural-search`, `lit-team`, `visual-qa`, and `wikify`.
615
-
616
- Tests, fixtures, test helpers, and Vitest configuration remain tracked repository coverage and are excluded from npm and installed marketplace payloads.
617
-
618
- [Contributing](https://github.com/wjgoarxiv/litcodex/blob/main/CONTRIBUTING.md) · [Security](https://github.com/wjgoarxiv/litcodex/blob/main/SECURITY.md) · [Code of conduct](https://github.com/wjgoarxiv/litcodex/blob/main/CODE_OF_CONDUCT.md) · [Support](https://github.com/wjgoarxiv/litcodex/blob/main/SUPPORT.md) · [Privacy](https://github.com/wjgoarxiv/litcodex/blob/main/docs/privacy.md)
619
-
620
- ### LITFAMILY
621
-
622
- ![LITFAMILY editorial illustration with five armored machines against a dark background](https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/litfamily-machines.png)
623
-
624
- Five armored machines, one for each product in the LIT family.
625
-
626
- ### Ignition motion
627
-
628
- Select the poster to watch the 10-second film.
629
-
630
- <p align="center"><a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.7/readme-assets/ignition-poster.png" width="720" alt="Ignition motion graphic poster" /></a></p>
631
-
632
- [Animated GIF](https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-readme.gif) · [Media and icon credits](https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/README.md)
207
+ [Usage reference](https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md) ·
208
+ [Migration from the old package](https://github.com/wjgoarxiv/litcodex/blob/main/docs/npm-migration.md) ·
209
+ [CHANGELOG.md](https://github.com/wjgoarxiv/litcodex/blob/main/CHANGELOG.md) ·
210
+ [Privacy](https://github.com/wjgoarxiv/litcodex/blob/main/docs/privacy.md) ·
211
+ [Issues](https://github.com/wjgoarxiv/litcodex/issues) · MIT license