Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -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'
2 changes: 2 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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`).
Expand Down
6 changes: 6 additions & 0 deletions apps/docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
tsconfig.tsbuildinfo
.vercel
.env*
lib/generated/
public/openapi.json
public/swagger/
9 changes: 9 additions & 0 deletions apps/docs/AGENTS.md
Original file line number Diff line number Diff line change
@@ -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 -->
37 changes: 37 additions & 0 deletions apps/docs/CLAUDE.md
Original file line number Diff line number Diff line change
@@ -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 `<details>`), `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): `/<path>.md` and requests that prefer `Accept: text/markdown` are served from `/md/<path>`; on a `trust.*` host, `/`, `/resources`, `/subprocessors`, `/faq` and `/updates` are served from `/trust/...`. `next.config.ts` adds `Link: </llms.txt>; 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 `<details>` 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.
69 changes: 69 additions & 0 deletions apps/docs/app/(docs)/[[...slug]]/page.tsx
Original file line number Diff line number Diff line change
@@ -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<Metadata> {
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 (
<div className="docs">
<aside className="sidebar">
<NavList current={page.slug} />
</aside>
<details className="mobile-nav">
<summary>Menu</summary>
<NavList current={page.slug} />
</details>
<main className="doc">
<article>
<p className="eyebrow">{orderedSections().find((s) => s.pages.some((p) => p.slug === page.slug))?.title}</p>
<h1>{page.title}</h1>
<p className="lede">{page.description}</p>
<div className="prose" dangerouslySetInnerHTML={{ __html: render(page.markdown) }} />
{page.slug === "api-reference" && <Swagger url="/openapi.json" />}
</article>
<footer className="doc-foot">
<div className="pager">
{prev ? <Link href={`/${prev.slug}`}>← {prev.title}</Link> : <span />}
{next ? <Link href={`/${next.slug}`}>{next.title} →</Link> : <span />}
</div>
<p className="muted small">
<a href={markdownUrl(page.slug)}>View as Markdown</a> · <a href={`${REPO_URL}/blob/main/apps/docs/content/${page.slug || "index"}.md`}>Edit on GitHub</a>
</p>
</footer>
</main>
</div>
);
}
19 changes: 19 additions & 0 deletions apps/docs/app/(docs)/layout.tsx
Original file line number Diff line number Diff line change
@@ -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 (
<>
<header className="topbar">
<Brand href="/" label="Docs" />
<div className="topbar-links">
<Link href="/trust">Trust</Link>
<a href={STATUS_URL}>Status</a>
<a href={REPO_URL}>GitHub</a>
</div>
</header>
{children}
</>
);
}
23 changes: 23 additions & 0 deletions apps/docs/app/.well-known/mcp/route.ts
Original file line number Diff line number Diff line change
@@ -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": "*" } },
);
13 changes: 13 additions & 0 deletions apps/docs/app/_components/Brand.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
import Link from "next/link";

export function Brand({ href, label }: { href: string; label: string }) {
return (
<Link href={href} className="brand">
{/* eslint-disable-next-line @next/next/no-img-element */}
<img src="/icon.svg" width={28} height={28} alt="" />
<span>
HelloNear <span className="brand-sub">{label}</span>
</span>
</Link>
);
}
31 changes: 31 additions & 0 deletions apps/docs/app/_components/Faq.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
"use client";

import { useEffect, useRef } from "react";

// Expand all / Collapse all for the FAQ's <details>, and open the one a #link points at. The answers are plain
// <details>, so they work without JavaScript.
export function FaqControls({ children }: { children: React.ReactNode }) {
const ref = useRef<HTMLDivElement>(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 (
<div ref={ref}>
<div className="faq-controls">
<button type="button" onClick={() => setAll(true)}>Expand all</button>
<button type="button" onClick={() => setAll(false)}>Collapse all</button>
</div>
{children}
</div>
);
}
24 changes: 24 additions & 0 deletions apps/docs/app/_components/Sidebar.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
import Link from "next/link";
import { orderedSections } from "@/lib/content";

// Server-rendered nav. On phones it sits inside a <details> menu, so it works without JavaScript.
export function NavList({ current }: { current: string }) {
return (
<nav aria-label="Docs">
{orderedSections().map((s) => (
<div key={s.title} className="nav-group">
<p className="nav-title">{s.title}</p>
<ul>
{s.pages.map((p) => (
<li key={p.slug}>
<Link href={`/${p.slug}`} aria-current={p.slug === current ? "page" : undefined}>
{p.slug === "trust" ? "Trust Center" : p.title}
</Link>
</li>
))}
</ul>
</div>
))}
</nav>
);
}
37 changes: 37 additions & 0 deletions apps/docs/app/_components/Swagger.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
"use client";

import Script from "next/script";
import { useEffect, useRef, useState } from "react";

type SwaggerBundle = (options: Record<string, unknown>) => 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<HTMLDivElement>(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 (
<section className="swagger" aria-label="OpenAPI reference">
<link rel="stylesheet" href="/swagger/swagger-ui.css" />
<Script src="/swagger/swagger-ui-bundle.js" strategy="afterInteractive" onReady={() => setReady(true)} />
{ready ? null : <p className="muted">Loading the API reference…</p>}
<div ref={node} />
</section>
);
}
20 changes: 20 additions & 0 deletions apps/docs/app/_components/TrustTabs.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
"use client";

import Link from "next/link";
import { usePathname } from "next/navigation";
import { TRUST_TABS } from "@/lib/nav";

export function TrustTabs() {
const path = usePathname().replace(/\/$/, "");
return (
<nav className="tabs" aria-label="Trust Center">
<div className="tabs-inner">
{TRUST_TABS.map((t) => (
<Link key={t.slug} href={`/${t.slug}`} aria-current={path === `/${t.slug}` || (t.slug === "trust" && path === "") ? "page" : undefined}>
{t.label}
</Link>
))}
</div>
</nav>
);
}
17 changes: 17 additions & 0 deletions apps/docs/app/_components/UpdateCard.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
import Link from "next/link";
import { render } from "@/lib/markdown";

export function UpdateCard({ title, body, id, short }: { title: string; body: string; id: string; short?: boolean }) {
const [meta, ...rest] = body.split("\n");
const [date, category] = meta.replace(/^Published /, "").split(" · ");
const text = rest.join("\n").trim();
return (
<article className="tcard update" id={id}>
<p className="update-meta">
<span className="tag">{category}</span> <span className="muted">Published {date}</span>
</p>
<h3>{short ? <Link href={`/trust/updates#${id}`}>{title}</Link> : title}</h3>
{!short && <div className="prose" dangerouslySetInnerHTML={{ __html: render(text) }} />}
</article>
);
}
Binary file added apps/docs/app/apple-icon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added apps/docs/app/favicon.ico
Binary file not shown.
Loading
Loading