sigaoli.com

Personal website of Sigao Li — AI Product Manager · Spatial Data Scientist. From maps to models, and the products in between.

Bilingual (English at /, 中文 at /zh/), built with Astro + Tailwind CSS v4 + GSAP, deployed to GitHub Pages via GitHub Actions. Launched 2026-06-11, replacing the previous Jekyll (academicpages) site.

Highlights

• Generative canvas effects on a map motif — an interactive particle field (home), contour terrain (work), a "river as timeline" with a flow field (CV), and a geo-network arc map (photography); all vanilla canvas/SVG, tuned to 60fps with reduced-motion and mobile fallbacks
• Dotted world map — land sampled from Natural Earth, with 79 GPS-extracted photo footprints across 6 countries; click a marker to open that country's gallery
• Zoe, the digital doorcat — Sigao's cat (驺虞) lives in the corner of every page as a set of AI-generated, chroma-keyed VP9-alpha video clips pinned to shared anchor poses, driven by a state machine: she dozes off when ignored, reacts to page switches, listens while you type, "types back" while the assistant streams, and keeps a few easter eggs (production handbook in docs/)
• Built-in AI layer — a floating chat assistant (fronted by Zoe) on every page — it suggests the single most relevant page as you ask, and greets a returning visitor by name (stored only in their own browser, opt-in) — plus a personal MCP server, both fed by a build-time knowledge pack generated from the same sources as the pages (see below)
• Machine-readable by design — /llms.txt, /llms-full.txt, /resume.json (JSON Resume), /knowledge.json, /.well-known/mcp.json, JSON-LD, and a robots.txt that explicitly welcomes AI crawlers
• Photographs file themselves — drop the full-resolution originals into _inbox/ and commit. A pre-commit hook works out the country from the coordinates against Natural Earth polygons, archives the originals outside git, derives 2560px masters with the EXIF stripped, asks a vision model for the bilingual caption, and registers everything in photos.json — the map, the counts and the assistant's knowledge all follow from there
• Either language pulls the other along — edit the Chinese or the English and commit. The hook works out which side moved and asks a model whether the edit actually changed what the other side must say. Polishing one language leaves the other alone; a changed fact is revised rather than rewritten, so hand-picked wording survives. Editing both in one commit counts as already handled by hand
• Lighthouse (mobile): 96–100 across all categories; zero cookies, no paid services, and a plain-language privacy notice at /privacy

Commands

Command	Action
npm run dev	Dev server at localhost:4321 (Astro 7 runs it as a daemon — stop with npx astro dev stop)
npm run build	Production build to dist/
npm run preview	Serve the production build locally
npm test	Unit tests for both hook pipelines (node --test, no extra dependencies)
npm run ingest	Photo ingest by hand. Normally the pre-commit hook runs it; useful for watching what it does
npm run sync	Bilingual sync by hand. Same — the hook runs it, this is for watching
node scripts/check-links.mjs	Internal link integrity check over dist/
node scripts/verify-nav.mjs 等	Playwright interaction suites (run against a local server)
npm run dev (in worker/)	Chat + MCP Worker at localhost:8787 (wrangler; secrets in worker/.dev.vars, never committed)
node scripts/verify-chat.mjs	E2E chat-widget test (needs both dev servers running)
node scripts/verify-zoe.mjs	E2E for Zoe's action state machine (append ?zoe-fast locally to compress minute-scale timers)
node scripts/verify-typeroute.mjs	E2E for the intent-driven typing clip and the bilingual 404 page

Any Playwright suite that waits on Zoe's state must pin the clock (Date.prototype.getHours = () => 14): between 23:00 and 06:00 she starts the session asleep, so state never reaches idle and the run just times out.

When adding a Zoe clip, decide who prewarms it and when at the same time. A clip that is only fetched at playback stalls on a slow connection, and the stage shows nothing until it decodes. Prewarming has been missed three times already. Note warm() takes the file name (sit-to-loaf), not the ZOE key (sitToLoaf).

