{
  "id": "2026-04-29-bezel-docs-site-design-2d3d53eba8",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-04-29-bezel-docs-site-design.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.694Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "Bezel Docs Site — Design Spec",
  "summary": "Bezel Docs Site — Design Spec Date: 2026 04 29 URL: docs.bezeliq.ai Status: Approved for planning Overview 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 contin...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Bezel Docs Site — Design Spec",
      "level": 1,
      "body": "**Date:** 2026-04-29  \n**URL:** docs.bezeliq.ai  \n**Status:** Approved for planning\n\n---"
    },
    {
      "title": "Overview",
      "level": 2,
      "body": "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.\n\n---"
    },
    {
      "title": "Tech Stack",
      "level": 2,
      "body": "| Layer | Choice | Reason |\n|---|---|---|\n| Framework | Astro Starlight | Best docs framework available. Markdown-native, fast, beautiful. |\n| Hosting | Cloudflare Pages | Already used for studio.bezeliq.ai and dreamborn.ai. Free. |\n| Domain | docs.bezeliq.ai | Subdomain of existing bezeliq.ai domain. |\n| Content format | Markdown / MDX | Agents write .md files. MDX for interactive components where needed. |\n| Repo | New repo: `bezel-docs` | Separate from redk3y — docs have their own release cadence. |\n\n---"
    },
    {
      "title": "Visual Design",
      "level": 2,
      "body": "**Style:** Deep Dark / Branded  \n**Background:** `#0a0f1e` (near-black)  \n**Sidebar:** `#070b18`  \n**Accent:** Gradient purple `#7c6af7 → #a78bfa`  \n**Text:** `#fff` headings, `#888` body, `#555` secondary  \n**Code blocks:** Dark with purple border, monospace  \n**Logo:** Bezel `black-on-white.png` with `filter: invert(1); mix-blend-mode: screen`\n\nStarlight theme customization via `astro.config.mjs` custom CSS variables — no custom renderer needed.\n\n---"
    },
    {
      "title": "Navigation (sidebar, top-level)",
      "level": 3,
      "body": "```\nWhat is Bezel\nCore Concepts\nThe Agent Team\nHow Work Flows\nThe Studio\nGetting Started\nReference\n```"
    },
    {
      "title": "Section Breakdown",
      "level": 3,
      "body": "**① What is Bezel**\n- The Vision\n- The Two-World Model (agent artifacts vs human views)\n- Why Consensus Changes Everything\n- The Agent Economy\n\n*Audience:* Everyone  \n*Authors:* Justin + Atlas  \n\n---\n\n**② Core Concepts**\n- The Pull Model\n- HCS Consensus (topics, claiming, the read receipt)\n- Roles & Topics\n- The Wire Protocol (brief → claim → complete → blocked)\n- Agent Artifacts vs Human Views\n\n*Audience:* Partners, developers  \n*Authors:* Atlas, Quinn  \n\n---\n\n**③ The Agent Team**\n- How to Read an Agent Card\n- Platform Agents (Atlas, Engine, Claire, Iris)\n- Developer Agents (Quinn, Vikram, Priya, Luna)\n- Marketing Agents (Nova, Harper, Jade, Rosa, Ivy)\n- Sales & CRM Agents (Traci, Arlo)\n- Management Agents (Mindy, Zara)\n\n*Audience:* Everyone  \n*Authors:* Each agent writes their own page — seeded from agent cards in `definitions/cards/`  \n\n---\n\n**④ How Work Flows**\n- Task Lifecycle (available → claim → execute → complete)\n- The Engine & Dependency Graph\n- Exec Gates & Human-in-the-Loop\n- Completion Verification\n- Circuit Breakers & Blocked Tasks\n\n*Audience:* Partners, developers  \n*Authors:* Engine, Atlas  \n\n---\n\n**⑤ The Studio**\n- Cockpit Overview\n- Inbox & Exec Gates\n- Marketing Studio\n- Campaign → Piece → Publish Flow\n- Working with Atlas (interactive architect)\n\n*Audience:* Partners, clients  \n*Authors:* Justin + agents  \n\n---\n\n**⑥ Getting Started**\n- Your First Session with Claude Code\n- Doppler & Environment Setup\n- SSH into the VPS\n- How to Work with Atlas\n- Dispatching Your First Task\n\n*Audience:* Partners, developers  \n*Authors:* Quinn + Atlas — kept current as part of task completion contracts  \n\n---\n\n**⑦ Reference**\n- Topic Map (HCS topic IDs)\n- Wire Schemas (brief, claim, complete, blocked, inbox)\n- Agent Definitions\n- Supabase Tables\n- API Endpoints\n- Environment Variables\n- Systemd Units\n- Changelog\n\n*Audience:* Developers  \n*Authors:* Auto-generated where possible; Quinn and Vikram maintain  \n\n---"
    },
    {
      "title": "Homepage",
      "level": 2,
      "body": "Three-zone layout:\n\n**Nav:** Bezel logo (inverted for dark bg) + \"Docs\" label | Concepts · Agents · Reference · bezeliq.ai ↗\n\n**Hero:**\n- Tagline: *\"The operating system for AI-native businesses.\"*\n- One-paragraph platform description\n- Three audience entry cards: Partner (\"New to Bezel?\") · Developer (\"Ready to build?\") · Evaluating (\"How does it work?\")\n\n**Section strip:** Four preview tiles — Vision / Concepts / The Team / Reference\n\n**Footer:** Bezel logo (muted) · \"Built on Hedera · Maintained by the team that built it\" · \"Last updated by [agent] · [date]\"\n\n---"
    },
    {
      "title": "Agent Contribution Model",
      "level": 2,
      "body": "Agents contribute to docs as part of normal task completion. The contribution workflow:\n\n1. A `docs_update` step is added to relevant task templates in `definitions/workflows/`\n2. When an agent ships a feature (Quinn, Vikram, etc.), they write or update the relevant `.md` page in `bezel-docs/src/content/docs/`\n3. The agent commits and opens a PR to the `bezel-docs` repo\n4. Atlas reviews the PR — checks accuracy, consistency, voice\n5. Justin approves via exec gate before merge\n6. Cloudflare Pages auto-deploys on merge to main\n\nAgent 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.\n\nThe Getting Started section is explicitly owned by Quinn and Atlas — updated whenever the setup process changes.\n\n---"
    },
    {
      "title": "Repo Structure",
      "level": 2,
      "body": "```\nbezel-docs/\n  astro.config.mjs\n  src/\n    content/\n      docs/\n        what-is-bezel/\n          index.md\n          two-world-model.md\n          consensus.md\n          agent-economy.md\n        core-concepts/\n          pull-model.md\n          hcs-consensus.md\n          roles-topics.md\n          wire-protocol.md\n          artifacts-vs-views.md\n        agent-team/\n          index.md\n          atlas.md\n          engine.md\n          quinn.md\n          ... (one page per agent)\n        how-work-flows/\n          task-lifecycle.md\n          engine-dependency-graph.md\n          exec-gates.md\n          completion-verification.md\n          circuit-breakers.md\n        studio/\n          cockpit.md\n          inbox.md\n          marketing-studio.md\n          atlas-interactive.md\n        getting-started/\n          claude-code.md\n          doppler-setup.md\n          vps-ssh.md\n          atlas.md\n          first-task.md\n        reference/\n          topic-map.md\n          wire-schemas.md\n          agent-definitions.md\n          supabase-tables.md\n          api-endpoints.md\n          env-vars.md\n          systemd-units.md\n          changelog.md\n    assets/\n      bezel-logo.png\n      bezel-logo-white.png\n  public/\n  package.json\n```\n\n---"
    },
    {
      "title": "Deployment",
      "level": 2,
      "body": "- GitHub repo: `justinb2bea/bezel-docs`\n- Cloudflare Pages project: `bezel-docs`\n- Custom domain: `docs.bezeliq.ai` (CNAME to Cloudflare Pages)\n- Auto-deploy on push to `main`\n- PRs trigger preview deployments (Cloudflare Pages built-in)\n\n---"
    },
    {
      "title": "Launch Checklist",
      "level": 2,
      "body": "- [ ] Create `bezel-docs` repo\n- [ ] Scaffold Astro Starlight with custom dark theme\n- [ ] Wire Cloudflare Pages + custom domain\n- [ ] Seed agent team pages from `definitions/cards/*.json`\n- [ ] Write \"What is Bezel\" section (Justin + Atlas)\n- [ ] Write \"Core Concepts\" section (Atlas)\n- [ ] Write \"Getting Started\" section (Quinn)\n- [ ] Add `docs_update` step to developer workflow templates\n- [ ] Add `bezeliq_docs_update` milestone step to platform workflows\n- [ ] Atlas review pass before public launch"
    }
  ],
  "html_path": "artifacts/2026-04-29-bezel-docs-site-design-2d3d53eba8.html",
  "json_path": "artifacts/2026-04-29-bezel-docs-site-design-2d3d53eba8.json"
}