Skip to content

The one and only agent harness for complex codebases. Project memory, planning, execution, and verified completion inside Codex.

feat(web): rebuild docs with grouped nav, search, ToC and richer content

YeonGyu-Kim8056b8faeb54
diff --git a/packages/web/app/docs/page.tsx b/packages/web/app/docs/page.tsx
index cfac2e36..b9a377f5 100644
--- a/packages/web/app/docs/page.tsx
+++ b/packages/web/app/docs/page.tsx
@@ -1,22 +1,34 @@
import type { Metadata } from "next";
-import { DocsShell } from "@/components/docs/docs-shell";
+import { DocsShell, type SectionView } from "@/components/docs/docs-shell";
import { SiteFooter } from "@/components/site/site-footer";
import { SiteHeader } from "@/components/site/site-header";
-import { DOC_SECTIONS } from "@/lib/docs-sections";
-import { loadDocSource } from "@/lib/docs-source";
+import { DOC_SECTIONS, neighborSections } from "@/lib/docs-sections";
+import { loadDocSource, loadDocToc } from "@/lib/docs-source";
+import { SITE_CONFIG } from "@/lib/site-config";
import "@/app/styles/docs.css";
export const metadata: Metadata = {
title: "Documentation",
description:
- "LazyCodex documentation for the OmO agent harness: install, project memory, skills, ultrawork mode, $ulw-loop, $ulw-plan, and $start-work.",
+ "LazyCodex documentation for the OmO agent harness: install, getting started, commands, concepts, skills, and reference.",
alternates: {
canonical: "/docs",
},
};
export default function DocsPage() {
- const sections = DOC_SECTIONS.map((s) => ({ id: s.id, title: s.title }));
+ const sections: SectionView[] = DOC_SECTIONS.map((s) => {
+ const { prev, next } = neighborSections(s.id);
+ return {
+ id: s.id,
+ title: s.title,
+ group: s.group,
+ html: loadDocSource(s.file),
+ toc: loadDocToc(s.file),
+ prev,
+ next,
+ };
+ });
return (
<>
@@ -26,29 +38,17 @@ export default function DocsPage() {
<SiteHeader />
<main id="content" className="docs-page">
<div className="docs-hero">
+ <div className="docs-hero-badge">
+ <span className="docs-hero-dot" aria-hidden="true" />
+ {SITE_CONFIG.version}
+ </div>
<h1 className="docs-hero-title">Documentation</h1>
<p className="docs-hero-tagline">
- Learn how to install and run the OmO harness inside Codex for complex codebases.
+ Install and run the OmO harness inside Codex for complex codebases —
+ project memory, planning, execution, and verified completion.
</p>
</div>
- <DocsShell sections={sections}>
- {DOC_SECTIONS.map((s) => (
- <section
- key={s.id}
- id={s.id}
- aria-labelledby={`${s.id}-title`}
- className="docs-section"
- >
- <h2 id={`${s.id}-title`} className="docs-section-title">
- {s.title}
- </h2>
- <article
- className="docs-content"
- dangerouslySetInnerHTML={{ __html: loadDocSource(s.file) }}
- />
- </section>
- ))}
- </DocsShell>
+ <DocsShell sections={sections} />
</main>
<SiteFooter />
</>
diff --git a/packages/web/app/styles/docs.css b/packages/web/app/styles/docs.css
index a04de896..31c83809 100644
--- a/packages/web/app/styles/docs.css
+++ b/packages/web/app/styles/docs.css
@@ -2,7 +2,7 @@
position: absolute;
top: -40px;
left: 0;
- background: var(--accent-cyan);
+ background: var(--accent-primary);
color: var(--surface-base);
padding: 8px;
z-index: 100;
@@ -14,71 +14,161 @@
}
.docs-page {
- max-width: 1200px;
+ max-width: 1280px;
margin: 0 auto;
- padding: 2rem 1rem;
+ padding: 2rem 1rem 4rem;
}
+/* Hero */
.docs-hero {
- margin-bottom: 3rem;
- text-align: center;
+ margin-bottom: 2rem;
+ padding: 1.5rem 0 1.5rem;
+ border-bottom: 1px solid var(--border-subtle);
+}
+
+.docs-hero-badge {
+ display: inline-flex;
+ align-items: center;
+ gap: 0.5rem;
+ padding: 0.3rem 0.7rem;
+ border-radius: 999px;
+ border: 1px solid var(--accent-primary-border);
+ background: var(--accent-primary-soft);
+ color: var(--accent-primary);
+ font-family: var(--font-mono);
+ font-size: 0.75rem;
+ font-weight: 500;
+ margin-bottom: 1rem;
+}
+
+.docs-hero-dot {
+ width: 6px;
+ height: 6px;
+ border-radius: 999px;
+ background: var(--accent-primary);
+ box-shadow: 0 0 8px var(--accent-primary);
}
.docs-hero-title {
- font-size: 3rem;
+ font-size: clamp(2rem,3.5vw,2.6rem);
font-weight: 700;
+ letter-spacing: -0.02em;
color: var(--text-primary);
- margin-bottom: 1rem;
+ margin: 0 0 0.5rem;
}
.docs-hero-tagline {
- font-size: 1.25rem;
+ font-size: 1.05rem;
+ line-height: 1.55;
color: var(--text-secondary);
+ max-width: 60ch;
+ margin: 0;
}
+/* Layout: sidebar | content | toc */
.docs-layout {
- display: flex;
- gap: 3rem;
+ display: grid;
+ grid-template-columns: 260px minmax(0, 1fr) 220px;
+ gap: 2.5rem;
position: relative;
+ align-items: start;
}
.docs-mobile-toggle {
display: none;
width: 100%;
- padding: 1rem;
+ padding: 0.75rem 1rem;
background: var(--card-base);
color: var(--text-primary);
border: 1px solid var(--border-subtle);
border-radius: 8px;
margin-bottom: 1rem;
cursor: pointer;
+ font-size: 0.9rem;
}
+/* Sidebar */
.docs-sidebar {
- width: 250px;
- flex-shrink: 0;
position: sticky;
- top: 2rem;
- height: calc(100vh - 4rem);
+ top: 4.5rem;
+ max-height: calc(100dvh - 6rem);
overflow-y: auto;
+ padding-right: 0.5rem;
+}
+
+.docs-sidebar-inner {
+ display: flex;
+ flex-direction: column;
+ gap: 1.25rem;
}
-.docs-search {
- margin-bottom: 1.5rem;
+.docs-search-field {
+ position: relative;
+ display: flex;
+ align-items: center;
+}
+
+.docs-search-glyph {
+ position: absolute;
+ left: 0.6rem;
+ color: var(--text-tertiary);
+ pointer-events: none;
}
.docs-search-input {
width: 100%;
- padding: 0.75rem;
+ padding: 0.55rem 2.4rem 0.55rem 2rem;
background: var(--card-base);
border: 1px solid var(--border-subtle);
- border-radius: 6px;
+ border-radius: 8px;
color: var(--text-primary);
+ font-size: 0.85rem;
+ transition: border-color 0.15s, box-shadow 0.15s;
+}
+
+.docs-search-input::placeholder {
+ color: var(--text-tertiary);
}
.docs-search-input:focus {
- outline: 2px solid var(--accent-cyan);
- outline-offset: -1px;
+ outline: none;
+ border-color: var(--accent-primary);
+ box-shadow: 0 0 0 3px var(--accent-primary-soft);
+}
+
+.docs-search-kbd {
+ position: absolute;
+ right: 0.5rem;
+ font-family: var(--font-mono);
+ font-size: 0.7rem;
+ color: var(--text-tertiary);
+ border: 1px solid var(--border-subtle);
+ border-radius: 4px;
+ padding: 0.1rem 0.35rem;
+ pointer-events: none;
+}
+
+.docs-nav {
+ display: flex;
+ flex-direction: column;
+ gap: 1.25rem;
+}
+
+.docs-nav-group {
+ display: flex;
+ flex-direction: column;
+ gap: 0.4rem;
+}
+
+.docs-nav-heading {
+ font-family: var(--font-mono);
+ font-size: 0.7rem;
+ font-weight: 600;
+ letter-spacing: 0.08em;
+ text-transform: uppercase;
+ color: var(--text-secondary);
+ margin: 0 0 0.25rem;
+ padding: 0 0.5rem;
}
.docs-nav-list {
@@ -88,139 +178,337 @@
}
.docs-nav-item {
- margin-bottom: 0.5rem;
+ margin: 0;
}
.docs-nav-link {
+ position: relative;
display: block;
- padding: 0.5rem;
+ padding: 0.4rem 0.6rem;
color: var(--text-secondary);
text-decoration: none;
- border-radius: 4px;
- transition: color 0.2s, background 0.2s;
+ border-radius: 6px;
+ font-size: 0.875rem;
+ line-height: 1.4;
+ transition: color 0.15s, background 0.15s;
}
.docs-nav-link:hover {
color: var(--text-primary);
- background: var(--card-base);
+ background: var(--surface-1);
}
.docs-nav-link.active {
- color: var(--accent-cyan);
+ color: var(--accent-primary);
font-weight: 600;
+ background: transparent;
}
+/* Straight vertical accent bar — a flat indicator, never a curved border. */
+.docs-nav-link.active::before {
+ content: "";
+ position: absolute;
+ left: 0;
+ top: 50%;
+ height: 0.95rem;
+ width: 2px;
+ transform: translateY(-50%);
+ background: var(--accent-primary);
+}
+
+.docs-nav-link.active:hover {
+ background: var(--surface-1);
+}
+
+.docs-nav-empty {
+ color: var(--text-tertiary);
+ font-size: 0.85rem;
+ padding: 0 0.5rem;
+ margin: 0;
+}
+
+/* Main content */
.docs-main-content {
- flex-grow: 1;
min-width: 0;
}
.docs-section {
margin-bottom: 4rem;
+ padding-top: 1rem;
+ scroll-margin-top: 4.5rem;
}
.docs-section-title {
- font-size: 2rem;
- font-weight: 600;
+ font-size: 1.75rem;
+ font-weight: 700;
+ letter-spacing: -0.02em;
color: var(--text-primary);
- margin-bottom: 1.5rem;
- padding-top: 2rem;
- scroll-margin-top: 2rem;
+ margin: 0 0 1.25rem;
+ padding-bottom: 0.75rem;
+ border-bottom: 1px solid var(--border-subtle);
}
.docs-content {
color: var(--text-secondary);
- line-height: 1.6;
+ line-height: 1.7;
+ font-size: 0.975rem;
+}
+
+.docs-content h2 {
+ font-size: 1.4rem;
+ font-weight: 700;
+ color: var(--text-primary);
+ margin: 2.25rem 0 0.75rem;
+ scroll-margin-top: 4.5rem;
}
.docs-content h3 {
- font-size: 1.5rem;
+ font-size: 1.15rem;
+ font-weight: 600;
color: var(--text-primary);
- margin: 2rem 0 1rem;
+ margin: 1.75rem 0 0.5rem;
+ scroll-margin-top: 4.5rem;
}
.docs-content p {
- margin-bottom: 1rem;
+ margin: 0 0 1rem;
}
.docs-content ul,
.docs-content ol {
- margin-bottom: 1rem;
- padding-left: 1.5rem;
+ margin: 0 0 1rem;
+ padding-left: 1.25rem;
}
.docs-content li {
- margin-bottom: 0.5rem;
+ margin-bottom: 0.4rem;
+}
+
+.docs-content li::marker {
+ color: var(--accent-primary);
}
.docs-content a {
- color: var(--accent-cyan);
+ color: var(--accent-primary);
text-decoration: underline;
- text-decoration-color: transparent;
- transition: text-decoration-color 0.2s;
+ text-decoration-color: var(--accent-primary-border);
+ text-underline-offset: 2px;
+ transition: text-decoration-color 0.15s;
}
.docs-content a:hover {
- text-decoration-color: var(--accent-cyan);
+ text-decoration-color: var(--accent-primary);
}
.docs-content code {
- font-family: monospace;
- background: var(--card-base);
- padding: 0.2em 0.4em;
+ font-family: var(--font-mono);
+ background: var(--surface-2);
+ color: var(--accent-mint);
+ padding: 0.15em 0.4em;
border-radius: 4px;
- font-size: 0.9em;
+ font-size: 0.85em;
}
.docs-content pre {
- background: #0E1115;
- padding: 1.5rem;
- border-radius: 8px;
+ background: #0c100e;
+ border: 1px solid var(--border-subtle);
+ padding: 1.1rem 1.25rem;
+ border-radius: 10px;
overflow-x: auto;
- margin-bottom: 1.5rem;
+ margin: 0 0 1.25rem;
+ font-size: 0.85rem;
+ line-height: 1.6;
+ color: #cfe9d8;
}
.docs-content pre code {
background: transparent;
+ color: #dcfce7;
padding: 0;
- color: #e2e8f0;
}
.docs-content blockquote {
- border-left: 4px solid var(--accent-cyan);
- padding-left: 1rem;
- margin: 1.5rem 0;
+ border-left: 3px solid var(--accent-primary);
+ background: var(--accent-primary-soft);
color: var(--text-primary);
- background: var(--card-base);
- padding: 1rem;
+ padding: 0.9rem 1rem;
border-radius: 0 8px 8px 0;
+ margin: 1.25rem 0;
+}
+
+.docs-content blockquote p {
+ margin: 0;
+}
+
+.docs-content table {
+ width: 100%;
+ border-collapse: collapse;
+ margin: 0 0 1.25rem;
+ font-size: 0.9rem;
+}
+
+.docs-content th {
+ text-align: left;
+ font-weight: 600;
+ color: var(--text-primary);
+ border-bottom: 1px solid var(--border-default);
+ padding: 0.55rem 0.75rem;
+}
+
+.docs-content td {
+ border-bottom: 1px solid var(--border-subtle);
+ padding: 0.55rem 0.75rem;
+ color: var(--text-secondary);
+}
+
+.docs-content hr {
+ border: none;
+ border-top: 1px solid var(--border-subtle);
+ margin: 2rem 0;
+}
+
+/* Right ToC */
+.docs-toc {
+ position: sticky;
+ top: 4.5rem;
+ max-height: calc(100dvh - 6rem);
+ overflow-y: auto;
+ padding-left: 0.5rem;
+ border-left: 1px solid var(--border-subtle);
+}
+
+.docs-toc-heading {
+ font-family: var(--font-mono);
+ font-size: 0.7rem;
+ font-weight: 600;
+ letter-spacing: 0.08em;
+ text-transform: uppercase;
+ color: var(--text-secondary);
+ margin: 0 0 0.75rem;
+}
+
+.docs-toc-list {
+ list-style: none;
+ padding: 0;
+ margin: 0;
+ display: flex;
+ flex-direction: column;
+ gap: 0.35rem;
+}
+
+.docs-toc-item.indent {
+ padding-left: 0.75rem;
+}
+
+.docs-toc-link {
+ display: block;
+ color: var(--text-secondary);
+ text-decoration: none;
+ font-size: 0.8rem;
+ line-height: 1.4;
+ padding-left: 0.5rem;
+ border-left: 2px solid transparent;
+ transition: color 0.15s, border-color 0.15s;
+}
+
+.docs-toc-link:hover {
+ color: var(--text-primary);
+}
+
+.docs-toc-link.active {
+ color: var(--accent-primary);
+ border-left-color: var(--accent-primary);
+}
+
+/* Prev / next */
+.docs-prev-next {
+ display: grid;
+ grid-template-columns: 1fr 1fr;
+ gap: 1rem;
+ margin-top: 2.5rem;
+}
+
+.docs-prev-next-card {
+ display: flex;
+ flex-direction: column;
+ gap: 0.35rem;
+ padding: 1rem 1.1rem;
+ border: 1px solid var(--border-subtle);
+ border-radius: 10px;
+ background: var(--card-base);
+ text-decoration: none;
+ transition: border-color 0.15s, background 0.15s, transform 0.15s;
+}
+
+.docs-prev-next-card:hover {
+ border-color: var(--accent-primary-border);
+ background: var(--surface-1);
+ transform: translateY(-1px);
+}
+
+.docs-prev-next-card.next {
+ text-align: right;
+ align-items: flex-end;
+}
+
+.docs-prev-next-card.placeholder {
+ visibility: hidden;
+}
+
+.docs-prev-next-label {
+ font-family: var(--font-mono);
+ font-size: 0.7rem;
+ color: var(--text-tertiary);
+}
+
+.docs-prev-next-title {
+ font-size: 0.95rem;
+ font-weight: 600;
+ color: var(--text-primary);
+}
+
+/* Responsive */
+@media (max-width: 1100px) {
+ .docs-layout {
+ grid-template-columns: 240px minmax(0, 1fr);
+ gap: 2rem;
+ }
+ .docs-toc {
+ display: none;
+ }
}
@media (max-width: 768px) {
.docs-layout {
- flex-direction: column;
+ grid-template-columns: 1fr;
gap: 1rem;
}
-
.docs-mobile-toggle {
display: block;
}
-
.docs-sidebar {
display: none;
- width: 100%;
- height: auto;
position: static;
+ max-height: none;
+ overflow: visible;
}
-
.docs-sidebar.open {
display: block;
}
+ .docs-prev-next {
+ grid-template-columns: 1fr;
+ }
+ .docs-prev-next-card.next {
+ text-align: left;
+ align-items: flex-start;
+ }
}
@media (prefers-reduced-motion: reduce) {
.docs-nav-link,
- .docs-content a {
+ .docs-content a,
+ .docs-toc-link,
+ .docs-prev-next-card {
transition: none;
}
}
diff --git a/packages/web/components/docs/docs-prev-next.tsx b/packages/web/components/docs/docs-prev-next.tsx
new file mode 100644
index 00000000..98d99f89
--- /dev/null
+++ b/packages/web/components/docs/docs-prev-next.tsx
@@ -0,0 +1,32 @@
+import type { JSX } from "react";
+import type { DocSection } from "@/lib/docs-sections";
+
+interface DocsPrevNextProps {
+ readonly prev: DocSection | undefined;
+ readonly next: DocSection | undefined;
+}
+
+export function DocsPrevNext({ prev, next }: DocsPrevNextProps): JSX.Element {
+ if (!prev && !next) return <></>;
+
+ return (
+ <nav className="docs-prev-next" aria-label="Section navigation">
+ {prev ? (
+ <a className="docs-prev-next-card prev" href={`#${prev.id}`}>
+ <span className="docs-prev-next-label" aria-hidden="true">← Previous</span>
+ <span className="docs-prev-next-title">{prev.title}</span>
+ </a>
+ ) : (
+ <span className="docs-prev-next-card placeholder" aria-hidden="true" />
+ )}
+ {next ? (
+ <a className="docs-prev-next-card next" href={`#${next.id}`}>
+ <span className="docs-prev-next-label" aria-hidden="true">Next →</span>
+ <span className="docs-prev-next-title">{next.title}</span>
+ </a>
+ ) : (
+ <span className="docs-prev-next-card placeholder" aria-hidden="true" />
+ )}
+ </nav>
+ );
+}
diff --git a/packages/web/components/docs/docs-shell.tsx b/packages/web/components/docs/docs-shell.tsx
index c1a4bb5d..6da0f16b 100644
--- a/packages/web/components/docs/docs-shell.tsx
+++ b/packages/web/components/docs/docs-shell.tsx
@@ -1,65 +1,99 @@
"use client";
-import { useState, useEffect, useRef } from "react";
+import type { JSX } from "react";
+import { useEffect, useRef, useState } from "react";
+import type { DocHeading } from "@/lib/docs-content.generated";
+import type { DocSection } from "@/lib/docs-sections";
+import { DocsSidebar } from "./docs-sidebar";
+import { DocsToc } from "./docs-toc";
+import { DocsPrevNext } from "./docs-prev-next";
-interface Section {
- id: string;
- title: string;
-}
+export type SectionView = {
+ readonly id: string;
+ readonly title: string;
+ readonly group: string;
+ readonly html: string;
+ readonly toc: ReadonlyArray<DocHeading>;
+ readonly prev: DocSection | undefined;
+ readonly next: DocSection | undefined;
+};
interface DocsShellProps {
- sections: ReadonlyArray<Section>;
- children: React.ReactNode;
+ readonly sections: ReadonlyArray<SectionView>;
}
-export function DocsShell({ sections, children }: DocsShellProps) {
+export function DocsShell({ sections }: DocsShellProps): JSX.Element {
const [searchQuery, setSearchQuery] = useState("");
- const [activeId, setActiveId] = useState<string>("");
+ const [activeId, setActiveId] = useState<string>(sections[0]?.id ?? "");
+ const [activeHeadingId, setActiveHeadingId] = useState<string>("");
const [isMobileMenuOpen, setIsMobileMenuOpen] = useState(false);
- const observerRef = useRef<IntersectionObserver | null>(null);
-
- const filteredSections = sections.filter((s) =>
- s.title.toLowerCase().includes(searchQuery.toLowerCase())
- );
+ const searchRef = useRef<HTMLInputElement | null>(null);
+ const sectionObserverRef = useRef<IntersectionObserver | null>(null);
+ const headingObserverRef = useRef<IntersectionObserver | null>(null);
+ // ⌘K / Ctrl-K focuses the search field from anywhere on the page.
useEffect(() => {
- const handleHashChange = () => {
- const hash = window.location.hash.slice(1);
- if (hash) {
- setActiveId(hash);
+ function onKeyDown(event: KeyboardEvent): void {
+ if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
+ event.preventDefault();
+ searchRef.current?.focus();
+ searchRef.current?.select();
}
- };
+ }
+ window.addEventListener("keydown", onKeyDown);
+ return () => window.removeEventListener("keydown", onKeyDown);
+ }, []);
+ useEffect(() => {
+ function handleHashChange(): void {
+ const hash = window.location.hash.slice(1);
+ if (hash) setActiveId(hash);
+ }
window.addEventListener("hashchange", handleHashChange);
handleHashChange();
-
return () => window.removeEventListener("hashchange", handleHashChange);
}, []);
+ // Scroll-spy: which section is currently in view (drives sidebar + right ToC).
useEffect(() => {
- observerRef.current = new IntersectionObserver(
+ sectionObserverRef.current = new IntersectionObserver(
(entries) => {
for (const entry of entries) {
- if (entry.isIntersecting) {
- setActiveId(entry.target.id);
- }
+ if (entry.isIntersecting) setActiveId(entry.target.id);
}
},
- { rootMargin: "-20% 0px -80% 0px" }
+ { rootMargin: "-15% 0px -75% 0px" },
);
-
- const sectionElements = document.querySelectorAll(".docs-section h2[id]");
- for (const el of sectionElements) {
- observerRef.current.observe(el);
+ for (const el of document.querySelectorAll<HTMLElement>(".docs-section[id]")) {
+ sectionObserverRef.current.observe(el);
}
+ return () => sectionObserverRef.current?.disconnect();
+ }, [sections]);
- return () => {
- if (observerRef.current) {
- observerRef.current.disconnect();
- }
- };
+ // Scroll-spy: which heading is currently in view (drives right ToC highlight).
+ useEffect(() => {
+ headingObserverRef.current = new IntersectionObserver(
+ (entries) => {
+ for (const entry of entries) {
+ if (entry.isIntersecting) setActiveHeadingId(entry.target.id);
+ }
+ },
+ { rootMargin: "-15% 0px -80% 0px" },
+ );
+ for (const el of document.querySelectorAll<HTMLElement>(".docs-content h2[id], .docs-content h3[id]")) {
+ headingObserverRef.current.observe(el);
+ }
+ return () => headingObserverRef.current?.disconnect();
}, [sections]);
+ const navSections = sections.map((s) => ({
+ id: s.id,
+ title: s.title,
+ group: s.group,
+ }));
+
+ const activeSection = sections.find((s) => s.id === activeId) ?? sections[0];
+
return (
<div className="docs-layout">
<button
@@ -76,38 +110,35 @@ export function DocsShell({ sections, children }: DocsShellProps) {
id="docs-sidebar"
className={`docs-sidebar ${isMobileMenuOpen ? "open" : ""}`}
>
- <div className="docs-search">
- <label htmlFor="docs-search-input" className="sr-only">
- Search documentation
- </label>
- <input
- id="docs-search-input"
- type="search"
- placeholder="Search..."
- value={searchQuery}
- onChange={(e) => setSearchQuery(e.target.value)}
- className="docs-search-input"
- />
- </div>
- <nav aria-label="Documentation" className="docs-nav">
- <ul className="docs-nav-list">
- {filteredSections.map((s) => (
- <li key={s.id} className="docs-nav-item">
- <a
- href={`#${s.id}`}
- className={`docs-nav-link ${activeId === s.id ? "active" : ""}`}
- aria-current={activeId === s.id ? "location" : undefined}
- onClick={() => setIsMobileMenuOpen(false)}
- >
- {s.title}
- </a>
- </li>
- ))}
- </ul>
- </nav>
+ <DocsSidebar
+ sections={navSections}
+ activeId={activeId}
+ searchQuery={searchQuery}
+ onSearchChange={setSearchQuery}
+ searchRef={searchRef}
+ onNavigate={() => setIsMobileMenuOpen(false)}
+ />
</aside>
- <div className="docs-main-content">{children}</div>
+ <div className="docs-main-content">
+ {sections.map((s) => (
+ <section key={s.id} id={s.id} className="docs-section" aria-labelledby={`${s.id}-title`}>
+ <h2 id={`${s.id}-title`} className="docs-section-title">
+ {s.title}
+ </h2>
+ <article
+ className="docs-content"
+ dangerouslySetInnerHTML={{ __html: s.html }}
+ />
+ <DocsPrevNext prev={s.prev} next={s.next} />
+ </section>
+ ))}
+ </div>
+
+ <DocsToc
+ headings={activeSection?.toc ?? []}
+ activeHeadingId={activeHeadingId}
+ />
</div>
);
}
diff --git a/packages/web/components/docs/docs-sidebar.tsx b/packages/web/components/docs/docs-sidebar.tsx
new file mode 100644
index 00000000..2c602fe8
--- /dev/null
+++ b/packages/web/components/docs/docs-sidebar.tsx
@@ -0,0 +1,105 @@
+"use client";
+
+import type { JSX } from "react";
+import { DOC_GROUPS } from "@/lib/docs-sections";
+
+export type NavSection = {
+ readonly id: string;
+ readonly title: string;
+ readonly group: string;
+};
+
+interface DocsSidebarProps {
+ readonly sections: ReadonlyArray<NavSection>;
+ readonly activeId: string;
+ readonly searchQuery: string;
+ readonly onSearchChange: (value: string) => void;
+ readonly searchRef: React.RefObject<HTMLInputElement | null>;
+ readonly onNavigate: () => void;
+}
+
+export function DocsSidebar({
+ sections,
+ activeId,
+ searchQuery,
+ onSearchChange,
+ searchRef,
+ onNavigate,
+}: DocsSidebarProps): JSX.Element {
+ const query = searchQuery.trim().toLowerCase();
+
+ return (
+ <div className="docs-sidebar-inner">
+ <div className="docs-search">
+ <label htmlFor="docs-search-input" className="sr-only">
+ Search documentation
+ </label>
+ <div className="docs-search-field">
+ <SearchGlyph />
+ <input
+ id="docs-search-input"
+ ref={searchRef}
+ type="search"
+ placeholder="Search docs..."
+ value={searchQuery}
+ onChange={(e) => onSearchChange(e.target.value)}
+ className="docs-search-input"
+ />
+ <kbd className="docs-search-kbd" aria-hidden="true">⌘K</kbd>
+ </div>
+ </div>
+
+ <nav aria-label="Documentation" className="docs-nav">
+ {DOC_GROUPS.map((group) => {
+ const groupSections = sections.filter((s) => s.group === group);
+ const visible = groupSections.filter((s) =>
+ query ? s.title.toLowerCase().includes(query) : true,
+ );
+ if (visible.length === 0) return null;
+ return (
+ <div key={group} className="docs-nav-group">
+ <p className="docs-nav-heading">{group}</p>
+ <ul className="docs-nav-list">
+ {visible.map((s) => (
+ <li key={s.id} className="docs-nav-item">
+ <a
+ href={`#${s.id}`}
+ className={`docs-nav-link ${activeId === s.id ? "active" : ""}`}
+ aria-current={activeId === s.id ? "location" : undefined}
+ onClick={onNavigate}
+ >
+ {s.title}
+ </a>
+ </li>
+ ))}
+ </ul>
+ </div>
+ );
+ })}
+ {query && sections.every((s) => !s.title.toLowerCase().includes(query)) && (
+ <p className="docs-nav-empty">No matches.</p>
+ )}
+ </nav>
+ </div>
+ );
+}
+
+function SearchGlyph(): JSX.Element {
+ return (
+ <svg
+ width="16"
+ height="16"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="2"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ aria-hidden="true"
+ className="docs-search-glyph"
+ >
+ <circle cx="11" cy="11" r="8" />
+ <path d="m21 21-4.3-4.3" />
+ </svg>
+ );
+}
diff --git a/packages/web/components/docs/docs-toc.tsx b/packages/web/components/docs/docs-toc.tsx
new file mode 100644
index 00000000..42610b3d
--- /dev/null
+++ b/packages/web/components/docs/docs-toc.tsx
@@ -0,0 +1,36 @@
+"use client";
+
+import type { JSX } from "react";
+import type { DocHeading } from "@/lib/docs-content.generated";
+
+interface DocsTocProps {
+ readonly headings: ReadonlyArray<DocHeading>;
+ readonly activeHeadingId: string;
+}
+
+export function DocsToc({ headings, activeHeadingId }: DocsTocProps): JSX.Element {
+ const items = headings.filter((h) => h.level === 2 || h.level === 3);
+ if (items.length === 0) return <aside className="docs-toc" aria-hidden="true" />;
+
+ return (
+ <aside className="docs-toc" aria-label="On this section">
+ <p className="docs-toc-heading">On this section</p>
+ <ul className="docs-toc-list">
+ {items.map((h) => (
+ <li
+ key={h.id}
+ className={`docs-toc-item ${h.level === 3 ? "indent" : ""}`}
+ >
+ <a
+ href={`#${h.id}`}
+ className={`docs-toc-link ${activeHeadingId === h.id ? "active" : ""}`}
+ aria-current={activeHeadingId === h.id ? "location" : undefined}
+ >
+ {h.text}
+ </a>
+ </li>
+ ))}
+ </ul>
+ </aside>
+ );
+}
diff --git a/packages/web/content/docs/cli.md b/packages/web/content/docs/cli.md
new file mode 100644
index 00000000..8dc39efc
--- /dev/null
+++ b/packages/web/content/docs/cli.md
@@ -0,0 +1,45 @@
+The `lazycodex-ai` CLI is the entry point for installing and diagnosing the harness. It is meant to be run through `npx` — never install it globally.
+
+### install
+
+```bash
+npx lazycodex-ai install
+```
+
+Installs the OmO agent harness into Codex: commands, skills, hooks, model routing, and verification defaults in one pass. This is exactly equivalent to:
+
+```bash
+npx --yes --package oh-my-openagent omo install --platform=codex
+```
+
+To skip the TUI and let the installer run autonomously:
+
+```bash
+npx lazycodex-ai install --no-tui --codex-autonomous
+```
+
+### doctor
+
+```bash
+npx lazycodex-ai doctor
+```
+
+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.
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org) — any maintained LTS; `npx` ships with it. Bun is **not** required for the installer.
+- The [OpenAI Codex CLI](https://github.com/openai/codex) or the Codex app, logged in.
+
+> Do not use `npm install -g` or `bun add -g`. Always invoke via `npx`.
+
+### Marketplace alternative
+
+As an additive, experimental path you can install from inside Codex: type `/plugins`, open the **Add Marketplace** tab, and enter `https://github.com/code-yeongyu/lazycodex`, then install `omo` from the `sisyphuslabs` marketplace. Or from the CLI:
+
+```bash
+codex plugin marketplace add https://github.com/code-yeongyu/lazycodex
+codex plugin add omo@sisyphuslabs
+```
+
+The npx installer above stays the primary path. See [Installation](./installation.md) for the full walkthrough.
diff --git a/packages/web/content/docs/configuration.md b/packages/web/content/docs/configuration.md
new file mode 100644
index 00000000..27dd6b21
--- /dev/null
+++ b/packages/web/content/docs/configuration.md
@@ -0,0 +1,30 @@
+LazyCodex is a thin distribution layer over [OmO](https://github.com/code-yeongyu/oh-my-openagent). The configuration that the installer writes into Codex controls model routing, hooks, skills, and the agent roles the harness uses.
+
+### Where config lives
+
+- Codex configuration that the installer connects to.
+- Project-level `AGENTS.md` and rule files that shape agent behavior per repository.
+- User-level skill locations such as `~/.config/opencode/skills` and `~/.agents/skills`.
+
+### What you can tune
+
+- **Model routing** — 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.
+- **Hooks and lifecycle** — whether the Stop-hook auto-continues a plan, iteration caps (500 in ultrawork mode, 100 in normal mode), and how completion is gated.
+- **Skills** — which skills are active and where they load from.
+- **Agent** — 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.
+
+### Diagnosing config
+
+If something looks pending or degraded, run:
+
+```bash
+npx lazycodex-ai doctor
+```
+
+It explains what is misconfigured and why, and points at the specific field to fix.
+
+### Re-running setup
+
+The installer is idempotent. Re-running `npx lazycodex-ai install` 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.
+
+See the [CLI reference](./cli.md) for every command the installer exposes.
diff --git a/packages/web/content/docs/discipline-agents.md b/packages/web/content/docs/discipline-agents.md
new file mode 100644
index 00000000..00fd69f0
--- /dev/null
+++ b/packages/web/content/docs/discipline-agents.md
@@ -0,0 +1,35 @@
+LazyCodex ports a single discipline agent from OmO into Codex: **Hephaestus**, 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.
+
+### What Hephaestus is
+
+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.
+
+### The operating loop
+
+Hephaestus runs a short, tight loop on every unit of work:
+
+1. **Explore** — map the terrain. Read the code with tools, never speculate. Fire 2-5 parallel explore subagents before writing anything.
+2. **Plan** — chart the course. Record files to modify, specific changes, and dependencies via `update_plan`.
+3. **Implement** — build with precision. Surgical edits that match codebase style (naming, indentation, imports, error handling) even when a greenfield would read differently.
+4. **Verify** — prove it works. LSP diagnostics on changed files, related tests, and build — in parallel where possible.
+5. **Manually QA** — drive the artifact through its real surface (HTTP call, tmux, browser), then write the final message.
+
+### What it never does
+
+- **Never trusts subagent self-reports.** Verification is independent; a child saying "done" does not close the work.
+- **Never proposes when you asked for code.** Unless you explicitly want a plan or a brainstorm, it implements.
+- **Never speculates about code it has not read.** Exploration is cheap; assumption is expensive.
+- **Never leaves work unresolved at end of turn.** Every plan step is reconciled: `completed`, blocked (one-line reason), or removed (one-line reason).
+
+### Delegation, not orchestration
+
+Hephaestus stays the parent. For parallel exploration it spawns read-only Codex subagent roles (`multi_agent_v1.spawn_agent`) 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.
+
+### Where the boulder comes from
+
+The full OmO has a second primary agent, **Sisyphus**, the orchestrator with `.omo/boulder.json` session continuity. The Codex package is the Hephaestus-only light port, so on Codex the durable progress state lives in `.omo/boulder.json` as written by [`$start-work`](./start-work.md) and the Stop-hook continuation — without the Sisyphus orchestration layer.
+
+### Reading more
+
+- [ultrawork mode](./ultrawork.md) — the mode that turns the loop into a binding verified run.
+- [Hooks & Lifecycle](./hooks-lifecycle.md) — how the Stop-hook re-injects the next turn until the plan is complete.
diff --git a/packages/web/content/docs/getting-started.md b/packages/web/content/docs/getting-started.md
new file mode 100644
index 00000000..2c212c0a
--- /dev/null
+++ b/packages/web/content/docs/getting-started.md
@@ -0,0 +1,36 @@
+LazyCodex is most useful as a harness for complex codebases: project memory, planning, execution, verified completion, skills, hooks, model routing, and diagnostics. This page walks through the four commands you will reach for most often and when to pick each.
+
+### The four commands
+
+| Command | Use it when |
+| --- | --- |
+| `$init-deep` | The repository is too large or too old to explain from memory. |
+| `$ulw-plan` | The work needs decisions before any code is written. |
+| `$start-work` | A plan exists and should be executed to completion. |
+| `$ulw-loop` | You want the agent to keep going until the result is verified. |
+
+### How to choose
+
+Start with `$init-deep` once per repository so agents have hierarchical `AGENTS.md` context to work from.
+
+For anything ambiguous, run `$ulw-plan` first. It interviews you, explores the codebase in parallel, and writes a decision-complete plan to `plans/<slug>.md` without touching product code.
+
+Hand that plan to `$start-work` to execute it: durable Boulder state, parallel subagents, strict TDD, and five evidence gates. It prints `ORCHESTRATION COMPLETE` when every checkbox is done.
+
+`$ulw-loop` is the tightest loop — use it for a single task that must run until an oracle verifies completion. It does not plan; it executes and verifies.
+
+### A typical session
+
+```text
+$init-deep
+$ulw-plan "add rate limiting to the api gateway"
+$start-work plans/add-rate-limiting.md
+```
+
+If the job is small and well-understood, skip the plan and loop directly:
+
+```text
+ulw fix the flaky checkout test
+```
+
+See [Feature coverage](./skills.md) for the skills that add specialist judgment around these commands.
diff --git a/packages/web/content/docs/hooks-lifecycle.md b/packages/web/content/docs/hooks-lifecycle.md
new file mode 100644
index 00000000..2c0f6149
--- /dev/null
+++ b/packages/web/content/docs/hooks-lifecycle.md
@@ -0,0 +1,22 @@
+Hooks and lifecycle are how the harness keeps a long run moving without you re-prompting every turn. OmO installs lifecycle hooks into Codex that observe each turn and decide what happens next.
+
+### The core mechanism
+
+A Stop-hook fires when a turn ends. If a plan is still in progress, the hook re-injects the next turn automatically — the agent continues from durable progress state instead of waiting for you to say "continue". The run only stops when the plan is complete or a gate fails in a way that needs a human.
+
+### Where progress lives
+
+Progress state is written to `.omo/boulder.json` and survives across turns and sessions. That is what lets [`$start-work`](./start-work.md) resume a plan after a restart, and what keeps [`$ulw-loop`](./ulw-loop.md) honest about how far it has actually gotten.
+
+### Approval and trust
+
+Hooks never run before approval. On the first launch after install, Codex's startup review asks you to approve the omo hooks. After every upgrade the hooks show as **Modified** — expected, because the plugin files changed and the previous trust hashes no longer match — re-approve and the next session re-runs bootstrap on the new version.
+
+### Evidence gates
+
+During execution the lifecycle enforces five evidence gates before a step can close: plan reread, automated verification, manual-QA, adversarial QA, and cleanup. A step that cannot pass its gates does not advance, regardless of what the status text claims.
+
+### Reading more
+
+- [ultrawork mode](./ultrawork.md) — the mode that turns these gates into a binding loop.
+- [Configuration](./configuration.md) — how to tune hook behavior and lifecycle defaults.
diff --git a/packages/web/content/docs/init-deep.md b/packages/web/content/docs/init-deep.md
new file mode 100644
index 00000000..47715c24
--- /dev/null
+++ b/packages/web/content/docs/init-deep.md
@@ -0,0 +1,25 @@
+`$init-deep` generates hierarchical `AGENTS.md` context so agents start from local guidance before touching a large repository. Run it once per project, and again whenever the architecture shifts enough that the existing context no longer reflects reality.
+
+### What it produces
+
+- A root `AGENTS.md` that orients agents to the project: stack, layout, conventions, and where to look first.
+- Nested `AGENTS.md` files in the directories that matter most, so an agent descending into a package gets scoped guidance instead of guessing.
+- References to project rules, skills, and instruction files the harness should respect.
+
+### When to run it
+
+- Onboarding a repository that is too large or too old to explain from memory.
+- After a major refactor, migration, or layout change.
+- When agents keep picking the wrong files or ignoring local conventions.
+
+### How to use it
+
+```text
+$init-deep
+```
+
+The command walks the tree, reads the files that define how the project actually works, and writes the context. Review the generated `AGENTS.md` files, trim anything stale, and commit them. Agents in later turns read that context before they edit, so the first session pays for every session after it.
+
+### After init
+
+With context in place, move to [`$ulw-plan`](./ulw-plan.md) when the work needs a plan, or [`$ulw-loop`](./ulw-loop.md) for a single verified task.
diff --git a/packages/web/content/docs/model-routing.md b/packages/web/content/docs/model-routing.md
new file mode 100644
index 00000000..15f90160
--- /dev/null
+++ b/packages/web/content/docs/model-routing.md
@@ -0,0 +1,20 @@
+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.
+
+### What gets routed
+
+- **Planning and exploration** go to a strong reasoning model that can hold a large context and weigh trade-offs.
+- **Implementation turns** go to a fast, capable coding model for the bulk of the edit loop.
+- **Verification** goes to a model used as an oracle, chosen for judgment rather than throughput.
+- **Specialist skills** can target their own model when a skill benefits from a specific profile.
+
+### How it fits the harness
+
+Routing is part of the harness setup that `npx lazycodex-ai install` wires into Codex. It detects the available subscriptions and provider auth, then maps roles to models so you do not hand-configure each one.
+
+### Provider auth
+
+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.
+
+### Customizing it
+
+Routing and provider settings live in the configuration. See [Configuration](./configuration.md) for the fields that control which model handles which role, and how to override the defaults per project.
diff --git a/packages/web/content/docs/overview.md b/packages/web/content/docs/overview.md
index 25906925..9af4165d 100644
--- a/packages/web/content/docs/overview.md
+++ b/packages/web/content/docs/overview.md
@@ -1,16 +1,26 @@
-LazyCodex packages [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) (OmO) inside Codex as the agent harness for complex codebases. Think [LazyVim](https://github.com/LazyVim/LazyVim) for [lazy.nvim](https://github.com/folke/lazy.nvim), but for Codex.
+LazyCodex is a light port of [OmO](https://github.com/code-yeongyu/oh-my-openagent) into Codex. It does not ship the full harness — it ports one role, **Hephaestus**, the autonomous deep worker, and the workflows that keep its runs honest. Think [LazyVim](https://github.com/LazyVim/LazyVim) for [lazy.nvim](https://github.com/folke/lazy.nvim), but for Codex.
+
+### Where it comes from
+
+OmO is the full agent harness: a primary orchestrator (Sisyphus) with `.omo/boulder.json` session continuity, a deep worker (Hephaestus), specialist agents, multi-model routing, 54+ lifecycle hooks, and team mode. That is a lot. LazyCodex takes only the piece that matters for a focused Codex setup and packages it as a repeatable install.
### What you get
-OmO gives Codex a full agent harness: discipline agents (Sisyphus orchestrates Hephaestus, Oracle, and Librarian), parallel execution, multi-model routing, a skills system, hooks and lifecycle, and verification defaults. LazyCodex packages that harness as a repeatable Codex setup.
+The Hephaestus deep worker, ported into Codex with:
+
+- Goal-oriented execution — you give it objectives, not step-by-step recipes.
+- A tight operating loop: **Explore → Plan → Implement → Verify → Manually QA**.
+- Parallel explore subagents so it maps the terrain before writing anything.
+- The `$ulw-plan`, `$start-work`, and `$ulw-loop` workflows that keep complex work moving until it is verified.
+- Skills, hooks, model routing, and verification defaults wired into Codex in one pass.
### The harness workflow
-Use `{your prompt} ultrawork` when the job needs project memory, planning, parallel agents, and verified completion to run as one coordinated loop.
+Use `{your prompt} ultrawork` when the job needs the deep worker to run as one coordinated, evidence-bound loop instead of a single turn.
### How it fits together
-LazyCodex is a thin distribution layer. The core engine is [OmO](https://github.com/code-yeongyu/oh-my-openagent). LazyCodex is maintained by [Sisyphus Labs](https://sisyphuslabs.ai).
+LazyCodex is a thin distribution layer over [OmO](https://github.com/code-yeongyu/oh-my-openagent). The core engine is OmO; LazyCodex packages OmO's Hephaestus for Codex.
Credit: The LazyCodex name idea is inspired by [LazyVim](https://github.com/LazyVim/LazyVim). The Ultragoal and UltraQA ideas are inspired by [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex), reimplemented from concept for this Codex setup.
diff --git a/packages/web/content/docs/skills.md b/packages/web/content/docs/skills.md
index 297e3545..40f4692c 100644
--- a/packages/web/content/docs/skills.md
+++ b/packages/web/content/docs/skills.md
@@ -2,7 +2,7 @@ LazyCodex is most useful as a harness for complex codebases: project memory, pla
### Built-in workflows
-Start with `/init-deep` when the repository is too large or too old to explain from memory. It generates hierarchical `AGENTS.md` context so agents can find the right files before they change code.
+Start with `$init-deep` when the repository is too large or too old to explain from memory. It generates hierarchical `AGENTS.md` context so agents can find the right files before they change code.
Use `$ulw-plan` when the work needs decisions before implementation, `$start-work` when a plan should be executed, and `$ulw-loop` when you want the agent to keep going until the result is verified.
diff --git a/packages/web/lib/docs-content.generated.ts b/packages/web/lib/docs-content.generated.ts
index 2b7c9c4f..a6760287 100644
--- a/packages/web/lib/docs-content.generated.ts
+++ b/packages/web/lib/docs-content.generated.ts
@@ -1,10 +1,314 @@
// AUTO-GENERATED — do not edit. Run: node ./scripts/generate-docs-content.mjs
export const DOC_SOURCES: Record<string, string> = {
- "overview.md": "<p>LazyCodex packages <a href=\"https://github.com/code-yeongyu/oh-my-openagent\">oh-my-openagent</a> (OmO) inside Codex as the agent harness for complex codebases. Think <a href=\"https://github.com/LazyVim/LazyVim\">LazyVim</a> for <a href=\"https://github.com/folke/lazy.nvim\">lazy.nvim</a>, but for Codex.</p>\n<h3>What you get</h3>\n<p>OmO gives Codex a full agent harness: discipline agents (Sisyphus orchestrates Hephaestus, Oracle, and Librarian), parallel execution, multi-model routing, a skills system, hooks and lifecycle, and verification defaults. LazyCodex packages that harness as a repeatable Codex setup.</p>\n<h3>The harness workflow</h3>\n<p>Use <code>{your prompt} ultrawork</code> when the job needs project memory, planning, parallel agents, and verified completion to run as one coordinated loop.</p>\n<h3>How it fits together</h3>\n<p>LazyCodex is a thin distribution layer. The core engine is <a href=\"https://github.com/code-yeongyu/oh-my-openagent\">OmO</a>. LazyCodex is maintained by <a href=\"https://sisyphuslabs.ai\">Sisyphus Labs</a>.</p>\n<p>Credit: The LazyCodex name idea is inspired by <a href=\"https://github.com/LazyVim/LazyVim\">LazyVim</a>. The Ultragoal and UltraQA ideas are inspired by <a href=\"https://github.com/Yeachan-Heo/oh-my-codex\">oh-my-codex</a>, reimplemented from concept for this Codex setup.</p>\n<ul>\n<li><a href=\"https://github.com/code-yeongyu/lazycodex\">LazyCodex on GitHub</a></li>\n<li><a href=\"https://github.com/code-yeongyu/oh-my-openagent\">OmO on GitHub</a></li>\n</ul>\n",
- "installation.md": "<p>One command installs the OmO agent harness for Codex without a global package install.</p>\n<h3>Install</h3>\n<pre><code class=\"language-bash\">npx lazycodex-ai install\n</code></pre>\n<p>This is exactly equivalent to <code>npx --yes --package oh-my-openagent omo install --platform=codex</code>.</p>\n<h3>Autonomous one-liner</h3>\n<pre><code class=\"language-bash\">npx lazycodex-ai install --no-tui --codex-autonomous\n</code></pre>\n<h3>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: the installer runs on plain Node.</li>\n<li>The <a href=\"https://github.com/openai/codex\">OpenAI Codex CLI</a></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>Install from the Codex marketplace (experimental)</h3>\n<p>The npx installer above stays the primary path. As an additive, experimental alternative you can install from inside Codex itself: type <code>/plugins</code>, open the <strong>Add Marketplace</strong> tab (&quot;Add a marketplace from a Git repo or local root.&quot;), 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>On the next launch, approve the omo hooks in Codex&#39;s startup review — hooks never run before approval. The first approved session prints <code>LazyCodex bootstrap running in background — restart the session when it completes</code> while a background worker finishes the setup (config blocks, agent roles, bin links, a pinned <code>sg</code> binary for the <code>ast_grep</code> MCP); restart when it is done. The marketplace path never touches Codex permission settings — autonomous mode remains the explicit <code>npx lazycodex-ai install --no-tui --codex-autonomous</code> choice.</p>\n<p>Upgrade with <code>codex plugin marketplace upgrade sisyphuslabs</code>. The next startup review shows the hooks as <strong>Modified</strong> — expected after every upgrade, because the plugin files changed and the previous trust hashes no longer match — re-approve them and the following session re-runs bootstrap on the new version. If anything looks pending or degraded, <code>npx lazycodex-ai doctor</code> explains what and why.</p>\n<h3>Windows</h3>\n<p>Native Windows works with both install paths.</p>\n<ul>\n<li><strong>Node:</strong> <code>npx lazycodex-ai install</code> needs Node.js on <code>PATH</code> (LTS recommended). On marketplace installs the bootstrap step provisions a pinned Node LTS runtime into <code>%USERPROFILE%\\.codex\\runtime\\node\\</code> automatically when <code>node</code> is missing — installing Node yourself first also works and skips the download.</li>\n<li><strong>Git Bash:</strong> required for shell hooks. The installer and the marketplace bootstrap both try <code>winget install --id Git.Git -e --source winget</code> when Git Bash is missing. If Git lives somewhere custom, set <code>OMO_CODEX_GIT_BASH_PATH</code> to a path like <code>C:\\Program Files\\Git\\bin\\bash.exe</code>.</li>\n<li><strong><code>where bash</code> shows <code>C:\\Windows\\System32\\bash.exe</code>:</strong> that is the WSL launcher, not Git Bash — LazyCodex intentionally ignores <code>System32</code> and <code>WindowsApps</code> <code>bash.exe</code> shims when resolving Git Bash. Install Git for Windows or point <code>OMO_CODEX_GIT_BASH_PATH</code> at a real Git Bash so the resolver finds it.</li>\n<li><strong>Troubleshooting:</strong> the Windows marketplace bootstrap writes a transcript to <code>%USERPROFILE%\\.codex\\plugins\\data\\omo-sisyphuslabs\\bootstrap\\ps-bootstrap.log</code>; degraded lines look like <code>degraded component=node reason=... hint=npx lazycodex-ai doctor</code>. Run <code>npx lazycodex-ai doctor</code> for the full health report.</li>\n</ul>\n<h3>Let an agent do it</h3>\n<p>It is strongly recommended to let an LLM agent run the install and walk the setup for you. The agent handles subscription detection, model selection, and provider auth automatically.</p>\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>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>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>review-work</code></td>\n<td>Multi-angle 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</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>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<h3>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>&quot;Plan, execute, verify, and keep the evidence attached.&quot;</p>\n</blockquote>\n<h3>Usage</h3>\n<pre><code class=\"language-bash\">ulw add authentication\n</code></pre>\n<h3>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",
- "ulw-loop.md": "<p><code>$ulw-loop</code> is a self-referential development loop that runs until verified completion.</p>\n<h3>How it works</h3>\n<p>The agent works continuously and emits <code>&lt;promise&gt;DONE&lt;/promise&gt;</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 Oracle verified it. If verification fails, it continues with the message: &quot;Oracle verification failed. Continuing ULTRAWORK loop.&quot;</p>\n<h3>Syntax</h3>\n<pre><code class=\"language-bash\">$ulw-loop &quot;task description&quot; [--completion-promise=TEXT] [--strategy=reset|continue]\n</code></pre>\n<h3>Limits</h3>\n<p>The iteration cap is 500 in ultrawork mode (100 in normal mode).</p>\n",
- "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 &quot;do X&quot; it produces a plan for X and never writes product code.</p>\n<h3>The flow</h3>\n<ol>\n<li>Socratic interview</li>\n<li>Parallel codebase exploration</li>\n<li>Metis gap analysis</li>\n<li>Writes the plan to <code>plans/&lt;slug&gt;.md</code></li>\n<li>Optional Momus high-accuracy review</li>\n</ol>\n<h3>Output</h3>\n<p>Questions, research, and a work plan you can hand to <a href=\"#start-work\"><code>$start-work</code></a>.</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>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>Syntax</h3>\n<pre><code class=\"language-bash\">$start-work [plan-name] [--worktree &lt;absolute-path&gt;]\n</code></pre>\n<h3>Done</h3>\n<p>It prints an <code>ORCHESTRATION COMPLETE</code> block when every checkbox is checked.</p>\n"
+ "overview.md": "<p>LazyCodex is a light port of <a href=\"https://github.com/code-yeongyu/oh-my-openagent\">OmO</a> into Codex. It does not ship the full harness — it ports one role, <strong>Hephaestus</strong>, the autonomous deep worker, and the workflows that keep its runs honest. Think <a href=\"https://github.com/LazyVim/LazyVim\">LazyVim</a> for <a href=\"https://github.com/folke/lazy.nvim\">lazy.nvim</a>, but for Codex.</p>\n<h3 id=\"where-it-comes-from\">Where it comes from</h3>\n<p>OmO is the full agent harness: a primary orchestrator (Sisyphus) with <code>.omo/boulder.json</code> session continuity, a deep worker (Hephaestus), specialist agents, multi-model routing, 54+ lifecycle hooks, and team mode. That is a lot. LazyCodex takes only the piece that matters for a focused Codex setup and packages it as a repeatable install.</p>\n<h3 id=\"what-you-get\">What you get</h3>\n<p>The Hephaestus deep worker, ported into Codex with:</p>\n<ul>\n<li>Goal-oriented execution — you give it objectives, not step-by-step recipes.</li>\n<li>A tight operating loop: <strong>Explore → Plan → Implement → Verify → Manually QA</strong>.</li>\n<li>Parallel explore subagents so it maps the terrain before writing anything.</li>\n<li>The <code>$ulw-plan</code>, <code>$start-work</code>, and <code>$ulw-loop</code> workflows that keep complex work moving until it is verified.</li>\n<li>Skills, hooks, model routing, and verification defaults wired into Codex in one pass.</li>\n</ul>\n<h3 id=\"the-harness-workflow\">The harness workflow</h3>\n<p>Use <code>{your prompt} ultrawork</code> when the job needs the deep worker to run as one coordinated, evidence-bound loop instead of a single turn.</p>\n<h3 id=\"how-it-fits-together\">How it fits together</h3>\n<p>LazyCodex is a thin distribution layer over <a href=\"https://github.com/code-yeongyu/oh-my-openagent\">OmO</a>. The core engine is OmO; LazyCodex packages OmO&#39;s Hephaestus for Codex.</p>\n<p>Credit: The LazyCodex name idea is inspired by <a href=\"https://github.com/LazyVim/LazyVim\">LazyVim</a>. The Ultragoal and UltraQA ideas are inspired by <a href=\"https://github.com/Yeachan-Heo/oh-my-codex\">oh-my-codex</a>, reimplemented from concept for this Codex setup.</p>\n<ul>\n<li><a href=\"https://github.com/code-yeongyu/lazycodex\">LazyCodex on GitHub</a></li>\n<li><a href=\"https://github.com/code-yeongyu/oh-my-openagent\">OmO on GitHub</a></li>\n</ul>\n",
+ "installation.md": "<p>One command installs the OmO agent harness for Codex without a global package install.</p>\n<h3 id=\"install\">Install</h3>\n<pre><code class=\"language-bash\">npx lazycodex-ai install\n</code></pre>\n<p>This is exactly equivalent to <code>npx --yes --package oh-my-openagent omo install --platform=codex</code>.</p>\n<h3 id=\"autonomous-one-liner\">Autonomous one-liner</h3>\n<pre><code class=\"language-bash\">npx lazycodex-ai install --no-tui --codex-autonomous\n</code></pre>\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: the installer runs on plain Node.</li>\n<li>The <a href=\"https://github.com/openai/codex\">OpenAI Codex CLI</a></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=\"install-from-the-codex-marketplace-experimental\">Install from the Codex marketplace (experimental)</h3>\n<p>The npx installer above stays the primary path. As an additive, experimental alternative you can install from inside Codex itself: type <code>/plugins</code>, open the <strong>Add Marketplace</strong> tab (&quot;Add a marketplace from a Git repo or local root.&quot;), 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>On the next launch, approve the omo hooks in Codex&#39;s startup review — hooks never run before approval. The first approved session prints <code>LazyCodex bootstrap running in background — restart the session when it completes</code> while a background worker finishes the setup (config blocks, agent roles, bin links, a pinned <code>sg</code> binary for the <code>ast_grep</code> MCP); restart when it is done. The marketplace path never touches Codex permission settings — autonomous mode remains the explicit <code>npx lazycodex-ai install --no-tui --codex-autonomous</code> choice.</p>\n<p>Upgrade with <code>codex plugin marketplace upgrade sisyphuslabs</code>. The next startup review shows the hooks as <strong>Modified</strong> — expected after every upgrade, because the plugin files changed and the previous trust hashes no longer match — re-approve them and the following session re-runs bootstrap on the new version. If anything looks pending or degraded, <code>npx lazycodex-ai doctor</code> explains what and why.</p>\n<h3 id=\"windows\">Windows</h3>\n<p>Native Windows works with both install paths.</p>\n<ul>\n<li><strong>Node:</strong> <code>npx lazycodex-ai install</code> needs Node.js on <code>PATH</code> (LTS recommended). On marketplace installs the bootstrap step provisions a pinned Node LTS runtime into <code>%USERPROFILE%\\.codex\\runtime\\node\\</code> automatically when <code>node</code> is missing — installing Node yourself first also works and skips the download.</li>\n<li><strong>Git Bash:</strong> required for shell hooks. The installer and the marketplace bootstrap both try <code>winget install --id Git.Git -e --source winget</code> when Git Bash is missing. If Git lives somewhere custom, set <code>OMO_CODEX_GIT_BASH_PATH</code> to a path like <code>C:\\Program Files\\Git\\bin\\bash.exe</code>.</li>\n<li><strong><code>where bash</code> shows <code>C:\\Windows\\System32\\bash.exe</code>:</strong> that is the WSL launcher, not Git Bash — LazyCodex intentionally ignores <code>System32</code> and <code>WindowsApps</code> <code>bash.exe</code> shims when resolving Git Bash. Install Git for Windows or point <code>OMO_CODEX_GIT_BASH_PATH</code> at a real Git Bash so the resolver finds it.</li>\n<li><strong>Troubleshooting:</strong> the Windows marketplace bootstrap writes a transcript to <code>%USERPROFILE%\\.codex\\plugins\\data\\omo-sisyphuslabs\\bootstrap\\ps-bootstrap.log</code>; degraded lines look like <code>degraded component=node reason=... hint=npx lazycodex-ai doctor</code>. Run <code>npx lazycodex-ai doctor</code> for the full health report.</li>\n</ul>\n<h3 id=\"let-an-agent-do-it\">Let an agent do it</h3>\n<p>It is strongly recommended to let an LLM agent run the install and walk the setup for you. The agent handles subscription detection, model selection, and provider auth automatically.</p>\n",
+ "getting-started.md": "<p>LazyCodex is most useful as a harness for complex codebases: project memory, planning, execution, verified completion, skills, hooks, model routing, and diagnostics. This page walks through the four commands you will reach for most often and when to pick each.</p>\n<h3 id=\"the-four-commands\">The four commands</h3>\n<table>\n<thead>\n<tr>\n<th>Command</th>\n<th>Use it when</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>$init-deep</code></td>\n<td>The repository is too large or too old to explain from memory.</td>\n</tr>\n<tr>\n<td><code>$ulw-plan</code></td>\n<td>The work needs decisions before any code is written.</td>\n</tr>\n<tr>\n<td><code>$start-work</code></td>\n<td>A plan exists and should be executed to completion.</td>\n</tr>\n<tr>\n<td><code>$ulw-loop</code></td>\n<td>You want the agent to keep going until the result is verified.</td>\n</tr>\n</tbody></table>\n<h3 id=\"how-to-choose\">How to choose</h3>\n<p>Start with <code>$init-deep</code> once per repository so agents have hierarchical <code>AGENTS.md</code> context to work from.</p>\n<p>For anything ambiguous, run <code>$ulw-plan</code> first. It interviews you, explores the codebase in parallel, and writes a decision-complete plan to <code>plans/&lt;slug&gt;.md</code> without touching product code.</p>\n<p>Hand that plan to <code>$start-work</code> to execute it: durable Boulder state, parallel subagents, strict TDD, and five evidence gates. It prints <code>ORCHESTRATION COMPLETE</code> when every checkbox is done.</p>\n<p><code>$ulw-loop</code> is the tightest loop — use it for a single task that must run until an oracle verifies completion. It does not plan; it executes and verifies.</p>\n<h3 id=\"a-typical-session\">A typical session</h3>\n<pre><code class=\"language-text\">$init-deep\n$ulw-plan &quot;add rate limiting to the api gateway&quot;\n$start-work plans/add-rate-limiting.md\n</code></pre>\n<p>If the job is small and well-understood, skip the plan and loop directly:</p>\n<pre><code class=\"language-text\">ulw fix the flaky checkout test\n</code></pre>\n<p>See <a href=\"#skills\">Feature coverage</a> for the skills that add specialist judgment around these commands.</p>\n",
+ "init-deep.md": "<p><code>$init-deep</code> generates hierarchical <code>AGENTS.md</code> context so agents start from local guidance before touching a large repository. Run it once per project, and again whenever the architecture shifts enough that the existing context no longer reflects reality.</p>\n<h3 id=\"what-it-produces\">What it produces</h3>\n<ul>\n<li>A root <code>AGENTS.md</code> that orients agents to the project: stack, layout, conventions, and where to look first.</li>\n<li>Nested <code>AGENTS.md</code> files in the directories that matter most, so an agent descending into a package gets scoped guidance instead of guessing.</li>\n<li>References to project rules, skills, and instruction files the harness should respect.</li>\n</ul>\n<h3 id=\"when-to-run-it\">When to run it</h3>\n<ul>\n<li>Onboarding a repository that is too large or too old to explain from memory.</li>\n<li>After a major refactor, migration, or layout change.</li>\n<li>When agents keep picking the wrong files or ignoring local conventions.</li>\n</ul>\n<h3 id=\"how-to-use-it\">How to use it</h3>\n<pre><code class=\"language-text\">$init-deep\n</code></pre>\n<p>The command walks the tree, reads the files that define how the project actually works, and writes the context. Review the generated <code>AGENTS.md</code> files, trim anything stale, and commit them. Agents in later turns read that context before they edit, so the first session pays for every session after it.</p>\n<h3 id=\"after-init\">After init</h3>\n<p>With context in place, move to <a href=\"#ulw-plan\"><code>$ulw-plan</code></a> when the work needs a plan, or <a href=\"#ulw-loop\"><code>$ulw-loop</code></a> for a single verified task.</p>\n",
+ "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 &quot;do X&quot; it produces a plan for X and never writes product code.</p>\n<h3 id=\"the-flow\">The flow</h3>\n<ol>\n<li>Socratic interview</li>\n<li>Parallel codebase exploration</li>\n<li>Metis gap analysis</li>\n<li>Writes the plan to <code>plans/&lt;slug&gt;.md</code></li>\n<li>Optional Momus high-accuracy review</li>\n</ol>\n<h3 id=\"output\">Output</h3>\n<p>Questions, research, and a work plan you can hand to <a href=\"#start-work\"><code>$start-work</code></a>.</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 &lt;absolute-path&gt;]\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 runs until verified completion.</p>\n<h3 id=\"how-it-works\">How it works</h3>\n<p>The agent works continuously and emits <code>&lt;promise&gt;DONE&lt;/promise&gt;</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 Oracle verified it. If verification fails, it continues with the message: &quot;Oracle verification failed. Continuing ULTRAWORK loop.&quot;</p>\n<h3 id=\"syntax\">Syntax</h3>\n<pre><code class=\"language-bash\">$ulw-loop &quot;task description&quot; [--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",
+ "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>&quot;Plan, execute, verify, and keep the evidence attached.&quot;</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. &quot;The Legitimate Craftsman.&quot; 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 &quot;done&quot; 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 &amp; 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&#39;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&#39;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",
+ "hooks-lifecycle.md": "<p>Hooks and lifecycle are how the harness keeps a long run moving without you re-prompting every turn. OmO installs lifecycle hooks into Codex that observe each turn and decide what happens next.</p>\n<h3 id=\"the-core-mechanism\">The core mechanism</h3>\n<p>A Stop-hook fires when a turn ends. If a plan is still in progress, the hook re-injects the next turn automatically — the agent continues from durable progress state instead of waiting for you to say &quot;continue&quot;. The run only stops when the plan is complete or a gate fails in a way that needs a human.</p>\n<h3 id=\"where-progress-lives\">Where progress lives</h3>\n<p>Progress state is written to <code>.omo/boulder.json</code> and survives across turns and sessions. That is what lets <a href=\"#start-work\"><code>$start-work</code></a> resume a plan after a restart, and what keeps <a href=\"#ulw-loop\"><code>$ulw-loop</code></a> honest about how far it has actually gotten.</p>\n<h3 id=\"approval-and-trust\">Approval and trust</h3>\n<p>Hooks never run before approval. On the first launch after install, Codex&#39;s startup review asks you to approve the omo hooks. After every upgrade the hooks show as <strong>Modified</strong> — expected, because the plugin files changed and the previous trust hashes no longer match — re-approve and the next session re-runs bootstrap on the new version.</p>\n<h3 id=\"evidence-gates\">Evidence gates</h3>\n<p>During execution the lifecycle enforces five evidence gates before a step can close: plan reread, automated verification, manual-QA, 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 turns these gates into a binding loop.</li>\n<li><a href=\"#configuration\">Configuration</a> — how to tune hook behavior and lifecycle defaults.</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>review-work</code></td>\n<td>Multi-angle 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</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>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<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&#39;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",
+ "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"
+};
+
+export type DocHeading = { level: number; id: string; text: string };
+export const DOC_TOC: Record<string, DocHeading[]> = {
+ "overview.md": [
+ {
+ "level": 3,
+ "id": "where-it-comes-from",
+ "text": "Where it comes from"
+ },
+ {
+ "level": 3,
+ "id": "what-you-get",
+ "text": "What you get"
+ },
+ {
+ "level": 3,
+ "id": "the-harness-workflow",
+ "text": "The harness workflow"
+ },
+ {
+ "level": 3,
+ "id": "how-it-fits-together",
+ "text": "How it fits together"
+ }
+ ],
+ "installation.md": [
+ {
+ "level": 3,
+ "id": "install",
+ "text": "Install"
+ },
+ {
+ "level": 3,
+ "id": "autonomous-one-liner",
+ "text": "Autonomous one-liner"
+ },
+ {
+ "level": 3,
+ "id": "prerequisites",
+ "text": "Prerequisites"
+ },
+ {
+ "level": 3,
+ "id": "install-from-the-codex-marketplace-experimental",
+ "text": "Install from the Codex marketplace (experimental)"
+ },
+ {
+ "level": 3,
+ "id": "windows",
+ "text": "Windows"
+ },
+ {
+ "level": 3,
+ "id": "let-an-agent-do-it",
+ "text": "Let an agent do it"
+ }
+ ],
+ "getting-started.md": [
+ {
+ "level": 3,
+ "id": "the-four-commands",
+ "text": "The four commands"
+ },
+ {
+ "level": 3,
+ "id": "how-to-choose",
+ "text": "How to choose"
+ },
+ {
+ "level": 3,
+ "id": "a-typical-session",
+ "text": "A typical session"
+ }
+ ],
+ "init-deep.md": [
+ {
+ "level": 3,
+ "id": "what-it-produces",
+ "text": "What it produces"
+ },
+ {
+ "level": 3,
+ "id": "when-to-run-it",
+ "text": "When to run it"
+ },
+ {
+ "level": 3,
+ "id": "how-to-use-it",
+ "text": "How to use it"
+ },
+ {
+ "level": 3,
+ "id": "after-init",
+ "text": "After init"
+ }
+ ],
+ "ulw-plan.md": [
+ {
+ "level": 3,
+ "id": "the-flow",
+ "text": "The flow"
+ },
+ {
+ "level": 3,
+ "id": "output",
+ "text": "Output"
+ }
+ ],
+ "start-work.md": [
+ {
+ "level": 3,
+ "id": "how-it-works",
+ "text": "How it works"
+ },
+ {
+ "level": 3,
+ "id": "syntax",
+ "text": "Syntax"
+ },
+ {
+ "level": 3,
+ "id": "done",
+ "text": "Done"
+ }
+ ],
+ "ulw-loop.md": [
+ {
+ "level": 3,
+ "id": "how-it-works",
+ "text": "How it works"
+ },
+ {
+ "level": 3,
+ "id": "syntax",
+ "text": "Syntax"
+ },
+ {
+ "level": 3,
+ "id": "limits",
+ "text": "Limits"
+ }
+ ],
+ "ultrawork.md": [
+ {
+ "level": 3,
+ "id": "usage",
+ "text": "Usage"
+ },
+ {
+ "level": 3,
+ "id": "what-it-enforces",
+ "text": "What it enforces"
+ }
+ ],
+ "discipline-agents.md": [
+ {
+ "level": 3,
+ "id": "what-hephaestus-is",
+ "text": "What Hephaestus is"
+ },
+ {
+ "level": 3,
+ "id": "the-operating-loop",
+ "text": "The operating loop"
+ },
+ {
+ "level": 3,
+ "id": "what-it-never-does",
+ "text": "What it never does"
+ },
+ {
+ "level": 3,
+ "id": "delegation-not-orchestration",
+ "text": "Delegation, not orchestration"
+ },
+ {
+ "level": 3,
+ "id": "where-the-boulder-comes-from",
+ "text": "Where the boulder comes from"
+ },
+ {
+ "level": 3,
+ "id": "reading-more",
+ "text": "Reading more"
+ }
+ ],
+ "model-routing.md": [
+ {
+ "level": 3,
+ "id": "what-gets-routed",
+ "text": "What gets routed"
+ },
+ {
+ "level": 3,
+ "id": "how-it-fits-the-harness",
+ "text": "How it fits the harness"
+ },
+ {
+ "level": 3,
+ "id": "provider-auth",
+ "text": "Provider auth"
+ },
+ {
+ "level": 3,
+ "id": "customizing-it",
+ "text": "Customizing it"
+ }
+ ],
+ "hooks-lifecycle.md": [
+ {
+ "level": 3,
+ "id": "the-core-mechanism",
+ "text": "The core mechanism"
+ },
+ {
+ "level": 3,
+ "id": "where-progress-lives",
+ "text": "Where progress lives"
+ },
+ {
+ "level": 3,
+ "id": "approval-and-trust",
+ "text": "Approval and trust"
+ },
+ {
+ "level": 3,
+ "id": "evidence-gates",
+ "text": "Evidence gates"
+ },
+ {
+ "level": 3,
+ "id": "reading-more",
+ "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,
+ "id": "where-config-lives",
+ "text": "Where config lives"
+ },
+ {
+ "level": 3,
+ "id": "what-you-can-tune",
+ "text": "What you can tune"
+ },
+ {
+ "level": 3,
+ "id": "diagnosing-config",
+ "text": "Diagnosing config"
+ },
+ {
+ "level": 3,
+ "id": "re-running-setup",
+ "text": "Re-running setup"
+ }
+ ],
+ "cli.md": [
+ {
+ "level": 3,
+ "id": "install",
+ "text": "install"
+ },
+ {
+ "level": 3,
+ "id": "doctor",
+ "text": "doctor"
+ },
+ {
+ "level": 3,
+ "id": "prerequisites",
+ "text": "Prerequisites"
+ },
+ {
+ "level": 3,
+ "id": "marketplace-alternative",
+ "text": "Marketplace alternative"
+ }
+ ]
};
diff --git a/packages/web/lib/docs-sections.ts b/packages/web/lib/docs-sections.ts
index a02912aa..95f6a18b 100644
--- a/packages/web/lib/docs-sections.ts
+++ b/packages/web/lib/docs-sections.ts
@@ -1,26 +1,68 @@
export type DocSectionId =
| "overview"
| "installation"
- | "skills"
- | "ultrawork"
- | "ulw-loop"
+ | "getting-started"
+ | "init-deep"
| "ulw-plan"
- | "start-work";
+ | "start-work"
+ | "ulw-loop"
+ | "ultrawork"
+ | "discipline-agents"
+ | "model-routing"
+ | "hooks-lifecycle"
+ | "skills"
+ | "configuration"
+ | "cli";
export type DocSection = {
readonly id: DocSectionId;
readonly file: string;
readonly title: string;
+ readonly group: string;
};
+// Ordered list of sidebar groups. Each group renders as a category header with
+// its sections nested underneath, matching the lzx.vibetip.help docs layout.
+export const DOC_GROUPS: readonly string[] = [
+ "Install",
+ "Getting started",
+ "Commands",
+ "Concepts",
+ "Skills",
+ "Reference",
+];
+
export const DOC_SECTIONS: readonly DocSection[] = [
- { id: "overview", file: "overview.md", title: "Overview" },
- { id: "installation", file: "installation.md", title: "Installation" },
- { id: "skills", file: "skills.md", title: "Feature coverage" },
- { id: "ultrawork", file: "ultrawork.md", title: "ultrawork mode" },
- { id: "ulw-loop", file: "ulw-loop.md", title: "$ulw-loop" },
- { id: "ulw-plan", file: "ulw-plan.md", title: "$ulw-plan" },
- { id: "start-work", file: "start-work.md", title: "$start-work" },
+ { id: "installation", file: "installation.md", group: "Install", title: "Installation" },
+ { id: "overview", file: "overview.md", group: "Getting started", title: "Overview" },
+ { id: "getting-started", file: "getting-started.md", group: "Getting started", title: "Getting started" },
+ { id: "init-deep", file: "init-deep.md", group: "Commands", title: "$init-deep" },
+ { 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: "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" },
+ { id: "hooks-lifecycle", file: "hooks-lifecycle.md", group: "Concepts", title: "Hooks & Lifecycle" },
+ { id: "skills", file: "skills.md", group: "Skills", title: "Feature coverage" },
+ { id: "configuration", file: "configuration.md", group: "Reference", title: "Configuration" },
+ { id: "cli", file: "cli.md", group: "Reference", title: "CLI" },
] as const;
export const DOC_SECTION_IDS = DOC_SECTIONS.map((s) => s.id);
+
+export function sectionsByGroup(group: string): readonly DocSection[] {
+ return DOC_SECTIONS.filter((s) => s.group === group);
+}
+
+export function neighborSections(id: DocSectionId): {
+ prev: DocSection | undefined;
+ next: DocSection | undefined;
+} {
+ const index = DOC_SECTIONS.findIndex((s) => s.id === id);
+ if (index === -1) return { prev: undefined, next: undefined };
+ return {
+ prev: index > 0 ? DOC_SECTIONS[index - 1] : undefined,
+ next: index < DOC_SECTIONS.length - 1 ? DOC_SECTIONS[index + 1] : undefined,
+ };
+}
diff --git a/packages/web/lib/docs-source.ts b/packages/web/lib/docs-source.ts
index de550fe3..b2e92f5d 100644
--- a/packages/web/lib/docs-source.ts
+++ b/packages/web/lib/docs-source.ts
@@ -1,4 +1,4 @@
-import { DOC_SOURCES } from "./docs-content.generated";
+import { DOC_SOURCES, DOC_TOC, type DocHeading } from "./docs-content.generated";
export function loadDocSource(file: string): string {
const source = DOC_SOURCES[file];
@@ -9,3 +9,13 @@ export function loadDocSource(file: string): string {
}
return source;
}
+
+export function loadDocToc(file: string): DocHeading[] {
+ const toc = DOC_TOC[file];
+ if (toc === undefined) {
+ throw new Error(
+ `Unknown doc file: ${file}. Run \`node ./scripts/generate-docs-content.mjs\` to regenerate docs content.`,
+ );
+ }
+ return toc;
+}
diff --git a/packages/web/scripts/generate-docs-content.mjs b/packages/web/scripts/generate-docs-content.mjs
index 28883396..d4912aeb 100644
--- a/packages/web/scripts/generate-docs-content.mjs
+++ b/packages/web/scripts/generate-docs-content.mjs
@@ -6,14 +6,23 @@ 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.
const SECTIONS = [
- { id: "overview", file: "overview.md" },
- { id: "installation", file: "installation.md" },
- { id: "skills", file: "skills.md" },
- { id: "ultrawork", file: "ultrawork.md" },
- { id: "ulw-loop", file: "ulw-loop.md" },
- { id: "ulw-plan", file: "ulw-plan.md" },
- { id: "start-work", file: "start-work.md" },
+ { id: "overview", file: "overview.md", group: "Getting started", title: "Overview" },
+ { id: "installation", file: "installation.md", group: "Install", title: "Installation" },
+ { id: "getting-started", file: "getting-started.md", group: "Getting started", title: "Getting started" },
+ { id: "init-deep", file: "init-deep.md", group: "Commands", title: "$init-deep" },
+ { 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: "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" },
+ { id: "hooks-lifecycle", file: "hooks-lifecycle.md", group: "Concepts", title: "Hooks & Lifecycle" },
+ { id: "skills", file: "skills.md", group: "Skills", title: "Feature coverage" },
+ { id: "configuration", file: "configuration.md", group: "Reference", title: "Configuration" },
+ { id: "cli", file: "cli.md", group: "Reference", title: "CLI" },
];
const DOCS_ROOT = path.resolve(process.cwd(), "content", "docs");
@@ -60,14 +69,38 @@ function createMarked() {
return marked;
}
+// 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) {
+ 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 level = tag === "h2" ? 2 : 3;
+ toc.push({ level, id, text });
+ return `<${tag} id="${id}">${inner}</${tag}>`;
+ });
+ return { withIds, toc };
+}
+
const sources = {};
+const tocs = {};
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.
- sources[section.file] = await createMarked().parse(markdown);
+ const rawHtml = await createMarked().parse(markdown);
+ const { withIds, toc } = injectHeadingIds(rawHtml);
+ sources[section.file] = withIds;
+ tocs[section.file] = toc;
}
-const out = `${BANNER}export const DOC_SOURCES: Record<string, string> = ${JSON.stringify(sources, null, 2)};\n`;
+const out =
+ `${BANNER}` +
+ `export const DOC_SOURCES: Record<string, string> = ${JSON.stringify(sources, null, 2)};\n\n` +
+ `export type DocHeading = { level: number; id: string; text: string };\n` +
+ `export const DOC_TOC: Record<string, DocHeading[]> = ${JSON.stringify(tocs, null, 2)};\n`;
async function outputIsCurrent(content) {
try {