oh-my-opencode 4.8.1 → 4.9.0

package/packages/omo-codex/plugin/scripts/sync-version.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const defaultPluginRoot = dirname(scriptDir);
+const defaultRepoRoot = join(defaultPluginRoot, "..", "..", "..");
+
+async function readJson(path) {
+	return JSON.parse(await readFile(path, "utf8"));
+}
+
+async function writeJson(path, value) {
+	await writeFile(path, `${JSON.stringify(value, null, "\t")}\n`);
+}
+
+function normalizeVersion(version) {
+	if (typeof version !== "string") return "";
+	return version.trim();
+}
+
+export async function resolveAuthoritativeVersion(options = {}) {
+	const env = options.env ?? process.env;
+	const explicit = normalizeVersion(options.version ?? env.LAZYCODEX_RELEASE_VERSION);
+	if (explicit.length > 0) return explicit;
+
+	const repoRoot = options.repoRoot ?? defaultRepoRoot;
+	const rootVersion = normalizeVersion((await readJson(join(repoRoot, "package.json"))).version);
+	if (rootVersion.length === 0) {
+		throw new Error(`Cannot resolve authoritative version: ${join(repoRoot, "package.json")} has no version`);
+	}
+	return rootVersion;
+}
+
+async function stampJsonVersion(path, version) {
+	let parsed;
+	try {
+		parsed = await readJson(path);
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+		throw error;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return false;
+	if (!("version" in parsed)) return false;
+	if (parsed.version === version) return false;
+	parsed.version = version;
+	await writeJson(path, parsed);
+	return true;
+}
+
+async function collectComponentManifests(pluginRoot) {
+	const componentsRoot = join(pluginRoot, "components");
+	let entries;
+	try {
+		entries = await readdir(componentsRoot, { withFileTypes: true });
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return [];
+		throw error;
+	}
+	const manifests = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		manifests.push(join(componentsRoot, entry.name, "package.json"));
+	}
+	return manifests;
+}
+
+export function manifestTargets(pluginRoot, componentManifests) {
+	const omoCodexRoot = dirname(pluginRoot);
+	return [
+		join(omoCodexRoot, "package.json"),
+		join(pluginRoot, "package.json"),
+		join(pluginRoot, ".codex-plugin", "plugin.json"),
+		...componentManifests,
+	];
+}
+
+export async function syncVersion(options = {}) {
+	const pluginRoot = options.pluginRoot ?? defaultPluginRoot;
+	const version = options.version ?? (await resolveAuthoritativeVersion({ ...options, version: undefined }));
+	const componentManifests = await collectComponentManifests(pluginRoot);
+	const targets = manifestTargets(pluginRoot, componentManifests);
+	const changed = [];
+	for (const target of targets) {
+		if (await stampJsonVersion(target, version)) changed.push(target);
+	}
+	return { version, targets, changed };
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+	const result = await syncVersion();
+	console.log(`Synced OMO Codex manifests to version ${result.version} (${result.changed.length} updated)`);
+}

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

@@ -8,17 +8,17 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 | OpenCode example | Codex tool to use |
 | --- | --- |
-| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
-| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` |
-| `task(subagent_type="plan", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a planning agent. ...","fork_turns":"none"})` |
-| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})` |
-| `task(category="...", ...)` for implementation or QA | `spawn_agent({"task_name":"...","message":"TASK: act as an implementation or QA worker. ...","fork_turns":"none"})` |
-| `background_output(task_id="...")` | `wait_agent(...)` for mailbox signals; after a timeout, run one `list_agents` check for the named child if reassurance is needed |
-| `team_*(...)` | Use Codex native subagents plus `send_message`, `followup_task`, `wait_agent`, and `close_agent` |
+| `call_omo_agent(subagent_type="explore", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as an explorer. ...","agent_type":"explorer","fork_context":false})` |
+| `call_omo_agent(subagent_type="librarian", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a librarian. ...","agent_type":"librarian","fork_context":false})` |
+| `task(subagent_type="plan", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a planning agent. ...","agent_type":"plan","fork_context":false})` |
+| `task(subagent_type="oracle", ...)` for final verification | `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"codex-ultrawork-reviewer","fork_context":false})` |
+| `task(category="...", ...)` for implementation or QA | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false})` |
+| `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals |
+| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent`, `multi_agent_v1.send_input`, `multi_agent_v1.wait_agent`, and `multi_agent_v1.close_agent` |
 
-Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained `message` and usually should use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, and `codex-ultrawork-reviewer` — pass the matching name as `agent_type` so the child gets that role's model and instructions. On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
-For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `wait_agent` timeout only means no new mailbox update arrived. Treat a running child or latest `WORKING:` message as alive. Do not use `list_agents` as a polling loop. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
+For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 # /init-deep
 

package/packages/omo-codex/plugin/skills/lcx-contribute-bug-fix/SKILL.md

@@ -30,7 +30,22 @@ Create a PR that includes:
 
 1. Read the user's bug report and identify the affected surface.
 2. Invoke `$omo:debugging` for the investigation. If only unqualified skill names are exposed, invoke `$debugging` and state that it is the OMO debugging skill.
-3. Decide the target repository. If ownership is close, compare against upstream Codex source under `/tmp/openai-codex-source` before choosing.
+3. Materialize the latest sources, then decide the target repository. Sync both checkouts on every run and compare them before choosing — a stale checkout routes the fix to the wrong repo:
+
+```bash
+sync_latest_source() {
+  REPO="$1"; DEST="$2"
+  if [ ! -d "$DEST/.git" ]; then
+    gh repo clone "$REPO" "$DEST" -- --depth=1 \
+      || git clone --depth=1 "https://github.com/$REPO" "$DEST"
+  fi
+  DEFAULT_BRANCH="$(git -C "$DEST" remote show origin | sed -n '/HEAD branch/s/.*: //p')"
+  git -C "$DEST" fetch --depth=1 origin "$DEFAULT_BRANCH"
+  git -C "$DEST" checkout -B "$DEFAULT_BRANCH" FETCH_HEAD
+}
+sync_latest_source code-yeongyu/lazycodex /tmp/lazycodex-source
+sync_latest_source openai/codex /tmp/openai-codex-source
+```
 4. Create a fresh temporary clone and branch. Do not modify the user's current repository for the target fix unless the current repository is itself the requested target and the user explicitly asked for local edits.
 
 ```bash

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

