Architecture

The short version

There is one source of truth — a corpus of Markdown files in git — and everything else is generated from it or reads from it: the website in seven languages, the files for agents, the Ask Jenks assistant, the REST API, the MCP servers and the CLI.

The corpus

content/corpus/ holds one Markdown file per experience, project, community role and education entry, each with YAML frontmatter (dates, tags, role lenses, key results, skills, proof links) and a long-form body. Alongside them are the core profile, capabilities, credentials, talks, worldview, the role lenses and the assistant's skills. Facts were assembled from Jenks's résumés, LinkedIn, Linktree and his speaker page, with conflicts resolved conservatively.

Keeping the corpus in git means every change is a commit: reviewable, attributable and reversible.

The compiler

scripts/build-corpus.mjs reads the corpus, validates every file against one schema (scripts/corpus-schema.mjs) and compiles it into a single JSON corpus plus the agent files /llms-full.txt and /experience.json. Unknown tags or lenses, bad dates, missing images or a missing section stop the build. The admin API runs the same validation before it commits, so a bad edit — by a person or an AI — is refused before it can break anything.

Media

Photos, video clips and PDFs are not in git. They are uploaded through the admin interfaces to a Cloudflare R2 bucket shared by dev and production, and served by the Worker at /media/<year>/<month>/<name>-<fingerprint>.<ext> with year-long caching. Content refers to them by that path; the admin API checks every referenced file exists before it commits.

The website

The site is a Next.js static export served by Cloudflare Workers Static Assets. A small Worker in front of it handles redirects (jenksguo.com and www hosts → jenksguo.xyz), security headers and the APIs.

The site has two addresses that always show the same thing. https://jenksguo.pages.dev is the canonical one, on CVs and QR codes: company networks often block newly registered domains, and pages.dev is old and widely allowed. https://jenksguo.xyz is a mirror. The pages.dev address is a Cloudflare Pages project (mirror/) whose only code forwards every request to the site Worker, so one deploy updates both addresses and there is nothing to keep in sync. English lives at /; the other six languages at /zh, /zh-hant, /ja, /fr, /es and /eo. Every entry gets its own page in every language.

The Ask Jenks assistant

The assistant is a tool-using agent rather than a long prompt. Its system prompt holds only the core profile and a one-line index of every entry, lens and skill. When it needs detail it calls tools:

• load_skill — a playbook for the type of question (role fit, consulting scoping, AI transformation, STAR stories, governance, career navigation…),
• get_entries — full write-ups by slug,
• list_entries — filtered by tag, lens or kind,
• search_corpus — keyword search.

This progressive disclosure keeps answers grounded in the whole corpus without a huge prompt. Models are reached through OpenRouter.

One spec, four surfaces

src/spec.js defines every public and admin tool once: name, description, input schema, REST route and CLI command. From it come:

• the remote MCP servers (/mcp, /mcp/admin),
• the REST API (/api/v1/*, /api/admin/*),
• the jenks CLI and its local MCP mode (jenks mcp),
• the reference docs and /openapi.json.

Change a tool in one place and every surface follows, so the documentation cannot drift from the behaviour.

Publishing pipeline

Admin edits are commits made through the GitHub API. Each push runs CI:

1. compile and validate the corpus,
2. re-translate only the entries that changed into the six other languages (translations are cached by a hash of their English source; a fixed glossary sets headings and lens names),
3. build the site and the agent files,
4. deploy — main to https://jenksguo.pages.dev, dev to https://dev.jenksguo.xyz (not indexed).

CLI binaries for macOS, Linux and Windows are published under /downloads.

Why it is shaped like this

A personal site is small, but it is read by people, search engines and increasingly by agents, in several languages, and edited by an AI as often as by hand. A single validated source with generated surfaces is the simplest design that keeps all of those consistent.