The chat panel is rebuilt on every navigation — transition:persist keeps Zoe's stage, not the panel. Anything that lives only in panel DOM is gone the moment a visitor clicks a link. The streaming reply, the guidance chip and the unsent draft each had to be given module state plus a path back through paint(); the chip was lost for weeks before anyone noticed. So when adding persistent UI here, answer two questions up front: how does paint() rebuild it, and should it ride along in sessionStorage with the history? Measure geometry only once the panel is visible — scrollHeight is 0 while it is hidden, which silently writes height: 0px.

Turnstile guards /chat and /classify. It must never guard /mcp. That endpoint exists so machines can read Sigao's profile — it is in the official registry — and Turnstile exists to stop machines. It also costs nothing to serve: the tools read the knowledge pack and never call a model. The static outlets (llms.txt, knowledge.json, .well-known/mcp.json) are served by Pages and never reach the Worker at all.

Locally, Turnstile uses Cloudflare's always-pass test keys — sitekey in site.ts behind import.meta.env.DEV, secret in worker/.dev.vars. The real key rejects headless browsers, which is exactly its job, so every suite that drives a real Worker would fail against it. The real secret exists only in production, set with wrangler secret put. A corollary worth remembering: the production happy path cannot be verified from a script — reaching it needs a human in a real browser. Automation can still prove the gate is up (a request with no credential must return 403).

src/
├── pages/            # en routes + zh/ mirrors; llms.txt / resume.json / knowledge.json endpoints
├── components/       # Nav, Hero, WorldMap, Lightbox, CommandK, ChatWidget …
│   └── pages/        # shared page bodies rendered by both locales
├── content/          # cases & research (en) + cases-zh & research-zh (generated, reviewed)
├── data/             # cv.json / cv.zh.json / photos.json (GPS + bilingual alts)
│   └── knowledge/    # persona sources for the AI assistant (about / faq / guidelines / boundaries)
├── lib/              # i18n dict, GSAP lifecycle helper, site config
│   └── knowledge/    # knowledge-pack pipeline (same-source layers + build-time privacy guard)
└── assets/           # photo originals (optimized at build; originals never shipped)
worker/               # Cloudflare Worker: /chat (SSE) + /classify (intent) + /mcp (MCP server)
└── src/core/         # runtime-agnostic logic; Cloudflare specifics live only in src/adapter/
public/zoe/           # Zoe's clip library (600p VP9 alpha, lazy-loaded; idle loads first)
docs/                 # zoe-production-handbook.md — clip production specs & prompt cards

AI layer

One knowledge layer, three outlets: /llms-full.txt for passive crawlers, a chat assistant (POST /chat, SSE) for humans, and an MCP server (/mcp, Streamable HTTP, no auth — tools: get_profile / list_experience / get_case_study) for visiting agents, both served from api.sigaoli.com (Cloudflare Worker, code in worker/). The knowledge pack (/knowledge.json) is assembled at build time from the same sources as the pages — persona markdown, cv.json, case studies, photo stats — so any content edit propagates to all three outlets on the next deploy, no manual step. A privacy guard fails the build if sensitive patterns (phone numbers, IDs, coordinates) ever leak into the pack.

Alongside each reply the chat runs a lightweight intent classifier (POST /classify, a small model) to suggest the single most relevant page, and can remember a returning visitor's name — both kept entirely in the visitor's own browser (opt-in, clearable via "Forget me"), never on a server. Visitors in the EU/EEA/UK have their chat and classification routed to an EU-hosted provider, never the China-direct API. What the site stores and sends is described in plain language at /privacy.

Editing content

