🌐 BDB HTML Manual & Live Documentation System (bdbhtmlmanueldocs)

This skill codifies the complete specification for building and deploying neutral, enterprise-grade developer documentation and bilingual user manuals. The Google Antigravity / BDB OS look described below is one example aesthetic; the project's own tokens or style sheet override it. Includes automated GitHub Pages live hosting.

---

🎯 Core Design Philosophy (Anti-Slop & Neutrality)

1. Restrained, Professional Aesthetic:
   • Deep matte charcoal surfaces (#0f1117, #161922) with subtle crisp borders (#232733).
   • High-contrast neutral typography (#f0f3f6 headers, #9aa1b2 body).
   • Zero loud rainbow gradients or toy-like cartoon icons.
2. 3-Column Doc Architecture:
   • Left Sidebar (260px): Sticky navigation tree with version badges (v1.1.0) and soft pill active highlights.
   • Center Main (860px max): Breadcrumbs navigation, title lead, neutral platform tables with action pills (.pill-btn), interactive pre-flight checklists, and syntax-highlighted copyable terminal blocks.
   • Right Sidebar (220px): "On this page" dynamic Table of Contents tracking active scroll position in real-time.
3. Zero External Dependencies:
   • 100% self-contained single-file HTML5 with inlined CSS, vector SVGs, and lightweight vanilla JS.
   • 100% offline-ready, instant load, zero CDN failure risk.
4. Bilingual Parity (DE / EN):
   • Native segmented toggle (DE / EN) with instant content morphing and localStorage persistence.

---

⚡ The Live Documentation GitHub Hosting Trick (CI/CD Recipe)

Follow this exact procedure to host any documentation live at https://<owner>.github.io/<repo>/ in under 60 seconds with automated push-to-deploy:

1. Workspace Directory Setup

Place the documentation files at the root of the docs/ folder:

docs/
├── index.html          # Main standalone bilingual manual (or symlink)
├── .nojekyll           # Bypasses Jekyll processing to serve raw HTML/CSS assets
└── ...

2. GitHub Actions Deployment Workflow

Create .github/workflows/deploy-docs.yml:

name: Deploy Documentation to GitHub Pages

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - '.github/workflows/deploy-docs.yml'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: 'docs/'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

3. Switch GitHub Pages Build Type via CLI (One-Liner)

To activate GitHub Actions-based Pages deployment programmatically without opening the browser:

gh api -X PUT repos/<owner>/<repo>/pages -f build_type=workflow

4. Trigger & Verify Live URL

gh workflow run deploy-docs.yml
gh run watch --exit-status

The documentation is now live at https://<owner>.github.io/<repo>/.

5. README.md Badge & Header Link

Add the live documentation badge and banner to the top of README.md:

[![Documentation](https://img.shields.io/badge/Docs-Live%20Manual-blue?style=flat-square&logo=github)](https://<owner>.github.io/<repo>/)

> 🌐 **Live User Manual & Interactive Guide:** [https://<owner>.github.io/<repo>/](https://<owner>.github.io/<repo>/)

---

🎨 DTCG Design Tokens

:root {
  /* Layout */
  --header-height: 60px;
  --sidebar-left-width: 260px;
  --sidebar-right-width: 220px;
  --content-max-width: 860px;

  /* Matte Dark Theme */
  --bg-header: #0f1117;
  --bg-body: #0f1117;
  --bg-sidebar: #0f1117;
  --bg-surface: #161922;
  --bg-surface-elevated: #1e222d;
  --bg-card: #161922;
  --bg-table-header: #1c202a;
  
  --border-subtle: #232733;
  --border-strong: #323847;
  
  --text-primary: #f0f3f6;
  --text-secondary: #9aa1b2;
  --text-muted: #656d81;
  --text-link: #58a6ff;
  
  --accent-blue: #3b82f6;
  --accent-blue-subtle: rgba(59, 130, 246, 0.12);
  --accent-pill: #252b38;
  --accent-pill-hover: #32394a;
  
  --success: #3fb950;
  --warning: #d29922;
  --danger: #f85149;
  
  --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", "Google Sans", Inter, Roboto, sans-serif;
  --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
}

[data-theme="light"] {
  --bg-header: #ffffff;
  --bg-body: #ffffff;
  --bg-sidebar: #f8fafc;
  --bg-surface: #f1f5f9;
  --bg-surface-elevated: #e2e8f0;
  --bg-card: #ffffff;
  --bg-table-header: #f8fafc;
  --border-subtle: #e2e8f0;
  --border-strong: #cbd5e1;
  
  --text-primary: #0f172a;
  --text-secondary: #475569;
  --text-muted: #94a3b8;
  --text-link: #2563eb;
  
  --accent-blue: #2563eb;
  --accent-blue-subtle: rgba(37, 99, 235, 0.08);
  --accent-pill: #e2e8f0;
  --accent-pill-hover: #cbd5e1;
}

---

📁 Turnkey Template Location

Agents can read and duplicate the full standalone template file:

• ~/.agents/skills/bdbhtmlmanueldocs/templates/docs_template.html

1. Overview

This skill provides domain-specific logic and rules for its respective BDB pipeline component to ensure standardization across multi-agent workflows.

2. When to Use

• Use when specifically requested by the user or triggered by an orchestration agent.
• Use when the current task aligns with the skill's domain.
• Exclude when standard tool execution is sufficient.

3. Core Process

1. Read the provided context and ensure preconditions are met.
2. Run the required script or tool and confirm the state change.
3. Verify exit codes, file modifications, or DB counts to guarantee success before reporting completion.

4. Common Rationalizations

Rationalization	Reality
"The code change was small, so I skipped updating OpenWiki docs."	Every state change must be reflected in the relevant system records.
"The ingest script exited without an error, so the memB index must be updated."	Silent failures happen; explicit verification of the side effect is mandatory.
"I'll let the /startcycle proceed without a defined rollback path."	Proceeding without a rollback path corrupts the workflow integrity and safety.
"I trust the cached agent registry instead of rescanning after a skill change."	Caches stale out quickly; explicit rescans prevent ghost failures.

5. Red Flags

• Bypassing the verification step after a script execution.
• Proceeding to the next pipeline stage without confirming the previous stage's side effects.
• Ignoring domain-specific constraints listed in this skill.

6. Verification

• Verified script exit codes are explicitly checked.
• Confirmed target files or database records reflect the expected change.
• Ensured no silent failures were ignored before reporting success.