Bezel Docs Site — Design Spec

Date: 2026-04-29 URL: docs.bezeliq.ai Status: Approved for planning

---

A public-facing documentation site for the Bezel platform. Serves three audiences — partners/collaborators, developers, and clients evaluating Bezel. Built on Astro Starlight, hosted on Cloudflare Pages, written primarily by agents and maintained continuously as the platform evolves.

---

| Layer | Choice | Reason | |---|---|---| | Framework | Astro Starlight | Best docs framework available. Markdown-native, fast, beautiful. | | Hosting | Cloudflare Pages | Already used for studio.bezeliq.ai and dreamborn.ai. Free. | | Domain | docs.bezeliq.ai | Subdomain of existing bezeliq.ai domain. | | Content format | Markdown / MDX | Agents write .md files. MDX for interactive components where needed. | | Repo | New repo: bezel-docs | Separate from redk3y — docs have their own release cadence. |

---

Style: Deep Dark / Branded Background: #0a0f1e (near-black) Sidebar: #070b18 Accent: Gradient purple #7c6af7 → #a78bfa Text: #fff headings, #888 body, #555 secondary Code blocks: Dark with purple border, monospace Logo: Bezel black-on-white.png with filter: invert(1); mix-blend-mode: screen

Starlight theme customization via astro.config.mjs custom CSS variables — no custom renderer needed.

---

`` What is Bezel Core Concepts The Agent Team How Work Flows The Studio Getting Started Reference ``

• The Vision
• The Two-World Model (agent artifacts vs human views)
• Why Consensus Changes Everything
• The Agent Economy

*Audience:* Everyone *Authors:* Justin + Atlas

---

• The Pull Model
• HCS Consensus (topics, claiming, the read receipt)
• Roles & Topics
• The Wire Protocol (brief → claim → complete → blocked)
• Agent Artifacts vs Human Views

*Audience:* Partners, developers *Authors:* Atlas, Quinn

---

• How to Read an Agent Card
• Platform Agents (Atlas, Engine, Claire, Iris)
• Developer Agents (Quinn, Vikram, Priya, Luna)
• Marketing Agents (Nova, Harper, Jade, Rosa, Ivy)
• Sales & CRM Agents (Traci, Arlo)
• Management Agents (Mindy, Zara)

*Audience:* Everyone *Authors:* Each agent writes their own page — seeded from agent cards in definitions/cards/

Three-zone layout:

Nav: Bezel logo (inverted for dark bg) + "Docs" label | Concepts · Agents · Reference · bezeliq.ai ↗

• Tagline: *"The operating system for AI-native businesses."*
• One-paragraph platform description
• Three audience entry cards: Partner ("New to Bezel?") · Developer ("Ready to build?") · Evaluating ("How does it work?")

Section strip: Four preview tiles — Vision / Concepts / The Team / Reference

Footer: Bezel logo (muted) · "Built on Hedera · Maintained by the team that built it" · "Last updated by [agent] · [date]"

---

Agents contribute to docs as part of normal task completion. The contribution workflow:

1. A docs_update step is added to relevant task templates in definitions/workflows/ 2. When an agent ships a feature (Quinn, Vikram, etc.), they write or update the relevant .md page in bezel-docs/src/content/docs/ 3. The agent commits and opens a PR to the bezel-docs repo 4. Atlas reviews the PR — checks accuracy, consistency, voice 5. Justin approves via exec gate before merge 6. Cloudflare Pages auto-deploys on merge to main

Agent pages (in The Agent Team section) are seeded from definitions/cards/*.json and each agent writes their own narrative page as a one-time task at site launch.

The Getting Started section is explicitly owned by Quinn and Atlas — updated whenever the setup process changes.

---

``` bezel-docs/ astro.config.mjs src/ content/ docs/ what-is-bezel/ index.md two-world-model.md consensus.md agent-economy.md core-concepts/ pull-model.md hcs-consensus.md roles-topics.md wire-protocol.md artifacts-vs-views.md agent-team/ index.md atlas.md engine.md quinn.md ... (one page per agent) how-work-flows/ task-lifecycle.md engine-dependency-graph.md exec-gates.md completion-verification.md circuit-breakers.md studio/ cockpit.md inbox.md marketing-studio.md atlas-interactive.md getting-started/ claude-code.md doppler-setup.md vps-ssh.md atlas.md first-task.md reference/ topic-map.md wire-schemas.md agent-definitions.md supabase-tables.md api-endpoints.md env-vars.md systemd-units.md changelog.md assets/ bezel-logo.png bezel-logo-white.

---

• GitHub repo: justinb2bea/bezel-docs
• Cloudflare Pages project: bezel-docs
• Custom domain: docs.bezeliq.ai (CNAME to Cloudflare Pages)
• Auto-deploy on push to main
• PRs trigger preview deployments (Cloudflare Pages built-in)

---

• [ ] Create bezel-docs repo
• [ ] Scaffold Astro Starlight with custom dark theme
• [ ] Wire Cloudflare Pages + custom domain
• [ ] Seed agent team pages from definitions/cards/*.json
• [ ] Write "What is Bezel" section (Justin + Atlas)
• [ ] Write "Core Concepts" section (Atlas)
• [ ] Write "Getting Started" section (Quinn)
• [ ] Add docs_update step to developer workflow templates
• [ ] Add bezeliq_docs_update milestone step to platform workflows
• [ ] Atlas review pass before public launch