📦 Documentation Site Generator Agent Specification¶

📌 Purpose¶

The Documentation Site Generator Agent is responsible for scaffolding, configuring, and maintaining MkDocs-based documentation sites across the ConnectSoft platform — from initial project creation through navigation management, CI/CD pipeline configuration, ADR tooling integration, and deployment to Azure Static Web Apps or GitHub Pages.

It ensures every ConnectSoft project, module, and edition has a consistent, navigable, and automatically deployed documentation site built from the ConnectSoft.DocumentationTemplate.

🧾 Documentation that exists but isn't published is invisible. This agent makes every document built, deployed, and discoverable as a live site.

🎯 Primary Goals¶

Goal	Description
📦 Scaffold MkDocs projects	Generate new documentation sites from `ConnectSoft.DocumentationTemplate` with proper structure
🧭 Manage `mkdocs.yml` navigation	Automatically update nav trees when new documents, ADRs, or API docs are added
⚙️ Configure CI/CD pipelines	Generate Azure Pipelines or GitHub Actions workflows for building and deploying doc sites
🔗 Integrate ADR tooling	Configure log4brains integration and ADR navigation within the documentation site
🚀 Deploy to hosting targets	Manage deployments to Azure Static Web Apps, GitHub Pages, or internal preview environments
🔄 Keep sites current	Detect documentation structure changes and trigger site rebuilds automatically

🧠 Core Role in the Factory¶

The Documentation Site Generator Agent sits within the Documentation and Knowledge Management cluster as the build and deploy layer for all documentation content. While other agents (Documentation Writer, API Documentation, ADR) produce content, this agent ensures that content is assembled, navigated, and published as a cohesive site.

🧩 Position in the Documentation and Knowledge Management Cluster¶

Layer	Cluster	Description
📦 Build & Deploy Layer	Documentation & Knowledge Management	Assembles documentation content into deployable MkDocs sites
🧭 Navigation Manager	Maintains `mkdocs.yml` nav structure as content evolves
⚙️ Pipeline Orchestrator	Configures and triggers CI/CD for documentation deployments

flowchart TD
    DOC_WRITER[📝 Documentation Writer Agent] -->|documentation_structure_changed| DOC_SITE[📦 Documentation Site Generator Agent]
    ADR_AGENT[📜 ADR Agent] -->|adr_published| DOC_SITE
    API_DOC[📡 API Documentation Agent] -->|api_docs_updated| DOC_SITE
    DEVOPS[⚙️ DevOps Engineer Agent] -->|project_created| DOC_SITE
    DOC_SITE --> AZURE_SWA[☁️ Azure Static Web Apps]
    DOC_SITE --> GH_PAGES[🌐 GitHub Pages]
    DOC_SITE --> STUDIO[📊 Studio Agent]

Hold "Alt" / "Option" to enable pan & zoom

⚡ Triggering Events¶

Event	Description
`project_created`	A new ConnectSoft project or microservice is created, requiring documentation site scaffolding
`documentation_structure_changed`	New documents, sections, or ADRs are added that require `mkdocs.yml` nav updates
`release_published`	A new release triggers documentation site rebuild with updated version references
`doc_site_config_drift_detected`	The `mkdocs.yml` is out of sync with the actual documentation file structure
`doc_deployment_failed`	A previous documentation deployment failed and requires correction and retry

📋 Responsibilities and Deliverables¶

🧰 Key Responsibilities¶

Responsibility	Description
📦 MkDocs Project Scaffolding	Generate `mkdocs.yml`, `docs/` folder structure, and theme configuration from `ConnectSoft.DocumentationTemplate`
🧭 Navigation Management	Automatically update `mkdocs.yml` nav when documents are added, moved, or removed
⚙️ CI/CD Pipeline Generation	Create Azure Pipelines YAML or GitHub Actions workflows for building and deploying MkDocs sites
🔗 ADR Integration	Configure log4brains tooling and add ADR sections to the documentation site navigation
🎨 Theme and Plugin Configuration	Apply ConnectSoft Material for MkDocs theme, search plugin, mermaid diagrams, and admonitions
🚀 Deployment Management	Deploy built sites to Azure Static Web Apps or GitHub Pages with proper routing and custom domains
🔄 Drift Detection and Repair	Detect when `mkdocs.yml` nav drifts from the actual file structure and auto-repair

📤 Deliverables¶

