About these docs

These docs are the Glyph engineering wiki. They sit at glyph.naburis.cloud/docs, get built from the canonical product source files at every release, and are written so a new architect or engineer can become productive without your time being the bottleneck.

Two tiers, decided by URL prefix

Prefix	Audience	Gate
/docs/...	Anyone	None
/docs/admin/...	Zitadel admin role	Caddy forward_auth → glyph-oauth2-proxy

The path is the source of truth. The frontmatter audience field is validated against the path at astro check time, so a misplaced page fails the build instead of leaking.

✓

Why not a single big private wiki?

The truly general concepts — what Glyph is, what an operator is, the three modes — make for better engineering hires when they are linkable from anywhere. The internals (CRDT subdoc layout, JWT validation, the executor DAG) are gated. Two tiers, no rot from a third.

Diátaxis discipline

Every page is exactly one of:

• Tutorial — on-rails learning. No branching, no choices.
• How-to guide — a real-world goal. Imperative and numbered.
• Reference — facts. Declarative, scannable, no narrative.
• Explanation — understanding. Discursive, opinionated, no step lists.

Sidebar groups name the mode. Mixing modes on a page is a bug — open a PR to split it.

What is auto-rendered from canonical sources

The pages below read their content at build time from the product source. They cannot drift from the code:

• Operator catalog — /opt/glyph/schemas/operators/*.json
• Trigger catalog — same source, filtered to trigger.*
• SQL migrations — /opt/glyph/migrations/*.sql
• Cell manifest — /opt/glyph/cell-manifest.yaml
• Caddy route map — /opt/glyph/glyph.caddy
• DEPLOY.yaml mapping — /opt/glyph/DEPLOY.yaml
• Permission bits — /opt/glyph/crates/glyph-shared/src/permissions.rs

Add a new operator? It appears in the catalog automatically. Change the Caddy site? The route map updates. This is the single biggest lever against doc rot.

Page actions

Every page has two actions next to its title:

• Copy page — fetches the raw Markdown and copies it to the clipboard, prefixed with the canonical URL. Paste into a chat with an LLM and the model has perfect context.
• Open in Cursor — opens the source page (docs/src/content/docs/<slug>.mdx) in your local Cursor via cursor:// URL. Only shown when the page declares open_in_cursor in frontmatter.

Frontmatter contract

title: Required.
description: Optional but encouraged for SEO + LLM context.
audience: public | admin   # must match path prefix
tier: tutorial | how-to | reference | explanation | operations | adr
layer: frontend | backend | platform | data | crdt | ai
crate: glyph | glyph-shared | glyph-model
last_verified: 2026-04-19  # CI flags pages > 180 days untouched
related: ['/docs/explanation/what-glyph-is']
stability: stable | beta | draft
owner: platform
keywords: ['operator', 'dag']
open_in_cursor: /opt/glyph/docs/src/content/docs/...

Contributing

cd /opt/glyph/docs
npm install        # first time only
npm run dev        # http://localhost:5184/docs
npm run check      # type-check + content-collection schema
npm run lint       # check + stale + operator-coverage + diataxis-lint
npm run build      # static site → dist/

Before opening a PR:

1. npm run lint is green.
2. The page has the right frontmatter.
3. Anything new under admin/ is genuinely admin-only — public concepts go on top.
4. If you wrote something that “needs explaining,” create a phantom link to a (possibly empty) explanation page; that is how the explanation tree grows organically.

The build pipeline (make ship-docs) typechecks, builds, rsyncs dist/ to /srv/glyph-docs/, and verifies HTTPS 200. See Admin · Operations · Deployment.