diff --git a/CLAUDE.md b/CLAUDE.md index 28769d3..0fab3b3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,13 +6,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co Web properties for [fold](https://github.com/fold-run/fold), the enterprise MCP gateway. The gateway itself lives in fold-run/fold — that repo's README is the source of truth for features and configuration. Docs pages here **curate** that content, they don't fork it. -pnpm workspace (`apps/*`), Node >= 22, all apps deploy to Cloudflare Workers: +pnpm workspace (`apps/*` + `packages/*`), Node >= 22, all apps deploy to Cloudflare Workers: -- `apps/site` — marketing site at fold.run. Plain Astro, static-only build served via Workers Static Assets (worker `fold-site`). +- `apps/site` — marketing site at fold.run. Astro with `@astrojs/mdx` + `@astrojs/sitemap`, static-only, served via Workers Static Assets (worker `fold-site`). Blog posts and changelog entries are **content collections** in `src/content/{blog,changelog}` (schemas in `src/content.config.ts`), not hand-written pages: the blog index, `/rss.xml`, `/llms.txt` and the sitemap all render from them, so adding a post is one file. Routes beyond the landing page: `blog/[...slug].astro`, `changelog.astro`, `rss.xml.ts`, `llms.txt.ts`. - `apps/docs` — docs.fold.run. Astro + Starlight, with `starlight-llms-txt` emitting `/llms.txt` + `/llms-full.txt`. Static-only, no worker entrypoint (worker `fold-docs`). Content is markdown/MDX in `apps/docs/src/content/docs/`; the sidebar is defined in `apps/docs/astro.config.mjs` — new pages must be added there. - `apps/uptime` — cron Worker (`fold-uptime`, every 5 min) in a single file, `apps/uptime/src/index.ts`. HTTP checks on site and docs plus an MCP initialize round trip against the demo; state in one Durable Object (`UptimeMonitorDO`, SQLite-backed); `/status` serves a JSON snapshot (CORS-open, rendered by the site's `/status` page); optional `ALERT_WEBHOOK` secret gets a POST on up↔down transitions (down = 2 consecutive failures). Targets are the hardcoded `TARGETS` list; the DO prunes state for targets removed from that list. - `apps/demo` — demo.fold.run: the unmodified fold Go binary (image pinned in `apps/demo/Dockerfile`) in a **Cloudflare Container** behind worker `fold-demo`. A single named instance preserves fold's session-keyed clients; the federation config is inline in `apps/demo/src/index.ts` (`FOLD_CONFIG` env). Deploying needs local Docker running. - `apps/demo-tasks` — the demo's `jobs__*` upstream: a Go MCP task server (`main.go`, official MCP Go SDK — the only Go code in this repo) in a Cloudflare Container behind worker `fold-demo-tasks`. Mints tasks in the tool result's `_meta["task"]` (what fold's affinity pin reads) and serves `tasks/*` via the SDK's custom-method mechanism, mirroring fold's own pattern. Job state is in-memory and ephemeral by design. `pnpm --filter @fold-run/demo-tasks build` runs `go vet` + `tsc`. +- `packages/tokens` (`@fold-run/tokens`) — the single home for design token values (`src/vars.css`) and the self-hosted `@font-face` block (`src/fonts.css`). Both origins import it: `apps/site` in `Base.astro`, `apps/docs` in `src/styles/fold.css`, which maps the tokens onto Starlight's `--sl-*` variables rather than restating hexes. **Change a colour here, not in an app.** The `.woff2` binaries stay in each app's `public/fonts/` because the two sites are separate origins; only the declarations are shared. The docs light ramp is deliberately local to `fold.css`: it is hand-tuned rather than a mirror of the dark ramp. ## Commands @@ -45,3 +46,8 @@ Custom domains are attached via `custom_domain: true` routes in each `wrangler.j - Shared tooling versions (typescript, biome, wrangler, workers-types) come from the pnpm catalog in `pnpm-workspace.yaml` — reference them as `"catalog:"` in app package.json files. - Biome formats and lints: 2-space indent, 100-char lines, single quotes, trailing commas. `noExplicitAny` is an error; non-null assertions are allowed. - Docs use `.mdx` where components are needed; `remark-gfm` is wired into the MDX pipeline in `astro.config.mjs` because Astro doesn't apply GFM to `.mdx` by default (markdown tables would render as literal pipes). +- Site CSS is layered: `@fold-run/tokens` (values) → `src/styles/base.css` (document defaults) → `primitives.css` (the shared class vocabulary: `.wrap`, `.btn`, `.chip`, `.code-panel`, `.closing`) → `chrome.css` (header, mega menu, footer). Page-specific section styles stay in the page. Note the cascade: **`primitives.css` outranks a page's own `