Deliverable Type	Description
📦 `documentation-site`	Complete MkDocs project with `docs/`, `mkdocs.yml`, theme, and plugins configured
🧭 `mkdocs-config`	Updated `mkdocs.yml` with current navigation tree, plugins, and theme settings
⚙️ `doc-pipeline`	CI/CD pipeline definition (Azure Pipelines YAML or GitHub Actions) for doc site build and deploy
🔗 `log4brains-config`	log4brains configuration file and ADR navigation integration

📘 Example Output: `mkdocs.yml`¶

site_name: ConnectSoft VetClinic Documentation
site_url: https://docs.connectsoft.ai/vetclinic
repo_url: https://github.com/connectsoft/vetclinic

theme:
  name: material
  palette:
    primary: indigo
    accent: teal
  features:
    - navigation.tabs
    - navigation.sections
    - search.suggest
    - content.code.copy

plugins:
  - search
  - mermaid2

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

nav:
  - Home: index.md
  - Architecture:
    - Overview: architecture/overview.md
    - Decisions:
      - ADR-0001 Use MassTransit: decisions/adr-0001-use-masstransit.md
      - ADR-0002 Multi-Tenant Strategy: decisions/adr-0002-multi-tenant-strategy.md
  - API Reference:
    - Appointments API: api/appointments.md
    - Notifications API: api/notifications.md
  - Modules:
    - Appointment Service: modules/appointment-service/README.md
    - Notification Service: modules/notification-service/README.md
  - Guides:
    - Getting Started: guides/getting-started.md
    - SDK Integration: guides/sdk-integration.md

📘 Example Output: CI/CD Pipeline¶

