lazycodex-ai 5.1.61 → 5.1.63

package/packages/omo-codex/plugin/skills/frontend/references/perfection/README.md

@@ -16,7 +16,7 @@ The correct path:
 3. Run Lighthouse against the Playwright-controlled page via `playwright-lighthouse` OR via `chrome-launcher` + the `lighthouse` Node API, attaching to the Playwright CDP endpoint so cookies, auth state, and warmed caches mirror what a real returning user sees.
 4. Use the **mobile** preset (4x CPU throttle, Fast 3G) for the primary number, AND the **desktop** preset for the secondary number. Report both.
 
-If the `playwright` skill is not loaded in this session, load it now via the `skill` tool.
+If no browser-automation skill is loaded in this session, load the `browser` skill now (read its `SKILL.md`).
 
 ### 2. 100 IN EVERY CATEGORY IS THE FLOOR.
 
@@ -90,7 +90,6 @@ Quick audit via the cross-platform Python CLI (macOS, Linux, Windows):
 
 ```bash
 uv run $SKILL_DIR/scripts/perfection/lighthouse-audit.py https://localhost:3000
-uv run $SKILL_DIR/scripts/perfection/lighthouse-audit.py https://localhost:3000 --threshold 95
 uv run $SKILL_DIR/scripts/perfection/lighthouse-audit.py https://localhost:3000 --desktop-only
 bun $SKILL_DIR/scripts/perfection/check-draft-guard.ts src/   # exit 1 = accent stripe or outline, promo copy, emoji icon, hype badge, or vanity stat
 ```

package/packages/omo-codex/plugin/skills/frontend/references/perfection/react-perf-tooling.md

@@ -20,17 +20,38 @@ If the project does not yet have react-scan and react-doctor wired into its dev
 import { chromium } from "playwright";
 import { playAudit } from "playwright-lighthouse";
 