@@ -0,0 +1,93 @@
+---
+name: lcx-doctor
+description: "Diagnose LazyCodex and Codex CLI installation health against the latest sources. Use whenever the user asks for a doctor or health check, says LazyCodex, lazycodex-ai, omo-codex, or Codex behaves oddly after an install, update, or config change, suspects a stale, drifted, or broken setup, or wants the local install audited and compared with the latest LazyCodex and Codex code."
+metadata:
+  short-description: Diagnose LazyCodex/Codex install health against latest sources
+---
+
+# lcx-doctor
+
+You are a LazyCodex install doctor. Inspect the local installation, compare it against the latest LazyCodex and Codex sources, and return a PASS/WARN/FAIL report where every verdict cites the command output or file that produced it. Diagnose only: the only writes you make are under `/tmp`. Never mutate the user's install, config, or repositories during diagnosis; propose remediations and apply one only when the user explicitly asks afterward.
+
+Use GPT-5.5 style: outcome first, concise, evidence-bound.
+
+## Required Workflow
+
+1. Materialize the latest sources under `/tmp` first. Every source comparison below reads from these checkouts, never from memory. Re-sync on every run so a cached checkout cannot go stale:
+
+```bash
+sync_latest_source() {
+  REPO="$1"; DEST="$2"
+  if [ ! -d "$DEST/.git" ]; then
+    gh repo clone "$REPO" "$DEST" -- --depth=1 \
+      || git clone --depth=1 "https://github.com/$REPO" "$DEST"
+  fi
+  DEFAULT_BRANCH="$(git -C "$DEST" remote show origin | sed -n '/HEAD branch/s/.*: //p')"
+  git -C "$DEST" fetch --depth=1 origin "$DEFAULT_BRANCH"
+  git -C "$DEST" checkout -B "$DEFAULT_BRANCH" FETCH_HEAD
+}
+sync_latest_source code-yeongyu/lazycodex /tmp/lazycodex-source
+sync_latest_source openai/codex /tmp/openai-codex-source
+```
+
+2. Inventory the installed surface. Resolve `CODEX_HOME` (default `~/.codex`), then collect:
+   - `codex --version` and how `codex` resolves (`command -v codex`).
+   - Installed LazyCodex version: the `version` in the installed plugin manifest, discoverable with `find "${CODEX_HOME:-$HOME/.codex}/plugins" -path '*/.codex-plugin/plugin.json'`. Installed plugins live under `$CODEX_HOME/plugins/cache/<marketplace>/<name>/<version>/`.
+   - Latest LazyCodex version from `/tmp/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`).
+3. Check config and wiring against the latest installer, not against assumptions. Read what the current installer under `/tmp/lazycodex-source` writes (installer sources live in the omo-codex package, e.g. `scripts/install/`), 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: `hooks/hooks.json`, `skills/`, `.mcp.json`, components under the installed plugin root.
+   - Stale project-local leftovers the installer now removes (e.g. `.codex/hooks.json`, `.codex/skills` in the project) are flagged, not deleted.
+4. Probe the real surface. Run the built-in diagnostics first: `lazycodex doctor --json` (add `--verbose` when a check needs deeper traces) and fold its results into the report. A missing or crashing `lazycodex doctor` is itself a FAIL finding, not a reason to skip probing — fall back to `codex --version` plus a trivial non-interactive invocation that loads the plugin. Capture stderr verbatim; a clean exit with warnings is WARN, not PASS.
+5. Compare for drift. Where installed bundled files differ from the same files at the installed version, or the latest source renamed or removed something the local config still references, record it with both paths.
+6. Check whether each FAIL is already known: `gh issue list --repo code-yeongyu/lazycodex --search "<short symptom>" --state open` (and `openai/codex` when the failure points upstream). Link matches in the report instead of re-diagnosing from scratch.
+7. If a probe fails and the cause is not explained by config or source comparison, invoke `$omo:debugging` for the investigation. If Codex exposes only unqualified skill names in the current session, invoke `$debugging` and state that it is the OMO debugging skill.
+8. Emit the report.
+
+## Doctor Report Template
+
+```markdown
+## LazyCodex Doctor Report
+
+### Summary
+[One sentence: healthy, degraded, or broken — and the single most important next action.]
+
+### Environment
+- LazyCodex installed / latest:
+- Codex CLI installed / latest:
+- CODEX_HOME:
+- OS / install method:
+
+### Checks
+| Check | Verdict | Evidence |
+| --- | --- | --- |
+| Versions current | PASS/WARN/FAIL | [command output or file:line] |
+| config.toml integrity | PASS/WARN/FAIL | [evidence] |
+| Plugin payload wiring | PASS/WARN/FAIL | [evidence] |
+| Bin links / aliases | PASS/WARN/FAIL | [evidence] |
+| Runtime probe | PASS/WARN/FAIL | [evidence] |
+| Drift vs latest source | PASS/WARN/FAIL | [evidence, citing /tmp/lazycodex-source or /tmp/openai-codex-source paths] |
+
+### Remediations
+1. [Most important fix first: exact command or config edit, and what it resolves.]
+
+### Known Issues Matched
+- [issue URL — or "none found"]
+```
+
+## Follow-up Routing
+
+- Local misconfiguration or stale install: give the remediation; reinstalling via the standard LazyCodex install command is the default fix for payload drift.
+- Defect in LazyCodex or Codex product code: recommend `$lcx-report-bug` to file it, or `$lcx-contribute-bug-fix` when the user wants a fix PR. Both reuse the `/tmp` checkouts you already synced.
+
+## Stop Conditions
+
+Ask one narrow question only when a finding requires a destructive decision, such as deleting user-edited config or downgrading a version.
+
+Do not:
+
+- mutate config, installs, or repositories during diagnosis
+- report a verdict without captured evidence
+- compare against remembered source layout instead of `/tmp/lazycodex-source` and `/tmp/openai-codex-source`
+- declare healthy while any probe output was never captured

