Updated 2026-07-06

Operations Runbook

This runbook covers public-site, docs, local preview, and integration evidence for AgentHub. It is intentionally secret-free: production host paths, rollback commands, keys, and private logs belong in the private operator workspace.

Daily Checks

Check	Command or route	Expected result
Public home	`https://hub.tokendancelab.com/zh` and `/en`	Current homepage, no old hero copy, no old purple accent
Docs entry	`/zh/docs` and `/en/docs`	Styled docs page with sidebar, TOC, and body content
Deep docs	`/zh/docs/workflows`, `/en/docs/desktop`, `/zh/docs/hub-edge`	Correct body, localized navigation, no 404
Discovery	`/robots.txt`, `/sitemap.xml`, `/llms.txt`	New routes present and secret-free
Login entry	`/zh/login` or nav login button	Redirects to TokenDance ID rather than implementing a separate product login

Use cache-busting when validating a recent deploy:

curl.exe -I "https://hub.tokendancelab.com/zh/docs/desktop?v=YYYYMMDDTHHMMSS"
curl.exe "https://hub.tokendancelab.com/llms.txt?v=YYYYMMDDTHHMMSS"

Local Build Gate

Run these from the registered release source worktree:

corepack pnpm --filter @tokendance-site/hub exec astro check
corepack pnpm --filter @tokendance-site/hub test
corepack pnpm --filter @tokendance-site/hub lint
corepack pnpm --filter @tokendance-site/hub build

Expected result:

static export exists in apps/hub/out/;
localized docs pages export to both apps/hub/out/en/docs/... and apps/hub/out/zh/docs/...;
tests cover docs registry, i18n routes, search index, nav, footer, and hero behavior;
lint has no new warnings.

Docs Release Gate

Every new docs route must update:

File or system	Required update
English page	`src/content/docs/<slug>.md`
Chinese page	`src/content/docs/zh/<slug>.md`
Navigation	Sidebar group and label for the new doc
TOC	Page headings rendered in the right sidebar
Search	Search index terms for the new page
Discovery	dynamic `src/pages/sitemap.xml.ts` output and generated `llms.txt` docs index / route source
Reader docs	README Documentation IA and changelog
Tests	Docs registry/search assertions where useful

If any of these are missing, the route may render but search, sidebar, prev/next, crawler discovery, or zh/en parity will drift.

Visual QA Gate

For UI or docs layout changes, check:

desktop viewport around 1440 x 900;
mobile viewport around 390 x 844;
/zh, /en, /zh/docs, /en/docs;
the changed docs route;
theme toggle state when the page includes the Desktop mock;
language switch state when mock copy is visible.

Look for:

text wrapping inside pills, buttons, nav, or footer;
stale purple accents instead of TokenDance Blue;
hard black footer backgrounds;
excessive hover shadows on the Desktop mock;
focus rectangles inside the non-interactive mock preview;
old docs body missing styles.

Product Runtime Signals

When validating AgentHub product behavior rather than only the public site, record public-safe signals instead of private logs:

Area	Signal	Healthy shape
Hub session	auth/session check	TokenDance ID subject maps to a Hub-local session; denied actions have request ids
Project routing	task target selection	target Edge is authorized before work is queued
Edge presence	heartbeat or health shape	Edge reports reachable state, version, workspace policy, and runtime inventory
Run lifecycle	event stream	created -> preparing -> running -> completed/failed/cancelled with monotonic events
Runtime adapter	adapter readiness	mock passes first; real CLI reports installed/authenticated/available or a clear `runtime_unavailable`
Artifacts and diff	review surfaces	relative paths, base/target metadata, approval id, and no private absolute paths
Queue/integration	async work	webhook/card path acknowledges quickly and slow work moves to queue/retry state
Audit	action record	actor, project, target, run id, action, result, timestamp, and redacted failure reason

Use this table for smoke reports and issue triage. Do not paste full prompts, raw provider output, private file content, access tokens, or host-specific logs into public docs.

Live Smoke Shape

A live smoke result should record:

site: hub.tokendancelab.com
version: cache-busting timestamp
routes: /zh, /en, /zh/docs, /en/docs, changed deep docs route
checks: body keyword, status code, discovery files, no stale old hero
result: pass/fail

Public changelog entries should say what changed, not where the server files live.

Failure Triage

Failure	First action
Old homepage still visible	Check deploy source, CDN/browser cache, and whether the wrong worktree was built
Docs page empty or plain text	Confirm the built static route, CSS assets, and browser cache
New docs page missing from sidebar	Update sidebar configuration and tests
Search cannot find new page	Update search index terms
Sitemap misses route	Update the dynamic sitemap route inputs and rerun public-surface checks
`llms.txt` stale	Confirm the docs collection generated the missing route; update route-source notes/key links only when site-level context changed
Login page looks standalone	Keep static site login as TokenDance ID redirect shell only
Web route cannot reach an Edge target	Check Hub authorization, Edge presence, target id, and audit denial before changing Web UI
Event stream stops mid-run	Check run state, queue backlog, adapter process state, and schema validation failures
`unauthorized_target`	Confirm user/project membership and device target binding
`workspace_outside_allowlist`	Confirm the workspace is registered for the selected Edge
`runtime_unavailable`	Verify mock runtime first, then local CLI install/auth/profile compatibility
Real runtime fails	Reproduce with mock first, then inspect local CLI auth and Edge adapter logs

Runtime Incident Triage

Use this table when a product behavior fails after the public site itself is healthy.

Symptom	Severity	First check	Owner	Public-safe evidence	Private evidence
Edge unreachable	High	Edge health URL from the selected target	Edge Server	status code, request id, target id	local process logs and host details
Web target unauthorized	High	Hub audit/request id for the target route	Hub Server	error code, request id, project id placeholder	authorization trace and member records
Workspace rejected	Medium	selected workspace against Edge allowlist	Edge Server	`workspace_outside_allowlist`, target id	local allowlist and path details
Runtime unavailable	Medium	mock runtime first, then CLI install/auth state	Edge adapter	`runtime_unavailable`, adapter id	local CLI output and credential state
Event stream stalls	Medium	last monotonic event and queue/run state	Edge + Hub	run id, last event type, request id	adapter logs and queue traces
Feishu/Lark callback slow	High	callback acknowledgement latency	Integration Gateway	event type, action id, latency bucket	raw provider payload and retry logs
Audit missing	High	Hub action record for the task/run	Hub Server	actor placeholder, run id, action, result	full audit row and internal correlation ids

Public issues should stop at error code, request id, route class, and redacted identifiers. Private evidence can include local logs, host paths, queue names, callback payloads, and raw runtime output only inside the operator workspace.

Status Words

Use conservative language:

Word	Meaning
Live	Public site or route is reachable
Preview-ready	Works in local or controlled preview with clear evidence
Contract shaped	Interface is documented but public SDK/package may still change
In progress	Implementation exists or is actively being integrated
In development	Planned or partially implemented; do not sell as available

When unsure, choose the more conservative word and link to roadmap or changelog.

Edit this page on GitHub