• Case studies / research: edit either language and commit. The pre-commit hook works out which side moved, asks a model whether the edit actually changed what the other side must say, and only then revises it — passing the existing translation along so a changed fact gets fixed without the rest of your wording being rewritten. Polish one language and the other is left alone. Edit both in one commit and that counts as already handled by hand. See docs/bilingual-sync-design.md.
• CV: edit src/data/cv.json or cv.zh.json — the hook keeps the other in step entry by entry, so changing one role doesn't touch the rest. The timeline, /resume.json and /llms-full.txt all render from it. Replace public/files/pdf/CV__Sigao_Li.pdf alongside. (skills is deliberately left out of the sync: the two languages use different shapes there and the renderer handles both.)
• UI strings & hero copy: hand-written bilingual dictionary in src/lib/i18n.ts.
• Photos: drop the full-resolution originals into _inbox/ and commit. The pre-commit hook files them by GPS, archives the originals to _originals/ (never committed), derives 2560px serving masters, writes bilingual captions with a vision model, and registers them in src/data/photos.json. Photos without GPS go in _inbox/<country-id>/ instead. Counts, the map and the AI knowledge pack all follow from photos.json automatically. See docs/photo-ingest-design.md.
• AI assistant persona: edit src/data/knowledge/*.md; the knowledge pack rebuilds on every deploy and the assistant follows within ~10 minutes (Worker-side cache TTL).
• Zoe's actions: source clips live outside the repo; the pipeline (scripts/zoe-board2.mjs → zoe-qc2.mjs → zoe-prod2.mjs) keys, QCs, mirrors and encodes them into public/zoe/. New actions = one clip + one row in the ZOE table in ChatWidget.astro; specs and prompt cards in docs/zoe-production-handbook.md.

Local setup

Two chains run from a pre-commit hook: photo ingest, and bilingual sync. After cloning, point git at the tracked hooks directory once:

git config core.hooksPath .githooks

Without this neither runs — photos dropped into _inbox/ stay there, and the two languages stop tracking each other. Both exit immediately when there is nothing to do, so an ordinary commit is unaffected.

Both need .env (copy .env.example): the model calls for captions, translation and the staleness check all go through that gateway.

Regenerating the lock file. package-lock.json has to be built on Linux. npm records only the optional dependencies it can resolve on the machine it runs on, so a lock made on Windows omits what sharp needs on a runner and npm ci refuses to install. After changing dependencies here, run the Relock on Linux workflow from the Actions tab; it rebuilds the lock, proves npm ci works, and commits the result. Ordinary pushes never need it — and if you forget, the verify job says so.

Deployment

Push to master → deploy.yml builds and deploys to Pages. Pushes to v2 build without deploying (verification).

Two more workflows watch rather than gate, each emailing on failure and neither able to hold up a release:

Workflow	When	What
verify.yml	every push	Builds, checks internal links, then drives eight browser scripts against the production build. Failures upload screenshots and Playwright traces — drop a trace into trace.playwright.dev to replay the run frame by frame
audit.yml	Mondays	npm audit over the site and the worker

The audit used to gate the build. It reads the day's advisory database rather than this repository, so an untouched commit could go from green to red overnight — which is exactly what stopped a photo batch from shipping on 13 September. Knowing is worth an email; being blocked is not.

The Worker deploys separately: cd worker && npx wrangler deploy (secrets via wrangler secret put; custom domain api.sigaoli.com bound in the Cloudflare dashboard). When a batch changes both, deploy the Worker first — the chat UI calls its endpoints, so a site push ahead of the Worker leaves a brief window where those calls 404.

A deploy takes up to a minute to reach every edge location. Checking immediately reads the previous version, which has twice looked like a broken deploy when nothing was wrong — wait, then check.

Daily chat usage is at https://api.sigaoli.com/usage (last seven days, plus whether today has hit the cap). The cap itself is DAILY_CAP in worker/src/core/quota.ts; when it trips it emails once via Cloudflare Email Routing.

⚠️ Never click "Sync fork". This repository began as an academicpages fork; syncing would reset master to the upstream template. If that ever happens again: git push --force origin <good-commit>:master.