siao.ai — project docs index

What this is: the siao.ai domain family — the personal homepage, the applications on its subdomains, and the self-hosted infrastructure behind them. Several codebases, one umbrella of notes.

Current shape, if you are picking this up cold: siao.ai is a static page on Cloudflare Pages, and so is blog.siao.ai. Everything else runs on one self-hosted box — Forgejo (hidden backend, never public), SiaoHub (the UI at git.siao.ai), AnswerHub (apps.siao.ai/answerhub), and Logto at accounts.siao.ai, which is the single identity provider for all of them. No application has credentials of its own any more.

Note the split that matters when deploying: the two Cloudflare Pages sites publish themselves from a git push; the self-hosted three do not, and git.siao.ai in particular neither deploys from main nor rebuilds its own image — see HANDOFF.md.

Read HANDOFF.md first — these journals are long and several of their older status lines describe a world that later chapters replaced.

Status is not in this file. The entries below say what each document covers. Whether the thing it describes is written, committed, deployed or reachable lives in HANDOFF.md and nowhere else — a "not built" note in an index is written once and believed long after it stops being true, which had already happened to two entries here by 2026-08-10.

Files in this directory:

• NOTES_HOMEPAGE.md — the journal for the siao.ai homepage repo itself (this git repository). Chaptered by task, written as work happened, includes the paths that were tried and abandoned. Read this before touching the animation question again — it has already been asked and answered twice.
• NOTES_GIT_SERVER.md — the journal for the self-hosted git.siao.ai Forgejo instance, running on the owner's own hardware (not part of this repo — reached over SSH). Read this before touching that server again; it records a directory that was created in the wrong place and never actually took effect, among other things worth not re-discovering the hard way.
• NOTES_SIAOHUB.md — the journal for SiaoHub, the self-authored Next.js frontend that is the only UI surface at git.siao.ai (Forgejo demoted to a pure backend). Built and running on the host. Read chapter 8 before touching the visibility model — but note that chapter's clone-approval half is superseded by NOTES_ACCOUNTS.md chapters 5–7: identity now comes from accounts.siao.ai, approval is a version-controlled file, and clone is served by SiaoHub's own git proxy.
• SPEC_SIAOHUB.md — the SiaoHub spec. Its auth and clone-gating sections are superseded — a banner at the top says which. Read SPEC_ACCOUNTS.md for those. Everything else (visibility tiers via repo topics, the preview tier, the single-seam rule) still holds.
• NOTES_BLOG.md — the journal for blog.siao.ai (blog-siao-ai repo), the single-author Markdown blog. Read ch.3 before adding a test for anything visual — it records the pass where a green suite coexisted with a formula rendering as E = mc²E = mc2 on every page, and ch.9 before trusting that a deployed CSS change is what a browser is actually showing you.
• SPEC_BLOG.md — the blog spec: two-way linkage with SiaoHub (build-time file embeds one way, a backlinks manifest the other), Markdown-only content model, per-post optional translations. Its "Further Notes" carry the one question it deliberately left open.
• NOTES_ACCOUNTS.md — the journal for accounts.siao.ai, the self-hosted Logto instance that is the single identity provider for every siao.ai application. Running on the host; both applications sign in through it. Chapters are newest-first. Read chapter 1 before touching authentication anywhere in this family — it records two reversed recommendations and one architectural hole (the clone-approval script cannot express an approval for a user with no Forgejo account) that only surfaced at question 13 of 14.
• SPEC_ACCOUNTS.md — the accounts.siao.ai spec. Supersedes parts of SPEC_SIAOHUB.md: Forgejo is no longer SiaoHub's identity provider, registration no longer implies clone access, and clone is served by a SiaoHub-side read-only git proxy rather than by Forgejo. Read this before implementing any auth or clone-gating decision from SPEC_SIAOHUB.md.
• NOTES_APPS.md — the journal for apps.siao.ai (apps-siao-ai repo), which is now the nav homepage plus AnswerHub under /answerhub. Read chapter 1 for the original decision trail (stack, deploy target) and the Debian→Ubuntu correction. Its account/auth chapters are superseded — AnswerHub's own credential store is gone; see NOTES_ACCOUNTS.md chapter 8.
• SPEC_APPS.md — the apps.siao.ai nav-homepage spec. Built. Covers only the nav homepage slice, not the later Lwopan migration.
• SPEC_ANSWERHUB_FRONTEND.md — partly superseded (its account pages no longer exist). Spec for renaming Lwopan to AnswerHub（答案庫） and restyling its frontend (shared SiaoHub color tokens, page structure mirrored from the old app, blog/ knowledge base cut from nav). Visual-only — no backend changes, no /lwopan path rename (deferred). Read this before touching any Lwopan/AnswerHub page's styling.
• SPEC_ANSWERHUB_LIVE.md — spec for the first end-to-end run of AnswerHub on the tailnet against the live identity provider — nobody has ever completed a sign-in — plus fixing whatever that walk finds and the three known AnswerHub defects. Supersedes nothing; it finishes what SPEC_ANSWERHUB_FRONTEND.md and SPEC_ACCOUNTS.md started. Corrects two stale claims: the sign-in experience is email + verification code, not username/password (NOTES_ACCOUNTS.md), and pushing is not blocked for apps-siao-ai (HANDOFF.md). Scoped at the time to the tailnet, with no Google sign-in and no auth-method changes — where any of that stands now is HANDOFF.md's to say, not this line's.
• SPEC_ANSWERHUB_SHELL.md — spec for AnswerHub's foundations and page frame, written after the owner saw it in a browser and said it does not look like a normal modern web page — which decomposed into ten checkable defects, the largest being no Chinese font at all on an entirely Chinese product. Covers: a platform CJK font stack (in siaohub too, for the Chinese content it renders), one shared page shell replacing nine per-page improvisations, real form labels, route-level loading/error/not-found states, a theme control adopting siaohub's mechanism, and settling the product's vocabulary on 解答. Does not reopen the visual direction — APP_FAMILY.md's colors and tone stand. Reorders SPEC_ANSWERHUB_LIVE.md: the browser walk now happens after this, against the rebuilt interface.
• SPEC_ANSWERHUB_CRAFT.md — spec for the navigation AnswerHub does not have, the craft its existing tone was not executed with, and three features migrated as shells. Crawling the deployed site found that search, settings, bulk upload and moderation have no entry point anywhere — they answer 200 only if you already know the URL. The profile page never queries its owner's submissions. views exists on three models and nothing writes to it. Explicitly does not amend APP_FAMILY.md: the owner's "太方太平" read as a design-direction complaint and is not one — SiaoHub ships the same tokens and draws none. Adds a structural test that a page with no entry point fails the suite.
• SPEC_ANSWERHUB_SEO.md — spec for AEO/SEO/GEO plus the import of the two question corpora the owner already holds: 6258 distinct holiday-homework questions crawled from netholiday.reh.tw, and 7308 reading-certification questions across 184 books from happyread.kh.edu.tw — the second corpus has almost no answers, which is why this spec carries a three-state verification model (VERIFIED / DISPUTED / UNVERIFIED) rather than treating every published answer as equal. Adds the discovery surface the product has none of (sitemap, real robots.txt, canonical URLs, QAPage structured data, a nested taxonomy of index pages) behind one new seam — an SEO module that every page, the sitemap and robots all read from. Read the Further Notes before questioning why a thousand disputed and 4838 unverified answers ship anyway: those are recorded decisions, not oversights.
• SPEC_ANSWERHUB_ANTIBOT.md — spec for selective anti-scraping on the answer blocks only, written after the owner asked for Meta-grade obfuscation that costs nothing in search or AI citation. Resolves that three-way tension by splitting on verified identity rather than on behaviour: verified crawlers (Googlebot and all eight retrieval crawlers, policy unchanged from SPEC_ANSWERHUB_SEO.md) get clean server-rendered HTML, everyone else gets an encoded answer block restored by client JavaScript and mutated per response at the edge. Does not reopen the crawler policy — CCBot keeps full access and the recorded cost of that is in the Out of Scope section. Watermarking of every kind is explicitly deferred. Carries the fix for a defect that predates the whole question: question pages are dynamic with no cache on one process and one SQLite file.
• SPEC_LWOPAN_MIGRATION.md — built, and its account user stories are superseded (email/password registration, magic link and 2FA were built here and have since been removed). Spec for merging ~/Lwopan/learning-platform's backend logic into apps-siao-ai under /lwopan, frontend rebuilt from scratch (Tailwind + Radix, Liquid Glass dropped). This overturns SPEC_APPS.md's "plain CSS" decision — read the Implementation Decisions section before touching either spec's styling assumptions again. Scoped to local build + tests only; going live is explicitly deferred, same as the nav homepage.
• SPEC_HOMEPAGE_I18N.md — not built. Spec for the siao.ai homepage's third section (a colophon), richer exit descriptions, and a second language at /zh/ with a self-hosted Chinese subset font. Extends siao-ai/SPEC.md rather than replacing it — every original decision (no build step, no nav, animation untested) still holds; the only one it overturns is "the homepage has one URL". Also carries the soft-404 fix for unknown paths returning 200 with the English homepage (whether that still happens: HANDOFF.md).
• HANDOFF.md — current state across both of the above: what's live, what's outstanding, what to do next. Rewritten each time it goes stale, not appended to.

This directory is gitignored, same as SPEC.md and .scratch/ — planning and working notes live here and in the owner's self-hosted git, not in the public repo's history.

Directory layout

All of this now lives under one umbrella folder, ~/siao-ai/, as sibling polyrepos (standard practice for projects with different deploy targets — not a monorepo, not submodules):

~/siao-ai/
  ClaudeDocs/       <- this directory — top-level, not inside any one repo
  ClaudeDesign/     <- settled visual decisions, one file per identity
  siao-ai/          <- the siao.ai homepage repo (shihte/siao.ai on GitHub)
  git-siao-ai/      <- infra config repo (git.siao.ai/siao/infra, self-hosted)
  apps-siao-ai/     <- apps.siao.ai repo — nav homepage + AnswerHub
  siaohub/          <- git.siao.ai's UI (deployed on the self-hosted box)
  blog-siao-ai/     <- blog.siao.ai (shihte/blog-siao-ai on GitHub, private)

ClaudeDocs/ moved here from inside siao-ai/ because it covers all three repos, not just the homepage — it was always gitignored inside siao-ai/, so the move didn't touch that repo's git history at all.