Tier0 Docs

Documentation site for Tier0 — the agentic industrial platform — built with Astro Starlight.

Human-friendly and agent-readable: every build emits a single /llms.txt (full docs) via starlight-llms-txt.

Quick start

npm install
npm run dev       # http://localhost:4321
npm run build     # static output in dist/ — must pass before committing
npm run preview   # preview the production build

Requires Node 22.12+ and npm 9.6.5+. No other services needed.

PDF manuals

npm run pdf builds the site and refreshes the downloadable manuals in all five languages: English (en), Simplified Chinese (zh-cn), Japanese (ja), Spanish (es), and Korean (ko). The export dialog defaults to the current page language and allows a separate PDF language choice. Untranslated chapters include a localized notice and use the English source; OpenAPI source descriptions remain in English.

Run this command after changing documentation before publishing updated PDF downloads. It requires Chrome, Edge, or Playwright Chromium. To refresh one language after building, use PDF_LOCALE=ja node scripts/export-pdf.mjs (PowerShell: $env:PDF_LOCALE='ja'; node scripts/export-pdf.mjs). The PDFs are written to public/downloads/ and copied into dist/downloads/; include the updated download files in the release.

Structure

src/content/docs/                  # pages — URL mirrors the file path
├── index.mdx                      # wireframe landing
├── get-started/
│   ├── installation.mdx           # CLI via Skill/GitHub + edition tabs
│   ├── demo-factory.mdx           # Cloud trial tour
│   └── choosing-version.mdx       # edition board + hw requirements + matrix
├── using-tier0/
│   ├── uns-concepts.mdx           # Metric/State/Action, VQT, storage (skeleton)
│   ├── connect-data.md            # modeling + SourceFlow
│   ├── working-with-uns-data.mdx  # MQTT / API / CLI (skeleton)
│   ├── build-apps.mdx             # containers as apps + Event Flow (skeleton)
│   ├── analyze-data.md            # Notebook, interactive + ML
│   └── agents.mdx                 # Tier0 Skill (skeleton)
└── best-practice/
    ├── uns-modeling.mdx           # topic explosion, payloads (skeleton)
    ├── protocol-connections.mdx   # OPC UA/Modbus flows + JSON refs (skeleton)
    └── analytics-apps.mdx         # Aramco Bowtie case (skeleton)

astro.config.mjs                   # sidebar, plugins (mermaid, llms.txt), site URL
src/styles/custom.css              # the entire theme, sectioned by comments
src/components/PageTitle.astro     # renders edition badges from frontmatter
src/content.config.ts              # frontmatter schema (editions field)

Skeleton pages carry a :::caution[TODO — 写作线索] block with writing directions — search the repo for 写作线索 to list everything awaiting content.

Adding a page

1. Create src/content/docs/<section>/<slug>.md (use .mdx only if you need components):

   ---
   title: My Page
   description: One sentence — this feeds search and llms.txt.
   editions: [cloud, enterprise]   # omit if the page applies to all editions
   ---

2. Add it to the sidebar in astro.config.mjs.

3. npm run build — a broken internal link or bad frontmatter fails the build.

Conventions

The complete, binding conventions live in AGENTS.md (symlinked as CLAUDE.md, so AI coding tools load them automatically). Headlines:

• Editions are frontmatter metadata — one docs tree, never per-edition trees.
• Diagrams are Mermaid only — no ASCII art; brand-highlight nodes with classDef t0accent.
• Typography = Stripe rules — system fonts, mono for code only, zero letter-spacing.
• Colors = neutral gray + Tier0 lime, no blue anywhere.
• Tier0 with a zero; FREEZONEX all caps; answer-first writing.

Before going live (open TODOs)

Item	Where
Set the real docs domain (currently https://docs.tier0.app placeholder)	site in astro.config.mjs
Re-verify prices against tier0.app/pricing	architecture/choosing-version.mdx
Add CI running npm run build on PRs	—