From 4186f76b14e6433a9d4e0d5d1bce219d6fa7bc5e Mon Sep 17 00:00:00 2001 From: Joe Blau Date: Wed, 14 Oct 2026 10:39:11 -0700 Subject: [PATCH] fix(docs): serve local docs at root and highlight workflow --- README.md | 8 ++-- apps/docs/README.md | 8 ++-- apps/docs/app/global.css | 17 +++++--- apps/docs/app/page.tsx | 13 +----- apps/docs/components/hero-code.tsx | 59 ++++++++++++++++++++++++++++ apps/docs/lib/site.ts | 2 +- apps/docs/next.config.mjs | 2 +- apps/docs/public/llms.txt | 28 ++++++------- apps/docs/public/robots.txt | 2 +- apps/docs/scripts/check-export.mjs | 2 +- apps/docs/scripts/prepare-public.mjs | 2 +- docs/PROGRESS.md | 2 + 12 files changed, 102 insertions(+), 43 deletions(-) create mode 100644 apps/docs/components/hero-code.tsx diff --git a/README.md b/README.md index 964c3e3..195be47 100644 --- a/README.md +++ b/README.md @@ -70,16 +70,16 @@ The published CLI still supports Node.js **22.12+**. ```sh npm ci -npm run docs:dev # http://localhost:3903/agent-cli/ +npm run docs:dev # http://localhost:3903/ npm run docs:build # static export at apps/docs/out npm run docs:check npm run docs:preview # previews the export at port 3903 npm run pack:cli # packs only @bloxwap/agent-cli ``` -The site defaults to `/agent-cli`; override `NEXT_PUBLIC_BASE_PATH` for another -host (use an empty value for a root deployment). Pages CI builds and checks pull -requests and deploys main. Command schemas and the skill guide are generated +The site defaults to the host root; the docs are under `/docs/`. Pages CI sets +`NEXT_PUBLIC_BASE_PATH=/agent-cli` for its deployment, builds and checks pull +requests, and deploys main. Command schemas and the skill guide are generated from the CLI with `npm run docs:generate` and before docs builds. [Docs index](docs/index.md), [security](docs/security.md), diff --git a/apps/docs/README.md b/apps/docs/README.md index 224471d..da455f9 100644 --- a/apps/docs/README.md +++ b/apps/docs/README.md @@ -14,9 +14,11 @@ npm run docs:check npm run docs:preview ``` -Development and preview use port **3903**. The default base path is `/agent-cli`, -so open http://localhost:3903/agent-cli/. Set `NEXT_PUBLIC_BASE_PATH` to override it, -including an empty string for a root deployment. Set `NEXT_PUBLIC_SITE_URL` for +Development and preview use port **3903**. The default base path is empty, +so open http://localhost:3903/ for the landing page and http://localhost:3903/docs/ +for the documentation. The Pages workflow sets `NEXT_PUBLIC_BASE_PATH=/agent-cli` +for deployment; set it explicitly when building or previewing that path locally. +Set `NEXT_PUBLIC_SITE_URL` for canonical and social URLs (default `https://bloxwap.github.io`). The static preview reads the base path from the built artifact and needs no Next.js server. diff --git a/apps/docs/app/global.css b/apps/docs/app/global.css index c018f5f..97b48ac 100644 --- a/apps/docs/app/global.css +++ b/apps/docs/app/global.css @@ -228,21 +228,26 @@ html > body[data-scroll-locked] { .install-feedback { display: block; } /* Hero code window: zero-stroke fill card with the Bloxwap code palette (as on the Hyperliquid SDK site). */ -.code-window { min-width: 0; margin: 0; overflow: hidden; border-radius: var(--radius-xl); background: var(--card); color: var(--foreground); } +.code-window { + --code-keyword: color-mix(in oklab, #ff479c 70%, var(--foreground)); + --code-type: color-mix(in oklab, var(--hig-info) 60%, var(--foreground)); + min-width: 0; margin: 0; overflow: hidden; border-radius: var(--radius-xl); background: var(--card); color: var(--foreground); +} .code-toolbar { - display: flex; align-items: center; justify-content: space-between; gap: var(--space-md); - padding: var(--space-lg) var(--space-2xl) 0; font: var(--text-2xs) / 1.5 var(--font-mono); color: var(--muted-foreground); + display: grid; grid-template-columns: auto minmax(0, 1fr) auto; align-items: center; gap: var(--space-md); + padding: var(--space-md) var(--space-2xl) 0; font: var(--text-2xs) / 1.5 var(--font-mono); color: var(--muted-foreground); } .window-dots { display: flex; gap: var(--space-xs); } .window-dots > i { width: 6px; height: 6px; border-radius: var(--radius-full); background: var(--muted); } -.code-language { color: color-mix(in oklab, var(--bloxwap-blue) 60%, var(--foreground)); } +.code-caption { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.code-language { color: var(--code-type); } .code-actions { display: flex; align-items: center; gap: var(--space-xs); margin-right: calc(-1 * var(--space-md)); } .code-toolbar { min-height: var(--control-h-sm); } .code-window pre { margin: 0; overflow-x: auto; padding: var(--space-xl) var(--space-2xl); font: var(--text-xs) / 1.85 var(--font-mono); tab-size: 2; scrollbar-width: none; } .code-window pre::-webkit-scrollbar { display: none; } -.syntax-keyword { color: color-mix(in oklab, var(--bloxwap-pink) 70%, var(--foreground)); } +.syntax-keyword { color: var(--code-keyword); } .syntax-string { color: var(--bloxwap-green); } -.syntax-type { color: color-mix(in oklab, var(--bloxwap-blue) 60%, var(--foreground)); } +.syntax-type { color: var(--code-type); } .syntax-muted { color: var(--muted-foreground); } .code-status { display: flex; align-items: center; gap: var(--space-sm); margin: 0; diff --git a/apps/docs/app/page.tsx b/apps/docs/app/page.tsx index ba195d3..e7d520a 100644 --- a/apps/docs/app/page.tsx +++ b/apps/docs/app/page.tsx @@ -4,6 +4,7 @@ import { HomeLayout } from 'fumadocs-ui/layouts/home'; import { baseOptions } from '@/lib/layout.shared'; import { InstallCommand } from '@/components/install-command'; import { SiteFooter } from '@/components/site-footer'; +import { HeroCode } from '@/components/hero-code'; export default function Home() { return @@ -16,17 +17,7 @@ export default function Home() {
Get started
-
-
init → fund → status → runShell
- 
{`agent-cli schema order
-agent-cli init --network testnet
-# Complete external wallet approvals.
-# Fund using a supported test route and show the QR.
-agent-cli status --network testnet
-# Wait for deposits to settle.
-agent-cli run --network testnet --detach
-agent-cli events --follow --since 0`}
-
+
01

