diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..238418e --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,38 @@ +# Docs and Trust Center CI: typecheck, unit tests (content, llms, search, MCP, proxy) and a production build. No secrets. +name: docs + +on: + pull_request: + paths: ['apps/docs/**', 'docs/openapi.json', '.github/workflows/docs.yml'] + push: + branches: [main] + paths: ['apps/docs/**', 'docs/openapi.json', '.github/workflows/docs.yml'] + +concurrency: + group: docs-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + build: + runs-on: ubuntu-latest + timeout-minutes: 15 + defaults: + run: + working-directory: apps/docs + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 24.22.1 + - uses: oven-sh/setup-bun@v2 + with: + bun-version: 1.3.9 + - run: bun install --frozen-lockfile + - run: bun run typecheck + - run: bun run test + - run: bun run build + env: + NEXT_TELEMETRY_DISABLED: '1' diff --git a/CLAUDE.md b/CLAUDE.md index 2ce8290..edcf00f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -46,6 +46,7 @@ HelloNear is an AI agent persona platform on NEAR, built for NEAR HACKATHON (1 | `apps/be` | Backend API, Postgres + pgvector, NEP-413 login, OutLayer + Composio | James | | `engine` | AI engine (Mastra + NEAR AI Cloud) | Axel | | `sc` | Mind registry contract (Rust `near-sdk`) | Axel | +| `apps/docs` | Docs site (docs.hellonear.xyz) and Trust Center (trust.hellonear.xyz), with llms.txt, Markdown export and an MCP server; Vercel | Axel | | `docs` | Shared technical docs, incl. `api-contract.md` | James + Axel | | `design` | Design tokens, screens, Mind characters (`hellonear.pen`, pen.dev) | Nabil | | `deploy` | Hosted demo: systemd units + `deploy.sh` for one Proxmox LXC, and the automatic deploy after a merge (`deploy/autodeploy/`) (#22) | James | @@ -72,6 +73,7 @@ Each folder has its own workflow in `.github/workflows/`. It runs on pull reques | `fe` | `apps/fe` | lint, typecheck, `next build` | | `sc` | `sc` | unit tests, sandbox tests (incl. upgrades from the fixtures), clippy | | `landing` | `apps/landing` | typecheck, `next build` | +| `docs` | `apps/docs` (and `docs/openapi.json`) | typecheck, unit tests, `next build` | | `status` | `apps/status` | typecheck, unit tests, `next build` | CI does not replace the local integration and load tests required by the rules below. Nothing deploys from CI itself. A merged `main` is deployed to the hosted demo after its CI passes, by a poller on James's always-on LAN machine that comments the result on the merged PR (rule 3, `deploy/README.md`). diff --git a/apps/docs/.gitignore b/apps/docs/.gitignore new file mode 100644 index 0000000..ecf83ec --- /dev/null +++ b/apps/docs/.gitignore @@ -0,0 +1,6 @@ +tsconfig.tsbuildinfo +.vercel +.env* +lib/generated/ +public/openapi.json +public/swagger/ diff --git a/apps/docs/AGENTS.md b/apps/docs/AGENTS.md new file mode 100644 index 0000000..af3b7c8 --- /dev/null +++ b/apps/docs/AGENTS.md @@ -0,0 +1,9 @@ + + +## 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. + + diff --git a/apps/docs/CLAUDE.md b/apps/docs/CLAUDE.md new file mode 100644 index 0000000..b2ea2e5 --- /dev/null +++ b/apps/docs/CLAUDE.md @@ -0,0 +1,37 @@ +# CLAUDE.md — apps/docs + +The docs site, **docs.hellonear.xyz**, and the Trust Center, **trust.hellonear.xyz**: one Next.js app, one Vercel project (`hellonear-docs`). Built 13 Nov 2026. Owner: Axel. Root rules in `/CLAUDE.md` also apply. + +**Update this file in the same PR whenever you change setup, commands, routes, content rules or where it is deployed.** + +## How it works + +- **One source:** every page is a Markdown file in `content/` (frontmatter `title`, `description`). `scripts/build-content.mjs` turns them into `lib/generated/pages.json` (gitignored; runs before `dev`, `build`, `typecheck` and `test`) and copies `../../docs/openapi.json` to `public/openapi.json` and Swagger UI to `public/swagger/` (both gitignored). The HTML pages, the `.md` export, `/llms.txt`, `/llms-full.txt` and the MCP tools all read that JSON, so nothing reads files at request time. The build fails on an en or em dash. +- **Content is true to the repo.** Most pages were sliced from `README.md` and `docs/api-contract.md` §3 on 13 Nov (README images stripped, relative links pointed at GitHub); they do not update by themselves, so change the page when the README section changes. Never invent features, numbers or claims; link proof (tx, report, file) where you can. +- **Sidebar order** is `lib/nav.ts`. A test fails if a page in `content/` is missing from it or listed twice; the trust pages are the `TRUST_TABS`. +- **Routes:** `app/(docs)/[[...slug]]` (docs pages; `api-reference` adds Swagger UI from `/openapi.json`, client-only: `swagger-ui-dist`'s prebuilt bundle copied to `public/swagger/` by the content script and loaded with `next/script`, because swagger-ui-react bundled by Turbopack throws `OpenApi3_1Element.refract is not a function` and an opened operation never loads), `app/trust` (Trust Center: Overview, `resources`, `subprocessors`, `faq`, `updates`, each built from its Markdown by heading: `###` sections become cards, FAQ `##` categories and `###` questions become `
`), `app/md/[[...slug]]` (Markdown), `app/llms.txt`, `app/llms-full.txt`, `app/skill.md` (`lib/skill.ts`, an Agent Skill), `app/mcp` and `app/.well-known/mcp`. +- **`proxy.ts`** (Next 16's middleware): `/.md` and requests that prefer `Accept: text/markdown` are served from `/md/`; on a `trust.*` host, `/`, `/resources`, `/subprocessors`, `/faq` and `/updates` are served from `/trust/...`. `next.config.ts` adds `Link: ; rel="llms-txt"` to every response. +- **MCP** (`lib/mcp.ts`): stateless Streamable HTTP, one JSON-RPC message per POST, JSON answers, no sessions. `initialize`, `ping`, `tools/list`, `tools/call` with `search_docs` (`search()` in `lib/content.ts`: keyword scoring, title > description > body) and `read_page`. Read-only, CORS `*`; GET answers 405. +- **Trust Center rules (Axel, 13 Nov):** no compliance badges or certifications (HelloNear has none), no "audit" as a claim, no team members' names, no emoji. Every "Yes" in the scope table links to its proof; "N/A" where a control does not apply. Updates only for what git log or the README proves. +- Styles: plain CSS (`app/globals.css`) with the web app's Stone & Lime tokens, light and dark by `prefers-color-scheme`. Sidebar on desktop, a `
` menu on phones (no JavaScript needed), 16px gutters, no horizontal scroll (checked at 390 px). + +## Commands + +```sh +bun install +bun run dev # http://localhost:3300 +bun run typecheck +bun run test # node:test: content, nav, links, llms, search, markdown, proxy, MCP +bun run build +``` + +Try the MCP server locally: + +```sh +curl -s localhost:3300/mcp -H 'content-type: application/json' \ + -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"daily limit"}}}' +``` + +## Deploy + +On **Vercel**, project `hellonear-docs` (created 13 Nov), deployed by Axel with the Vercel CLI from this folder. **Build locally and upload the result** (`vercel build --prod` then `vercel deploy --prebuilt --prod`): the content script copies `../../docs/openapi.json`, which a plain `vercel deploy` from this folder does not upload, so a remote build fails with ENOENT. Domains on the project: `docs.hellonear.xyz` and `trust.hellonear.xyz`, each a `CNAME` in the `hellonear.xyz` Cloudflare zone to the target Vercel gives (DNS only, not proxied). The DNS change is on the box owner's side (James), with Axel's approval. No env vars. diff --git a/apps/docs/app/(docs)/[[...slug]]/page.tsx b/apps/docs/app/(docs)/[[...slug]]/page.tsx new file mode 100644 index 0000000..1b6bcbb --- /dev/null +++ b/apps/docs/app/(docs)/[[...slug]]/page.tsx @@ -0,0 +1,69 @@ +import type { Metadata } from "next"; +import Link from "next/link"; +import { notFound } from "next/navigation"; +import { getPage, markdownUrl, orderedSections, pages } from "@/lib/content"; +import { render } from "@/lib/markdown"; +import { REPO_URL } from "@/lib/site"; +import { NavList } from "../../_components/Sidebar"; +import { Swagger } from "../../_components/Swagger"; + +type Props = { params: Promise<{ slug?: string[] }> }; + +export const dynamicParams = false; + +export function generateStaticParams() { + return pages.filter((p) => !p.slug.startsWith("trust")).map((p) => ({ slug: p.slug ? p.slug.split("/") : [] })); +} + +async function pageOf(props: Props) { + const { slug } = await props.params; + const page = getPage((slug ?? []).join("/")); + if (!page || page.slug.startsWith("trust")) notFound(); + return page; +} + +export async function generateMetadata(props: Props): Promise { + const page = await pageOf(props); + return { + title: page.slug ? page.title : { absolute: "HelloNear Docs" }, + description: page.description, + alternates: { canonical: `/${page.slug}`, types: { "text/markdown": markdownUrl(page.slug) } }, + }; +} + +export default async function DocPage(props: Props) { + const page = await pageOf(props); + const flat = orderedSections().flatMap((s) => s.pages).filter((p) => !p.slug.startsWith("trust")); + const i = flat.findIndex((p) => p.slug === page.slug); + const prev = flat[i - 1]; + const next = flat[i + 1]; + return ( +
+ +
+ Menu + +
+
+
+

