The one and only agent harness for complex codebases. Project memory, planning, execution, and verified completion inside Codex.
JavaScript aiai-agentsclaudeclaude-codeclicodexdeveloper-toolslazylazycodexoh-my-openagentomoopenaiorchestrationtypescript
fix(web): stabilize stars and move skills earlier
YeonGyu-Kimc2195f1d8f1a
diff --git a/packages/web/DESIGN.md b/packages/web/DESIGN.mdindex f5fda84e..00ac9602 100644--- a/packages/web/DESIGN.md+++ b/packages/web/DESIGN.md@@ -44,7 +44,7 @@ Borders / status:## 6. Docs Information Architecture (vibetip-inspired)The docs are a single richly-sectioned page with a grouped sidebar, ⌘K search, a per-section right-side table of contents, and prev/next navigation cards — inspired by the lzx.vibetip.help docs layout.-- **Sidebar groups** (ordered): Install · Getting started · Commands · Concepts · Skills · Reference.+- **Sidebar groups** (ordered): Install · Getting started · Commands · Skills · Concepts · Reference.- **⌘K / Ctrl-K** focuses the search field from anywhere; typing filters sidebar entries by title.- **Right ToC ("On this section")** lists the active section's `h2`/`h3` headings with scroll-spy highlighting.- **Prev/next cards** at the end of every section link to the neighboring section.diff --git a/packages/web/app/api/github-stars/route.ts b/packages/web/app/api/github-stars/route.tsindex 03e58eac..a5e4f87a 100644--- a/packages/web/app/api/github-stars/route.ts+++ b/packages/web/app/api/github-stars/route.ts@@ -5,8 +5,8 @@ import { FALLBACK_GITHUB_STARS, formatStarsCount } from "../../../lib/github-staexport const dynamic = "force-dynamic"export const revalidate = 60-const LIVE_CACHE_CONTROL = "public, s-maxage=60, stale-while-revalidate=300"-const FALLBACK_CACHE_CONTROL = "no-store"+const LIVE_CACHE_CONTROL = "public, s-maxage=300, stale-while-revalidate=3600"+const FALLBACK_CACHE_CONTROL = "public, s-maxage=3600, stale-while-revalidate=86400"type GitHubStarsFallbackPayload = {readonly stars: numberdiff --git a/packages/web/app/page.tsx b/packages/web/app/page.tsxindex 20ca8d0f..f6fec7a9 100644--- a/packages/web/app/page.tsx+++ b/packages/web/app/page.tsx@@ -27,8 +27,8 @@ export default function LandingPage(): JSX.Element {</div><InstallBlock /><CommandCards />- <HephaestusSection /><FeatureWorkflowsSection />+ <HephaestusSection /><UltraworkSection /><DocsCta /></main>diff --git a/packages/web/components/site/github-stars-pill.tsx b/packages/web/components/site/github-stars-pill.tsxindex 596f1a89..bb576b8e 100644--- a/packages/web/components/site/github-stars-pill.tsx+++ b/packages/web/components/site/github-stars-pill.tsx@@ -10,12 +10,19 @@ function readFormattedStars(payload: unknown): string | undefined {return undefined}+ if ("stars" in payload) {+ const stars = payload.stars+ if (typeof stars !== "number" || !Number.isFinite(stars) || stars <= 0) {+ return undefined+ }+ }+const formatted = payload.formattedif (typeof formatted !== "string" || formatted.trim().length === 0) {return undefined}- return formatted+ return formatted === "0" ? undefined : formatted}export function GithubStarsPill(): JSX.Element {@@ -26,7 +33,7 @@ export function GithubStarsPill(): JSX.Element {async function refreshStars(): Promise<void> {try {- const response = await fetch("/api/github-stars", { cache: "no-store" })+ const response = await fetch("/api/github-stars")if (!response.ok || cancelled) returnconst payload: unknown = await response.json()diff --git a/packages/web/content/docs/skills.md b/packages/web/content/docs/skills.mdindex eaeb8d7d..c730a498 100644--- a/packages/web/content/docs/skills.md+++ b/packages/web/content/docs/skills.md@@ -14,7 +14,9 @@ The three command pillars stay simple:- `$ulw-plan` turns fuzzy work into a decision-complete plan- `$start-work` executes a plan with durable Boulder progress-Skills add specialist judgment around those pillars:+Skills add specialist judgment around those pillars.++Most skills auto-activate when a request matches their domain, so you do not need to study or manually select every skill before using LazyCodex. When you want to be explicit, put the skill name in the prompt — for example `$visual-qa`, `$git-master`, or `$ultraresearch`.| Skill | Use it for || --- | --- |@@ -24,13 +26,13 @@ Skills add specialist judgment around those pillars:| `start-work` | Execute a plan with durable Boulder progress || `review-work` | Five-lane parallel post-implementation review || `remove-ai-slops` | Behavior-preserving cleanup of AI-looking code |-| `frontend-ui-ux` | Designed UI work instead of generic layout filling |+| `frontend` | Designed UI work instead of generic layout filling || `programming` | Strict TypeScript, Rust, Python, or Go discipline, TDD-first || `git-master` | Atomic commits, rebase/squash, push safety, history investigation || `visual-qa` | Screenshot/TUI diff plus dual-oracle visual QA || `debugging` | Evidence-led root-cause investigation || `refactor` | Behavior-preserving restructure of existing code |-| `ultraresearch` | Deep multi-source research synthesis |+| `ultraresearch` | Maximum-saturation research: parallel codebase, web, official-docs, and OSS-repo swarms, recursive lead expansion, empirical verification, and cited synthesis || `LSP` | Diagnostics, definitions, references, symbols, and renames || `lsp-setup` | Configure language servers for a project || `AST-grep` | Structural search and rewrite across code |diff --git a/packages/web/e2e/docs.spec.ts b/packages/web/e2e/docs.spec.tsindex ca2669aa..a29e7a23 100644--- a/packages/web/e2e/docs.spec.ts+++ b/packages/web/e2e/docs.spec.ts@@ -1,5 +1,5 @@import { expect, test } from "@playwright/test"-import { DOC_SECTIONS } from "../lib/docs-sections"+import { DOC_GROUPS, DOC_SECTIONS } from "../lib/docs-sections"/*** Docs `/docs` contract (TDD target state).@@ -69,11 +69,22 @@ test.describe("docs page — structure", () => {await expect(body).toContainText("Feature coverage")await expect(body).toContainText("review-work")await expect(body).toContainText("remove-ai-slops")- await expect(body).toContainText("frontend-ui-ux")+ await expect(body).toContainText("frontend")+ await expect(body).toContainText("Most skills auto-activate")+ await expect(body).toContainText("Maximum-saturation research")await expect(body).toContainText("LSP")await expect(body).toContainText("AST-grep")await expect(body).toContainText("comment-checker")})++ test("orders Skills immediately after Commands and before Concepts", () => {+ const sectionIds = DOC_SECTIONS.map((section) => section.id)++ expect(DOC_GROUPS.indexOf("Commands")).toBeLessThan(DOC_GROUPS.indexOf("Skills"))+ expect(DOC_GROUPS.indexOf("Skills")).toBeLessThan(DOC_GROUPS.indexOf("Concepts"))+ expect(sectionIds.indexOf("ulw-loop")).toBeLessThan(sectionIds.indexOf("skills"))+ expect(sectionIds.indexOf("skills")).toBeLessThan(sectionIds.indexOf("ultrawork"))+ })})test.describe("docs page — navigation", () => {diff --git a/packages/web/e2e/github-stars.spec.ts b/packages/web/e2e/github-stars.spec.tsindex 755cf9c4..60c85fc5 100644--- a/packages/web/e2e/github-stars.spec.ts+++ b/packages/web/e2e/github-stars.spec.ts@@ -3,8 +3,10 @@ import { join } from "node:path"import { expect, test } from "@playwright/test"import {fetchGitHubStars,+ parseGitHubStarsPayload,parseShieldsStarsPayload,} from "../lib/github-stars"+import { FALLBACK_GITHUB_STARS, formatStarsCount } from "../lib/github-stars-format"function restoreEnvVar(name: string, value: string | undefined): void {if (value === undefined) {@@ -88,9 +90,19 @@ test.describe("github stars live source parsing", () => {expect(parseShieldsStarsPayload({ message: "invalid" })).toBeUndefined()})- test("does not cache static fallback responses", () => {+ test("caches the non-zero fallback instead of serving a zero-star shell", () => {const routeSource = readFileSync(join(process.cwd(), "app/api/github-stars/route.ts"), "utf8")- expect(routeSource).toContain('const FALLBACK_CACHE_CONTROL = "no-store"')+ expect(FALLBACK_GITHUB_STARS).toBeGreaterThan(0)+ expect(formatStarsCount(FALLBACK_GITHUB_STARS)).not.toBe("0")+ expect(routeSource).toContain(+ 'const FALLBACK_CACHE_CONTROL = "public, s-maxage=3600, stale-while-revalidate=86400"',+ )+ })++ test("rejects zero-star upstream payloads as stale or broken source data", () => {+ expect(parseGitHubStarsPayload({ stargazers_count: 0 })).toBeUndefined()+ expect(parseShieldsStarsPayload({ value: 0 })).toBeUndefined()+ expect(parseShieldsStarsPayload({ message: "0" })).toBeUndefined()})})diff --git a/packages/web/e2e/landing.spec.ts b/packages/web/e2e/landing.spec.tsindex be6bbc78..3e1db252 100644--- a/packages/web/e2e/landing.spec.ts+++ b/packages/web/e2e/landing.spec.ts@@ -66,6 +66,21 @@ test.describe("landing page — install + commands", () => {await expect(page.getByText("Evidence at the end", { exact: false }).first()).toBeVisible()await expect(page.getByText("Built-in skill coverage", { exact: false }).first()).toBeVisible()})++ test("places skill coverage before the concept section", async ({ page }) => {+ await page.goto("/")++ const skillsTop = await page+ .getByText("Built-in skill coverage", { exact: false })+ .first()+ .evaluate((node) => node.getBoundingClientRect().top)+ const conceptsTop = await page+ .getByText("Where it comes from", { exact: false })+ .first()+ .evaluate((node) => node.getBoundingClientRect().top)++ expect(skillsTop).toBeLessThan(conceptsTop)+ })})test.describe("landing page — links + footer", () => {@@ -75,6 +90,7 @@ test.describe("landing page — links + footer", () => {await expect(stars).toBeVisible()await expect(stars).toContainText(/stars/i)await expect(stars).toContainText(/\d/)+ await expect(stars).not.toContainText(/^0\sstars$/)})test("updates the github stars pill from the live API", async ({ page }) => {diff --git a/packages/web/lib/docs-content.generated.ts b/packages/web/lib/docs-content.generated.tsindex ce050520..6f41dd65 100644--- a/packages/web/lib/docs-content.generated.ts+++ b/packages/web/lib/docs-content.generated.ts@@ -7,6 +7,7 @@ export const DOC_SOURCES: Record<string, string> = {"ulw-plan.md": "<p><code>$ulw-plan</code> is the strategic planning consultant (Prometheus). It turns an idea into a decision-complete work plan. It is a planner, NOT an implementer. When you say "do X" it produces a plan for X and never writes product code.</p>\n<h3 id=\"the-flow\">The flow</h3>\n<ol>\n<li><strong>Socratic interview</strong> — ask only the forks that exploration cannot resolve. When intent is fuzzy, research to best practice instead of interrogating.</li>\n<li><strong>Parallel codebase exploration</strong> — fan out read-only subagents to ground every decision in the actual code, never in memory.</li>\n<li><strong>Metis gap analysis</strong> — name every unknown the plan depends on and either close it or surface it as an explicit fork.</li>\n<li><strong>Write the plan</strong> to <code>plans/<slug>.md</code> — one decision-complete plan a worker executes with zero further interview.</li>\n<li><strong>Optional Momus high-accuracy review</strong> — an adversarial pass that tries to break the plan before it ships.</li>\n</ol>\n<h3 id=\"output\">Output</h3>\n<p>Questions, research, and a work plan whose every todo carries references, acceptance criteria, a QA plan, and a commit boundary. The plan records <code>status: awaiting-approval</code> and waits — it never begins execution itself.</p>\n<h3 id=\"handoff\">Handoff</h3>\n<p>Once you approve, hand the plan to <a href=\"#start-work\"><code>$start-work</code></a>, which executes it against durable Boulder state with the five evidence gates.</p>\n","start-work.md": "<p><code>$start-work</code> executes a Prometheus work plan until every top-level checkbox is done.</p>\n<h3 id=\"how-it-works\">How it works</h3>\n<ul>\n<li>Durable Boulder state in <code>.omo/boulder.json</code> survives across turns and sessions</li>\n<li>A Stop-hook re-injects the next turn until the plan is complete</li>\n<li>Independent sub-tasks fan out to parallel subagents</li>\n<li>Strict TDD plus five evidence gates: plan reread, automated verification, manual-QA, adversarial QA, cleanup</li>\n<li>Progress is recorded to a ledger</li>\n</ul>\n<h3 id=\"syntax\">Syntax</h3>\n<pre><code class=\"language-bash\">$start-work [plan-name] [--worktree <absolute-path>]\n</code></pre>\n<h3 id=\"done\">Done</h3>\n<p>It prints an <code>ORCHESTRATION COMPLETE</code> block when every checkbox is checked.</p>\n","ulw-loop.md": "<p><code>$ulw-loop</code> is a self-referential development loop that decomposes work into systematic, evidence-bound steps and runs until verified completion.</p>\n<h3 id=\"how-it-works\">How it works</h3>\n<p>The agent works continuously and emits <code><promise>DONE</promise></code> when it believes the task is complete, but that does NOT end the loop. An Oracle must verify the result first. The loop ends only after the system confirms the Oracle verified it. If verification fails, it continues with the message: "Oracle verification failed. Continuing ULTRAWORK loop."</p>\n<p>Each step carries its own evidence: a real artifact, not a dry-run claim. Progress is checkpointed, so a long run survives restarts without losing what was already proven.</p>\n<h3 id=\"bootstrap\">Bootstrap</h3>\n<p>Before the first run, the loop reads its full workflow reference (Bootstrap tier triage, the Execution Loop, and the Manual-QA channels table) so every later phase executes the same way. It only reads the sections the current phase needs.</p>\n<h3 id=\"manual-qa-channels\">Manual-QA channels</h3>\n<p>A step does not close on a status string. It closes on a captured artifact from a real surface — an HTTP call, a tmux session, or a browser — plus an adversarial pass and a cleanup receipt. See <a href=\"#manual-qa\">manual QA</a>.</p>\n<h3 id=\"syntax\">Syntax</h3>\n<pre><code class=\"language-bash\">$ulw-loop "task description" [--completion-promise=TEXT] [--strategy=reset|continue]\n</code></pre>\n<h3 id=\"limits\">Limits</h3>\n<p>The iteration cap is 500 in ultrawork mode (100 in normal mode).</p>\n<h3 id=\"reading-more\">Reading more</h3>\n<ul>\n<li><a href=\"#ultrawork\">ultrawork mode</a> — the mode that turns the loop into a binding verified run.</li>\n<li><a href=\"#hooks-lifecycle\">Hooks & Lifecycle</a> — how the Stop-hook re-injects the next turn.</li>\n</ul>\n",+ "skills.md": "<p>LazyCodex is most useful as a harness for complex codebases: project memory, planning, execution, verified completion, skills, hooks, model routing, and diagnostics.</p>\n<h3 id=\"built-in-workflows\">Built-in workflows</h3>\n<p>Start with <code>$init-deep</code> when the repository is too large or too old to explain from memory. It generates hierarchical <code>AGENTS.md</code> context so agents can find the right files before they change code.</p>\n<p>Use <code>$ulw-plan</code> when the work needs decisions before implementation, <code>$start-work</code> when a plan should be executed, and <code>$ulw-loop</code> when you want the agent to keep going until the result is verified.</p>\n<h3 id=\"feature-coverage\">Feature coverage</h3>\n<p>The three command pillars stay simple:</p>\n<ul>\n<li><code>$ulw-loop</code> keeps moving until verified completion</li>\n<li><code>$ulw-plan</code> turns fuzzy work into a decision-complete plan</li>\n<li><code>$start-work</code> executes a plan with durable Boulder progress</li>\n</ul>\n<p>Skills add specialist judgment around those pillars.</p>\n<p>Most skills auto-activate when a request matches their domain, so you do not need to study or manually select every skill before using LazyCodex. When you want to be explicit, put the skill name in the prompt — for example <code>$visual-qa</code>, <code>$git-master</code>, or <code>$ultraresearch</code>.</p>\n<table>\n<thead>\n<tr>\n<th>Skill</th>\n<th>Use it for</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>init-deep</code></td>\n<td>Hierarchical <code>AGENTS.md</code> context for large or old repos</td>\n</tr>\n<tr>\n<td><code>ulw-plan</code></td>\n<td>Explore-first planning before coding</td>\n</tr>\n<tr>\n<td><code>ulw-loop</code></td>\n<td>Evidence-bound loop until verified completion</td>\n</tr>\n<tr>\n<td><code>start-work</code></td>\n<td>Execute a plan with durable Boulder progress</td>\n</tr>\n<tr>\n<td><code>review-work</code></td>\n<td>Five-lane parallel post-implementation review</td>\n</tr>\n<tr>\n<td><code>remove-ai-slops</code></td>\n<td>Behavior-preserving cleanup of AI-looking code</td>\n</tr>\n<tr>\n<td><code>frontend</code></td>\n<td>Designed UI work instead of generic layout filling</td>\n</tr>\n<tr>\n<td><code>programming</code></td>\n<td>Strict TypeScript, Rust, Python, or Go discipline, TDD-first</td>\n</tr>\n<tr>\n<td><code>git-master</code></td>\n<td>Atomic commits, rebase/squash, push safety, history investigation</td>\n</tr>\n<tr>\n<td><code>visual-qa</code></td>\n<td>Screenshot/TUI diff plus dual-oracle visual QA</td>\n</tr>\n<tr>\n<td><code>debugging</code></td>\n<td>Evidence-led root-cause investigation</td>\n</tr>\n<tr>\n<td><code>refactor</code></td>\n<td>Behavior-preserving restructure of existing code</td>\n</tr>\n<tr>\n<td><code>ultraresearch</code></td>\n<td>Maximum-saturation research: parallel codebase, web, official-docs, and OSS-repo swarms, recursive lead expansion, empirical verification, and cited synthesis</td>\n</tr>\n<tr>\n<td><code>LSP</code></td>\n<td>Diagnostics, definitions, references, symbols, and renames</td>\n</tr>\n<tr>\n<td><code>lsp-setup</code></td>\n<td>Configure language servers for a project</td>\n</tr>\n<tr>\n<td><code>AST-grep</code></td>\n<td>Structural search and rewrite across code</td>\n</tr>\n<tr>\n<td><code>rules</code></td>\n<td>Project instructions from AGENTS, rules, and instruction files</td>\n</tr>\n<tr>\n<td><code>comment-checker</code></td>\n<td>Feedback after edit-like operations</td>\n</tr>\n</tbody></table>\n<p>The command pillars and the disciplines behind them are covered in depth: <a href=\"#ulw-plan\">ulw-plan</a>, <a href=\"#ulw-loop\">ulw-loop</a>, <a href=\"#start-work\">start-work</a>, <a href=\"#tdd\">TDD</a>, <a href=\"#manual-qa\">manual QA</a>, and <a href=\"#git-workflow\">git workflow</a>.</p>\n<h3 id=\"where-skills-live\">Where skills live</h3>\n<p>OmO can load skills from project and user locations such as <code>.opencode/skills</code>, <code>~/.config/opencode/skills</code>, <code>.claude/skills</code>, <code>.agents/skills</code>, and <code>~/.agents/skills</code>.</p>\n<p>LazyCodex installs the Codex Light setup with:</p>\n<pre><code class=\"language-bash\">npx lazycodex-ai install\n</code></pre>\n<p>That installer wires the Codex marketplace plugin as <code>omo@sisyphuslabs</code> while keeping the public package alias easy to remember.</p>\n","ultrawork.md": "<p>ultrawork is the headline mode. Typing <code>ultrawork</code> (or the short alias <code>ulw</code>) anywhere in your prompt activates maximum-precision, outcome-first, evidence-driven orchestration.</p>\n<blockquote>\n<p>"Plan, execute, verify, and keep the evidence attached."</p>\n</blockquote>\n<h3 id=\"usage\">Usage</h3>\n<pre><code class=\"language-bash\">ulw add authentication\n</code></pre>\n<h3 id=\"what-it-enforces\">What it enforces</h3>\n<ul>\n<li>Strict TDD: RED → GREEN → SURFACE → CLEAN</li>\n<li>At least 3 realistic QA scenarios</li>\n<li>Real manual-QA channels (HTTP call, tmux, browser)</li>\n<li>A binding verification gate that loops until the work is genuinely done</li>\n</ul>\n","discipline-agents.md": "<p>LazyCodex ports a single discipline agent from OmO into Codex: <strong>Hephaestus</strong>, the autonomous deep worker. There is no Sisyphus orchestrator in the Codex package — Hephaestus is the one role, and it carries the whole run itself with read-only subagents for parallel exploration.</p>\n<h3 id=\"what-hephaestus-is\">What Hephaestus is</h3>\n<p>Named after the Greek god of the forge. Goal-oriented: you give it objectives, not step-by-step recipes, and it executes them end-to-end. "The Legitimate Craftsman." Methodical, thorough, obsessive — built for deep architectural reasoning, complex debugging, and cross-domain synthesis.</p>\n<h3 id=\"the-operating-loop\">The operating loop</h3>\n<p>Hephaestus runs a short, tight loop on every unit of work:</p>\n<ol>\n<li><strong>Explore</strong> — map the terrain. Read the code with tools, never speculate. Fire 2-5 parallel explore subagents before writing anything.</li>\n<li><strong>Plan</strong> — chart the course. Record files to modify, specific changes, and dependencies via <code>update_plan</code>.</li>\n<li><strong>Implement</strong> — build with precision. Surgical edits that match codebase style (naming, indentation, imports, error handling) even when a greenfield would read differently.</li>\n<li><strong>Verify</strong> — prove it works. LSP diagnostics on changed files, related tests, and build — in parallel where possible.</li>\n<li><strong>Manually QA</strong> — drive the artifact through its real surface (HTTP call, tmux, browser), then write the final message.</li>\n</ol>\n<h3 id=\"what-it-never-does\">What it never does</h3>\n<ul>\n<li><strong>Never trusts subagent self-reports.</strong> Verification is independent; a child saying "done" does not close the work.</li>\n<li><strong>Never proposes when you asked for code.</strong> Unless you explicitly want a plan or a brainstorm, it implements.</li>\n<li><strong>Never speculates about code it has not read.</strong> Exploration is cheap; assumption is expensive.</li>\n<li><strong>Never leaves work unresolved at end of turn.</strong> Every plan step is reconciled: <code>completed</code>, blocked (one-line reason), or removed (one-line reason).</li>\n</ul>\n<h3 id=\"delegation-not-orchestration\">Delegation, not orchestration</h3>\n<p>Hephaestus stays the parent. For parallel exploration it spawns read-only Codex subagent roles (<code>multi_agent_v1.spawn_agent</code>) and keeps the parent session live with brief status updates while children run. It does not hand the run off to a separate orchestrator — it owns the goal, delegates the grunt work, and verifies the results itself.</p>\n<h3 id=\"where-the-boulder-comes-from\">Where the boulder comes from</h3>\n<p>The full OmO has a second primary agent, <strong>Sisyphus</strong>, the orchestrator with <code>.omo/boulder.json</code> session continuity. The Codex package is the Hephaestus-only light port, so on Codex the durable progress state lives in <code>.omo/boulder.json</code> as written by <a href=\"#start-work\"><code>$start-work</code></a> and the Stop-hook continuation — without the Sisyphus orchestration layer.</p>\n<h3 id=\"reading-more\">Reading more</h3>\n<ul>\n<li><a href=\"#ultrawork\">ultrawork mode</a> — the mode that turns the loop into a binding verified run.</li>\n<li><a href=\"#hooks-lifecycle\">Hooks & Lifecycle</a> — how the Stop-hook re-injects the next turn until the plan is complete.</li>\n</ul>\n","model-routing.md": "<p>Multi-model routing sends each part of a run to the model that fits it best, instead of running everything on one model. LazyCodex installs OmO's routing defaults into Codex so a serious repository is not bottlenecked by a single context window or price point.</p>\n<h3 id=\"what-gets-routed\">What gets routed</h3>\n<ul>\n<li><strong>Planning and exploration</strong> go to a strong reasoning model that can hold a large context and weigh trade-offs.</li>\n<li><strong>Implementation turns</strong> go to a fast, capable coding model for the bulk of the edit loop.</li>\n<li><strong>Verification</strong> goes to a model used as an oracle, chosen for judgment rather than throughput.</li>\n<li><strong>Specialist skills</strong> can target their own model when a skill benefits from a specific profile.</li>\n</ul>\n<h3 id=\"how-it-fits-the-harness\">How it fits the harness</h3>\n<p>Routing is part of the harness setup that <code>npx lazycodex-ai install</code> wires into Codex. It detects the available subscriptions and provider auth, then maps roles to models so you do not hand-configure each one.</p>\n<h3 id=\"provider-auth\">Provider auth</h3>\n<p>Auth targets Codex itself, not LazyCodex. Once Codex is logged in, the installer's subscription detection and provider routing take over. If you let an LLM agent run the install, it walks the same detection and selection for you.</p>\n<h3 id=\"customizing-it\">Customizing it</h3>\n<p>Routing and provider settings live in the configuration. See <a href=\"#configuration\">Configuration</a> for the fields that control which model handles which role, and how to override the defaults per project.</p>\n",@@ -14,9 +15,8 @@ export const DOC_SOURCES: Record<string, string> = {"git-workflow.md": "<p>Git work runs through the <code>git-master</code> skill. It is exact, conservative, and evidence-led: the agent reads the repository state before it infers anything, and never commits, rebases, pushes, force-pushes, resets, or stash-pops unless you explicitly asked for that operation.</p>\n<h3 id=\"mode-gate\">Mode gate</h3>\n<p>Every request is classified first:</p>\n<ul>\n<li><code>COMMIT</code> — stage and commit local changes.</li>\n<li><code>REBASE</code> — rebase, squash, fixup, autosquash, reorder, or split branch history.</li>\n<li><code>HISTORY</code> — answer when, where, who, why, or which commit changed something.</li>\n<li><code>STATUS</code> — inspect branch, diff, or working-tree state without changing it.</li>\n</ul>\n<p>Investigative requests report findings and stop.</p>\n<h3 id=\"commit-mode\">Commit mode</h3>\n<p>Commits are atomic by behavior, module, and revertability. The agent detects message style from recent history (dominant pattern, language, casing — it does not default to Conventional Commits unless the repo uses them), inspects the full diff, and stages by path or hunk so each commit contains only its group. Implementation and its direct tests land together; unrelated concerns split into separate commits. Before each commit it verifies <code>git diff --staged --stat</code>; after, <code>git log -1 --oneline</code>.</p>\n<h3 id=\"rebase-and-merge\">Rebase and merge</h3>\n<p>History rewriting is a shared-impact operation. The agent never rebases or rewrites <code>main</code>, <code>master</code>, <code>dev</code>, release, or protected branches unless you named that exact operation. If commits may already be pushed, it asks before force-pushing and uses <code>--force-with-lease</code>, never plain <code>--force</code>. Conflicts are resolved by intent — never a blind ours/theirs. If a rebase goes wrong, <code>git rebase --abort</code> is the first move; the reflog is the recovery path, explained before use.</p>\n<h3 id=\"push-safety\">Push safety</h3>\n<p>Before any write to history: the current branch is known, dirty work is accounted for, upstream/pushed status is known or explicitly unknown, the operation matches your request, and the recovery path is known. Afterward it runs the cheapest relevant verification and leaves the worktree state explicit.</p>\n<h3 id=\"reading-more\">Reading more</h3>\n<ul>\n<li><a href=\"#start-work\">start-work</a> — the executor that lands planned work as commits.</li>\n<li><a href=\"#manual-qa\">manual QA</a> — the gates a step passes before it is allowed to close.</li>\n</ul>\n","tdd.md": "<p>Strict test-driven development is the discipline that lets the harness call work "done" without hoping. Every change follows the red → green → refactor loop, in that order. Reverse it and you have written speculative code.</p>\n<h3 id=\"the-order\">The order</h3>\n<ol>\n<li><strong>Red.</strong> Write a failing test that names the behavior in <code>Given / When / Then</code>. Run it. Confirm it fails for the right reason — not a typo or a missing import.</li>\n<li><strong>Green.</strong> Write the minimum code to make it pass. Resist the second case until the first passes; the second case is the next red.</li>\n<li><strong>Refactor.</strong> With the test green, restructure ruthlessly. If the test is hard to refactor against, the test is bad — fix it before the code.</li>\n</ol>\n<h3 id=\"the-test-pyramid\">The test pyramid</h3>\n<p>Every feature ships all three rungs: many fast units (pure-function correctness across happy, edge, boundary, and error paths, < 10 ms each), some integrations against the real downstream via testcontainers or httptest (< 1 s each), and a few E2E scenarios that drive the binary through its real surface and assert the observable outcome. A feature with zero E2E coverage is undone, even if every unit passes.</p>\n<h3 id=\"deterministic-or-it-is-broken\">Deterministic, or it is broken</h3>\n<p>A test that passes 9 of 10 times is failing 10% of the time. Forbidden in test bodies unless time itself is the system under test: <code>setTimeout(resolve, N)</code>, <code>await sleep(N)</code>, "wait long enough for X". The replacement is subscribe-first, timeout-bound — register the listener before the trigger, then race against an explicit circuit breaker that fails with a useful message on timeout. The whole repo must pass <code>bun test</code> in one process, one go, no isolation flags, no retries.</p>\n<h3 id=\"prompt-tests-assert-behavior-not-text\">Prompt tests assert behavior, not text</h3>\n<p>When testing code that builds an LLM prompt, never pin the current wording (<code>toContain("You are Sisyphus")</code>, <code>toMatchSnapshot</code>, <code>toBe(EXPECTED_PROMPT)</code>). Assert the structural invariant the logic enforces — the conditional branch, the negative branch, the redaction, the skill inclusion/exclusion. Test what would break the behavior, never what would only break a diff.</p>\n<h3 id=\"the-five-evidence-gates\">The five evidence gates</h3>\n<p>During execution the lifecycle enforces five gates before a step can close: plan reread, automated verification, <a href=\"#manual-qa\">manual QA</a>, adversarial QA, and cleanup. A step that cannot pass its gates does not advance, regardless of what the status text claims.</p>\n<h3 id=\"reading-more\">Reading more</h3>\n<ul>\n<li><a href=\"#ultrawork\">ultrawork mode</a> — the mode that makes the loop binding.</li>\n<li><a href=\"#start-work\">start-work</a> — where the five gates are enforced per checkbox.</li>\n</ul>\n","manual-qa.md": "<p>Manual QA is the gate that turns "it should work" into "it works, here is the proof". No step closes on a status string; it closes on a captured artifact from a real surface, plus an adversarial pass and a cleanup receipt. Two skills carry this: <code>visual-qa</code> for UI surfaces, <code>review-work</code> for whole-implementation review.</p>\n<h3 id=\"visual-qa\">visual-qa</h3>\n<p>For any UI you built or changed — web page or TUI — visual QA runs three phases. First it captures objective reference evidence with a bundled diff script: <code>image-diff</code> for screenshots (similarity score, hotspots, <code>alphaChannelIntact</code>), <code>tui-check</code> for terminal captures (<code>maxWidth</code>, <code>overflowLines</code>, <code>borderMisaligned</code>, wide-char columns). That JSON is reference, not the verdict.</p>\n<p>Then it dispatches two read-only oracle subagents in parallel:</p>\n<ul>\n<li><strong>Pass A — design-system and functional integrity.</strong> The deeper, stricter pass. Proves the surface is a real design-system implementation driven by coherent tokens and reused primitives, not a mock-only screen or a pasted raster faked as live elements. Checks alpha, responsiveness, and that the user-intended features actually work.</li>\n<li><strong>Pass B — visual fidelity and CJK precision.</strong> The focused pass. Opens the screenshots directly and inspects source/content for clipping, baseline drop, glyph breakage, and Korean/Japanese/Chinese precision.</li>\n</ul>\n<p>The harness synthesizes the two passes into one <code>PASS | REVISE | FAIL</code> verdict with located findings.</p>\n<h3 id=\"review-work\">review-work</h3>\n<p>After significant implementation, <code>review-work</code> launches five parallel background subagents. All five must pass for the review to pass; if one fails, the review fails.</p>\n<table>\n<thead>\n<tr>\n<th>Lane</th>\n<th>Role</th>\n<th>Asks</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>1</td>\n<td>Goal Verifier</td>\n<td>Did we build what was asked?</td>\n</tr>\n<tr>\n<td>2</td>\n<td>QA Executor</td>\n<td>Does it actually work?</td>\n</tr>\n<tr>\n<td>3</td>\n<td>Code Reviewer</td>\n<td>Is the code well-written?</td>\n</tr>\n<tr>\n<td>4</td>\n<td>Security Auditor</td>\n<td>Is it secure?</td>\n</tr>\n<tr>\n<td>5</td>\n<td>Context Miner</td>\n<td>Did we miss any context?</td>\n</tr>\n</tbody></table>\n<p>Oracle lanes receive the diff plus full file contents in the prompt (they cannot read files). A crashed, <code>BLOCKED:</code>, or inconclusive lane is never counted as a pass — it is respawned smaller, and if the retry budget is exhausted it stays <code>INCONCLUSIVE</code> while the aggregate result still emits.</p>\n<h3 id=\"adversarial-classes-and-cleanup\">Adversarial classes and cleanup</h3>\n<p>Within <a href=\"#start-work\"><code>$start-work</code></a>, every checkbox probes each applicable adversarial class and records the observable result for each; skipped classes need a one-line not-applicable reason in the ledger. Every QA resource — scripts, tmux assets, browser sessions, PIDs, ports, containers, temp dirs — is registered as its own teardown todo and executed with a captured receipt. No QA asset is left running.</p>\n<h3 id=\"reading-more\">Reading more</h3>\n<ul>\n<li><a href=\"#tdd\">TDD</a> — the automated-verification gate that precedes manual QA.</li>\n<li><a href=\"#ulw-loop\">ulw-loop</a> — the loop whose completion depends on this gate.</li>\n</ul>\n",- "skills.md": "<p>LazyCodex is most useful as a harness for complex codebases: project memory, planning, execution, verified completion, skills, hooks, model routing, and diagnostics.</p>\n<h3 id=\"built-in-workflows\">Built-in workflows</h3>\n<p>Start with <code>$init-deep</code> when the repository is too large or too old to explain from memory. It generates hierarchical <code>AGENTS.md</code> context so agents can find the right files before they change code.</p>\n<p>Use <code>$ulw-plan</code> when the work needs decisions before implementation, <code>$start-work</code> when a plan should be executed, and <code>$ulw-loop</code> when you want the agent to keep going until the result is verified.</p>\n<h3 id=\"feature-coverage\">Feature coverage</h3>\n<p>The three command pillars stay simple:</p>\n<ul>\n<li><code>$ulw-loop</code> keeps moving until verified completion</li>\n<li><code>$ulw-plan</code> turns fuzzy work into a decision-complete plan</li>\n<li><code>$start-work</code> executes a plan with durable Boulder progress</li>\n</ul>\n<p>Skills add specialist judgment around those pillars:</p>\n<table>\n<thead>\n<tr>\n<th>Skill</th>\n<th>Use it for</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>init-deep</code></td>\n<td>Hierarchical <code>AGENTS.md</code> context for large or old repos</td>\n</tr>\n<tr>\n<td><code>ulw-plan</code></td>\n<td>Explore-first planning before coding</td>\n</tr>\n<tr>\n<td><code>ulw-loop</code></td>\n<td>Evidence-bound loop until verified completion</td>\n</tr>\n<tr>\n<td><code>start-work</code></td>\n<td>Execute a plan with durable Boulder progress</td>\n</tr>\n<tr>\n<td><code>review-work</code></td>\n<td>Five-lane parallel post-implementation review</td>\n</tr>\n<tr>\n<td><code>remove-ai-slops</code></td>\n<td>Behavior-preserving cleanup of AI-looking code</td>\n</tr>\n<tr>\n<td><code>frontend-ui-ux</code></td>\n<td>Designed UI work instead of generic layout filling</td>\n</tr>\n<tr>\n<td><code>programming</code></td>\n<td>Strict TypeScript, Rust, Python, or Go discipline, TDD-first</td>\n</tr>\n<tr>\n<td><code>git-master</code></td>\n<td>Atomic commits, rebase/squash, push safety, history investigation</td>\n</tr>\n<tr>\n<td><code>visual-qa</code></td>\n<td>Screenshot/TUI diff plus dual-oracle visual QA</td>\n</tr>\n<tr>\n<td><code>debugging</code></td>\n<td>Evidence-led root-cause investigation</td>\n</tr>\n<tr>\n<td><code>refactor</code></td>\n<td>Behavior-preserving restructure of existing code</td>\n</tr>\n<tr>\n<td><code>ultraresearch</code></td>\n<td>Deep multi-source research synthesis</td>\n</tr>\n<tr>\n<td><code>LSP</code></td>\n<td>Diagnostics, definitions, references, symbols, and renames</td>\n</tr>\n<tr>\n<td><code>lsp-setup</code></td>\n<td>Configure language servers for a project</td>\n</tr>\n<tr>\n<td><code>AST-grep</code></td>\n<td>Structural search and rewrite across code</td>\n</tr>\n<tr>\n<td><code>rules</code></td>\n<td>Project instructions from AGENTS, rules, and instruction files</td>\n</tr>\n<tr>\n<td><code>comment-checker</code></td>\n<td>Feedback after edit-like operations</td>\n</tr>\n</tbody></table>\n<p>The command pillars and the disciplines behind them are covered in depth: <a href=\"#ulw-plan\">ulw-plan</a>, <a href=\"#ulw-loop\">ulw-loop</a>, <a href=\"#start-work\">start-work</a>, <a href=\"#tdd\">TDD</a>, <a href=\"#manual-qa\">manual QA</a>, and <a href=\"#git-workflow\">git workflow</a>.</p>\n<h3 id=\"where-skills-live\">Where skills live</h3>\n<p>OmO can load skills from project and user locations such as <code>.opencode/skills</code>, <code>~/.config/opencode/skills</code>, <code>.claude/skills</code>, <code>.agents/skills</code>, and <code>~/.agents/skills</code>.</p>\n<p>LazyCodex installs the Codex Light setup with:</p>\n<pre><code class=\"language-bash\">npx lazycodex-ai install\n</code></pre>\n<p>That installer wires the Codex marketplace plugin as <code>omo@sisyphuslabs</code> while keeping the public package alias easy to remember.</p>\n","configuration.md": "<p>LazyCodex is a thin distribution layer over <a href=\"https://github.com/code-yeongyu/oh-my-openagent\">OmO</a>. The configuration that the installer writes into Codex controls model routing, hooks, skills, and the agent roles the harness uses.</p>\n<h3 id=\"where-config-lives\">Where config lives</h3>\n<ul>\n<li>Codex configuration that the installer connects to.</li>\n<li>Project-level <code>AGENTS.md</code> and rule files that shape agent behavior per repository.</li>\n<li>User-level skill locations such as <code>~/.config/opencode/skills</code> and <code>~/.agents/skills</code>.</li>\n</ul>\n<h3 id=\"what-you-can-tune\">What you can tune</h3>\n<ul>\n<li><strong>Model routing</strong> — which model handles planning, implementation, verification, and specialist skills. The installer sets sensible defaults from your detected subscriptions; override per role when a project needs a different profile.</li>\n<li><strong>Hooks and lifecycle</strong> — whether the Stop-hook auto-continues a plan, iteration caps (500 in ultrawork mode, 100 in normal mode), and how completion is gated.</li>\n<li><strong>Skills</strong> — which skills are active and where they load from.</li>\n<li><strong>Agent</strong> — Hephaestus, the autonomous deep worker, and its model/prompt overrides. The Codex package is the Hephaestus-only light port; the full OmO's Sisyphus orchestrator is not included.</li>\n</ul>\n<h3 id=\"diagnosing-config\">Diagnosing config</h3>\n<p>If something looks pending or degraded, run:</p>\n<pre><code class=\"language-bash\">npx lazycodex-ai doctor\n</code></pre>\n<p>It explains what is misconfigured and why, and points at the specific field to fix.</p>\n<h3 id=\"re-running-setup\">Re-running setup</h3>\n<p>The installer is idempotent. Re-running <code>npx lazycodex-ai install</code> rewrites the config blocks, agent roles, and bin links on top of what is there, so it is safe to run after editing configuration by hand.</p>\n<p>See the <a href=\"#cli\">CLI reference</a> for every command the installer exposes.</p>\n",- "deploy.md": "<p>The docs site at <code>lazycodex.ai</code> deploys automatically to Cloudflare Workers. There is no manual publish step for the web — a push to <code>main</code> that touches the web package ships it.</p>\n<h3 id=\"trigger\">Trigger</h3>\n<p>The <code>Web Deploy (Cloudflare Workers)</code> workflow runs on push to <code>main</code> when <code>packages/web/**</code> or the workflow file itself changes, and on manual <code>workflow_dispatch</code>. A concurrency group keyed by ref serializes runs and never cancels an in-flight deploy.</p>\n<h3 id=\"build\">Build</h3>\n<p>Inside <code>packages/web</code>, the prebuild step regenerates <code>lib/docs-content.generated.ts</code> from <code>content/docs/*.md</code>. The site is then built with OpenNext for Cloudflare (<code>pnpm exec opennextjs-cloudflare build</code>).</p>\n<h3 id=\"deploy\">Deploy</h3>\n<p><code>cloudflare/wrangler-action@v4</code> runs <code>wrangler deploy</code> (or <code>deploy --env <environment></code> when an environment is supplied) against the <code>web-production</code> environment, whose URL is <code>https://lazycodex.ai</code>.</p>\n<h3 id=\"post-deploy-smoke-checks\">Post-deploy smoke checks</h3>\n<p>The workflow fails the job if any check breaks:</p>\n<ul>\n<li>Apex <code>https://lazycodex.ai/</code> returns <code>200</code>.</li>\n<li><code>www.lazycodex.ai</code>, <code>lazycodex.dev</code>, and <code>www.lazycodex.dev</code> each return <code>301</code> redirecting to <code>https://lazycodex.ai</code>.</li>\n</ul>\n<p>A PageSpeed Insights pass audits the live URL for Lighthouse 100/100/100/100 across performance, accessibility, best-practices, and SEO, on both mobile and desktop. It is non-blocking here because PSI shared quota throttles frequent CI; the gating Lighthouse check runs in <code>web-ci.yml</code> via real Playwright Chromium.</p>\n<h3 id=\"local-preview\">Local preview</h3>\n<pre><code class=\"language-bash\">cd packages/web\npnpm preview # opennextjs-cloudflare build && preview\npnpm deploy # build && deploy (requires Cloudflare auth)\n</code></pre>\n<h3 id=\"reading-more\">Reading more</h3>\n<ul>\n<li><a href=\"#skills\">Skills</a> — what the docs site documents.</li>\n<li><a href=\"#configuration\">Configuration</a> — tuning that affects the build.</li>\n</ul>\n",+ "deploy.md": "<p>The docs site at <code>lazycodex.ai</code> deploys automatically to Cloudflare Workers. There is no manual publish step for the web — a push to <code>main</code> that touches the web package ships it.</p>\n<h3 id=\"trigger\">Trigger</h3>\n<p>The <code>Web Deploy (Cloudflare Workers)</code> workflow runs on push to <code>main</code> when <code>packages/web/**</code> or the workflow file itself changes, and on manual <code>workflow_dispatch</code>. A concurrency group keyed by ref serializes runs and never cancels an in-flight deploy.</p>\n<h3 id=\"build\">Build</h3>\n<p>Inside <code>packages/web</code>, the prebuild step regenerates <code>lib/docs-content.generated.ts</code> from <code>content/docs/*.md</code>. The site is then built with OpenNext for Cloudflare (<code>pnpm exec opennextjs-cloudflare build</code>).</p>\n<h3 id=\"deploy-2\">Deploy</h3>\n<p><code>cloudflare/wrangler-action@v4</code> runs <code>wrangler deploy</code> (or <code>deploy --env <environment></code> when an environment is supplied) against the <code>web-production</code> environment, whose URL is <code>https://lazycodex.ai</code>.</p>\n<h3 id=\"post-deploy-smoke-checks\">Post-deploy smoke checks</h3>\n<p>The workflow fails the job if any check breaks:</p>\n<ul>\n<li>Apex <code>https://lazycodex.ai/</code> returns <code>200</code>.</li>\n<li><code>www.lazycodex.ai</code>, <code>lazycodex.dev</code>, and <code>www.lazycodex.dev</code> each return <code>301</code> redirecting to <code>https://lazycodex.ai</code>.</li>\n</ul>\n<p>A PageSpeed Insights pass audits the live URL for Lighthouse 100/100/100/100 across performance, accessibility, best-practices, and SEO, on both mobile and desktop. It is non-blocking here because PSI shared quota throttles frequent CI; the gating Lighthouse check runs in <code>web-ci.yml</code> via real Playwright Chromium.</p>\n<h3 id=\"local-preview\">Local preview</h3>\n<pre><code class=\"language-bash\">cd packages/web\npnpm preview # opennextjs-cloudflare build && preview\npnpm deploy # build && deploy (requires Cloudflare auth)\n</code></pre>\n<h3 id=\"reading-more\">Reading more</h3>\n<ul>\n<li><a href=\"#skills\">Skills</a> — what the docs site documents.</li>\n<li><a href=\"#configuration\">Configuration</a> — tuning that affects the build.</li>\n</ul>\n","cli.md": "<p>The <code>lazycodex-ai</code> CLI is the entry point for installing and diagnosing the harness. It is meant to be run through <code>npx</code> — never install it globally.</p>\n<h3 id=\"install\">install</h3>\n<pre><code class=\"language-bash\">npx lazycodex-ai install\n</code></pre>\n<p>Installs the OmO agent harness into Codex: commands, skills, hooks, model routing, and verification defaults in one pass. This is exactly equivalent to:</p>\n<pre><code class=\"language-bash\">npx --yes --package oh-my-openagent omo install --platform=codex\n</code></pre>\n<p>To skip the TUI and let the installer run autonomously:</p>\n<pre><code class=\"language-bash\">npx lazycodex-ai install --no-tui --codex-autonomous\n</code></pre>\n<h3 id=\"doctor\">doctor</h3>\n<pre><code class=\"language-bash\">npx lazycodex-ai doctor\n</code></pre>\n<p>Prints a health report: what is configured, what is missing, and why. Run this first when a hook is pending, a skill is not loading, or routing looks wrong.</p>\n<h3 id=\"prerequisites\">Prerequisites</h3>\n<ul>\n<li><a href=\"https://nodejs.org\">Node.js</a> — any maintained LTS; <code>npx</code> ships with it. Bun is <strong>not</strong> required for the installer.</li>\n<li>The <a href=\"https://github.com/openai/codex\">OpenAI Codex CLI</a> or the Codex app, logged in.</li>\n</ul>\n<blockquote>\n<p>Do not use <code>npm install -g</code> or <code>bun add -g</code>. Always invoke via <code>npx</code>.</p>\n</blockquote>\n<h3 id=\"marketplace-alternative\">Marketplace alternative</h3>\n<p>As an additive, experimental path you can install from inside Codex: type <code>/plugins</code>, open the <strong>Add Marketplace</strong> tab, and enter <code>https://github.com/code-yeongyu/lazycodex</code>, then install <code>omo</code> from the <code>sisyphuslabs</code> marketplace. Or from the CLI:</p>\n<pre><code class=\"language-bash\">codex plugin marketplace add https://github.com/code-yeongyu/lazycodex\ncodex plugin add omo@sisyphuslabs\n</code></pre>\n<p>The npx installer above stays the primary path. See <a href=\"#installation\">Installation</a> for the full walkthrough.</p>\n"};@@ -181,6 +181,23 @@ export const DOC_TOC: Record<string, DocHeading[]> = {"text": "Reading more"}],+ "skills.md": [+ {+ "level": 3,+ "id": "built-in-workflows",+ "text": "Built-in workflows"+ },+ {+ "level": 3,+ "id": "feature-coverage",+ "text": "Feature coverage"+ },+ {+ "level": 3,+ "id": "where-skills-live",+ "text": "Where skills live"+ }+ ],"ultrawork.md": [{"level": 3,@@ -355,23 +372,6 @@ export const DOC_TOC: Record<string, DocHeading[]> = {"text": "Reading more"}],- "skills.md": [- {- "level": 3,- "id": "built-in-workflows",- "text": "Built-in workflows"- },- {- "level": 3,- "id": "feature-coverage",- "text": "Feature coverage"- },- {- "level": 3,- "id": "where-skills-live",- "text": "Where skills live"- }- ],"configuration.md": [{"level": 3,@@ -407,7 +407,7 @@ export const DOC_TOC: Record<string, DocHeading[]> = {},{"level": 3,- "id": "deploy",+ "id": "deploy-2","text": "Deploy"},{diff --git a/packages/web/lib/docs-sections.ts b/packages/web/lib/docs-sections.tsindex 7b007b00..efcfc6e7 100644--- a/packages/web/lib/docs-sections.ts+++ b/packages/web/lib/docs-sections.ts@@ -31,8 +31,8 @@ export const DOC_GROUPS: readonly string[] = ["Install","Getting started","Commands",- "Concepts","Skills",+ "Concepts","Reference",];@@ -44,6 +44,7 @@ export const DOC_SECTIONS: readonly DocSection[] = [{ id: "ulw-plan", file: "ulw-plan.md", group: "Commands", title: "$ulw-plan" },{ id: "start-work", file: "start-work.md", group: "Commands", title: "$start-work" },{ id: "ulw-loop", file: "ulw-loop.md", group: "Commands", title: "$ulw-loop" },+ { id: "skills", file: "skills.md", group: "Skills", title: "Feature coverage" },{ id: "ultrawork", file: "ultrawork.md", group: "Concepts", title: "ultrawork mode" },{ id: "discipline-agents", file: "discipline-agents.md", group: "Concepts", title: "Hephaestus" },{ id: "model-routing", file: "model-routing.md", group: "Concepts", title: "Multi-model routing" },@@ -51,7 +52,6 @@ export const DOC_SECTIONS: readonly DocSection[] = [{ id: "git-workflow", file: "git-workflow.md", group: "Concepts", title: "Git workflow" },{ id: "tdd", file: "tdd.md", group: "Concepts", title: "TDD" },{ id: "manual-qa", file: "manual-qa.md", group: "Concepts", title: "Manual QA" },- { id: "skills", file: "skills.md", group: "Skills", title: "Feature coverage" },{ id: "configuration", file: "configuration.md", group: "Reference", title: "Configuration" },{ id: "deploy", file: "deploy.md", group: "Reference", title: "Deploy" },{ id: "cli", file: "cli.md", group: "Reference", title: "CLI" },diff --git a/packages/web/lib/github-stars-format.ts b/packages/web/lib/github-stars-format.tsindex bbeeb2e3..c61ac9df 100644--- a/packages/web/lib/github-stars-format.ts+++ b/packages/web/lib/github-stars-format.ts@@ -1,4 +1,4 @@-export const FALLBACK_GITHUB_STARS = 0+export const FALLBACK_GITHUB_STARS = 1_864export function formatStarsCount(stars: number): string {if (stars >= 1_000_000) {diff --git a/packages/web/lib/github-stars.ts b/packages/web/lib/github-stars.tsindex f2014bf2..138c2240 100644--- a/packages/web/lib/github-stars.ts+++ b/packages/web/lib/github-stars.ts@@ -39,7 +39,7 @@ export function parseGitHubStarsPayload(payload: unknown): number | undefined {}const stars = payload.stargazers_count- if (typeof stars !== "number" || !Number.isFinite(stars) || stars < 0) {+ if (typeof stars !== "number" || !Number.isFinite(stars) || stars <= 0) {return undefined}@@ -53,7 +53,7 @@ function parseStarsText(value: string): number | undefined {const [, amountText, suffix] = matchconst amount = Number(amountText)- if (!Number.isFinite(amount) || amount < 0) return undefined+ if (!Number.isFinite(amount) || amount <= 0) return undefinedif (suffix?.toLowerCase() === "m") {return Math.round(amount * 1_000_000)@@ -67,7 +67,7 @@ function parseStarsText(value: string): number | undefined {}function parseStarsValue(value: unknown): number | undefined {- if (typeof value === "number" && Number.isFinite(value) && value >= 0) {+ if (typeof value === "number" && Number.isFinite(value) && value > 0) {return Math.floor(value)}diff --git a/packages/web/lib/site-config.ts b/packages/web/lib/site-config.tsindex 6454fd7b..0ec6f34d 100644--- a/packages/web/lib/site-config.ts+++ b/packages/web/lib/site-config.ts@@ -76,8 +76,8 @@ export const SITE_CONFIG = {builtInSkills: {title: "Built-in skill coverage",summary:- "Skills give the harness specialist judgment for review, cleanup, UI, strict language work, LSP diagnostics, AST-grep rewrites, project rules, and comment-checker feedback.",- skills: ["review-work", "remove-ai-slops", "frontend-ui-ux", "programming", "LSP", "AST-grep", "rules", "comment-checker"],+ "Skills auto-activate when a task matches their domain, so you do not need to study every one first. Add a skill name to your prompt when you want to call it explicitly; ultraresearch is the maximum-saturation mode for deep codebase, web, official-docs, and OSS-repo research.",+ skills: ["ultraresearch", "review-work", "remove-ai-slops", "frontend", "programming", "visual-qa", "LSP", "AST-grep", "rules", "comment-checker"],},} as const;diff --git a/packages/web/scripts/generate-docs-content.mjs b/packages/web/scripts/generate-docs-content.mjsindex 46178085..ccd3394e 100644--- a/packages/web/scripts/generate-docs-content.mjs+++ b/packages/web/scripts/generate-docs-content.mjs@@ -6,8 +6,8 @@ import path from "node:path";import { Marked } from "marked";// Fixed, ordered section list. Key = output map key (the markdown file name).-// Grouped for the sidebar: Install / Getting started / Commands / Concepts /-// Skills / Reference.+// Grouped for the sidebar: Install / Getting started / Commands / Skills /+// Concepts / Reference.const SECTIONS = [{ id: "overview", file: "overview.md", group: "Getting started", title: "Overview" },{ id: "installation", file: "installation.md", group: "Install", title: "Installation" },@@ -16,6 +16,7 @@ const SECTIONS = [{ id: "ulw-plan", file: "ulw-plan.md", group: "Commands", title: "$ulw-plan" },{ id: "start-work", file: "start-work.md", group: "Commands", title: "$start-work" },{ id: "ulw-loop", file: "ulw-loop.md", group: "Commands", title: "$ulw-loop" },+ { id: "skills", file: "skills.md", group: "Skills", title: "Feature coverage" },{ id: "ultrawork", file: "ultrawork.md", group: "Concepts", title: "ultrawork mode" },{ id: "discipline-agents", file: "discipline-agents.md", group: "Concepts", title: "Hephaestus" },{ id: "model-routing", file: "model-routing.md", group: "Concepts", title: "Multi-model routing" },@@ -23,7 +24,6 @@ const SECTIONS = [{ id: "git-workflow", file: "git-workflow.md", group: "Concepts", title: "Git workflow" },{ id: "tdd", file: "tdd.md", group: "Concepts", title: "TDD" },{ id: "manual-qa", file: "manual-qa.md", group: "Concepts", title: "Manual QA" },- { id: "skills", file: "skills.md", group: "Skills", title: "Feature coverage" },{ id: "configuration", file: "configuration.md", group: "Reference", title: "Configuration" },{ id: "deploy", file: "deploy.md", group: "Reference", title: "Deploy" },{ id: "cli", file: "cli.md", group: "Reference", title: "CLI" },@@ -76,12 +76,30 @@ function createMarked() {// Inject id attributes into <h2>/<h3> and collect a table of contents for the// section. Done as a post-parse string transform so it is robust across marked// versions (no renderer API dependency).-function injectHeadingIds(html) {+function uniqueSlug(base, usedIds) {+ if (!usedIds.has(base)) {+ usedIds.add(base);+ return base;+ }++ let suffix = 2;+ while (usedIds.has(`${base}-${suffix}`)) {+ suffix += 1;+ }++ const unique = `${base}-${suffix}`;+ usedIds.add(unique);+ return unique;+}++function injectHeadingIds(html, sectionId) {+ const usedIds = new Set([sectionId]);const toc = [];const withIds = html.replace(/<(h[23])>(.*?)<\/\1>/g, (match, tag, inner) => {const text = inner.replace(/<[^>]+>/g, "").trim();- const id = slugify(text);- if (!id) return match;+ const baseId = slugify(text);+ if (!baseId) return match;+ const id = uniqueSlug(baseId, usedIds);const level = tag === "h2" ? 2 : 3;toc.push({ level, id, text });return `<${tag} id="${id}">${inner}</${tag}>`;@@ -95,7 +113,7 @@ for (const section of SECTIONS) {const markdown = await readFile(path.join(DOCS_ROOT, section.file), "utf8");// JSON.stringify (below) escapes backticks/${} safely — never template strings.const rawHtml = await createMarked().parse(markdown);- const { withIds, toc } = injectHeadingIds(rawHtml);+ const { withIds, toc } = injectHeadingIds(rawHtml, section.id);sources[section.file] = withIds;tocs[section.file] = toc;}