+declare global {
+  interface Window {
+    __renderEvents: unknown[];
+  }
+}
+
+// Narrow only the fields this gate reads from a react-scan commit event.
+function hasUnnecessaryRender(event: unknown): boolean {
+  if (typeof event !== "object" || event === null || !("tree" in event) || !Array.isArray(event.tree)) return false;
+  return event.tree.some(
+    (node: unknown) =>
+      typeof node === "object" &&
+      node !== null &&
+      "changeDescription" in node &&
+      typeof node.changeDescription === "object" &&
+      node.changeDescription !== null &&
+      "kind" in node.changeDescription &&
+      node.changeDescription.kind === "unnecessary",
+  );
+}
+
 const browser = await chromium.launch({ channel: "chrome" });
 const context = await browser.newContext();
 
 // Inject react-scan/lite BEFORE the app boots
 await context.addInitScript(() => {
-  // @ts-ignore — pulled from the project's node_modules or a self-hosted bundle
+  // react-scan is a dev dependency of the project (see ../design/react-dev-tooling-skill.md), so its types resolve
   import("react-scan/lite").then(({ instrument }) => {
-    (window as any).__renderEvents = [];
+    window.__renderEvents = [];
     instrument({
-      onEvent: (event: any) => {
-        if (event.kind === "commit") (window as any).__renderEvents.push(event);
+      onEvent: (event) => {
+        if (event.kind === "commit") window.__renderEvents.push(event);
       },
       recordChangeDescriptions: true,
       includeFiberSource: true,
@@ -51,10 +72,8 @@ await playAudit({
 });
 
 // Pull render events and assert on render quality
-const events = await page.evaluate(() => (window as any).__renderEvents);
-const unnecessary = events.filter((e: any) =>
-  e.tree?.some((node: any) => node.changeDescription?.kind === "unnecessary"),
-);
+const events = await page.evaluate(() => window.__renderEvents);
+const unnecessary = events.filter(hasUnnecessaryRender);
 
 if (unnecessary.length > 0) {
   console.error(`FAIL: ${unnecessary.length} unnecessary renders detected during audit`);

package/packages/omo-codex/plugin/skills/frontend/scripts/perfection/lighthouse-audit.py

@@ -16,7 +16,6 @@
 # 3. Run:
 #      uv run lighthouse-audit.py https://example.com
 #      uv run lighthouse-audit.py https://example.com --desktop-only
-#      uv run lighthouse-audit.py https://example.com --threshold 95
 # ──────────────────
 
 """Lighthouse audit via real Playwright Chrome.

package/packages/omo-codex/plugin/skills/git-master/SKILL.md

@@ -16,7 +16,7 @@ Classify the request first:
 - `HISTORY`: answer when, where, who, why, or which commit changed something.
 - `STATUS`: inspect branch, diff, or working-tree state without changing it.
 
-Do not commit, rebase, push, force-push, reset, stash-pop, or delete anything unless the user explicitly asked for that operation. If the request is only investigative, report findings and stop.
+Do not commit, rebase, push, force-push, reset, stash-pop, or delete anything unless the user explicitly asked for that operation. When a workflow the user started mandates one of them (ulw-loop commits each verified unit, ulw-execute lands its branches), that workflow's instruction is the ask. If the request is only investigative, report findings and stop.
 
 ## Ground Truth
 
@@ -38,7 +38,17 @@ Missing upstream or missing `main`/`master` is normal. Fall back to the best ava
 
 ## PR Body Evidence Attachments
 
-When a PR body needs screenshots or terminal PNGs, use the repo reference at `docs/reference/github-attachment-upload.md`. The allowed hosting path is GitHub user attachments from the authenticated web attachment flow; never commit temporary images, never use GitHub Releases for PR evidence, and never use external image hosts. Do not log browser cookies, CSRF tokens, S3 form fields, or upload headers.
+When a PR body needs screenshots or terminal PNGs, the allowed hosting path is GitHub user attachments from the authenticated web attachment flow; never commit temporary images, never use GitHub Releases for PR evidence, and never use external image hosts. Do not log browser cookies, CSRF tokens, S3 form fields, or upload headers.
+
+The flow needs an authenticated GitHub web session (a `gh` API token alone is not enough):
+
+1. Open the target PR or issue page in that session and read its file-attachment CSRF token and repository id.
+2. `POST https://github.com/upload/policies/assets` with `repository_id`, `name`, `size`, `content_type`, and that token as `authenticity_token`.
+3. Upload the bytes to the returned S3 URL with the returned form fields exactly as given.
+4. `PUT https://github.com/upload/assets/:id` with the returned `asset_upload_authenticity_token`.
+5. Put only the final `https://github.com/user-attachments/assets/<uuid>` URL in the PR body (write the body to a temp file and pass it with `gh pr edit --body-file`).
+
+If no authenticated browser session is available, leave the local evidence paths in the PR body and state the blocker.
 
 ## Commit Mode
 

package/packages/omo-codex/plugin/skills/init-deep/SKILL.md

@@ -195,7 +195,7 @@ for each background task ID (`bg_...`): background_output(task_id="bg_...")
 ```
 AGENTS_LOCATIONS = [
   { path: ".", type: "root" },
-  { path: "src/hooks", score: 18, reason: "high complexity" },
+  { path: "src/hooks", score: 16, reason: "high complexity" },
   { path: "src/api", score: 12, reason: "distinct domain" }
 ]
 ```

package/packages/omo-codex/plugin/skills/lcx-doctor/SKILL.md

@@ -67,7 +67,7 @@ sync_latest_source openai/codex "$LAZYCODEX_SOURCE_ROOT/chatgpt-subscription-sou
    - Latest LazyCodex version from `$LAZYCODEX_SOURCE_ROOT/lazycodex-source` (release tags or the version stamped in the repo) and latest Codex release (`gh release view --repo openai/codex`).
    - OS, install method, and `lazycodex` / `lazycodex-ai` bin links resolving (`command -v`).
    - Astra readiness. The LazyCodex catalog default is `gpt-6-astra`, which Codex only knows from codex-cli 0.153.1 onward. First release tag containing the `models.json` change: `rust-v0.153.1` (backport commit `5cc1c94b8e`). Reproduce on a full clone with tags: `git -C <codex-clone> log --format='%h %d' -S gpt-6-astra -- codex-rs/models-manager/models.json`, then `git -C <codex-clone> tag --contains 5cc1c94b8e | sort -V | head -1`; a shallow clone or one without tags returns nothing. Record the installed version from `codex --version`, the root `model` in `$CODEX_HOME/config.toml` (informational only, it doesn't change the verdict), and, when `$CODEX_HOME/models_cache.json` exists, whether it contains `gpt-6-astra` (`grep -c gpt-6-astra "${CODEX_HOME:-$HOME/.codex}/models_cache.json"`). Verdict: PASS when `codex --version` is 0.153.1 or newer and `models_cache.json` is either absent or lists `gpt-6-astra`. WARN when the version is older than 0.153.1, or the cache exists but lacks `gpt-6-astra`; remediation is upgrading Codex (`npm install -g @openai/codex@latest`, or the package manager that installed `codex`), then starting Codex once so `models_cache.json` refreshes.
-3. Check config and wiring against the latest installer, not against assumptions. Read what the current installer under `$LAZYCODEX_SOURCE_ROOT/lazycodex-source` writes (installer sources live in the omo-codex package, e.g. `scripts/install/`), then verify the local equivalents:
+3. Check config and wiring against the latest installer, not against assumptions. Read what the current installer under `$LAZYCODEX_SOURCE_ROOT/lazycodex-source` writes (in that checkout, `plugins/omo/scripts/migrate-codex-config.mjs` and its `migrate-codex-config/` helpers produce the LazyCodex-managed `config.toml` entries, and `plugins/omo/.codex-plugin/plugin.json` declares the payload), then verify the local equivalents:
    - `$CODEX_HOME/config.toml` exists and parses; LazyCodex-managed entries match what the latest installer would write.
    - Plugin payload present and non-empty: read `.codex-plugin/plugin.json`; when that manifest declares a `hooks` array, validate every direct hook path declared by the manifest; require `hooks/hooks.json` only when the manifest declares it; do not require retired paths such as `components/workflow-selector` or `hooks/user-prompt-submit-selecting-lazycodex-workflow.json` unless the current manifest declares them.
    - Verify the manifest-declared runtime payload, not a remembered source tree. Current payload includes `skills/`, `.mcp.json`, root CLI runtimes such as `dist/cli/index.js` and `dist/cli-node/index.js`, and every hook/MCP `components/*/dist/*.js` target referenced by installed manifests.

package/packages/omo-codex/plugin/skills/lsp-setup/SKILL.md

@@ -27,11 +27,11 @@ reference before installing or configuring anything**.
 | `.py .pyi` | `references/python/README.md` |
 | `.go` | `references/go/README.md` |
 | `.rs` | `references/rust/README.md` |
-| `.c .cpp .cc .cxx .h .hpp .hh .hxx` | `references/c-cpp/README.md` |
+| `.c .cpp .cc .cxx .c++ .h .hpp .hh .hxx .h++` | `references/c-cpp/README.md` |
 | `.java` | `references/java/README.md` |
 | `.kt .kts` | `references/kotlin/README.md` |
 | `.cs .razor .cshtml` | `references/csharp/README.md` |
-| `.swift` | `references/swift/README.md` |
+| `.swift .m .mm` | `references/swift/README.md` |
 | `.rb .rake .gemspec .ru` | `references/ruby/README.md` |
 | `.php` | `references/php/README.md` |
 | `.dart` | `references/dart/README.md` |
@@ -75,13 +75,20 @@ command -v <server-executable>   # e.g. typescript-language-server, gopls, rust-
 
 Most builtin servers need **no config** — they are resolved automatically by
 file extension. Write config only to: pick between competing servers, set a
-`priority`, pass `initialization` options, override `extensions`, set `env`, or
-`disable` a server.
+`priority`, pass `initialization` options, override `extensions`, set `env`
+(user config only), or `disable` a server.
 
-Two project-scoped config files, **identical JSON shape**:
+Config files per harness, **identical JSON shape**. Each harness reads the
+first project file that exists, plus one user file:
 
-- Codex harness → `.codex/lsp-client.json` (user: `~/.codex/lsp-client.json`)
-- OpenCode/omo harness → `.opencode/lsp.json` (also `.omo/lsp.json`)
+| Harness | Project config | User config |
+|---|---|---|
+| Codex | `.codex/lsp-client.json` | `$CODEX_HOME/lsp-client.json` (default `~/.codex/lsp-client.json`) |
+| OpenCode | `.opencode/lsp.json`, then `.omo/lsp.json`, then `.omo/lsp-client.json` | `lsp.json` in the OpenCode config dir (default `~/.config/opencode/lsp.json`) |
+| OmO native | `.omo/lsp-client.json`, then `.pi/lsp-client.json` | `~/.omo/lsp-client.json` (`~/.pi/lsp-client.json` when only that one exists) |
+
+A standalone `lsp-tools-mcp` launch reads the paths in
+`LSP_TOOLS_MCP_PROJECT_CONFIG` / `LSP_TOOLS_MCP_USER_CONFIG` instead.
 
 ```jsonc
 {
@@ -100,14 +107,16 @@ Two project-scoped config files, **identical JSON shape**:
 
 Rules enforced by `config-loader.ts`:
 
-- In a **project** config (`.codex/lsp-client.json`, `.opencode/lsp.json`) an
-  entry whose id is a **builtin** server inherits `command` automatically — you
-  only override `extensions` / `priority` / `initialization`. A non-builtin id
-  in a project config is **ignored**.
-- To define a **fully custom** (non-builtin) server with its own `command`, put
-  it in the **user** config (`~/.codex/lsp-client.json`, or the path set by
-  `LSP_TOOLS_MCP_USER_CONFIG`), where `command` + `extensions` are honored.
-- Project entries win over user entries; both win over builtin defaults.
+- In a **project** config an entry whose id is a **builtin** server inherits
+  `command` automatically — you only override `extensions` / `priority` /
+  `initialization` / `disabled`. Its `env` is dropped, and a non-builtin id in
+  a project config is **ignored**.
+- To set `env`, or to define a **fully custom** (non-builtin) server with its
+  own `command`, put it in the **user** config from the table above, where
+  `command` + `extensions` + `env` are honored.
+- Project entries win over user entries; both win over builtin defaults. A user
+  entry is skipped when an enabled project entry has the same id, so keep an id
+  that needs `env` out of the project config.
 
 Each language reference gives a ready-to-paste snippet.
 

package/packages/omo-codex/plugin/skills/lsp-setup/references/bash/README.md

@@ -27,17 +27,17 @@ command -v shellcheck
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "bash": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)
 
-None commonly required. `bash-language-server` discovers `shellcheck` on PATH automatically. To point at a non-PATH binary, export `SHELLCHECK_PATH` via `env`:
+None commonly required. `bash-language-server` discovers `shellcheck` on PATH automatically. To point at a non-PATH binary, export `SHELLCHECK_PATH` via `env` (USER config only; a project entry drops `env`):
 
 ```json
 { "lsp": { "bash": { "env": { "SHELLCHECK_PATH": "/opt/bin/shellcheck" } } } }

package/packages/omo-codex/plugin/skills/lsp-setup/references/c-cpp/README.md

@@ -20,13 +20,13 @@ command -v clangd
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "clangd": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)
 

package/packages/omo-codex/plugin/skills/lsp-setup/references/csharp/README.md

@@ -22,13 +22,13 @@ command -v csharp-ls
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "csharp": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)
 

package/packages/omo-codex/plugin/skills/lsp-setup/references/dart/README.md

@@ -20,13 +20,13 @@ command -v dart
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "dart": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)
 

package/packages/omo-codex/plugin/skills/lsp-setup/references/elixir/README.md

@@ -21,13 +21,13 @@ command -v elixir-ls
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "elixir-ls": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)
 

package/packages/omo-codex/plugin/skills/lsp-setup/references/go/README.md

@@ -25,13 +25,13 @@ command -v gopls
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "gopls": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)
 

package/packages/omo-codex/plugin/skills/lsp-setup/references/haskell/README.md

@@ -27,13 +27,13 @@ command -v haskell-language-server-wrapper
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "haskell-language-server": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)
 

package/packages/omo-codex/plugin/skills/lsp-setup/references/java/README.md

@@ -20,17 +20,17 @@ command -v jdtls
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "jdtls": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)
 
-jdtls maintains a per-project **workspace data directory** and the **first index is slow** (it resolves the full classpath and builds). Point `JAVA_HOME` at a JDK 17+ if `jdtls` cannot find one:
+jdtls maintains a per-project **workspace data directory** and the **first index is slow** (it resolves the full classpath and builds). Point `JAVA_HOME` at a JDK 17+ if `jdtls` cannot find one (USER config only; a project entry drops `env`):
 
 ```json
 { "lsp": { "jdtls": { "env": { "JAVA_HOME": "/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home" } } } }

package/packages/omo-codex/plugin/skills/lsp-setup/references/julia/README.md

@@ -28,17 +28,17 @@ command -v julia
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "julials": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)
 
-None commonly required. To pin which environment hosts LanguageServer.jl, set `JULIA_PROJECT` (or `JULIA_DEPOT_PATH`) via `env`:
+None commonly required. To pin which environment hosts LanguageServer.jl, set `JULIA_PROJECT` (or `JULIA_DEPOT_PATH`) via `env` (USER config only; a project entry drops `env`):
 
 ```json
 { "lsp": { "julials": { "env": { "JULIA_PROJECT": "@lsp" } } } }

package/packages/omo-codex/plugin/skills/lsp-setup/references/kotlin/README.md

@@ -1,6 +1,6 @@
 # Kotlin — LSP setup
 
-- **Builtin server:** `kotlin-ls` — `kotlin-lsp`
+- **Builtin server:** `kotlin-ls` — `kotlin-lsp --stdio`
 - **Extensions:** `.kt .kts`
 - **Install hint:** `https://github.com/Kotlin/kotlin-lsp`
 
@@ -22,17 +22,17 @@ command -v kotlin-lsp
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "kotlin-ls": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)
 
-None commonly required. If `kotlin-lsp` cannot find a Java runtime, set `JAVA_HOME`:
+None commonly required. If `kotlin-lsp` cannot find a Java runtime, set `JAVA_HOME` (USER config only; a project entry drops `env`):
 
 ```json
 { "lsp": { "kotlin-ls": { "env": { "JAVA_HOME": "/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home" } } } }

package/packages/omo-codex/plugin/skills/lsp-setup/references/lua/README.md

@@ -20,13 +20,13 @@ command -v lua-language-server
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "lua-ls": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)
 

package/packages/omo-codex/plugin/skills/lsp-setup/references/php/README.md

@@ -20,13 +20,13 @@ command -v intelephense
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "php": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)
 
@@ -51,7 +51,7 @@ Without a key the server runs fine in free mode.
 - **phpactor** (not builtin): `phpactor language-server`. Pure-PHP, no Node dependency.
 
 ## Troubleshooting
-- **PATH:** `intelephense` must be on PATH; reopen the shell after a global npm install. If missing, check `npm bin -g` is on PATH.
+- **PATH:** `intelephense` must be on PATH; reopen the shell after a global npm install. If missing, check that `$(npm prefix -g)/bin` (Windows: `npm prefix -g`) is on PATH.
 - **No Node:** Intelephense fails to start without Node.js. Install Node, then reinstall.
 - **Wrong PHP version inference:** set `intelephense.environment.phpVersion` via `initialization` to match your project.
 

package/packages/omo-codex/plugin/skills/lsp-setup/references/python/README.md

@@ -21,13 +21,13 @@ command -v basedpyright-langserver
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "basedpyright": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)
 
@@ -36,27 +36,28 @@ or `[tool.basedpyright]` in `pyproject.toml`, not the LSP config.
 
 ## Choosing a server
 
-All four are builtin. Type checkers and the linter serve different roles — run a
-type server, and optionally `ruff` ALONGSIDE it (not instead).
+All four are builtin. The engine starts ONE server per extension: the first
+installed candidate after ordering by config source (project > user > builtin)
+and then `priority`. So `ruff` cannot run alongside a type server for `.py` —
+choosing it replaces type checking with lint/format diagnostics.
 
 | id            | command                       | install                | role                                    |
 | ------------- | ----------------------------- | ---------------------- | --------------------------------------- |
 | `basedpyright`| `basedpyright-langserver --stdio` | `pip install basedpyright` | strictest types, **default**       |
 | `pyright`     | `pyright-langserver --stdio`  | `pip install pyright`  | upstream Microsoft type checker         |
 | `ty`          | `ty server`                   | `pip install ty`       | Astral, very fast, pre-1.0/experimental |
-| `ruff`        | `ruff server`                 | `pip install ruff`     | lint + format only, complements a type server |
+| `ruff`        | `ruff server`                 | `pip install ruff`     | lint + format only, no type checking    |
 
-Recommended priority: **basedpyright** (default) > pyright > ty (experimental).
-`ruff` complements via priority — it does not type-check, so keep a type server
-enabled.
+Recommended: **basedpyright** (default) > pyright > ty (experimental). Keep a
+type server as the `.py` server; run `ruff` from the shell or a pre-commit hook
+for lint/format.
 
-Enable ruff alongside basedpyright, disabling pyright:
+Switch this project to pyright:
 
 ```json
 { "lsp": {
-  "basedpyright": { "priority": 100 },
-  "ruff": { "priority": 90 },
-  "pyright": { "disabled": true }
+  "pyright": { "priority": 100 },
+  "basedpyright": { "disabled": true }
 } }
 ```
 

package/packages/omo-codex/plugin/skills/lsp-setup/references/ruby/README.md

@@ -22,13 +22,13 @@ command -v rubocop
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "ruby-lsp": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)
 

package/packages/omo-codex/plugin/skills/lsp-setup/references/rust/README.md

@@ -22,13 +22,13 @@ command -v rust-analyzer
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "rust": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)
 

package/packages/omo-codex/plugin/skills/lsp-setup/references/swift/README.md

@@ -1,7 +1,7 @@
 # Swift — LSP setup
 
 - **Builtin server:** `sourcekit-lsp` — `sourcekit-lsp`
-- **Extensions:** `.swift .objc .objcpp`
+- **Extensions:** `.swift .m .mm`
 - **Install hint:** `Included with Xcode or the Swift toolchain`
 
 ## Install
@@ -20,13 +20,13 @@ command -v sourcekit-lsp
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "sourcekit-lsp": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)
 
@@ -41,7 +41,7 @@ None commonly required. For best results the project needs a **SwiftPM `Package.
 - **PATH:** `sourcekit-lsp` on PATH; reopen shell after install (or after `xcode-select -s`).
 - **Wrong toolchain (macOS):** point `xcode-select` at the right Xcode/toolchain; mismatches cause stale or missing results.
 - **No `Package.swift` / compile db:** add a SwiftPM manifest or generate `compile_commands.json` for accurate indexing.
-- **Objective-C (`.objc`/`.objcpp`):** needs a compilation database to resolve headers and frameworks.
+- **Objective-C (`.m`/`.mm`):** needs a compilation database to resolve headers and frameworks.
 - **First build slow:** the server builds the module graph on first open; wait for it.
 
 ## Verify

package/packages/omo-codex/plugin/skills/lsp-setup/references/terraform/README.md

@@ -23,13 +23,13 @@ command -v terraform
 
 ## Configure
 
-Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in every harness's project config (per-harness paths: the Configure step in `SKILL.md`):
 
 ```json
 { "lsp": { "terraform": { "priority": 100 } } }
 ```
 
-For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled` (a project entry drops `env`). `env`, and a fully custom (non-builtin) server with its own `command`, must go in your harness's USER config (see the Configure step in `SKILL.md`).
 
 ### Initialization options (only if commonly needed)