package/packages/omo-codex/plugin/skills/lcx-doctor/agents/openai.yaml

@@ -0,0 +1,11 @@
+interface:
+  display_name: "lcx-doctor (omo)"
+  short_description: "Diagnose LazyCodex/Codex install health against latest sources"
+  search_terms:
+    - "lcx-doctor"
+    - "lazycodex doctor"
+    - "lazycodex health check"
+    - "codex doctor"
+    - "lazycodex install broken"
+    - "omo-codex diagnose"
+  default_prompt: "Use $lcx-doctor to sync the latest LazyCodex and Codex sources into /tmp, inventory the local installation, compare versions, config, and wiring against the latest sources, probe the real surface, and report PASS/WARN/FAIL findings with evidence and remediations."

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

@@ -33,24 +33,28 @@ Create or prepare a GitHub issue or PR that includes:
 
 1. Read the user's bug report and identify the affected surface: LazyCodex installer, Codex plugin, skill, hook, MCP, CLI alias, GitHub marketplace sync, or web/docs.
 2. Invoke `$omo:debugging` for the investigation. If Codex exposes only unqualified skill names in the current session, invoke `$debugging` and state that it is the OMO debugging skill.
-3. Materialize upstream Codex source under `/tmp` before deciding ownership:
+3. Materialize the latest LazyCodex and upstream Codex sources under `/tmp` before deciding ownership. Re-sync on every run so a cached checkout cannot go stale — stale source produces wrong routing and dead line references:
 
 ```bash
-CODEX_SRC="/tmp/openai-codex-source"
-if [ ! -d "$CODEX_SRC/.git" ]; then
-  gh repo clone openai/codex "$CODEX_SRC" -- --depth=1
-else
-  git -C "$CODEX_SRC" fetch --depth=1 origin
-fi
+sync_latest_source() {
+  REPO="$1"; DEST="$2"
+  if [ ! -d "$DEST/.git" ]; then
+    gh repo clone "$REPO" "$DEST" -- --depth=1 \
+      || git clone --depth=1 "https://github.com/$REPO" "$DEST"
+  fi
+  DEFAULT_BRANCH="$(git -C "$DEST" remote show origin | sed -n '/HEAD branch/s/.*: //p')"
+  git -C "$DEST" fetch --depth=1 origin "$DEFAULT_BRANCH"
+  git -C "$DEST" checkout -B "$DEFAULT_BRANCH" FETCH_HEAD
+}
+sync_latest_source code-yeongyu/lazycodex /tmp/lazycodex-source
+sync_latest_source openai/codex /tmp/openai-codex-source
 ```
-
-If `gh` is unavailable, use `git clone --depth=1 https://github.com/openai/codex "$CODEX_SRC"`.
 4. Follow the debugging skill far enough to gather runtime evidence:
    - form at least three plausible hypotheses
    - run the smallest reproduction that exercises the real surface
    - confirm the root cause by observing the failing state
    - identify the minimal fix path or maintainer action
-5. Compare local LazyCodex evidence with `/tmp/openai-codex-source` before choosing the target repo. Cite exact files, commands, logs, or source paths that support the routing decision.
+5. Compare runtime evidence with both `/tmp/lazycodex-source` and `/tmp/openai-codex-source` before choosing the target repo. Cite exact files, commands, logs, or source paths that support the routing decision.
 6. Choose the target repo:
    - Use `code-yeongyu/lazycodex` when the bug is in LazyCodex integration, distribution, bundled plugin code, skills, hooks, MCP wiring, installer behavior, aliases, marketplace sync, docs, or any behavior that disappears in clean upstream Codex.
    - Use `openai/codex` when the bug reproduces in clean upstream Codex without LazyCodex, or the failing behavior comes from Codex CLI core, plugin API contracts, sandboxing, approvals, config loading, or built-in tool behavior.
@@ -106,7 +110,7 @@ Write the issue body in English and keep it direct:
 ## Repository Decision
 - Target repository:
 - Why this belongs there:
-- LazyCodex evidence:
+- LazyCodex evidence (runtime + `/tmp/lazycodex-source`):
 - Upstream Codex source evidence from `/tmp/openai-codex-source`:
 
 ## Reproduction