JSON in. JSON out.

Discover input and output schemas for every command. Handle stable error codes and exact decimal strings.

diff --git a/apps/docs/components/hero-code.tsx b/apps/docs/components/hero-code.tsx new file mode 100644 index 0000000..9e0850c --- /dev/null +++ b/apps/docs/components/hero-code.tsx @@ -0,0 +1,59 @@ +import type { ReactNode } from 'react'; +import { CopyButton } from './copy-button'; + +const SOURCE = `agent-cli schema order +agent-cli init --network testnet +# Complete external wallet approvals. +# Fund using a supported test route and show the QR. +agent-cli status --network testnet +# Wait for deposits to settle. +agent-cli run --network testnet --detach +agent-cli events --follow --since 0`; + +// Highlight this fixed shell example with the same code roles as the other docs sites. +const TOKEN = /(#[^\n]*)|(--[a-z][\w-]*)|(\bagent-cli\b)|(\b(?:schema|order|init|status|run|events)\b)|(\btestnet\b|\b\d+\b)|([\s\S])/g; + +function highlight(code: string): ReactNode[] { + const output: ReactNode[] = []; + let plain = ''; + + const flush = () => { + if (plain) output.push(plain); + plain = ''; + }; + + for (const [, comment, flag, executable, command, value, other] of code.matchAll(TOKEN)) { + const text = comment ?? flag ?? executable ?? command ?? value ?? other; + const className = comment ? 'syntax-muted' + : flag ? 'syntax-type' + : command ? 'syntax-keyword' + : executable || value ? 'syntax-string' + : null; + + if (className) { + flush(); + output.push({text}); + } else { + plain += text; + } + } + + flush(); + return output; +} + +export function HeroCode() { + return ( +
+
+ + init → fund → status → run + + Shell + + +
+ 
{highlight(SOURCE)}
+
+ ); +} diff --git a/apps/docs/lib/site.ts b/apps/docs/lib/site.ts index 8c60e3b..ba5567c 100644 --- a/apps/docs/lib/site.ts +++ b/apps/docs/lib/site.ts @@ -1,4 +1,4 @@ -export const basePath = process.env.NEXT_PUBLIC_BASE_PATH ?? '/agent-cli'; +export const basePath = process.env.NEXT_PUBLIC_BASE_PATH ?? ''; export const siteUrl = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://bloxwap.github.io'; export const repository = 'https://github.com/bloxwap/agent-cli'; diff --git a/apps/docs/next.config.mjs b/apps/docs/next.config.mjs index b1817e8..7668157 100644 --- a/apps/docs/next.config.mjs +++ b/apps/docs/next.config.mjs @@ -6,7 +6,7 @@ const withMDX = createMDX(); export default withMDX({ output: 'export', trailingSlash: true, - basePath: process.env.NEXT_PUBLIC_BASE_PATH ?? '/agent-cli', + basePath: process.env.NEXT_PUBLIC_BASE_PATH ?? '', images: { unoptimized: true }, reactStrictMode: true, // Resolve dependencies from the npm workspace root. diff --git a/apps/docs/public/llms.txt b/apps/docs/public/llms.txt index d4eedb7..652aac2 100644 --- a/apps/docs/public/llms.txt +++ b/apps/docs/public/llms.txt @@ -2,19 +2,19 @@ Hyperliquid trading with Privy custody and Relay funding. Master keys stay external. -- [Overview and installation](https://bloxwap.github.io/agent-cli/docs/) -- [quickstart](https://bloxwap.github.io/agent-cli/docs/quickstart/) -- [commands](https://bloxwap.github.io/agent-cli/docs/commands/) -- [config](https://bloxwap.github.io/agent-cli/docs/config/) -- [errors](https://bloxwap.github.io/agent-cli/docs/errors/) -- [runner](https://bloxwap.github.io/agent-cli/docs/runner/) -- [events](https://bloxwap.github.io/agent-cli/docs/events/) -- [funding](https://bloxwap.github.io/agent-cli/docs/funding/) -- [custody](https://bloxwap.github.io/agent-cli/docs/custody/) -- [security](https://bloxwap.github.io/agent-cli/docs/security/) -- [skill](https://bloxwap.github.io/agent-cli/docs/skill/) -- [audit](https://bloxwap.github.io/agent-cli/docs/audit/) +- [Overview and installation](https://bloxwap.github.io/docs/) +- [quickstart](https://bloxwap.github.io/docs/quickstart/) +- [commands](https://bloxwap.github.io/docs/commands/) +- [config](https://bloxwap.github.io/docs/config/) +- [errors](https://bloxwap.github.io/docs/errors/) +- [runner](https://bloxwap.github.io/docs/runner/) +- [events](https://bloxwap.github.io/docs/events/) +- [funding](https://bloxwap.github.io/docs/funding/) +- [custody](https://bloxwap.github.io/docs/custody/) +- [security](https://bloxwap.github.io/docs/security/) +- [skill](https://bloxwap.github.io/docs/skill/) +- [audit](https://bloxwap.github.io/docs/audit/) -- [Sitemap](https://bloxwap.github.io/agent-cli/sitemap.xml) -- [Static search index](https://bloxwap.github.io/agent-cli/search.json) +- [Sitemap](https://bloxwap.github.io/sitemap.xml) +- [Static search index](https://bloxwap.github.io/search.json) - [Source and packaged SKILL.md](https://github.com/bloxwap/agent-cli/tree/main/packages/agent-cli) diff --git a/apps/docs/public/robots.txt b/apps/docs/public/robots.txt index 2d56fba..bb560ea 100644 --- a/apps/docs/public/robots.txt +++ b/apps/docs/public/robots.txt @@ -1,3 +1,3 @@ User-agent: * Allow: / -Sitemap: https://bloxwap.github.io/agent-cli/sitemap.xml +Sitemap: https://bloxwap.github.io/sitemap.xml diff --git a/apps/docs/scripts/check-export.mjs b/apps/docs/scripts/check-export.mjs index b74d5e3..4597c40 100644 --- a/apps/docs/scripts/check-export.mjs +++ b/apps/docs/scripts/check-export.mjs @@ -3,7 +3,7 @@ import { resolve, join, dirname, extname, relative, sep } from 'node:path'; import { fileURLToPath } from 'node:url'; const root = fileURLToPath(new URL('../out/', import.meta.url)); -const basePath = process.env.NEXT_PUBLIC_BASE_PATH ?? '/agent-cli'; +const basePath = process.env.NEXT_PUBLIC_BASE_PATH ?? ''; const siteUrl = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://bloxwap.github.io'; const failures = []; const exists = async (path) => { try { return (await stat(path)).isFile(); } catch { return false; } }; diff --git a/apps/docs/scripts/prepare-public.mjs b/apps/docs/scripts/prepare-public.mjs index f6cb868..979480b 100644 --- a/apps/docs/scripts/prepare-public.mjs +++ b/apps/docs/scripts/prepare-public.mjs @@ -1,5 +1,5 @@ import { writeFileSync, readFileSync } from 'node:fs'; -const basePath = process.env.NEXT_PUBLIC_BASE_PATH ?? '/agent-cli'; +const basePath = process.env.NEXT_PUBLIC_BASE_PATH ?? ''; const siteUrl = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://bloxwap.github.io'; const absolute = (path) => new URL(`${basePath}${path}`, siteUrl).href; const pages = JSON.parse(readFileSync(new URL('../content/docs/meta.json', import.meta.url), 'utf8')).pages; diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md index d96f31f..30bfcf2 100644 --- a/docs/PROGRESS.md +++ b/docs/PROGRESS.md @@ -52,4 +52,6 @@ Final local verification: supported Node 22, strict build/lint/typecheck and iso - Workspace migration: done — CLI sources, tests, skill, policies and release tooling live in `packages/agent-cli`; root scripts delegate, publish targets the CLI workspace. - Fumadocs site: done — Chart conventions, HIG assets, local fonts, static search/social cards, MDX operating guides, generated schemas/skill, and main-only Pages deployment. +- Local docs URLs: done — development defaults to `http://localhost:3903/` with documentation under `/docs/`; the Pages workflow explicitly retains `/agent-cli` as its deployment base path. +- Landing workflow panel: done — shared code-window toolbar and copy control, highlighted shell commands, muted comments, and HIG-backed blue syntax colors. - Verification: Node 24; clean `npm ci`; root build/lint/typecheck/tests (71 tests), docs build/check, export link/social checks, static preview 200/404 checks, CLI pack and global-install smoke passed. No push or publish.