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.

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. 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.xyz, 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.