The docs estate declared its typeface in 30 root layouts and one linked
stylesheet, each pulling a third-party family off a hosted font CDN on the
critical path of every route. Two of those surfaces also self-hosted the
faces, so the same bytes were vendored by hand in the repo.
@hanzo/font 1.8.8 is where Zen is authored. It is now mounted the way this
repo already mounts every other package stylesheet — `@import '@hanzo/font/css'`
at the top of the app's own sheet — which declares the @font-face rules and
publishes --font-zen-sans / --font-zen-mono. A single :root block per app binds
those to --font-sans / --font-mono, the pair every rule and every font-*
utility already read, so the variable contract is untouched and the next face
swap is two lines rather than a sweep. Genuine system fallbacks stay.
Mounting through the sheet rather than a JS side-effect import also drops the
untyped bare subpath TypeScript could not resolve, so no per-app declaration
shim is needed.
public/reference/ is static HTML with no bundler, so it keeps its own
@font-face; scripts/sync-reference-fonts.ts copies the two variable faces out
of the installed package on each build and the directory is ignored, the same
rule public/openapi/ already follows. The hand-vendored faces are deleted.
Also corrects the brand typography table, which still named a face Hanzo does
not ship, and the three sample configs and two skill pages that repeated it.
Measured across apps/*/content/**/meta.json: 76 separators, 2 with an
icon, 74 without. A bare "---Title---" renders as naked text between
icon-bearing rows, so the majority case looked like the broken one.
72 of 76 now carry one. The remaining 4 are in
content/docs/projects/hanzoai/python-sdk/, which is gitignored upstream
content mirrored by scripts/sync-project-docs.ts — this repo's rule for
ported docs is "port, don't re-author", and an edit there is overwritten
on the next sync anyway.
11 of the 72 could not be fixed by editing the file. services/meta.json
is REGENERATED from the @hanzo/products catalog on every build:pre, so a
hand-added icon survives until the next build and no further. The map
lives in the generator instead. It lives there and not in @hanzo/products
because the catalog owns the taxonomy while how a category is DRAWN is a
docs concern; putting it upstream leaks presentation into the product
catalog. A category with no entry now warns by name rather than quietly
shipping a bare separator again.
One vocabulary, reused on purpose: the same idea takes the same mark
everywhere (Getting Started/Setup -> Rocket, Commands -> Terminal,
Reference -> BookOpen, Security -> ShieldCheck, ...). Every name is a
verified lucide export; an unknown one would not fail the build, it would
warn and render nothing, which is the state this commit removes.
Co-authored-by: Hanzo Dev <[email protected]>
`@hanzo/docs-mdx` writes the collection modules to its outDir, `.docs/`.
Nothing read them there. Apps read a committed `docs/` copy instead, reached
three different ways:
13 apps `@hanzo/mdx:collections/server` + a webpack alias -> ./docs/*.ts
3 apps `@/docs/server`, straight into the committed copy
2 apps the alias, with no committed copy at all
The two with no copy — bootnode-docs and tasks-docs — could not build:
./lib/source.tsx
Module not found: Can't resolve '@hanzo/mdx:collections/server'
and four more built from a copy that no longer matched the content beside it:
./docs/server.ts
Module not found: Can't resolve
'../content/docs/reference/templates/USER.mdx?collection=docs&only=frontmatter'
That is what committing generated code buys: the build reads a snapshot of
the content rather than the content.
One name, one location, every app: `@hanzo/mdx:collections/*`, resolved to
`.docs/` — the generator's own output, rewritten on every build, gitignored.
`tsconfig` gains the matching `paths` entry so the specifier type-checks
instead of relying on `ignoreBuildErrors`; apps/docs stops overriding outDir
in both `next.config.mts` and `gen:collections`; turbo caches `.docs/**`. The
16 committed mirrors are deleted. Examples already did it this way.
`.source` goes with them — this fork's outDir has been `.docs` for a while,
leaving `.source` in the vite plugin's JSDoc, an example's import map, an
oxlint ignore and `.gitignore` pointing at a directory nothing writes.
Also declares in `globalEnv` the env vars the build scripts actually read
(HANZO_DOCS_SYNC, HIPS_REPO_DIR, DOCS_SECTION, the search vars...). Turbo
does not forward undeclared vars, so `HANZO_DOCS_SYNC=0 turbo run build` had
no effect on the sync it names.
turbo run build --filter='./apps/*' --continue
before Tasks: 33 successful, 40 total
Failed: bootnode-docs, docs, engine-docs, ml-docs, router-docs,
spec, tasks-docs
after Tasks: 38 successful, 40 total
Failed: docs, spec (both for unrelated reasons, fixed next)
(cherry picked from commit 3d11394b092530489b60931e46b4938a88a2bdd5)
Co-authored-by: Hanzo Dev <[email protected]>
apps/docs imported the same component library under three names — 11 files
from `@hanzo/docs/ui/*` (a pure re-export shell), 10 from `@hanzo/docs-ui`
(the Radix fork), plus 5 hand-copied shadcn files under components/ui.
All of it now resolves to `@hanzo/docs-base-ui`.
The 5 local copies are deleted. badge, hover-card, select and the container
card move into base-ui on `@base-ui/react` — preview-card is the hover-card
analog and Select.Value already takes `placeholder`, so the swap is 1:1 and
introduces no Radix. buttonVariants gains `xs`/`md`/`lg` and `link`, purely
additive, so no existing caller changes. Three Radix packages leave
apps/docs; `presence` and `tooltip` stay because non-shadcn code uses them.
global.css now takes base-ui's preset rather than the Radix fork's. The two
are not duplicates: `neutral.css` defines the colours, `preset.css` carries
base styles plus the `@source inline` safelists. Only `default-colors.css`
declares a `--color-fd-*` value, and it is byte-identical across both forks,
so no colour moves.
`types:check` never ran. pnpm installs the mdx bin scope-stripped as
`docs-mdx`, so `@hanzo/docs-mdx &&` died at `sh: no such file` and took
`tsc` with it — silently, in every app, for `lint` too. Fixed in all 32
scripts. apps/docs reports 107 first-party errors; that is the real number,
unchanged by this commit.
Also unbreaks two undefined references in openapi's server entry that a
large upstream merge left behind: PlaygroundAuthProvider was used but never
imported, and pickSchema/encodeInternalRef were orphaned utilities. Both
crashed the docs export. More remain in that package (renderResponse is a
missing function, not an import) — noted, not guessed at.
Co-authored-by: Hanzo Dev <[email protected]>
Three things the workspace disagreed with itself about.
Versions. apps/docs ran ahead on next 16.2.6 / react 19.2.6 / TS 6, the other
21 apps trailed on next 16.1.6 / react 19.2.3 / TS 5.9.3, and the packages sat
somewhere between with five different @types/react pins. Everything is now on
the newest patch of the line it was already on — react 19.2.8, next 16.2.12,
@types/react 19.2.18, @types/react-dom 19.2.4 — and the TS-5 stragglers join
the TS 6.0.3 the root and every package already used. No majors were invented:
6.0.3 IS the top of the 6.x line, and TS 7 is blocked because [email protected]
declares `typescript: ^5.5.0 || ^6.0.0`.
The duplicate key. next.config.mts declared `transpilePackages` twice in one
object literal, so the later list won and @hanzogui/shell and @hanzo/brand had
never been transpiled — the comment explaining why they must be outlived the
setting it described. tsc had been reporting this the whole time as
next.config.mts(193,3) TS1117; the app's `types:check` never reaches tsc (its
script starts with a bare `@hanzo/docs-mdx`, which is not the bin's name and
fails immediately), so nobody saw it. One list now, both groups in it.
Dead weight. Twelve packages apps/docs declared and no file, config, script or
browserslist field referenced: @radix-ui/react-dialog, @floating-ui/react-dom,
@mixedbread/sdk, @orama/orama, openapi-sampler, react-remove-scroll,
algoliasearch, gray-matter, tinyexec, tinyglobby, @types/three (types for a
package that isn't installed) and shadcn (no components.json exists anywhere in
the repo, so the CLI was never initialized). The ones that are real
dependencies of packages/openapi, packages/core and packages/cli keep their own
copies — pnpm's node_modules is isolated, so nothing lost a resolution.
@orama/core stays: apps/docs/app/static.json/route.ts pulls OramaDocument
through @hanzo/docs-core/search/orama-cloud, which types against it.
Verified against a clean worktree at HEAD, since the working tree carries
gigabytes of untracked synced project docs that CI never checks out:
turbo build, apps + packages 43/52 before, 43/52 after, same 9 failures
docs export 1764 html pages, byte-identical page count
deploy.yml gate index/docs/services present, /docs has nav
tsc --noEmit in apps/docs 325 errors before, 324 after (the TS1117)
vitest 169 passed / 13 failed, both sides
The 9 build failures and 13 test failures are unchanged from HEAD and none are
version-related: 7 sibling apps cannot resolve @hanzo/mdx:collections/server
under `next build --webpack`, zen-docs has a committed docs/server.ts importing
a deleted zen5-coder-flash.mdx, and packages/preview cannot resolve its own
@/lib/source alias under waku/vite.
Co-authored-by: Hanzo Dev <[email protected]>
The <script src="analytics.hanzo.ai/script.js" data-website-id> tag is a shim:
it talks to a read LENS instead of the one ingestion front door, so a docs site
could only ever produce pageviews — no errors, no product events, and a separate
per-site id to keep in sync. Replaced across all 12 sites with @hanzo/event
POSTing api.hanzo.ai/v1/event, which Cloud fans server-side into the web
(analytics), product (insights) and error (sentry) lenses. `product` is the only
per-site knob; Cloud resolves the tenant, so no site carries an id any more.
One implementation, not twelve: packages/analytics (@hanzo/docs-analytics)
mounts the provider, adds a pageview per client-side route change, and honors
Global Privacy Control / Do-Not-Track by disabling the client outright. The main
hub's inline Insights snippet goes too — that lens is already fed by the one
stream.
Co-authored-by: Hanzo Dev <[email protected]>
Follow-up to 903b1c38: the package-name normalization covered JS/TS imports +
package.json but missed four other surfaces that name the same phantom packages,
relocating the breakage from 'pnpm install' to 'next/vite/astro build':
- H1: 46 CSS @import strings (@hanzo/docs-{base-ui,ui,openapi}/css/*) → real pkgs
(preserved legit @hanzo/docs-{twoslash,story} CSS)
- H2: examples/astro .astro imports (base-ui/mdx→fumadocs-ui/mdx, docs-core/toc→fumadocs-core/toc)
- L1: .changeset/config.json fixed-array lockstep names
- L2: removed apps/docs/next.config.mts dead phantom→phantom self-alias + dup keys
Found by adversarial red review of 903b1c38.
The fumadocs-fork rebrand left ~13 apps + examples referencing packages under
names that don't exist in the workspace (in BOTH directions: some kept
fumadocs-*, some became @hanzo/docs-*). pnpm install failed outright. Mapped
every reference (deps + imports, 607 source + 61 package.json) to the package
that actually exists, by suffix:
@hanzo/docs-{core,mdx,ui,base-ui} → fumadocs-{core,mdx,ui} / @fumadocs/base-ui
@fumadocs/{story,cli,mdx-remote,tailwind} → @hanzo/docs-{story,cli,...}
fumadocs-{docgen,epub,twoslash,typescript} → @hanzo/docs-{...}
drop phantom eslint-config-custom
Guarded @hanzo/docs-mdx vs -mdx-remote. Also fixes a pre-existing cli bug
(createConfigSchema referenced undefined isSrc) that blocked the package build.
Verified: pnpm install resolves clean (46.8s, was broken); package dist
regenerates phantom-free from the corrected source (hanzo-docs 430→0). Full
app build-green is blocked only by a node v26 toolchain bug in fumadocs-mdx's
config loader (repo targets node >=24.14; CI node builds it).
MDX collection generation is already handled by createMDX() plugin
in next.config.ts. The npx CLI call fails on CI because tsdown
bundles @hanzo/docs-mdx with external deps that aren't resolved
in the CI environment.
Wire project docs sync into pre-build step, add comprehensive dark theme
CSS variables, integrate ProjectSwitcher into sidebar, and add custom
Cloudflare Pages deployment script with batched uploads and retry logic.
dev-docs dev server requires --webpack flag (Turbopack doesn't support webpack aliases).
Renamed "Fumadocs" card titles to "Hanzo Docs" in template content.
- Remove invalid Card component imports (provided globally by MDX)
- Replace bare < symbols with text equivalents to prevent JSX parsing
- Change unsupported capnp code fence to text
zooqueen
zeekayandHanzo Dev