docs: Fumadocs site at apps/docs (npm workspace layout)

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 24
           cache: npm
       - run: npm ci
       - run: npm run build

.github/workflows/docs.yml

@@ -1,23 +1,54 @@
 name: Documentation
+
 on:
+  push:
+    branches: [main]
+    paths: ['apps/**', 'packages/**', 'package.json', 'package-lock.json', '.github/workflows/docs.yml']
+  pull_request:
+    paths: ['apps/**', 'packages/**', 'package.json', 'package-lock.json', '.github/workflows/docs.yml']
   workflow_dispatch:
+
 permissions:
   contents: read
-  pages: write
-  id-token: write
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
-  docs:
+  build:
     runs-on: ubuntu-latest
-    environment: github-pages
+    env:
+      NEXT_PUBLIC_BASE_PATH: /agent-cli
+      NEXT_PUBLIC_SITE_URL: https://bloxwap.github.io
+      NEXT_TELEMETRY_DISABLED: '1'
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
         with:
-          node-version: 22
+          node-version: '24'
           cache: npm
+          cache-dependency-path: package-lock.json
       - run: npm ci
-      - run: npm run docs:generate
-      - uses: actions/upload-pages-artifact@v3
+      - run: npm run docs:build
+      - run: npm run docs:check
+      - run: npm run lint
+      - uses: actions/upload-pages-artifact@v5
         with:
-          path: site
-      - uses: actions/deploy-pages@v4
+          path: apps/docs/out
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/configure-pages@v6
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.github/workflows/e2e.yml

@@ -19,7 +19,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 24
           cache: npm
       - run: npm ci
       - run: npm run build
@@ -28,4 +28,4 @@ jobs:
         if: always()
         with:
           name: testnet-journals
-          path: artifacts/
+          path: packages/agent-cli/artifacts/

.github/workflows/install.yml

@@ -13,7 +13,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 24
           cache: npm
       - uses: oven-sh/setup-bun@v2
       - run: npm ci

.github/workflows/release.yml

@@ -15,28 +15,28 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 24
           cache: npm
           registry-url: https://registry.npmjs.org
       - uses: oven-sh/setup-bun@v2
       - run: npm ci
       - name: Verify tag and package version
         if: startsWith(github.ref, 'refs/tags/')
-        run: node -e 'const p=require("./package.json");if(process.env.GITHUB_REF_NAME!==`v${p.version}`)throw Error("Tag/version mismatch")'
+        run: node -e 'const p=require("./packages/agent-cli/package.json");if(process.env.GITHUB_REF_NAME!==`v${p.version}`)throw Error("Tag/version mismatch")'
       - run: npm run build
       - run: npm run lint
       - run: npm run typecheck
       - run: npm test
       - run: npm run test:package
       - run: npm run build:binaries
-      - run: npm publish --provenance --access public
+      - run: npm publish --workspace @bloxwap/agent-cli --provenance --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
       - uses: softprops/action-gh-release@v2
         if: startsWith(github.ref, 'refs/tags/')
         with:
           generate_release_notes: true
           files: |