@@ -150,7 +154,7 @@ Use this when a PR is the right artifact:
 ## Repository Decision
 - Target repository:
 - Why this belongs there:
-- LazyCodex evidence:
+- LazyCodex evidence (runtime + `/tmp/lazycodex-source`):
 - Upstream Codex source evidence from `/tmp/openai-codex-source`:
 
 ## Root Cause
@@ -227,6 +231,6 @@ Do not file:
 - a vague issue without reproduction steps
 - an issue that claims a root cause not supported by runtime evidence
 - a duplicate when commenting on an existing issue is enough
-- an upstream Codex issue without checking `/tmp/openai-codex-source`
+- an issue without checking the latest `/tmp/lazycodex-source` and `/tmp/openai-codex-source` checkouts
 - a LazyCodex issue when the bug is proven to reproduce in clean upstream Codex
 - a fix PR without a concrete branch, implemented fix, and verification result

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

@@ -0,0 +1,139 @@
+---
+name: lsp-setup
+description: "Configure a Language Server (LSP) for a specific language so editor/agent tooling — diagnostics, go-to-definition, find-references, rename — works. Use when you need to: configure LSP, lsp setup, set up or install a language server, fix 'no LSP server configured' / 'server not installed', choose between servers (basedpyright vs pyright vs ty vs ruff), or wire .codex/lsp-client.json / .opencode/lsp.json. 언어서버 설정. Routes by file extension to references/<language>/README.md for the exact builtin server, per-OS install commands (macOS/Linux/Windows), config snippets for both config files, initialization options, alternatives, and troubleshooting. Ships scripts: detect-lsp.ts (scan a project for languages + each server's install/config status) and verify-lsp.ts (run a real diagnostics roundtrip). Covers typescript, python, go, rust, c/c++, java, kotlin, c#/razor, swift, ruby, php, dart, elixir, zig, lua, bash, yaml, terraform, haskell, julia."
+---
+
+# LSP Setup
+
+Configure the right Language Server for a project so the `lsp` MCP tools
+(`diagnostics`, `goto_definition`, `find_references`, `symbols`, `rename`)
+actually work. This skill is an index: detect what a project needs, install the
+server, write the config, then verify with a real roundtrip.
+
+The list of servers we ship as **builtin** is the source of truth in
+`packages/lsp-tools-mcp/src/lsp/server-definitions.ts` (`BUILTIN_SERVERS` +
+`LSP_INSTALL_HINTS`). The per-language references below mirror it.
+
+---
+
+## PHASE 0 — LANGUAGE GATE (run first)
+
+Identify the language from the file extension, then **read the matching
+reference before installing or configuring anything**.
+
+| Extension(s) | Reference |
+|---|---|
+| `.ts .tsx .js .jsx .mjs .cjs .mts .cts .vue .svelte .astro` | `references/typescript/README.md` |
+| `.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` |
+| `.java` | `references/java/README.md` |
+| `.kt .kts` | `references/kotlin/README.md` |
+| `.cs .razor .cshtml` | `references/csharp/README.md` |
+| `.swift` | `references/swift/README.md` |
+| `.rb .rake .gemspec .ru` | `references/ruby/README.md` |
+| `.php` | `references/php/README.md` |
+| `.dart` | `references/dart/README.md` |
+| `.ex .exs` | `references/elixir/README.md` |
+| `.zig .zon` | `references/zig/README.md` |
+| `.lua` | `references/lua/README.md` |
+| `.sh .bash .zsh .ksh` | `references/bash/README.md` |
+| `.yaml .yml` | `references/yaml/README.md` |
+| `.tf .tfvars` | `references/terraform/README.md` |
+| `.hs .lhs` | `references/haskell/README.md` |
+| `.jl` | `references/julia/README.md` |
+
+---
+
+## WORKFLOW — detect → install → configure → verify
+
+### 1. Detect
+
+Scan the project to see which languages are present and whether each server is
+installed and configured:
+
+```bash
+bun scripts/detect-lsp.ts <projectDir>      # human report (default: cwd)
+bun scripts/detect-lsp.ts <projectDir> --json
+```
+
+For each detected language it prints the builtin server id, the executable it
+needs on `PATH`, whether that executable is installed, an install hint, and
+whether a project config file already references it.
+
+### 2. Install
+
+Open `references/<language>/README.md` and run the install command for your OS.
+Then confirm the executable resolves:
+
+```bash
+command -v <server-executable>   # e.g. typescript-language-server, gopls, rust-analyzer
+```
+
+### 3. Configure
+
+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.
+
+Two project-scoped config files, **identical JSON shape**:
+
+- Codex harness → `.codex/lsp-client.json` (user: `~/.codex/lsp-client.json`)
+- OpenCode/omo harness → `.opencode/lsp.json` (also `.omo/lsp.json`)
+
+```jsonc
+{
+  "lsp": {
+    "<server-id>": {
+      "command": ["<bin>", "<args>"],   // optional for builtin ids (supplied automatically)
+      "extensions": [".ext"],            // optional override
+      "priority": 100,                    // higher wins when several servers match an extension
+      "initialization": { },              // server-specific initializationOptions
+      "env": { "KEY": "value" },          // optional
+      "disabled": false                   // set true to turn a server off
+    }
+  }
+}
+```
+
+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.
+
+Each language reference gives a ready-to-paste snippet.
+
+### 4. Verify
+
+Run a real diagnostics roundtrip against a source file. This spawns the server,
+opens the file, requests diagnostics, and reports `OK`/`FAIL`:
+
+```bash
+bun scripts/verify-lsp.ts <path/to/file.ext>
+bun scripts/verify-lsp.ts <file> --timeout=90000
+```
+
+`OK` = the server started and answered. `FAIL: language server not installed`
+= go back to step 2. Other `FAIL` text carries the server/startup error.
+`SKIP` = the engine source could not be located; run from inside the omo
+repo/worktree, or call the `lsp` MCP `diagnostics` tool directly.
+
+---
+
+## Scripts
+
+| Script | Purpose |
+|---|---|
+| `scripts/detect-lsp.ts` | Scan a directory; per detected language report server id, install status, install hint, config status. `--json` for machine output. |
+| `scripts/verify-lsp.ts` | Real LSP diagnostics roundtrip for one file via the `lsp-tools-mcp` engine; `OK`/`FAIL`/`SKIP` + exit code 0/1/3. |
+| `scripts/lsp-server-table.ts` | Embedded snapshot of the primary builtin server per language (mirrors `server-definitions.ts`). |
+
+Run with [Bun](https://bun.sh): `curl -fsSL https://bun.sh/install | bash`.

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

@@ -0,0 +1,60 @@
+# Bash — LSP setup
+
+- **Builtin server:** `bash` — `bash-language-server start`
+- **Extensions:** `.sh .bash .zsh .ksh`
+- **Install hint:** `npm install -g bash-language-server`
+
+An alias id `bash-ls` exists with the identical command; either id works.
+
+## Install
+
+- **macOS:** `npm install -g bash-language-server`
+- **Linux:** `npm install -g bash-language-server`
+- **Windows:** `npm install -g bash-language-server` (PowerShell)
+
+For real diagnostics, also install `shellcheck`:
+
+- **macOS:** `brew install shellcheck`
+- **Linux:** `apt install shellcheck` (or `dnf install ShellCheck`)
+- **Windows:** `scoop install shellcheck`
+
+Confirm it resolves:
+
+```bash
+command -v bash-language-server
+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):
+
+```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`).
+
+### 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`:
+
+```json
+{ "lsp": { "bash": { "env": { "SHELLCHECK_PATH": "/opt/bin/shellcheck" } } } }
+```
+
+## Alternatives
+
+- `shellcheck` standalone as a linter-only flow (no LSP).
+- `shfmt` for formatting (complements, does not replace, the LSP).
+
+## Troubleshooting
+- **PATH:** `bash-language-server` on PATH; reopen shell after `npm -g` install.
+- **No diagnostics:** `shellcheck` missing — diagnostics are powered by it; install and reopen.
+- **Wrong shell dialect:** `.zsh`/`.ksh` are linted as bash; shellcheck may flag shell-specific syntax.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.sh
+```

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

@@ -0,0 +1,61 @@
+# C / C++ — LSP setup
+
+- **Builtin server:** `clangd` — `clangd --background-index --clang-tidy`
+- **Extensions:** `.c .cpp .cc .cxx .c++ .h .hpp .hh .hxx .h++`
+- **Install hint:** `https://clangd.llvm.org/installation`
+
+## Install
+
+- **macOS:** `brew install llvm` (clangd ships in the LLVM keg; add its `bin` to PATH)
+- **Linux:** `apt install clangd` (Debian/Ubuntu); use your distro package elsewhere
+- **Windows:** install LLVM from `https://releases.llvm.org` or `winget install LLVM.LLVM`
+
+See `https://clangd.llvm.org/installation` for other platforms.
+
+Confirm it resolves:
+
+```bash
+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):
+
+```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`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required. clangd reads flags from a project `.clangd` file rather
+than initializationOptions. The builtin command already passes
+`--background-index --clang-tidy`.
+
+## Compile commands
+
+clangd needs a `compile_commands.json` at the project root (or in `build/`) for
+accurate diagnostics and cross-file navigation. Generate it with:
+
+- **CMake:** `cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON` (symlink/copy `build/compile_commands.json` to the root)
+- **Make / other:** `bear -- make`
+
+Without it, clangd falls back to heuristic flags and reports spurious errors.
+
+## Alternatives
+
+None builtin. `ccls` exists as a third-party server but is not builtin — it would
+need a custom `command` in the USER config.
+
+## Troubleshooting
+- **PATH:** `clangd` must be on PATH; reopen shell after install. Homebrew LLVM is keg-only — add `$(brew --prefix llvm)/bin` to PATH.
+- **Spurious "file not found" / unknown flags:** missing or stale `compile_commands.json` — regenerate it after changing the build.
+- **Header-only diagnostics wrong:** ensure the header's translation unit appears in the compile database, or add a `.clangd` `CompileFlags` block.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.cpp
+```

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

@@ -0,0 +1,71 @@
+# C# — LSP setup
+
+- **Builtin server:** `csharp` — `csharp-ls`
+- **Extensions:** `.cs`
+- **Install hint:** `dotnet tool install -g csharp-ls`
+
+## Install
+
+Requires the **.NET SDK**. Install the tool globally:
+
+- **macOS:** `dotnet tool install -g csharp-ls`
+- **Linux:** `dotnet tool install -g csharp-ls`
+- **Windows:** `dotnet tool install -g csharp-ls`
+
+Global .NET tools land in `~/.dotnet/tools` — ensure that directory is on PATH (Windows: `%USERPROFILE%\.dotnet\tools`).
+
+Confirm it resolves:
+
+```bash
+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):
+
+```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`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required. `csharp-ls` picks up the nearest `.sln` or `.csproj`; keep the solution restorable (`dotnet restore`).
+
+## Razor / Blazor
+
+Razor and Blazor files use a separate builtin server:
+
+- **Builtin server:** `razor` — `roslyn-language-server --stdio`
+- **Extensions:** `.razor .cshtml`
+- **Install hint:** `dotnet tool install -g roslyn-language-server --prerelease` (requires **v5.8.0+**; see [dotnet/razor](https://github.com/dotnet/razor))
+
+```bash
+dotnet tool install -g roslyn-language-server --prerelease
+command -v roslyn-language-server
+```
+
+Enable it in a project/user config:
+
+```json
+{ "lsp": { "razor": { } } }
+```
+
+## Alternatives
+
+- **OmniSharp** — legacy C# language server (not builtin). Still works but is being superseded by the Roslyn-based servers; prefer `csharp-ls` / `roslyn-language-server`.
+
+## Troubleshooting
+
+- **PATH:** `csharp-ls` / `roslyn-language-server` on PATH (`~/.dotnet/tools`); reopen shell after install.
+- **No .NET SDK:** install the SDK (not just the runtime) before installing the tool.
+- **No symbols:** run `dotnet restore`; an unrestored solution yields empty results.
+- **Razor needs v5.8.0+:** older `roslyn-language-server` builds lack the `--stdio` Razor support — install with `--prerelease`.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/File.cs
+```