{orderedSections().find((s) => s.pages.some((p) => p.slug === page.slug))?.title}

+

{page.title}

+

{page.description}

+
+ {page.slug === "api-reference" && } +
+ +
+
+ ); +} diff --git a/apps/docs/app/(docs)/layout.tsx b/apps/docs/app/(docs)/layout.tsx new file mode 100644 index 0000000..b8e6e2f --- /dev/null +++ b/apps/docs/app/(docs)/layout.tsx @@ -0,0 +1,19 @@ +import Link from "next/link"; +import { Brand } from "../_components/Brand"; +import { REPO_URL, STATUS_URL } from "@/lib/site"; + +export default function DocsLayout({ children }: { children: React.ReactNode }) { + return ( + <> +
+ +
+ Trust + Status + GitHub +
+
+ {children} + + ); +} diff --git a/apps/docs/app/.well-known/mcp/route.ts b/apps/docs/app/.well-known/mcp/route.ts new file mode 100644 index 0000000..cad812b --- /dev/null +++ b/apps/docs/app/.well-known/mcp/route.ts @@ -0,0 +1,23 @@ +import { SERVER_INFO, TOOLS } from "@/lib/mcp"; +import { SITE_URL } from "@/lib/site"; + +export const dynamic = "force-static"; + +// Discovery for agents that look for an MCP server at a well-known path. +export const GET = () => + Response.json( + { + servers: [ + { + name: SERVER_INFO.name, + title: SERVER_INFO.title, + description: "Read-only search and reading of the HelloNear docs and Trust Center.", + url: `${SITE_URL}/mcp`, + transport: "streamable-http", + authentication: "none", + tools: TOOLS.map((t) => ({ name: t.name, description: t.description })), + }, + ], + }, + { headers: { "access-control-allow-origin": "*" } }, + ); diff --git a/apps/docs/app/_components/Brand.tsx b/apps/docs/app/_components/Brand.tsx new file mode 100644 index 0000000..522f022 --- /dev/null +++ b/apps/docs/app/_components/Brand.tsx @@ -0,0 +1,13 @@ +import Link from "next/link"; + +export function Brand({ href, label }: { href: string; label: string }) { + return ( + + {/* eslint-disable-next-line @next/next/no-img-element */} + + + HelloNear {label} + + + ); +} diff --git a/apps/docs/app/_components/Faq.tsx b/apps/docs/app/_components/Faq.tsx new file mode 100644 index 0000000..ddc4599 --- /dev/null +++ b/apps/docs/app/_components/Faq.tsx @@ -0,0 +1,31 @@ +"use client"; + +import { useEffect, useRef } from "react"; + +// Expand all / Collapse all for the FAQ's
, and open the one a #link points at. The answers are plain +//
, so they work without JavaScript. +export function FaqControls({ children }: { children: React.ReactNode }) { + const ref = useRef(null); + const setAll = (open: boolean) => ref.current?.querySelectorAll("details").forEach((d) => (d.open = open)); + useEffect(() => { + const openHash = () => { + const el = location.hash ? document.getElementById(decodeURIComponent(location.hash.slice(1))) : null; + if (el instanceof HTMLDetailsElement) { + el.open = true; + el.scrollIntoView({ block: "start" }); + } + }; + openHash(); + window.addEventListener("hashchange", openHash); + return () => window.removeEventListener("hashchange", openHash); + }, []); + return ( +
+
+ + +
+ {children} +
+ ); +} diff --git a/apps/docs/app/_components/Sidebar.tsx b/apps/docs/app/_components/Sidebar.tsx new file mode 100644 index 0000000..890cd8a --- /dev/null +++ b/apps/docs/app/_components/Sidebar.tsx @@ -0,0 +1,24 @@ +import Link from "next/link"; +import { orderedSections } from "@/lib/content"; + +// Server-rendered nav. On phones it sits inside a
menu, so it works without JavaScript. +export function NavList({ current }: { current: string }) { + return ( + + ); +} diff --git a/apps/docs/app/_components/Swagger.tsx b/apps/docs/app/_components/Swagger.tsx new file mode 100644 index 0000000..4d54f87 --- /dev/null +++ b/apps/docs/app/_components/Swagger.tsx @@ -0,0 +1,37 @@ +"use client"; + +import Script from "next/script"; +import { useEffect, useRef, useState } from "react"; + +type SwaggerBundle = (options: Record) => unknown; +declare global { + interface Window { + SwaggerUIBundle?: SwaggerBundle; + } +} + +// Swagger UI only runs in the browser; the prose above it is server-rendered and readable without JavaScript. +// It loads swagger-ui-dist's prebuilt bundle from /swagger (copied by scripts/build-content.mjs), not through the +// bundler: Turbopack breaks swagger-ui-react's OpenAPI resolver, so an opened operation never finished loading. +export function Swagger({ url }: { url: string }) { + const node = useRef(null); + const [ready, setReady] = useState(false); + + useEffect(() => { + if (window.SwaggerUIBundle) setReady(true); + }, []); + + useEffect(() => { + if (!ready || !node.current || !window.SwaggerUIBundle) return; + window.SwaggerUIBundle({ url, domNode: node.current, docExpansion: "list", defaultModelsExpandDepth: 0, tryItOutEnabled: false }); + }, [ready, url]); + + return ( +
+ +