-            binaries/*
-            SKILL.md
-            CHANGELOG.md
+            packages/agent-cli/binaries/*
+            packages/agent-cli/SKILL.md
+            packages/agent-cli/CHANGELOG.md

.github/workflows/version.yml

@@ -11,7 +11,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 24
           cache: npm
       - run: npm ci
       - uses: changesets/action@v1

.gitignore

@@ -7,3 +7,9 @@ site/
 artifacts/
 .bloxwap/
 binaries/
+
+.next/
+.source/
+out/
+*.tsbuildinfo
+apps/docs/next-env.d.ts

.prettierignore

@@ -2,7 +2,10 @@ node_modules/
 dist/
 site/
 binaries/
-src/core/skill-content.ts
+.next/
+.source/
+out/
+packages/agent-cli/src/core/skill-content.ts
 docs/issues/
 docs/commands.md
-test/__snapshots__/
+packages/agent-cli/test/__snapshots__/

README.md

@@ -12,21 +12,22 @@ or current Bun. No postinstall script. Publishing is release-gated.
 ```sh
 npm ci
 npm run build
-node dist/cli.js --help
-node dist/cli.js config set privyAppId YOUR_APP_ID
-node dist/cli.js config set privyAppSecretRef env:BLOXWAP_PRIVY_APP_SECRET
+node packages/agent-cli/dist/cli.js --help
+node packages/agent-cli/dist/cli.js config set privyAppId YOUR_APP_ID
+node packages/agent-cli/dist/cli.js config set privyAppSecretRef env:BLOXWAP_PRIVY_APP_SECRET
 # Set BLOXWAP_PRIVY_APP_SECRET securely outside the CLI/conversation.
-node dist/cli.js init --network testnet --master-address 0xYOUR_MASTER_ADDRESS
+node packages/agent-cli/dist/cli.js init --network testnet --master-address 0xYOUR_MASTER_ADDRESS
 # Sign returned EIP-712 approval externally, then submit its 65-byte signature:
-node dist/cli.js init --network testnet --signature 0xYOUR_SIGNATURE
-node dist/cli.js fund --network testnet --amount 10 --origin-chain 42161
+node packages/agent-cli/dist/cli.js init --network testnet --signature 0xYOUR_SIGNATURE
+# Fund only with a supported test origin chain/token; inspect schema fund.
+# Chain 42161 and the default origin token are mainnet values.
 # Show QR/address and exact origin token/fees to user; complete any deposit steps.
-node dist/cli.js status --network testnet
+node packages/agent-cli/dist/cli.js status --network testnet
 # Continue only when active deposits report settled.
-node dist/cli.js run --network testnet --detach
-node dist/cli.js market --coin BTC
-node dist/cli.js order --json '{"coin":"BTC","side":"buy","size":"0.001","price":"20000","tif":"Gtc"}'
-node dist/cli.js events --follow
+node packages/agent-cli/dist/cli.js run --network testnet --detach
+node packages/agent-cli/dist/cli.js market --coin BTC
+node packages/agent-cli/dist/cli.js order --json '{"coin":"BTC","side":"buy","size":"0.001","price":"20000","tif":"Gtc"}'
+node packages/agent-cli/dist/cli.js events --follow
 ```
 
 Testnet onboarding/trades require Privy sandbox credentials, an externally signed
@@ -63,6 +64,24 @@ Override via `config set builder.address` / `config set builder.fee` or
 `npm run build`, `npm run lint`, `npm run typecheck`, `npm test` must pass before
 committing. Unit tests mock services. Credential-dependent tests are gated: `npm run test:sandbox` and `npm run test:e2e` skip without the required environment. The master-key testnet harness is CI-only; unit tests never access the network.
 
-`npm run docs:generate` creates [command schemas](docs/commands.md) and a static
-site in `site/`. [Docs index](docs/index.md), [security](docs/security.md),
-[error catalog](docs/errors.md), and [SKILL.md](SKILL.md) explain operation.
+The npm workspace keeps the publishable CLI in `packages/agent-cli` and the
+Fumadocs app in `apps/docs`. Use Node.js **24+** for repository development.
+The published CLI still supports Node.js **22.12+**.
+
+```sh
+npm ci
+npm run docs:dev       # http://localhost:3903/agent-cli/
+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
+from the CLI with `npm run docs:generate` and before docs builds.
+
+[Docs index](docs/index.md), [security](docs/security.md),
+[error catalog](docs/errors.md), and [SKILL.md](packages/agent-cli/SKILL.md) remain
+available as repository Markdown. See [docs app README](apps/docs/README.md).

apps/docs/AGENTS.md

@@ -0,0 +1,9 @@
+<!-- BEGIN:nextjs-agent-rules -->
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->

apps/docs/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

apps/docs/README.md

@@ -0,0 +1,48 @@
+# @bloxwap/agent-cli documentation
+
+Fumadocs + Next.js, statically exported for GitHub Pages. This npm workspace
+mirrors [`bloxwap/chart/apps/docs`](https://github.com/bloxwap/chart/tree/main/apps/docs) conventions and shares the Bloxwap brand
+used by the Hyperliquid docs. Docs dependencies stay out of the published CLI.
+
+From the repository root (Node.js 24+):
+
+```sh
+npm ci
+npm run docs:dev
+npm run docs:build
+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
+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.
+
+Edit MDX in `content/docs/` and sidebar order in `meta.json`. `commands.mdx` and
+`skill.mdx` are generated from the built CLI and packaged SKILL.md. Run
+`npm run docs:generate` after CLI changes. Dev/build also synchronize them;
+`docs:check` rejects stale generated content, checks sidebar/local MDX links,
+verifies HIG provenance, and checks Next.js/TypeScript types.
+
+Build output lives in `out/`. The postbuild checker validates local HTML links
+and assets, base-path containment, social metadata and 1200×630 PNG cards. Search
+uses a static `search.json` index in the browser. `llms.txt`, robots, and sitemap
+are generated for the configured deployment URL. The Pages workflow builds and
+checks PRs and deploys only main.
+
+The design mirrors Chart's dark surfaces, green accents, typography, navigation,
+footer, and HIG controls. `app/global.css`, `styles/hig.generated.css`, and
+`vendor/hig/` are copied from Chart, including the upstream license and provenance.
+`hig-tokens.mjs --check` verifies the pinned hashes and adapter; update vendor files
+from the upstream source rather than hand-editing generated tokens.
+
+Bloxwap Sans and Mono are self-hosted by `@bloxwap/[email protected]`. The social renderer
+uses local Bold/Black TTF instances; see `fonts/README.md` and the font license.
+Brand marks in `public/logos/` are supplied artwork, never typeset replacements.
+Every MDX page receives a static social card via `app/og/[...slug]/route.tsx`.
+
+The workspace pins `mdast-util-to-markdown` to Chart's 2.1.2: version 2.2.0
+changes attention handlers in a way incompatible with Fumadocs 16.15.14's
+stringifier (bold text recurses during structured search data generation).

apps/docs/app/docs/[[...slug]]/page.tsx

@@ -0,0 +1,33 @@
+import { notFound } from 'next/navigation';
+import { DocsBody, DocsDescription, DocsPage, DocsTitle, EditOnGitHub } from 'fumadocs-ui/layouts/docs/page';
+import { source } from '@/lib/source';
+import { getMDXComponents } from '@/mdx-components';
+import { repository } from '@/lib/site';
+import { socialImagePath, socialMetadata } from '@/lib/social';
+
+export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
+  const { slug } = await params;
+  const page = source.getPage(slug);
+  if (!page) notFound();
+  const MDX = page.data.body;
+  return <DocsPage toc={page.data.toc} footer={{ className: 'page-nav' }}>
+    <DocsTitle>{page.data.title}</DocsTitle>
+    <DocsDescription>{page.data.description}</DocsDescription>
+    <DocsBody><MDX components={getMDXComponents()} /></DocsBody>
+    <EditOnGitHub className="edit-on-github" href={`${repository}/blob/main/apps/docs/content/docs/${page.path}`} />
+  </DocsPage>;
+}
+
+export function generateStaticParams() { return source.generateParams(); }
+export async function generateMetadata({ params }: { params: Promise<{ slug?: string[] }> }) {
+  const page = source.getPage((await params).slug);
+  if (!page) notFound();
+  return {
+    title: page.data.title,
+    description: page.data.description,
+    ...socialMetadata({
+      title: page.data.title, description: page.data.description ?? '',
+      path: `${page.url}/`, imagePath: socialImagePath(page.slugs),
+    }),
+  };
+}

apps/docs/app/docs/layout.tsx

@@ -0,0 +1,16 @@
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import type { ReactNode } from 'react';
+import { ArrowUpRight } from 'lucide-react';
+import { organization } from '@/lib/structured-data';
+import { baseOptions } from '@/lib/layout.shared';
+import { source } from '@/lib/source';
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return <DocsLayout {...baseOptions()} tree={source.getPageTree()} sidebar={{
+    defaultOpenLevel: 1,
+    footer: <div className="docs-sidebar-footer">
+      <a href="https://bloxwap.app" className="docs-app-link">Open Bloxwap <ArrowUpRight className="size-4" aria-hidden="true" /></a>
+      <div className="docs-sidebar-links"><a href={organization.about}>About</a><a href={organization.contact}>Contact</a><a href={organization.privacy}>Privacy</a></div>
+    </div>,
+  }}>{children}</DocsLayout>;
+}