trigger:
  branches:
    include:
      - main
  paths:
    include:
      - docs/**
      - mkdocs.yml

pool:
  vmImage: ubuntu-latest

steps:
  - task: UsePythonVersion@0
    inputs:
      versionSpec: '3.11'

  - script: |
      pip install mkdocs-material pymdown-extensions mkdocs-mermaid2-plugin
      mkdocs build --strict
    displayName: 'Build MkDocs Site'

  - task: AzureStaticWebApp@0
    inputs:
      app_location: 'site'
      output_location: ''
    displayName: 'Deploy to Azure Static Web Apps'

🤝 Collaboration Interfaces¶

🔗 Upstream Agents (Inputs)¶

Agent	Input Provided
Documentation Writer Agent	New or updated Markdown documents requiring nav integration
ADR Agent	Published ADRs that need to be added to the decisions section
API Documentation Agent	API reference pages for inclusion in the API section
DevOps Engineer Agent	Project creation events and CI/CD infrastructure context

📤 Downstream Agents (Outputs Consumed By)¶

Agent	Output Consumed
DevOps Engineer Agent	CI/CD pipeline definitions for documentation deployment
Knowledge Management Agent	Site structure metadata for knowledge indexing
Studio Agent	Documentation site health, deployment status, and freshness metrics

📊 Collaboration Flow¶

flowchart TD
    DOC_WRITER[📝 Documentation Writer] --> DOC_SITE[📦 Doc Site Generator]
    ADR_AGENT[📜 ADR Agent] --> DOC_SITE
    API_DOC[📡 API Documentation] --> DOC_SITE
    DEVOPS_IN[⚙️ DevOps Engineer] --> DOC_SITE

    DOC_SITE --> DEVOPS_OUT[⚙️ DevOps Engineer]
    DOC_SITE --> KM[🧠 Knowledge Management]
    DOC_SITE --> STUDIO[📊 Studio Dashboard]
    DOC_SITE --> HOSTING[☁️ Hosting Targets]

Hold "Alt" / "Option" to enable pan & zoom

🧠 Memory and Knowledge¶

📚 Pre-Embedded Knowledge¶

Domain	Description
📦 MkDocs configuration	Full understanding of `mkdocs.yml` schema, Material theme options, and plugin ecosystem
⚙️ CI/CD pipeline patterns	Azure Pipelines and GitHub Actions templates for MkDocs build and deploy
🔗 log4brains integration	Configuration patterns for log4brains ADR browsing within MkDocs sites
🎨 ConnectSoft.DocumentationTemplate	Standard project structure, theme configuration, and nav conventions
☁️ Azure Static Web Apps	Deployment configuration, custom domain setup, and routing rules

🧠 Short-Term Memory¶

Capability	Description
📍 Active project context	Current documentation project being scaffolded or updated
🧭 Nav diff state	Changes detected between current `mkdocs.yml` nav and file system structure
⚙️ Pipeline generation context	Target hosting platform and CI/CD system for current deployment

🧠 Long-Term Memory¶

Memory Type	Storage	Purpose
📦 Site registry	`doc-sites-index.yaml`	Registry of all documentation sites with hosting URLs and last deploy dates
🧭 Nav history	`nav-change-history.yaml`	Tracks navigation changes across documentation site rebuilds
⚙️ Pipeline templates	Template library	Reusable CI/CD pipeline patterns by hosting target
📊 Deployment metrics	`doc-deploy.metrics.json`	Build success rates, deployment frequency, and site freshness

✅ Validation¶

🧪 Validation Checks¶

Check	Description
📦 MkDocs build success	Site must build successfully with `mkdocs build --strict` (no warnings)
🧭 Nav completeness	Every `.md` file in `docs/` must be reachable from the nav tree
🔗 Link integrity	All internal links between documentation pages must resolve
⚙️ Pipeline validity	Generated CI/CD pipelines must be syntactically valid YAML
🎨 Theme consistency	Theme configuration must match ConnectSoft documentation standards
📜 ADR integration	log4brains configuration must be valid and ADRs must appear in the decisions nav

🔁 Retry and Correction¶

Scenario	Correction
MkDocs build failure	Parse error output, fix `mkdocs.yml` syntax or missing files, rebuild
Orphaned documents not in nav	Auto-add to appropriate nav section based on file path conventions
Deployment failure	Check hosting credentials, retry deployment with backoff
Theme plugin incompatibility	Fall back to base Material theme without conflicting plugins

📊 Observability Hooks¶

Event	Trigger	Payload
`DocSiteScaffolded`	New documentation site created	`projectId`, `templateVersion`, `traceId`
`DocSiteNavUpdated`	Navigation tree updated	`addedPages`, `removedPages`, `traceId`
`DocSiteDeployed`	Documentation site successfully deployed	`siteUrl`, `hostingTarget`, `buildDuration`, `traceId`
`DocSiteDeployFailed`	Deployment failed	`reason`, `hostingTarget`, `traceId`
`DocSiteDriftDetected`	Nav/structure drift detected	`driftType`, `affectedFiles`, `traceId`

🧾 Summary and Positioning¶

The Documentation Site Generator Agent is the build and deploy engine for ConnectSoft documentation, ensuring every project has a:

📦 Properly scaffolded MkDocs site with ConnectSoft theming and structure
🧭 Current navigation that automatically reflects documentation additions and changes
⚙️ CI/CD pipeline for automated building and deployment on every change
🔗 ADR integration with log4brains tooling for browsable architecture decisions
🚀 Live deployment to Azure Static Web Apps or GitHub Pages with zero manual steps

🧩 Position in the ConnectSoft Platform¶

flowchart TD
    CONTENT_AGENTS[📄 Content Agents] --> DOC_SITE[📦 Doc Site Generator]
    DOC_SITE --> BUILD[🔨 MkDocs Build]
    BUILD --> DEPLOY[🚀 Deploy]
    DEPLOY --> AZURE_SWA[☁️ Azure Static Web Apps]
    DEPLOY --> GH_PAGES[🌐 GitHub Pages]
    DOC_SITE --> STUDIO[📊 Studio Dashboard]

Hold "Alt" / "Option" to enable pan & zoom

Without this agent, documentation is a collection of loose Markdown files. With it, documentation becomes a live, navigable, automatically deployed knowledge portal that serves developers, stakeholders, and AI agents alike.

📦 Documentation Site Generator Agent Specification¶

📌 Purpose¶

🎯 Primary Goals¶

🧠 Core Role in the Factory¶

🧩 Position in the Documentation and Knowledge Management Cluster¶

⚡ Triggering Events¶

📋 Responsibilities and Deliverables¶

🧰 Key Responsibilities¶

📤 Deliverables¶

📘 Example Output: mkdocs.yml¶

📘 Example Output: CI/CD Pipeline¶

🤝 Collaboration Interfaces¶

🔗 Upstream Agents (Inputs)¶

📤 Downstream Agents (Outputs Consumed By)¶

📊 Collaboration Flow¶

🧠 Memory and Knowledge¶

📚 Pre-Embedded Knowledge¶

🧠 Short-Term Memory¶

🧠 Long-Term Memory¶

✅ Validation¶

🧪 Validation Checks¶

🔁 Retry and Correction¶

📊 Observability Hooks¶

🧾 Summary and Positioning¶

🧩 Position in the ConnectSoft Platform¶

📘 Example Output: `mkdocs.yml`¶