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.
Our own prose called the analytics store by the upstream's name — "ClickHouse-
powered analytics", boxes labelled ClickHouse in every architecture diagram,
"Hanzo Datastore (ClickHouse)". That now says Datastore.
The line held: a name a reader must type or resolve EXACTLY is a value, not
branding, and renaming it makes the docs wrong. So these stay — the Go module
path, the pip package and the Rust crate, the OTEL exporter component names,
the DSN scheme, /var/lib/clickhouse, the server image's own CLICKHOUSE_USER and
CLICKHOUSE_PASSWORD, and every "Apache-2.0 ClickHouse fork", which is
attribution the licence requires.
Substituting blind produced nonsense the first time — "a Datastore-compatible
engine", "Hanzo Datastore (Datastore)" — so where the vendor carried the fact,
the sentence states the fact instead: Datastore speaks SQL over HTTP on 8123 and
a native binary protocol on 9000, and standard OLAP drivers for either wire
connect without a shim. Box art keeps its width; the borders still line up.
Three things the debrand turned up, each fixed:
commerce reads DATASTORE_URL and nothing else (commerce.go:165), yet the docs
told readers to set CLICKHOUSE_URL, CLICKHOUSE_DATABASE, CLICKHOUSE_USER and
CLICKHOUSE_PASSWORD — and gave http://…:8123 where the code wants the native
DSN on 9000. One DSN now, carrying host, credentials and database.
`kubectl port-forward svc/clickhouse` names a service that does not exist. The
cluster has datastore, hanzo-datastore and insights-datastore.
projects/ mirrored repos that 404 — clickhouse-go, clickhouse-go-mock and
datastore-orm all moved to hanzo-ds, so those pages mirrored nothing and could
not regenerate. Gone, with the nav entries that pointed at them, and the dead
hanzoai/infi.clickhouse_orm entry out of projects.json.
apps/spec is generated from hanzoai/hips and is not fixable here.
`@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]>
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).
zooqueen
zeekayandHanzo Dev