fix(docs): serve local docs at root and highlight workflow

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),

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.
 

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;

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 <HomeLayout {...baseOptions()}>
@@ -16,17 +17,7 @@ export default function Home() {
           <div className="hero-actions"><Link href="/docs/quickstart" className="btn">Get started <ArrowRight aria-hidden="true" /></Link><Link href="/docs/commands" className="btn btn--secondary">Command reference <ArrowRight aria-hidden="true" /></Link></div>
           <InstallCommand />
         </div>
-        <figure className="code-window">
-          <figcaption className="code-toolbar"><span>init → fund → status → run</span><span className="code-language">Shell</span></figcaption>
-          <pre><code>{`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`}</code></pre>
-        </figure>
+        <HeroCode />
       </section>
       <section className="principles" aria-label="CLI features">
         <div><span className="feature-number">01</span><h2>JSON in. JSON out.</h2><p>Discover input and output schemas for every command. Handle stable error codes and exact decimal strings.</p></div>

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(<span className={className} key={output.length}>{text}</span>);
+    } else {
+      plain += text;
+    }
+  }
+
+  flush();
+  return output;
+}
+
+export function HeroCode() {
+  return (
+    <figure className="code-window" aria-label="Agent CLI onboarding workflow">
+      <figcaption className="code-toolbar">
+        <span className="window-dots" aria-hidden="true"><i /><i /><i /></span>
+        <span className="code-caption">init → fund → status → run</span>
+        <span className="code-actions">
+          <span className="code-language">Shell</span>
+          <CopyButton text={`${SOURCE}\n`} label="Copy workflow commands" />
+        </span>
+      </figcaption>
+      <pre tabIndex={0} aria-label="Shell commands"><code>{highlight(SOURCE)}</code></pre>
+    </figure>
+  );
+}

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';
 

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.

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)

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

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; } };

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;

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.